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.