SAM System - A Technical Summary

See Also: DescriptionSystem, SignalSystem

The Problem of Dynamic Text

SkotOS is largely concerned with presenting text to users. In a dynamic, interactive system such as ours, environments and occurences are forever changing, yet they must be described in consistent ways, even artistic ways, to the inhabitants of the virtual world:

   You are kneeling next to Fred in a dingy hut.  Jane stands near the door. A
   long, black sword lies at her feet. The rain pours down outside.

This is a description which is clearly associated with the hut in which we are kneeling, yet refers to current occupants, items on the floor, and the weather outside: the description mingles static text with dynamic data. The system's ability to do this well is absolutely vital to making the user's experience in the world a good one.

A Solution

Since the program that serves the user with the description is the same one in which the dynamic data resides, there is a simple solution to the quandary above. Let the descriptive text contain special codes that instruct the world server to calculate and embed dynamic descriptions. This could be part of the description of a statue you find in a room:

   "The statue appears to be $(this.expression) at you."

This statue is alive, it turns out, and can either frown at you or smile, depending on whether or not you've kept up your sacrifices to the local dark lord. Thus when a user looks at the statue, the server knows to query the expression property of the statue. The definition of this property in the statue includes some logic that investigates the user staring at it, and sends back either ‘frowning' or ‘smiling'.

This is the core of SAM: the developer writes static descriptions that contain active markup. The markup is evaluated by the server at each time the user actually observes the description. The perceived description is populated with current data.

SAM Everywhere

Once we came up with this idea of marked-up text, a whole world of possibilities opened up before us. We look further than description; since web pages are essentially text, why not use this same system to generate web pages on the fly, populated with up-to-date world data:

   Welcome to Sir John's village status page!

   Johnsville currently has 612 inhabitants. The weather is cold
   and sunny. Thirty-one cows graze the fields. Alewife Christina
   made her latest batch of ale approximately nine hours ago.

The SAM in this case would underlie HTML rather than straight text, but to the server there is no difference.

More Power

The more we play with SAM, the more its potential power became apparant to us, and the more we added to it. Early on we decided to add conditional functionality:

   This is a long black sword with intricate carvings.
   
      
         . You recognize the make as Alvatian.
      
      
         It is nighttime.
      
   

where the user will only be told of the sword's make if he has studied his weapon lore.

We also add iteration, e.g.

   Welcome to Sir John's cow status page! Here's who's grazing
   the fields today:
   
      $(Cow.CapitalizedName) is grazing in $(Cow.Pasture) and is
      feeling $(Cow.Contendedness).
   

where $(Cows) is an array of, yes, cows, and the SAM within the for loop is executed once for each element of this array. The result is a list of cows, their whereabouts, and how happy they are at the moment.

We've introduced new syntax here; readers may recognize it as similar to HTML. It is in fact XML, a close relative, and it is the syntactic model we have chosen to express SAM.

Shortcuts for SAM

As we used more and more SAM, the extra "text" in the shortcuts required for XML often made reading descriptions more difficult. To address this, we created SAM Shortcuts. These are alternative ways to use SAM but with shorter tags, making it descriptions easier to read.

For example, in the Black Sword example above, the following SAM shortcut works exactly the same way:

   This is a long black sword with intricate carvings.
   {? greaterthan | $looker.skill:weapon-lore | 5 |
      . You recognize the make as Alvatian.|
      .}

Technically this is not XML markup, but internally SkotOS converts this to XML.

Existing Approaches

(We need someone to write up how LPMuds and other MUDs have tried to do this in the past)

Problems Solved by Skotos SAM System

Ok, there are many different problems that can be solved related to XYZ, but these are the ones that we specifically are addressing in this implementation of the XYZ System.

State of Development

The SAM System is relatively mature and complete. Much of the fundamental power of it was proven in Castle Marrach, and now is being used more fully in various Skotos-Seven games.

Open Issues in the SAM System

There are very few major issues with SAM itself, due to its maturity and several years of development. However, there are some related systems that have weaknesses that affect SAM:

• Right now brief/glance/look/examine descriptions (and their all/dark/dim/bright/superbright variants) are not actually socials, so they do not get as many arguments as do the social tags. Useful information that is lacking includes which verb was used, the distance the actor is from the detail being viewed, etc. As soon as these commands are converted to Merry, all of these useful arguments will be available to these descriptions as well.
• There are quite a few commands that are not converted to Merry yet, so can't be used with signal descriptions written in SAM.
• The combinables system may have impact on SAM tags, as not all ‘objects' will be single objects anymore.

SEE ALSO: Quick Summary of the SAM System

Practical SAM

SAM Arguments and References

SAM Arguments

These default arguments are available when objects are being described in brief, glance, look, examine, and their dim/dark/bright/superbright descriptions:

    $(actor)  - Person this object is being described to, an OBJECT
    $(looker) - Whoever is looking at the object, an OBJECT
    $(this)   - The object being described, an OBJECT
    #(target) - The detail of of the object being described, a NREF

Here are some useful arguments are typically available when signal descriptions are triggered in objects:

    $(actor)        - Object that triggered the action, an OBJECT
    $(target)       - The object that was acted upon, an OBJECT
    $(verb)         - The verb used by the actor, a STRING
    $(adverb)       - The adverb used by the actor (if any), a STRING

If you use these arguments directly in SAM, you'll typically get output like:

   actor: OBJ(Chatters:LC:ch:allen-christopher)
   target: NREF([Examples:complete:sam:sam-toy]#11527|button)
   verb: pull
   adverb: carefully

When you see OBJ() or NREF(), this means that these values are intended for use inside other same tags. For instance, the following will output the brief description of the actor:

   <describe what=$actor />

There are also a number other arguements, and sub-arguments that you might find useful:

    $(preps)        - Prepositions used by the actor (if any), an ARRAY

There are other arguments that are available to many signals, however, they may not be available to all signals. Even $verb may not be set if the action was not triggered by a social.

The best way to see what arguments are available, you can put inline Merry in descriptions to see every argument that is available to SAM in a particular description:

   Look: [*
      $[dump_value( args )]
   *]

   > look at toy's button
   ([ "actor":<Chatters:LC:ch:allen-christopher>,
      "looker":<Chatters:LC:ch:allen-christopher>,
      "node":</usr/SkotOS/data/merry#-1>,
      "target":(43)O(/base/data/nref#-1, <[Examples:complete:sam:sam-toy]#11527>, "button"),
      "this":<[Examples:complete:sam:sam-toy]#11527> ])
   >


   React-post:push-dob: [*
      $[dump_value( args )]
   *]

   > push toy's button carefully
   You push a button.
   ([ "actor":<Chatters:LC:ch:allen-christopher>,
      "adverb":"carefully",
      "adverb:position":"pp",
      "dob":({ (43)O(/base/data/nref#-1, <[Examples:complete:sam:sam-toy #11527>, "button") }),
      "dob:description":"push",
      "dob:distance":3,
      "imperative":"push",
      "ldef":X[S] $(you) $(verb) $(dobname).,
      "node":</usr/SkotOS/data/merry#-1>,
      "obscurity":0,
      "origtarget":"none",
      "parts":({ ({ "V" }), ({ "O", ({ (43)O(/base/data/nref#-1, <[Examples:complete:sam:sam-toy]#11527>, "button") }) }) }),
      "preps":([ ]), "privacy":0, "rob":</base/data/result#-1>,
      "roles":({ "dob" }),
      "target":(43)O(/base/data/nref#-1, <[Examples:complete:sam:sam-toy]#11527>, "button"),
      "this":<[Examples:complete:sam:sam-toy]#11527>,
      "verb":"push",
      "vob":<Socials:Verbs:push>,
      "witnesses":({ <Examples:complete:desc:room-go-nowhere>, ({ }) }) ])
      >

You can even use +tool has arguements available to it:

   > +tool sam exec $[dump_value( args )]

   Original input:
           $[dump_value( args )]

   Output:
           "([ \"actor\":<Chatters:LC:ch:allen-christopher>, \
                "body\":<Chatters:LC:ch:allen-christopher>, \
                "here\":<Examples:complete:desc:room-go-nowhere>, \
                "looker\":<Chatters:LC:ch:allen-christopher>, \
                "node\":</usr/SkotOS/data/merry#-1> ])"

   > +tool merry exec EmitTo( $actor, dump_value( args ) ) ;
   ([ "actor":<Chatters:LC:ch:allen-christopher>,
      "body":<Chatters:LC:ch:allen-christopher>,
      "here":<Examples:complete:desc:room-go-nowhere>,
      "looker":<Chatters:LC:ch:allen-christopher> ])

   Merry code:   EmitTo( $actor, dump_value( args ) ) ;
   Merry result: nil

SAM References

Pronouns References

Pronouns are those words that replace nouns: he, him, his, that type of thing. They exist in three different forms:

• Direct Object The pronoun you use when the noun you're replacing is active. He, she, it, they.
• Indirect Object The pronoun you use whn the noun you're replacing is being acted upon. Him, her, it, them.
• Possessive The pronoun you use when the noun you're replacing is owning something. His, her, its, their.

You may use SAM references to replace objects in a sentence with the appropriate pronouns, in order to create more beautiful output. The SAM references that do this are $(object.base:pronoun) for direct object pronouns; $(object:base:objective) for indirect object pronouns; and $(object.base:possessive) for possessive pronouns.

The $(object) is usually a general SAM reference like $(actor) or $(target) or one specific to an individual verb or skill like $(teacher) or $(student). Currently these pronoun SAM references may only be used with singular objects.

Object References

In addition, you can directly refer to objects named in Woe, either directly:

    $(woe:object:name)

Or indirectly (meaning if the object name changes, the reference changes with it):

    $[${woe:object:name}]

With these any of these, you can directly output properties that are in these objects into your descriptions, just by adding a period followed by the property name:

    $(this.trait:variant)
    $(actor.trait:variant)
    $(Full:Woe:Name.trait:variant)
    $[${Full:Woe:Name.trait:variant}]

The way to refer to a SAM reference with a space in it is to put it in quotes – e.g.

$("room.details:exit west:descriptions:look")

rather than

$(room.details:exit west:descriptions:look)

OBSOLETE INFORMATION:

<font=purple>

These are the SAM references and suffixes that are assigned by default.

Refs:

$(this)                     This object
$(actor)                    Person using this object
$(target)                   Target of this object
$(everyone)                 All volitionals in the room
$(all)                      Everything in the room
$(looker)                   Depricated.. use $(actor)
$(third)                    $(all) minus $(actor)

Suffixes:

.env                        The room this object is in
.room                       The room this object is in
.inv                        This object's inventory
.inventory                  This object's inventory
.prox                       This object's prox object
.prep                       This object's prox prep (near, on, etc)
.stance                     This object's stance prep (standing, sitting)
.tname                      This object's true name
.ur                         This object's Ur object

----
(also)

If $(actor) has been set then:

    $(target) - If there is a 2nd party. This is it. Not always set.
    $(everyone) - Everyone in the room but the $(actor)
    $(all) - Everyone in the room.
    $(third) - Everyone in the room.

----
(also)
The one tag you didn't include is a hack by Wesley
that we'll hopefully rip out some day, 'obsprep', it tries to
figure out if what's sent into the 'what' attribute is plural or
not. It outputs 'is' or 'are' depending... but it's a cheesy hack.

</font>

Heh. The pre-computation of $everyone, $all and $third were the sole cause of almost a year's worth of Marrach lag. That's exactly the kind of variable that should never, ever be precomputed and thus cannot be present in a simple $foo style lookup (i.e. placed into ‘args' before the SAM engine takes over).

This makes me a little nervous. You can't print out the contents of args and assume that everything you find there is going to be consistently provided in every situation… in fact, ‘args' picks up contents from every step of the chain from user input to action… through all the various events that can be triggered… until you finally get to see it in your own event handler. It could contain all kinds of junk.

Specifically, ‘witnesses' is a Merry-specific thing, and if anything it should probably be ripped out. It consists of the objects that saw the current action -and- which have the ‘script_runner' flag turned on, i.e. a rather specialized array of objects of little use to any other code.

Again, precomputing the inventory of the room into a $foo variable would be a bad mistake.

You don't even need Merry to get at the on-the-fly versions of those variables – $everyone and $all would be

$actor.base:inventory

and inline Merry for $third would be

$[ $actor."base:inventory" - ({ $actor }) ]

(the document is wrong: $third is the one that should exclude the actor).

– Main.ParWinzell - 13 March 2003

Old SAM references – many are for if statements, many should now use base properties instead:

$(break text="foo" margin="length")
Keep 'text' restricted to length of 'margin'.
QUESTION: Does this work? Shouldn't this be a SAM tag not a function?

It works, but is obsoleted by the inline Merry, e.g.

     $[ break_string($text, 80) ]

which will return $text with newlines inserted between words, so that no line is longer than 80 characters.

-- Main.ParWinzell - 18 March 2003


$(mapref map="foo" index="bar")
Returns the value of foo[bar].

Obsoleted by Merry:
    $[ $foo["bar"] ]
or even more generally
    $[ somemapping[someindex] ]

-- Main.ParWinzell - 18 March 2003

$(lessthan lhs="foo" rhs="bar")
Returns the result of 'foo < bar'.
Note: 'lhs' and 'rhs' should be integers.

The integer restriction has been removed. This is available as SAM sugar
now.

-- Main.ParWinzell - 18 March 2003


$(greaterthan lhs="foo" rhs="bar")
Returns the result of 'foo > bar'.
Note: 'lhs' and 'rhs' should be integers.

The integer restriction has been removed. This is available as SAM sugar
now.
-- Main.ParWinzell - 18 March 2003


$(range val="blah" start="foo" finish="bar")
Returns TRUE is 'val' is in the range of 'start' to 'finish'.
Note: 'val', 'start', and 'finish' should be integers.

The integer restriction has been removed. This is available as SAM sugar
now.
-- Main.ParWinzell - 18 March 2003


$(mapmake)
Returns an empty initialized mapping.

obsoleted by $[ ([ ]) ]
-- Main.ParWinzell - 18 March 2003


$(equal left="foo" right="bar")
Returns the result of 'left == right'.

$(foo.0)
If $(foo) is an array, returns the first item of that array. $(foo) can even be a property, so $(object.property:namearray.0) would return the first item in the property named "property:namearray".

This is available as SAM sugar now.
-- Main.ParWinzell - 18 March 2003

$(foo.even)
Does $(Foo) have an even number of elements?

$(foo.odd)
Does $(Foo) have an odd number of elements?

Both work... No harm in keeping them I guess.

-- Main.ParWinzell - 18 March 2003



$(foo.isfile)
Is $(Foo) a file?

This is completely useless and will only confuse a developer who will
never, ever, ever see it used. It's not been in the code since 2000.
-- Main.ParWinzell - 18 March 2003


$(foo.isobject)
Is $(Foo) an object?

$(foo.isnref)
Is $(Foo) an NRef?

Both exist & are useful.
-- Main.ParWinzell - 18 March 2003



$(foo.nrefob)
Returns the object of this NRef.
QUESTION: What is foo, text?

$(Foo.nrefdetail)
Returns the detail of the NRef.
QUESTION: What is foo, text?

Foo is an NRef, e.g. $target. Exists as $[ NRefOb($foo) ] but no harm in
keeping them, since they are probably somewhat common in SAM.
-- Main.ParWinzell - 18 March 2003



$(foo.size)
Returns size. If $(Foo) is an array then the number of elements will be
returned. If $(Foo) is a string then the string length will be returned.
If $(Foo) is a mapping then the size of the indices list is returned.

Yep, works.
-- Main.ParWinzell - 18 March 2003


$(object.environment)
$(object.env)
$(object.room)
Returns the environment object of $(object)
OBSOLETE: Use $(object.base:environment) instead.


$(object.inventory)
$(object.inv)
Returns the inventory array of $(object)
OBSOLETE: Use $(object.base:inventory) instead.


$(object.prox)
Returns the NRef proximity of $(object)
OBSOLETE: Use $(object.base:proximity) instead.

Yes, those are all obsolete because the derived properties are available.
-- Main.ParWinzell - 18 March 2003


$(object.prep)
Returns the string preposition of $(object).
COMMENT: There doesn't seem to be an equivalent derived property, probably should add one, and mark this obsolete

There most certainly is --

     integer: base:preposition
     string:  base:prepositionstring

They are both documented in TWiki's

     http://troll.skotos.net/twiki/bin/view/Builders/DerivedProperties
-- Main.ParWinzell - 18 March 2003

$(object.stance)
Returns the integer stance of $(object).
COMMENT: There doesn't seem to be an equivalent derived property, probably should add one, plus maybe one that returns the text value of the stance, and mark this obsolete

There most certainly is --

     integer: base:stance
     string:  base:stancestring

They are both documented in TWiki's

     http://troll.skotos.net/twiki/bin/view/Builders/DerivedProperties
-- Main.ParWinzell - 18 March 2003


$(object.Ur)
Returns the Ur object of $(object).
OBSOLETE: Use $(object.base:urparent) instead.


$(object.tname)
Returns the string object name of $(object).
OBSOLETE: Use $(object.base:objectname) instead


$(object.property:name)
Returns the value of property 'property:name' in $(object).


---
There are no newer SAM references -- there's virtually no reason for any
of these anymore and if we didn't have to keep them for backwards compat
they should all be erased.
-- Main.ParWinzell - 18 March 2003

SAM Shortcuts

** This is copied from above, needs to be rephrased

As we used more and more SAM, the extra "text" in the shortcuts required for XML often made reading descriptions more difficult. To address this, we created SAM Shortcuts. These are alternative ways to use SAM but with shorter tags, making it descriptions easier to read.

For example, in the Black Sword example above, the following SAM shortcut works exactly the same way:

   This is a long black sword with intricate carvings.
   {? greaterthen | $looker.skill:weapon-lore | 5 |
      . You recognize the make as Alvatian.|
      .}

Technically this is not XML markup, but internally Admins.SkotOS converts this to XML.

SAM Shortcuts List

Here is a list of SAM shortcuts that can be useful:

Oneof Shortcuts

    { random text 1 | random text 2 | random text 3 | etc. }

BOOLEAN

    {? | $this.trait.variant |
        true text output |
        false text output }

    {? not | $this.trait.variant |
        true text output |
        false text output }

Comparison Shortcuts

    {? equal | $this.trait:variant | ordinary |
        true text output |
        false text output }

    {? notequal | $this.trait.variant | ordinary |
        true text output |
        false text output }

    {? lessthen | $this.trait:variant | ordinary |
        true text output |
        false text output }

    {? lessthenorequal | $this.trait.variant | ordinary |
        true text output |
        false text output }

    {? greaterthen | $this.trait:variant | ordinary |
        true text output |
        false text output }

    {? greaterthenorequal | $this.trait.variant | ordinary |
        true text output |
        false text output }

    {? range | $this.trait.variant | lowervalue | uppervalue |
        true text output |
        false text output }

    {? when | $this.trait.variant |
        value1 | value1 equal $this.trait.variant |
        value2 | value2 equal $this.trait.variant |
        value3 | value2 equal $this.trait.variant |
        *      | any other value }

Note: The ? when SAM shortcut is similar to the case and switch comparisons in other languages.

Merry Shortcuts

You can also now put arbitrary Merry expressions for tests, as in the following:

    {? | $[this.foo == "bar"] |
        true text output |
        false text output }

    {? | $[random(100)] |
        true one in 100 times. |
        false text output }

    {? | $[random(6)+random(6)+random(6)+3 == 18] |
        You rolled 3 sixes! |
        You didn't roll 3 sixes. }

    {? range | $[random(100)] | 25 | 75 |
        You rolled in the middle of the range. |
        You rolled outside the range. }

SAM and Perceptions

For general perception where you either perceive it or don't, the following technique of putting SAM into an examine description would work:

    A fine steel dagger
    
        
            , which smells of fine steel and expensive metal oil, with a slight
            odor of raccoon.
        
        
            .
        
    

It is the same technique that is used on Marrach for seesmagic such that those who can perceive magic will see things glow if they examine them.

You should note that there is now a SAM shortcut to make this a little easier. The example below will work exactly as above:

    A fine steel dagger
        {? | $(actor.IronClaw:isasniffer)|
        , which smells of fine steel and expensive metal oil, with a slight odor
        of raccoon.|
        .}

This technique can be used for anything where the false value is 0 or nil – any other value is always true (a number, some text, etc.)

I'd recommend against putting a description into just plain look or glance descriptions – instead, require the player to do an actual smelling command. Only with examine should someone get a non-visual description.

This same technique can also be used in description named react-post:sense/smell-dob that will give output whenever someone uses a verb that is related to smelling, such as sniff. This would look like:

    The fine steel dagger {? | $(actor.IronClaw:isasniffer)| smells of fine
    steel and expensive metal oil, with a slight odor of raccoon.| has a slight
    smell of oil.}

A similar description name react-post:sense/hear-dob can be used for any use of a verb related to hearing, such as listen and hear. This would look like:

    The fine steel dagger {? | $(actor.IronClaw:goodhearing)| is speaking a
    word, 'Morias' over and over again.| has a faint hum.}

It can be useful to combine this SAM shortcut with OneOfs. The classic Marrach "seesmagic" SAM looks like this in look descriptions, giving the magic-perceptive viewer a slight chance of seeing magic. Just replace the last period of a look description with the following SAM.

    A normal look description without a final period{.|.|.|.|.|.|{? |
    $(actor.skill:seesmagic)|. You see  give off a
    {slight|faint} {glimmer|glow|aura}{{ of| that you recognize as} magic|}.|.}

This technique is not that useful for non-boolean ranges of perceptions, but there is a SAM shortcut for that as well:

    A fine steel dagger{? range | $(actor.IronClaw:isasniffer)| 5 | 10 | , which
    smells of fine steel and expensive metal oil, with a slight odor of
    raccoon.|.}

In this case, if IronClaw:isasniffer is false only if the value is between 5 and 10 (inclusive) will the true statement work.

If you want to be even more granular and want to specify each, there is the {? when statement:

    {? when | $actor.IronClaw:HasGreatHearing |
        0 | You hear a creaking noise. |
        1 | Something beneath you creaks. |
        2 | The boards under your feet creak. |
        3 | The boards under your feet creak ominously. |
        * | The boards under your feet creak and you hear the
            wood splintering.}

Using SAM with Merry

to be written

 processed_string = UnSAM(ParseXML("You are {happy|sad}."));

Using SAM with BILBO

Using Oneof's

Oneof's can be used inside Bilbo emit statements just like in any other SAM text. For example:

   bilbo:react:kiss:0050 emit.actor Spot is a {furry|fluffy|sweaty} dog.

The Variables

Regardless of which mode the script is in ("act" or "react"), the following Bilbo variables always refer to the following things:

   $(this) = The object containing the script
   $(other) = The other object, interacting with this object
   $(actor) = The object doing the action
   $(target) = The recipient of the action

If the script is in "act" mode, $(this) and $(actor) are the same object, and $(other) and $(target) are the same.

If the script is in "react" mode, $(this) is $(target), and $(other) is $(actor).

(Note that these arguments are not necessarily the same exact arguments that are available to SAM or Merry, for instance $other is not a valid argument in Merry or ordinary SAM. This is because Bilbo was written pre-Merry)

Basic Examples:

bilbo:react:kiss:0080 emit.actor This object is called a .
bilbo:react:kiss:0090 emit.actor The person who kissed this object is named 

Miscellania

+tool

Nino's +tool has a number of SAM related functionality

+tool sam info +tool sam info tagname +tool sam parse samtext +tool sam exec samtext

Test a client

How to test in a .sam page if a client is using ActiveX:

<if val="$(UDat.ActiveX)"><true>
   Your are running ActiveX.
</true></if>

Test if a user has chatmode enabled

<if val="$(UDat.ChatMode)"><true>
   You have chat mode enabled.
</true></if>

Output the chatmode char (if in chatmode)

If you are in chatmode $(UDat.ChatChar) will output the chat prefix character (typically a slash /) otherwise an empty string.

– Main.ChristopherAllen - 01 Aug 2001

Area below not part of system documen, but just for notes and such when we're putting the article together

Requirements:

• list requirements
• list requirements
• list requirements

References:

• Other systems that impacts XYZ

• Or systems the XYZ impacts

Put old text references here, between rulers.

More references

SAM Language Docs

SAM, short for Skotos Active Markup, is a language which can be used to produce dynamic text. Some textual abilities available in the Developer Interface such as [[DevDocs6OneOfs][One Ofs]] are actually syntactic sugar for underlying SAM code. SAM is primarily used within text descriptions entered into the Developer interface.

There are two types of markup in SAM, tags and references. The below lists provide information on each. They're very rough right now, without much explanation on how they work. This section of docs needs to be expanded out to make more sense.

Planned expansions: an introduction page, talking about what SAM is, why to use it, how to use it, etc; this page as a separate reference page; an example page showing SAM in real usage.

—+ SAM Tags Reference

#TagAcmd

<acmd>

Category: Text Formatting Description: Allows the client to have clickable text that sends a command to the server. Parameters:
tag: (optional) The theme that the this tag should use. (? What is the default used if no tag is specified?) cmd: (required) The command that should be sent to the server when the user clicks on it. The most common example of this is a parser command, say @help swords. When the user clicks on the highlighted text, the command "@help swords" is sent to the server. If echo is on in the client the user will see the command sent. Syntax: <acmd cmd="@help swords">click here to learn more about swords.</acmd>, <acmd tag="assist" cmd="verb">verb colored using assist theme</acmd>

#TagAddadj

<add-adj>

Category: Set Description: Add an adjective to an object detail. If the ‘obj' parameter is an object, by default the primary detail will be used, unless the ‘detail' parameter is used as well. Parameters: \

  <I>adjective</I>: The adjective to add.
  <I>detail&nbsp;(optional)</I>: The specific detail for which to add
                                 the adjective.  Only used if the 'obj'
                                 parameter isn't an NRef.
  <I>obj</I>: The object or NRef in which to add the adjective.

Example: \

Status: OBSOLETE – not to be used in any new objects Comments: To add an adjective to an object or detail, use the following inline Merry instead of the obsolete addadj tag:

To add an adjective $adj to NRef $what,

$[ Set($what, "detail:adjectives:" + $adj, TRUE); ]

To add an adjective $adj to detail $det on object $ob,

$[ Set($ob, "details:" + $det + ":adjectives:" + $adj, TRUE); ]

This duality between setting detail: on an NRef and details: on an object/detail pair works the same way for all these snippets and I will not explicitly repeat those variants below.

EXAMPLES REQUIRED

#TagAddname

<add-name>

Category: Set & query Description: Add a name to an object detail. If the ‘obj' parameter is an object, by default the primary detail will be used unless the ‘detail' parameter is used as well. Parameters: \

  <I>detail&nbsp;(optional)</I>: The specific detail for which to add
                                 the name.  Only used if the 'obj'
                                 parameter isn't an NRef.
  <I>name</I>: The name to add.
  <I>obj</I>: The object or NRef in which to add the name.
  <I>pname&nbsp;(optional)</I>: An optional plural-name to go along
                                with the (singular) name.

Example: \

Status: OBSOLETE – not to be used in any new objects Comments: To add an new name to an object or detail, use the following inline Merry instead of the obsolete addname tag:

To add a name $sname to NRef $what,

$[ Set($what, "detail:snames:" + $sname, TRUE); ]

To add a name $sname to detail $det on object $ob,

$[ Set($ob, "details:" + $det + ":snames:" + $sname, TRUE); ]

To add a name $sname with plural version $pname to NRef $what,

$[ Set($what, "detail:snames:" + $sname, $pname); ]

To add a name $sname with a plural version $pname to detail $det on object $ob,

$[ Set($ob, "details:" + $det + ":snames:" + $sname, $pname); ]

EXAMPLES REQUIRED

#TagAdjustproperty

<adjust-property>

Category: Set & query Description: Set the property in the given object to a new value. This differs from set-property in that it checks if the current property-value is an integer, in which case it will attempt to cast the new value to an integer as well. Parameters: \

  <I>prop</I>: The name of the property that needs to be changed.
  <I>val</I>: The new value for the property.
  <I>what</I>: The object in which to change the property.

Status: OBSOLETE – not to be used in any new objects Comments: To add to a numeric property in an object, you don't need this tag any more: use inline Merry instead.

To add 1 to property $prop on object $ob,

$[ Set($ob, $prop, Get($ob, $prop) + 1); ]

EXAMPLE REQUIRED

#TagAnd

<and>

Category: Flow control Description: Used as sub-tag for the <if> tag, to be able to build more complex conditions. Parameters: \

  <I>val</I>: The and-condition.

Examples:
The new AND and OR tags for SAM are now available on all servers (Marrach, S7, Welcome, and RPGnet) – this should make doing SAM tags much easier.

As an example, in a number of places in Marrach to currently do outside day and night descriptions (used in many of the outside views):

    
        
            
                
                   It is daytime.
                
                
                   It is nighttime.
                
            
        
        
            It is nighttime.
        
    

This can be confusing, and can be error prone, as you might add some more code and if statements in the first FALSE tag but forget to make identical changes to the second FALSE tag.

There is the same test done with the new AND tag:

    
        
            
                It is daytime.
            
            
                It is nighttime.
            
        
    

Or with the OR tag:

    
        
        
        
        
        
        
        
        
        
        
        
            
                It is daytime.
            
            
                It is nighttime.
            
        
        
        
        
        
        
        
        
        
        
        
    

Status: DATED Comments: Though and tags can be useful, using inline merry is now often a lot easier.

#TagAtag

<atag>

Category: Text Formatting Description: Sets the ‘theme' of the text, allowing it to be colored by the Client theme Parameters:
tag: The theme that the this tag should use. Syntax <atag tag="theme"> text tha you want themed </atag>

#TagBr

<br>

Category: Text formatting Description: Adds a newline to the output.

#TagCapitalize

<capitalize>

Category: Generic Description: Capitalizes the contents of the ‘what' parameter. Parameters:
what: That which needs to be capitalized. strip: If "1", strip the string before capitalizing it.

#TagCase

<case>

Category: Flow control Description: Depending on the value of the val parameter, the correct tag is picked from the contents of the tag and inserted into the output. Parameters: \ val: The value by which to select.

#TagConfigure-chatter

<configure-chatter>

This is associated with Theatres. The configure-chatter samtag works in conjuction with the Theatre-specific start-story stuff with the SSNuggets and whatnot… it sets all the properties given in the Edit form, and then calls descsub in the body. It's a nasty nasty hack – we really shouldn't have LPC calling Bilbo – Main.ParWinzell - 18 March 2003

#TagCreate-chatter

<create-chatter>

This is associated with Theatres. The create-chatter tag is -the- way to create a body for a player on a theatre. It sets all the relevant theatre values, sets the name to the right Chatters: directory, sets the gender, registers the body centrally so that pages work, sets the linkdeath room, etc. It cannot currently be duplicated in Merry – there's some calls that are not exported to that development layer. Yet. – Main.ParWinzell - 18 March 2003

#TagDescribe

<describe>

Category: Generic Description: Describe an object. Parameters: \

  <I>actor&nbsp;(optional)</I>: The acting party.
  <I>cap&nbsp;(optional)</I>: Whether to capitalize the resulting
                              output or not.
  <I>looker&nbsp;(optional)</I>: From whose perspective to describe the
                                 item.
  <I>lookers&nbsp;(optional)</I>: If 'looker' isn't used, the first
                                  entry from 'lookers' is used instead.
  <I>nonposs&nbsp;(optional)</I>: Adjust the style in which the
                                  description is written.
  <I>what</I>: The item you want to describe.
  <I>detail&nbsp;(optional)</I>: The detail of the item you want to describe.

Syntax<describe what="$(object)" looker="$(object)" cap/> Comments: \

• If the detail is not defined, it will describe the default detail. looker is optional, but is highly suggested that it is set and set to be the actor.

#TagDescribemany

<describemany>

Category: Generic Description: Describe a collection of objects. Parameters: \

  <I>actor&nbsp;(optional)</I>: The acting party.
  <I>cap&nbsp;(optional)</I>: Whether to capitalize the resulting
                              output or not.
  <I>looker&nbsp;(optional)</I>: From whose perspective to describe the
                                 item(s).
  <I>lookers&nbsp;(optional)</I>: If 'looker' isn't used, the first
                                  entry from 'lookers' is used instead.
  <I>style&nbsp;(optional)</I>: Adjust the style in which the
                                description is written.  Default is
                                'STYLE_NONPOSS'.
  <I>what</I>: The item(s) you want to describe.

Syntax: <describemany what="$(object)" lookers="$(arrayofobject)" looker="$(object)" cap/< Examples: \

• This tag is typically used in descriptions where you wish to show the contents of item even if the item is closed (say behind glass doors), or of a room that is on the other side of a window. For example:

Behind the glass doors you can see .

#TagDescribeprep

<describeprep>

Category: Generic Description: Describe the current proximity preposition of an object, i.e. against, before, behind, beside, close, inside, near, on, over, under, Parameters: \

  <I>cap&nbsp;(optional)</I>: Whether to capitalize the resulting
                              output or not.
  <I>what</I>: The object whose preposition you want.

Syntax: <describeprep what="$(object)" cap/<

Category: Generic Description:

#TagDescribe-Holder

<describe-holder>

If $what is an object held by some person named "Bubba", then this tag will output "Bubba's". It can imagine it used like this:

  <I>cap&nbsp;(optional)</I>: Whether to capitalize the resulting
                              output.
  <I>def&nbsp;(optional)</I>: Whether to describe it in a definite way
                              or not.
  <I>this</I>: The object in which you want to query the property.
  <I>what</I>: The name of the property.

  <b>describe-prop</b>

  <I>cap&nbsp;(optional)</I>: Whether to capitalize the resulting
                              output.
  <I>noun&nbsp;(optional)</I>: A noun to append after the properties and potentially a/an, 
                               if none of the defined properties are set.
  <I>delim&nbsp;(optional)</I>: Defaults to " "; if set, this is used to delimit properties.
  <strike><I>def&nbsp;(optional)</I>: Whether to describe it in a definite way
                              or not.</strike>
  <I>which</I>: The list of properties, space-separated (e.g. "trait:color trait:material")

  <b>describe-props</b>

       <I>what</I>: The NREF you wish hidden.

  <I>cap&nbsp;(optional)</I>: Capitalize the resulting output.
  <I>what</I>: The object that you want to describe.

       <I>what</I>: The NREF you wish hidden.

  <I>detail&nbsp;(optional)</I>: The detail for which you want to get
                                 the description.  Only used if the
                                 'obj' parameter isn't an NRef.
  <I>obj</I>: The object or NRef from which to get the description.
  <I>type</I>: The type of description that you want to get.

  <I>index</I>: The index value.
  <I>map</I>: The name of the mapping variable.
  <I>to</I>: The value to be associated with the index.

  <I>cap&nbsp;(optional)</I>: Whether to capitalize the resulting
                              output or not.
  <I>what</I>: The item(s) for which you want to get an objective
               pronoun.

   Look: [*
      React-post:squeeze-dob: [
        After you squeeze $(this.base:objective), you get the odd feeling that it doesn't like being squeezed tightly.
   *]

   > squeeze toy
   You squeeze a toy.
   After you squeeze it, you get the odd feeling that it doesn't like being squeezed tightly.

   
      
         feline
      
      
         catlike
      
   

   An empty beer {mug|vessel} {disappears|evaporates|dissolves|dissipates} into
   {a soft mist|a mist|a misty vapor|mist}.

   An empty beer {mug|vessel} {disappears|evaporates|dissolves|dissipates} into
   {a soft {mist|cloud|vapor}|a mist|a misty vapor|mist}.

   
    
     feline
    
    
     catlike
    
   

  <I>val</I>: The or-condition. Sometimes you'll want to create more complex If statements. You might want to output text if one of two things is true. For example, you might create a sign written in the magical language, and allow people to read it if they are magicians or if they know the magical language. Alternatively, you might want to output only if two or more things are all true.

   
      
         
            
               foo and bar
            
         
      
   

  <I>cap&nbsp;(optional)</I>: Whether to capitalize the resulting
                              output or not.
  <I>what</I>: The item(s) for which want to get the possessive
               pronoun.

   Look: [*
     A small embroidered flower is on the lapel of $(this.base:possessive) suit.
   *]

   > look at toy's flower
   A small embroidered flower is on the lapel of its suit.

  <I>cap&nbsp;(optional)</I>: Whether to capitalize the resulting
                              output or not.
  <I>what</I>: The item(s) for which you want to get a pronoun.

   Examine: [*
     A cute little toy, shaped like a hobbit. $(this.base:pronoun) is wearing a
     tuxedo with a embroidered flower on its lapel. On the toy's back is a ring
     with a string on it.
   *]

   > examine toy
   You begin to examine a toy.
   A cute little toy, shaped like a hobbit. it is wearing a tuxedo with a
   embroidered flower on its lapel. On the toy's back is a ring with a string on
   it.
   >

$[ Set($what, "detail:descriptions:" + $type, $desc); ]

   Glance: [*
      The tailors' storage room, a long, narrow space for storing and dispensing
      clothing. {? | $(actor.marrach:tailortip) ||

[TIP: The tailor
      makes clothing. Type "ask tailor" to get a list of clothing. Type "ask
      tailor for tunic" to get that specific piece of clothing. Type "help
      tailor" for more information.]}
   *]

   React-post:hug-dob: [*
     After you hug the toy, you get the odd feeling that you are loved back in return. $[Set($actor, "examples:sam-hug", 1);]
   *]

   > +stat me "property:examples*
   -- Properties (examples*)--
   > hug sam
   You hug a toy.
   After you hug the toy, you get the odd feeling that you are loved back in
   return.
   > +stat me "property:example*
   -- Properties (example*)--
   Property: examples:sam-hug = 1
   >

   React-desc:sense/smell-dob: [*
     You $(verb)  and sneeze.
   *]
   React3-desc:sense/smell-dob: [*
        and sneezes.
   *]

   > sniff sam's lapel
   You sniff the a lapel flower and sneeze.
   > smell sam's lapel
   You smell the a lapel flower and sneeze.
   > +force cat "sniff sam's lapel
   Forcing a cat to: sniff sam's lapel
   A cat sniffs the a lapel flower and sneezes.
   > +force cat "smell sam's lapel
   Forcing a cat to: sniff sam's lapel
   A cat sniffs the a lapel flower and sneezes.

   $[
      object *obs;

      /* find out which verb objects match $verb */
      obs = Get(${SkotOS:Socials:Socials}, "verbs:" + $verb);

      if (!obs || !sizeof(obs)) {
         error("no verbs found for: " + $verb);
      }
      return obs[0]."verb:second";
   ]

   $[ dump_value($val) ]

   
    
    
    
      $[ $actor."trait:nickname" = $nickname; ]
      
    
   

./usr/DevSys/samtags:
escape-attribute.c
escape-html.c

./usr/HTTP/samtags:
redirect.c

./usr/SAM/samtags:
and.c
br.c
capitalize.c
case.c
comment.c
dump.c
false.c
for.c
if.c
index.c
insert.c
mapset.c
oneof.c
or.c
p.c
quote.c
sbr.c
signal.c
spc2.c
spc3.c
spc4.c
spc5.c
spc6.c
spc7.c
spc8.c
tab.c
to.c
true.c
z.c
zact.c
zbitmap.c
zform.c
zlink.c

./usr/SkotOS/samtags:
acmd.c

atag.c
describe-holder.c
describe-poss.c
describe-prop.c
describe-view.c
describe.c
describemany.c
describeprep.c
eaten.c
obsprep.c
rename-body.c
unregister-body.c

add-adj.c               OBSOLETE: not to be used in any new objects
add-name.c              OBSOLETE: not to be used in any new objects
adjust-property.c       OBSOLETE: not to be used in any new objects
disable-detail.c        OBSOLETE: not to be used in any new objects
enable-detail.c         OBSOLETE: not to be used in any new objects
get-desc.c              OBSOLETE: not to be used in any new objects
objective.c             OBSOLETE: not to be used in any new objects
possessive.c            OBSOLETE: not to be used in any new objects
pronoun.c               OBSOLETE: not to be used in any new objects
rem-adj.c               OBSOLETE: not to be used in any new objects
rem-name.c              OBSOLETE: not to be used in any new objects
set-desc.c              OBSOLETE: not to be used in any new objects
set-property.c          OBSOLETE: not to be used in any new objects
social.c                OBSOLETE: not to be used in any new objects
xdebug.c                OBSOLETE: not to be used in any new objects

./usr/Theatre/samtags:
configure-chatter.c     Will soon be replaced by inline Merry.
create-chatter.c        Used to create a new body & link it to user

                  the brief of $(this)
          Capitalized version of the brief

                   he/she/it
           He/She/It

                 him/her/it
         Him/Her/It

                his/her/its
        His/Her/Its

    Describe($actor) = the brief of $actor; ex: a horse
    capitalize(Describe($actor)) = Capitalized version of the brief, ex: A horse
    $actor."base:nominative" = he/she/it
    capitalize($actor."base:nominative") = He/She/It
    $actor:"base:objective" = him/her/it
    capitalize($actor."base:nominative") = Him/Her/It
    $actor:"base:possessive" = his/her/its
    capitalize($actor:"base:possessive") = His/Her/Its