    Dead Souls Character Mode FAQ, v1

    Written by Cratylus @ Dead Souls, May 2009

    What is Dead Souls Character Mode?

    What is it for?

    Who can use it?

    How do I use it?

    What can I do with it?
    	Reprompt
    	Command recall
    	Context-sensitive command recall
    	Tab completion
    	Character mode editor

    What's broken in it?

    What is chario? Why do my errors keep pointing to it?

    What is Dead Souls Character Mode?

    	Telnet. Wow.

    	It's a neat protocol that can do a lot more than
    people realize. Character mode is one of the two most
    common ways to use telnet for mud communication.

    	The mode that most people are used to is "line mode".
    What this means is that when you type a command into your
    mud client, the mud client handles all the details of
    putting one character after another, and then when you press
    <Enter>, the client sends that whole line as a unit to
    the mud for processing. It's so common that it seems to be the
    default even for telnet clients that are not designed for mudding.

    	Character mode communicates in a different way. Instead
    of sending data line by line, a character mode connection has
    your client send your characters to the mud right when you
    type them, so that by the time you hit <Enter> the mud already
    has the complete line you wish to execute, and the <Enter> just
    tells it to go ahead and do so.

    What is it for?

    	The main usefulness of character mode in a mud is sending
    special control characters and sequences. This allows you to,
    for example, have a mud where players can enter a special "pilot"
    mode where the arrow keys control an airplane.

    	In Dead Souls, the default application of character mode
    is mostly creator oriented. Being a developer, and being a UNIX
    guy, I've sorely missed being able to use filename completion and
    such while on my mud. Character mode allows for the extension of
    the "Nightmare Shell", or nmsh, into something more homey.

    Who can use it?

    	Not every mud client supports character mode. For example,
    trying to use charmode in MUSHclient or TinyFugue will result in
    disappointment and confusion. I've heard that some clients do
    handle it, but I don't know which and I can't vouch for how well
    they do so. Before trying to use charmode with your favorite mud
    client, read its documentation to see how to enter character mode
    with it.

    	I use DS charmode from terminal windows, like xterm,
    gnome-terminal, and Windows cmd.exe. Other standard terminal clients
    like Putty probably support it too.

    How do I use it?

    	Pretty simple, really. One you are logged in to your
    mud with a terminal client (or a mud client you are sure handles
    character mode), type the command:

    charmode on

    	This sets your connection to character mode and sets your
    player object to interpret your input in that manner. To exit
    charmode you can either charmode off or <Ctrl>-D. To cancel a
    command you've decided not to issue, <Ctrl>-C.

    	In the inevitable circumstance that someone tries to, say,
    use charmode with Zmud32 from 1996, and then becomes hopelessly
    entangled in problems and errors while trying to use advanced
    charmode functions, your "charmode" flag is reset when you disconnect.
    If you get lost or stuck in charmode, just disconnect and reconnect,
    and you'll be in linemode again.

    What can I do with it?

    Reprompt

    This is where DS charmode has its origins. A while back some
    dudes where complaining along the lines of how the number one
    reason LP muds suck is the terrible awful handling of prompts.
    I was like "pffshyeah right" but once their complaints were
    explained to me in a way I understood, I realized it wasn't
    that hard to accommodate that preference...it was just a matter
    of erasing the prompt line before printing anything. Not
    rocket science. Then it occurred to me to take it a step further.
    If the screen receives data while you're in the middle of typing
    a command, and you're in reprompt mode, what you typed will be
    invisible. You'll just have to remember what it was. This seemed
    like it shouldn't be super hard to fix.

    A few weeks and efuns later, character mode and character mode
    reprompt were available. So now just entering charmode:

    charmode on

    Enables reprompt mode for you in a way that lets you keep your
    prompt at the bottom of the screen, and see your input even if
    interrupted by incoming text, and backspace to fix typos.

    Command recall

    It may sound weird but command recall is one of just two things
    I like mud clients for (the other is sound triggers). Now that
    DS has it integrated server side, I don't even bother with
    clients much.

    Basically charmode command recall lets you use your up and down
    keyboard arrows to summon entries in your command history
    that you can then issue again or modify.

    Context sensitive command recall

    If, for example, you typed:

    give a red ball to the troll

    a few commands ago, and now you want to give it
    another one, you can type:

    give a

    and then hit your uparrow key. The command recall system will now
    cycle through commands in your history that started with
    the string "give a".

    Tab completion

    I've wanted this in my mud for a long time, and charmode finally
    allows me to do it. The most obvious kind of tab completion is
    command completion. For example, you can type:

    inv<Tab>

    (Where <Tab> means you hit the Tab key)

    And the mud will present you with this:

    ({ "inventory", "invis" })

    To let you know which commands you might mean. Type one more
    matching letter:

    inve<Tab>

    And the mud will complete the "inventory" typing for you.

    DS charmode also does filename completion. If you want to
    see the contents of the welcome file, for example, you can:

    cd /ne<Tab>

    Which will auto complete to

    cd /news/

    Hit <Enter>, then

    more wel<Tab>

    Which will auto complete to

    more /news/welcome

    Or, more typically, you'd:

    more /n<Tab>we<Tab>

    DS charmode also does object name completion, so if you're
    in a room with a zyqxuwy, you can type:

    dest zy<Tab>

    Note that object name completion only works for creators,
    since giving this to players could result in trivial
    revelation of otherwise concealed information.

    The character mode editor, "ced"

    One of the favorite pet peeves of LP wizards for years has
    been the difficulty in getting used to the standard in-game
    editor, ed. As a line editor, ed can feel like ancient
    arcana and it tends to deter new folks from getting elbow
    deep in code like we used to do back in the day.

    What ced does is give you an editing interface that uses
    a more natural-feeling input mode. Rather than, say, issuing
    the commands:

    1z
    3c

    To view code and edit line 3, with ced you just use the
    arrow keys to navigate where you need to go. Rather than
    replace an entire line just to fix a typo, with ced you
    just move the cursor to the typo and overwrite it.

    For more details on the use of ced, type:

    help ced

    IMPORTANT NOTE: ced is not vi, nor modeled on vi. For
    "simple to learn and use", vi isn't much different than
    ed for the purposes of a mud, and I saw no advantage to
    making ced a vi-alike. It would displease people who don't
    know vi because vi is weird and difficult. It would displease
    people who do know vi because it wouldn't actually be vi and
    therefore it would be wrong in any number of ways for them.
    Having said that, I like vi and intend to eventually add a
    vi-ish editor, but don't hold your breath.

    IMPORTANT NOTE 2: If you're used to vi, you will wind up
    eventually hitting <esc> while in ced. This is going to lead
    to confusion, because now ced is waiting for the rest of your
    escape sequence. Hit an arrow key a few times until you see
    the cursor move again.

    IMPORTANT NOTE 3: Since ced is still somewhat experimental
    as of DS 2.10, it is disabled by default. To enable it
    and try it, type:

    help ced (you should see a warning about disabled stuff)
    mudconfig ced on
    userload me
    charmode on
    help ced (warning should be gone)

    You should see these as your control characters:
    Ctrl-Q -- quit without saving
    Ctrl-X -- quit and save
    Ctrl-S -- save
    Ctrl-I -- enable insert mode
    Ctrl-O -- enable overstrike mode
    Ctrl-L -- refresh the page
    Ctrl-F -- scroll forward one page
    Ctrl-B -- scroll backward one page
    Ctrl-D -- delete current line
    Ctrl-G -- Specify a line to go to
    Ctrl-/ -- Search for a string

    cd
    cp workroom.c wk1.c
    ced wk1.c.

    IMPORTANT NOTE 4: Since you're editing inside a mud, you'll
    eventually get some messages on your screen that you do not want
    while editing in ced. To clear your screen of such unwanted
    crud, use the "refresh" command: <Ctrl>-L. See also: help codeblock

    What's broken in it?

    A few caveats and fixmes:

    - You can use backspace to fix your typos when issuing commands,
    but side-arrow keys for full "command line editing" aren't yet supported
    as of DS 2.10.

    - Command recall tends not to include commands issued by add_action().
    It also can expand your alias to "what the alias was" rather than "what
    I literally typed" depending on your DS version. These idiosyncrasies
    can make your command history appear to be out of order at times, and
    will be made more standard in future releases.

    - Using ".." in tabbed file completion yields non-useful
    results. This will be fixed in later versions.

    - Copying and pasting large amounts of data into the screen while
    in charmode will result in a very slow experience for you. This is
    because the mud is accepting each char one at a time while at the
    same time performing whatever other vital mud functions are going
    on that don't include you. This is not actually a "bug" so much as
    just how it works. If you need to paste large text into the mud
    through your terminal, don't use charmode to do it.

    - The ced editor doesn't handle wrapping at all. If your lines extend
    past your screen's width, you'll just have to use your imagination
    for now.

    What is chario? Why do my errors keep pointing to it?

    Think of LIB_CHARIO as a traffic cop.

    The original design of charmode had all character data being
    sent to LIB_NMSH for interpretation. This was fine for
    development and testing, but very soon it became apparent
    that LIB_NMSH was doing a lot more work than intended. There
    was also the problem of having nmsh shunt off input to the
    editor. This setup became unwieldy fairly quickly.

    LIB_CHARIO is the object that identifies which characters
    the mud has received from the user, if charmode is enabled
    for that user. Depending on whether the user is editing,
    chario (character input/output) determines which lib object
    should receive the input, nmsh or ced.

    If you use charmode, get used to seeing chario and nmsh
    showing up in your runtime error chain. Even though they
    themselves may not be the source of the error, the fact that
    your command went through them means they are part of
    the function/object stack that caused the error to be
    generated, and so they'll show up in the error log.

The end.
Dead Souls Homepage