Phantasmal Site > DGD > Skotos > Quick SAM Summary

Quick Summary of the Skotos SAM System

SAM (Skotos Active Markup) allows text in descriptions (see Quick Summary: Description System) to be dynamic.

OneOf

The simplest SAM is the OneOf -- basically using a OneOf in your text allows you to randomize the output.

   Look: [
      You are inside {a large|an oversize|a} tent.
   ]
   Output(s):
      > look at tent
      You are inside a large tent.
      > look at tent
      You are inside an oversize tent
      > look at tent
      You are inside a tent.
      >

Output a Property

You can also output the value of a property very easily.

   Look: [
      The gem is $(this.gemcolor).
   ]
   Output(s):
      > look at gem
      The gem is blue.
      > +setp gem "gemcolor green
      Setting 'gemcolor' in <[Examples:complete:sam:gem]#4544> to "green".
      > look at gem
      The gem is green.
      >

In the above example, $(this) refers to the object itself, the gem itself. $(this.gemcolor) refers to the value of the property "gemcolor" inside the gem.

Arguments

$(this) is only one of many 'arguments' that SAM knows about that is different depending on the circumstance that the SAM is executed.

In almost every situation, the following arguments are available:

• $(actor) – The object executing the action, e.g. whomever is taking the sword
• $(action) – The name of the action currently executing, e.g. take
• $(this) – The object containing the SAM itself, e.g. the sword
• $(target) – The detail of the object that is the target of the action.

In addition, in many situations, the following additional arguments are available:

• $(verb) – The verb used in the action, e.g. 'polish' in "polish the sword with my cloth"
• $(dob) – The object that is the direct object of the action, e.g. the sword
• $(using) – the object that is the indirect object of the action, e.g. the cloth

References

In addition to arguments, you can also reference specific objects.

• $(Full:Woe:Name) – the object with the woe name "Full:Woe:Name"
• $[${Full:Woe:Name}] – the object that is currently named "Full:Woe:Name", and if the object is renamed, the reference will change with it.

Property References

Once you have object defined, either by argument $this or by reference $(Full:Woe:Name) or $[${Full:Woe:Name}], you can directly output the value of 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}]

Some commonly used properties that output text:

• $(this.base:possessive) – possessive pronoun e.g. 'his'
• $(this.base:objective) – objective pronoun e.g. 'him'
• $(this.base:pronoun) – basic pronoun e.g. 'he'
• $(this.base:light-category) – object's luminosity, e.g. "dark", "dim", or "bright"
• $(this.details:default:description:brief) – object's default brief description

Examples of use:

   Look: [
      $(this.base:pronoun) looks very fierce. A scar runs from
$(this.base:possessive) cheek to $(this.base:possessive) chin, which doesn't
seem to bother $(this.base:objective).
   ]
   Output:
      > look at warrior
      She looks very fierce. A scar runs from her cheek to her chin, which
doesn't seem to bother her.
      >

   Look: [
      You are in a $(this.base:light-category) room.
   ]
   Output:
      > look
      You are in a dim room.
      >

Some property references don't output text, but instead refer to other objects:

• $(this.base:environment) – object's environment
• $(this.base:worn-by) – object's wearer (same as wielded-by)
• $(this.base:wielded-by – object's wielder (same as worn-by)

These are not that useful to use directly, but in turn you can then use properties with these:

• $(this.base:environment.base:possessive) – object's environment possessive pronoun
• $(this.base:worn-by.base:pronoun) – object's wearer's basic pronoun

Details of objects can be output:

• $("this.details:default:descriptions:look") – the prime detail's look description
• $("this.details:lamp:descriptions:brief") – the lamp detail's brief description

Some detail IDs have spaces in them. The way to refer to a SAM reference with a space in it is to put it in quotes – e.g.

• $("this.details:exit west:descriptions:look") – the look description of exit west

rather than

• $(room.details:exit west:descriptions:look) – won't work

XHTML Tags

There are some XHTML formatting tags that can be useful are are available in SAM

• <br/> – a line break, a single newline
• <sbr> – single break, inserts <br/> when used in a webpage, or a newline when used elsewhere.
• <p/> – a paragraph break, two newlines
• <pre>text</pre> – will output the text in a monospace font, without formatting

Common Sam Tags

There are various times when you need specific output that is not easily available in a property, or the property is in the wrong form. These SAM tags can be useful in these cases:

These are Sam Tags for describing things:

• <describe what="$(this)"/> – This will output the brief of $(this) object, e.g. "a sword"
• <describemany what="$(this.base:inventory)"/> – Describe many will output multiple briefs, as if in an inventory, of the objects in $(this.base:inventory).
• <describe-holder what="$(this)"/> – Equivalent to <describe what="$(foo.base:holder)"/>'s except when the person's name ends in 's' or 'x' in which case it does the right thing and just adds the apostrophe without a trailing s.
• <describe-poss what="$(this)"> – Describes $(this) in the possessive form, e.g. "his sword"
• <describe-prop this="$(this)" what="property:name"/> – Adds "a" "the" "an" to the text of the property appropriately.
• *<describe-view view="$(this)" cap/> – Will give the full description of the object, including any visible inventory. e.g. "A tall orc, weilding his sword."
• <capitalize what="lower"> – will initial capitalize the text "lower" into "Lower"
• <eaten what="$(this)"/> – will output how much of the item has been consumed.

Most of these description Sam Tags have a variety of options, see SamSystem for details, but one of the most useful ones is the 'cap' option, which will capitalize the output. For instance:

• <describe what="$(this)"/> – This will output the brief of $(this) object, e.g. "A sword"

Client Sam

The following SAM tags are useful for special features in the Alice and Zealous clients:

• <atag tag="command"> text that you want themed with the color in the 'command' theme </atag>
• <acmd tag="command" cmd="open west door">click here to open the west door.</acmd>

Simple If Comparison

A simple if statement allows you to output one text if something is true, a different text if false.

   Look: [
      A statue of a man. The statue's face {? this.trait:expression |appears
to be $(this.trait:expression) at you. |is expressionless. }
   ]
   Result(s):
      > look at statue
      A statue of a man. The statue's face is expressionless.
      > +setp statue "trait:expression smiling
      Setting 'trait:expression' in <[Examples:complete:sam:statue]#4586> to
"smiling".
      > look at statue
      A statue of a man. The statue's face appears to be smiling at you.
      >

In this example, if the property trait:expression doesn't exist (i.e. false), then "is expressionless" is output. If it does exist (true) then it is "appears to be smiling at you" will be output.

Other Comparisons

There are quite a few kinds of comparisons you can do in SAM:

BOOLEAN

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

    {? not | $this.trait:variant |
        true text output |
        false text output }
    {? 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 }
    
    Comment: range is exclusive, i.e. 
         {? range | 1 | 3 | 6 | true | false }"
            1   false
            2   false
            3   false
            3.1 true
            4   true
            5   true
            6   true
            6.1 false
            7   false
            8   false
            9   false


    {? 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 }

Inline Merry

You can put Merry scripts inside of of SAM as follows:

   Look: [
      You are on a road. There are $[this.stars_in_sky + this.moons_in_sky]
celestial bodies above you.
   ]

If the piece of Merry does not end in a semi-colon or a right-brace, it is assumed to be a 'statement' rather than an 'expression'. This means the code needs to explicitly return a value. For example,

   You are on a road. There are
     $[
         if (this.stars_in_sky > 5) {
             return "lots of";
         }
         if (this.stars_in_sky > 0) {
             return "a few";
         }
         return "no";
      ]
   stars in the sky.

Inline Merry and Text

It can often be useful in SAM to manipulate text, so there are some very simple inline Merry functions that can perform this for you.

Text related:

• $[capitalize("this is a test")] – result: "This is a test"
• $[proper("This is a test")] – result: "This Is A Test"
• $[decapitalize("This Is A Test")] – result: "this Is A Test"
• $[upper_case("This Is A Test")] – result: "THIS IS A TEST"
• $[lower_case("this Is A Test")] – result: "this is a test"

Number related:

• $[desc_cardinal(128)] – result: "one hundred twenty-eight"
• $[desc_ordinal(128)] – result: "one hundred twenty-eighth"
• $[comma(1024)] – result: "1,024"

Inline Merry and Comparisons

You can combine arbitrary Merry expressions for tests to use in comparisons, to make very sophisticated output. For example:

    {? | $[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. }

These can be quite sophisticated, for instance:

    {? | $[sizeof(Match($actor, "cigarette"))] |
    Actor has a cigarette. | Actor doesn't have cigarette. }
       Actor has a cigarette.
       Actor doesn't have a cigarette

Common Inline Merry Uses

There are many things you can do in SAM by using inline Merry, but these are some of the most common:

• $[Set($this, "my:property:name", 1);] – Sets the property my:property:name in object $this to 1.
• $[Set($this, "my:property:name", Get($this, "my:property:name) + 1); ] – Adds 1 to property my:property:name on object $this

You look at <describe what=$(this)> and your surroundings change!
   $[      EmitIn(Get($actor, "base:environment"), Describe($actor) + "
looks at " + Describe($dbob) + " and disappears!\n", $actor);
         $actor."base:environment" =
${Examples:complete:desc:room-go-nowhere};
         $actor."base:proximity" =
NewNRef(${Examples:complete:desc:room-go-nowhere}, "floor");
         $actor."base:stancestring" = "lying";
         $actor."base:prepositionstring" = "on";
         EmitIn(Get($actor, "base:environment"), Describe($actor) + "
appears out of nowhere lying on the floor!\n", $actor);
   ]