The MudOS mudlib comes with an editable soul which can be used to create
new soul commands without having to alter the mudlib files. There are several
commands you can use to determine what soul commands are available and what
will happen if you use them.

  The first handy soul command is "semote". By itself, it shows all the soul
commands in the current soul database. With an argument (eg "semote shrug")
it shows you the current database entry for that command (More on entries
below.)

   Soul entries come in two kinds, targeted and untargeted. Targeted commands
are directed at another player: ie "worship truilkan" whereas untargeted
commands are not directed at any player: ie "think". Most of the soul commands
have both targeted forms and untargeted forms, such as the nod command. Some
have only untargeted forms, such as think, and others have only targeted forms
such as leer. The untargeted form of the soul commands is referred to by
name, and the targeted form is referred to by appending /t to the end of the
soul. Thus, you can see the untargeted form of the "shake" soul command by
typing "semote shake" and the targeted form by typing "semote shake/t". This
makes it possible to have the same soul command give different output
depending on whether there is a target or not; in the case of the shake
command, the untargeted output is "You shake your head" while the targeted
output is "You shake hands with Mobydick".

   The "temote" command will show you what will be seen if you use the given
soul command, both by you, by the target, and by other people in the room.
For example, the command "temote shake emphatically" would produce the output:

me:
You shake your head emphatically.
others:
Mobydick shakes his head emphatically.

   This makes it easy to debug new soul entries without having to ask other
people what they see when you use the command.

   The "edemote" command is used to create new entries in the soul command
database. Typing "edemote thwack" will allow you to create a new soul
command which players can use by typing "thwack". You can create a targeted
version of thwack by typing "edemote thwack/t".

For example, the entry for the kiss/t could (but really should not) be:

.me
You kiss $n $M
.target
$N kisses you $M
.others
$N kisses $n $M
.modifier
chastely
.end

where .me indicates the format that I will see, .others indicates the form
that others will see, and .target indicates the form that the target of the
command will see. .modifier gives a default modifier to use, which can be
overridden by a user-supplied modifier. Thus, if the user types "kiss psyche"
the result will be:

You kiss Psyche chastely.
but if the user types "kiss psyche passionately" the result will be
You kiss Psyche passionately.

By Using "temote kiss psyche", you can see what others will see:

me:
You kiss Psyche chastely.
target:
Waldo kisses you chastely.
others:
Waldo kisses Psyche chastely.

Hopefully you didn't stop reading before you reached this point, because
if you did, you will have missed one of the best features of the editable
soul.  Edemote allows the above kiss/t command to be rewritten in a much
simpler way:

.me
$N $V $n $M
.modifier
chastely
.end

That's all!  Since .target and .others aren't specified, edemote will use
what was specified for .me for .target and .others as well.  Note that
emoted (the emote daemon) is able to translate $N to "You" or "Waldo"
depending on who is to see the message.  Note that emoted translates
$V to "kiss" or "kisses" depending on who is to see the message.  And
finally, emoted translates $n to "Psyche" or "you" depending
on who is to see the message.

An even simpler method can be used to create standard emotes.  The
default value for .me is $N $V.  This means that a usable soul command
can be created by using 'edemote giggle' and entering the single line:

.end

then 'temote giggle' produces:

me:
You giggle.
others:
Waldo giggles.

There is also a default value for the .me of targetted emotes (it is
$N $V at $n).  Typing 'edemote giggle/t' and entering '.end' as the
contents of the giggle/t emote and then typing 'temote giggle psyche'
will produce:

me:
You giggle at Psyche.
others:
Waldo giggles at Psyche.
target:
Waldo giggles at you.

More complex emotes can be created via the use of the more advanced
editable-soul features.  For example, suppose that you want to make
a command 'schwing' that produces the following 'temote swchwing'
output:

me:
You go: Sch-wing!
others:
Waldo goes: Sch-wing!

The problem is that the command is named 'schwing' and the verb is 'go'.
Actually this isn't a problem at all.  Just use the '.verb' field to
specify that the verb is 'go' (instead of the default 'schwing').

Here is the edemote entry for the above command:

.me
$N $V: Sch-wing!
.verb
go
.end

Other emotes may need even more advanced features.  Some commands use
two different verbs.  This need is taken care of as well.  Use the
.verb2 field to specify the second verb and the $W variable in the
emote text.

Here is an emote that demonstrates many of the more advanced features of
the editable soul:

.me
$N $V $g lips to $Q and $W $o $m
.modifier
tenderly
.verb
pull
.verb2
kiss
.end

Typing 'temote kiss psyche' produces (assuming your name is Waldo):

me:
You pull Psyche's lips to yours and kiss her tenderly.
target:
Waldo pulls your lips to his and kisses you tenderly.
others:
Waldo pulls Psyche's lips to his and kisses her tenderly.

[yes i know having one's lips pulled like that sounds quite painful!]

The below chart is available via 'help soul.brief':

Anything of the form $[A-Z,a-z] is a special modifier which inserts the
appropriate names/pronouns/prepositions into the soul command. In the above
example, $N is replaced by the user's name, $V by the first verb (pull), $g
by the 'named' possessive of the target (Psyche's or 'your'), $Q by the
preceding possessive of the user (yours, his, etc.), $W by the second verb,
.verb2 (kiss), $o by the objective of the target, and $m by the modifier
(default tenderly).
There are the possible replacement parameters:

  $N = name of user       $n = name of target
  $S = subjective of user $O = objective of user  $P = possessive of user
  $s =   ''     '' target $o =   ''    '' target  $p =    ''   '' target

  $M = modifier (only appears if user ends command with " .")
  $m = modifier (always appears unless user types own modifier or " .")
  $V = verb (defaults to command name.  can be set with .verb)
  $W = second verb (set with .verb2)
  $G = possessive of user (either $N's or 'your' depending)
  $g = possessive of target ('' $n's '')
  $Q = preceding possessive (i.e. hers, his, its, hirs, yours) for user
  $q = '' for target

For $S, $O, $P, $s, $o, $p:

  subjective = (he, she, it, sie), objective = (him, her, it, hir),
  possessive = (his, her, its, hir)

The supported headers are listed in /include/emoted.h.

The MudOS soul was written by Truilkan@Portals in November 1992. This help
file was written by Mobydick@TMI-2 on 11-10-92 and is heavily based on
Truilkan's documentation.