Writing:Reference Section

Property types

 * Text
 * A block of text which is interpreted “wiki-style” – square brackets indicate special behavior.


 * Code
 * A block of text which is interpreted as Python (actually TworldPy) code.


 * Code (args)
 * Same as, but with an extra field for arguments. These are treated as formal parameters. A code property with arguments   is like a function defined   You can also specify default values:.


 * GenText
 * A structure used for procedural text generation.


 * Move
 * A special property which moves the player to another location (in the same world).


 * Event
 * A special property which sends a message to the player’s event pane (and possibly to other players in the same location).


 * Panic
 * A special property which throws the player out of the world. May optionally send an event message to the player and/or to nearby players.


 * EditStr
 * A special property which allows the player to edit a text property in the location. The first field must be the name of a string value (or text) property (which acts as a default value). When edited, an instance property is written with a new string value.
 * The label is displayed above the edit field. The two messages at the end appear to the editing player, and nearby players, when a change occurs. By default only players with  access may edit this field, but you may set access to   (everybody) or a higher level.


 * DateTime
 * Interpreted as a Python . The value must look like “YYYY-MM-DD” or “YYYY-MM-DD HH:MM:SS” or “YYYY-MM-DD HH:MM:SS.UUUUUU” (the last field is microseconds). It is always interpreted in UTC (not your local time zone). Leave the field blank to get a timestamp of right now.


 * Value
 * Interpreted as a Python native value.


 * (Delete)
 * Selecting this and confirming will delete the property entirely.

Python native values can be any of:


 * Integers or floating-point numbers
 * Quoted strings (single or double quotes are okay, but not curly quotes)
 * , : Booleans (must be capitalized)
 * : Python null value (must be capitalized)
 * : A list (array) of Python values in square brackets
 * : A dictionary (hash) written in curly braces. The keys must be strings; the values can be any Python values.

Caveats:


 * Python tuples are accepted but stored as lists. (So  will be stored as  .)
 * Python set literals  are rejected.
 * Python bytes objects  are accepted, but are probably not good for anything.
 * Integers are limited to 64 bits. (Values much beyond  cannot be stored.) (Float values have a much wider range, but less precision.)
 * Python  objects must be entered with the   property type, not with.
 * Python  objects cannot currently be entered in the build interface.

"The special property types (,, etc) are actually represented in the property database as Python dictionaries. For example, a  value “Foo.” is really   You will probably never need to know this, but if you do, the formats are defined here."

Text formatting and substitutions
Text is converted to HTML, so whitespace is generally not significant. Extra spaces, indentation, and single newlines are collapsed into single spaces. (Double newlines are taken as true paragraph breaks.)

All text, except when in square brackets, is displayed directly. You may freely enter Unicode characters as-is; you don’t have to escape them or use HTML character constants.

We’ve seen several different syntaxes for square-bracket substitutions in text.

Here’s the complete list. It can be broken down into three major groups:,  , and   codes.


 * The  cases, with the dollar signs, are not hyperlinks; they mostly interpolate text. You might therefore expect them to be written  . In fact that will work, but we also accept the single-square-bracket form – it’s easier to type.

Hyperlinks

 * Displays a hyperlink “prop”, which invokes the  property. If that’s , it is displayed as a close-up pop-up. If it’s  , it’s executed.  ,  , etc properties take effect as defined.   properties are displayed as events (to the player only).
 * Displays a hyperlink “prop”, which invokes the  property. If that’s , it is displayed as a close-up pop-up. If it’s  , it’s executed.  ,  , etc properties take effect as defined.   properties are displayed as events (to the player only).


 * A hyperlink; the contents are sluggified, then invokes a property as above. This example would display as “Text in brackets,” but invoke a property named.
 * A hyperlink; the contents are sluggified, then invokes a property as above. This example would display as “Text in brackets,” but invoke a property named.


 * A hyperlink that displays “single” but invokes the property named.
 * A hyperlink that displays “single” but invokes the property named.


 * A hyperlink that displays “single bar”, and executes the given line of code.
 * This is really the same as the previous case.  as a code statement means “invoke the property named  .”
 * This is really the same as the previous case.  as a code statement means “invoke the property named  .”


 * A hyperlink that displays “single bar” and opens an external web page (in a new browser window). The URL after the bar must begin with  to be recognized this way.
 * A hyperlink that displays “single bar” and opens an external web page (in a new browser window). The URL after the bar must begin with  to be recognized this way.


 * A hyperlink that displays “with double bar” and invokes the property named.
 * A hyperlink that displays “with double bar” and invokes the property named.


 * A hyperlink that displays “with double bar words” and invokes the property named . The text after the double bar is sluggified, so it may not contain arbitrary code.
 * A hyperlink that displays “with double bar words” and invokes the property named . The text after the double bar is sluggified, so it may not contain arbitrary code.

Interpolations

 * Evaluates the  symbol and inserts the result in-line. This is not a hyperlink.
 * Evaluates the  symbol and inserts the result in-line. This is not a hyperlink.


 * Executes the line of code and inserts the result in-line. The code doesn’t have to be a function call; it could be an expression, such as . However, it may not be an assignment (a property change).
 * Executes the line of code and inserts the result in-line. The code doesn’t have to be a function call; it could be an expression, such as . However, it may not be an assignment (a property change).


 * Displays  as the text of a hyperlink which invokes.
 * This nests an interpolation inside a hyperlink. You may not nest a hyperlink inside a hyperlink!
 * This nests an interpolation inside a hyperlink. You may not nest a hyperlink inside a hyperlink!

Substitutions

 * A paragraph break. This is the same as putting a blank line (two line-breaks) in the text.
 * A paragraph break. This is the same as putting a blank line (two line-breaks) in the text.


 * Literal square brackets.
 * Literal square brackets.


 * The name of the acting player.
 * The name of the acting player.


 * One of “he”, “she”, “it”, “they”, as appropriate for the acting player.
 * One of “he”, “she”, “it”, “they”, as appropriate for the acting player.


 * One of “him”, “her”, “it”, “them”.
 * One of “him”, “her”, “it”, “them”.


 * One of “his”, “her”, “its”, “their”.
 * One of “his”, “her”, “its”, “their”.


 * One of “his”, “hers”, “its”, “theirs”.
 * One of “his”, “hers”, “its”, “theirs”.


 * One of “himself”, “herself”, “itself”, “themself”.
 * One of “himself”, “herself”, “itself”, “themself”.


 * The pronouns are available in capital forms:  for “He”, “She”, “It”, etc.
 * You can use  or   to refer to the name or pronoun of a given player object. Currently there is no easy way to get any player object other than the acting player, so this is not interesting.
 * Why not also accept,  ,  , etc? First, it would be a lot of pronoun variants. Second, the male and female pronouns are ambiguous! Notice that “his” appears in two of the above lists. If you put   in your code, the system would not be able to figure out whether you meant   or  . “Her” also appears in two lists, but not the same lists. English is wacky.

Formatting

 * Emphasized text (italics).
 * Emphasized text (italics).


 * Fixed-width text (monospace font).
 * Fixed-width text (monospace font).


 * D’ni font. Notice that this is handled with double square brackets and function calls, rather than a dollar-sign notation. Sorry about the ugliness.
 * D’ni font. Notice that this is handled with double square brackets and function calls, rather than a dollar-sign notation. Sorry about the ugliness.


 * These style tags may be nested. However, if you screw up the nesting or fail to close a tag, you'll see an error message when Seltani tries to print your text.

Conditional statements

 * Displays the text if the  expression is true. Otherwise, displays nothing. A Python expression is considered false if it is ,  , zero, the empty string, the empty list, or the empty dictionary. Anything else is considered true.
 * Displays the text if the  expression is true. Otherwise, displays nothing. A Python expression is considered false if it is ,  , zero, the empty string, the empty list, or the empty dictionary. Anything else is considered true.


 * A property-not-found error in an  expression is also considered false.


 * If the expression is true, display ; otherwise, display.
 * If the expression is true, display ; otherwise, display.


 * The same, with an if... else-if... else chain.
 * The same, with an if... else-if... else chain.

global (top-level) symbols

 * The underscore always refers to the namespace of built-in functions, as described in this section. This can be useful if a property has shadowed one of these functions. For example, if you defined a location property named, it would replace the   function in that location. But you could still refer to.
 * The underscore always refers to the namespace of built-in functions, as described in this section. This can be useful if a property has shadowed one of these functions. For example, if you defined a location property named, it would replace the   function in that location. But you could still refer to.

"If you are silly enough to define a property called, it will be ignored. The global  cannot be replaced."


 * The length of a list, or the length of a string, or the number of entries in a dict.
 * The length of a list, or the length of a string, or the number of entries in a dict.


 * Return the smallest or greatest of a list or bunch of arguments.
 * Return the smallest or greatest of a list or bunch of arguments.
 * Return the smallest or greatest of a list or bunch of arguments.


 * Standard Python type constructors.
 * Standard Python type constructors.


 * Convert a Python string into a chunk of wiki-style text.
 * Convert a Python string into a chunk of wiki-style text.

"Square-bracket interpolations in the text are not performed immediately; they will be performed when the text is displayed."


 * Convert a Python string into a code object. The optional  specify parameters to be passed in to the code.
 * If the code object appears on a line by itself, it is executed immediately. In an expression, it is executed when written as a function call in the usual way (followed by arguments in parentheses).
 * If the code object appears on a line by itself, it is executed immediately. In an expression, it is executed when written as a function call in the usual way (followed by arguments in parentheses).


 * Find the database key for a player or location. If obj is not given, this generates a new unique database key (but does not store it in the database). If obj is a string with the correct form (a 24-character hex string), this generates a database key with that value.
 * Find the database key for a player or location. If obj is not given, this generates a new unique database key (but does not store it in the database). If obj is a string with the correct form (a 24-character hex string), this generates a database key with that value.


 * Test whether the object is an instance of the given type.
 * Test whether the object is an instance of the given type.


 * Return a Python dictionary that reflects the current set of local variables. (Not properties or builtins.) This dict is “live”; modifying it affects the locals in the environment.
 * Return a Python dictionary that reflects the current set of local variables. (Not properties or builtins.) This dict is “live”; modifying it affects the locals in the environment.


 * Begin or end a style span with a named style. Currently only supports three values:  (same as  ),   (same as  ), and.
 * Begin or end a style span with a named style. Currently only supports three values:  (same as  ),   (same as  ), and.


 * Print a paragraph break. This is equivalent to the  interpolation in a   property.
 * Print a paragraph break. This is equivalent to the  interpolation in a   property.


 * Print a string. A  call in a   property is generally equivalent to putting plain text in a   property.
 * You may include several arguments; they will be displayed with spaces between them.
 * If the argument is, it will be interpolated according to the usual rules. For example,   generates a paragraph break.
 * If the argument is, it will be interpolated according to the usual rules. For example,   generates a paragraph break.


 * Display a message in the event pane of the acting player, and (optionally) other players in the same location.
 * Display a message in the event pane of the acting player, and (optionally) other players in the same location.
 * Display a message in the event pane of the acting player, and (optionally) other players in the same location.

"If the message contains square-bracket tokens, remember to wrap it in."


 * Display a message in the the event pane of the given player, and (optionally) other players in the same location. The given player must be in the current instance.
 * Display a message in the the event pane of the given player, and (optionally) other players in the same location. The given player must be in the current instance.


 * Display a message to everybody in the given location. This may be given as a location reference or a short name string . If you pass   as the first argument, the message will go to every player in the instance.
 * Display a message to everybody in the given location. This may be given as a location reference or a short name string . If you pass   as the first argument, the message will go to every player in the instance.


 * Move the acting player to a location. This may be given as a location reference or a short name string . The optional other arguments are event messages for the moving player, other players in the start room, and other players in the destination room.
 * Move the acting player to a location. This may be given as a location reference or a short name string . The optional other arguments are event messages for the moving player, other players in the start room, and other players in the destination room.
 * Move the acting player to a location. This may be given as a location reference or a short name string . The optional other arguments are event messages for the moving player, other players in the start room, and other players in the destination room.


 * The acting player. This can be used to get or set player properties; e.g.,.
 * The acting player. This can be used to get or set player properties; e.g.,.


 * The acting player’s location.
 * The acting player’s location.


 * The location with the given database key (an ObjectId).
 * The location with the given database key (an ObjectId).


 * The location with the given short name.
 * The location with the given short name.


 * The location of the given player.
 * The location of the given player.


 * The location with the given short name. Same as, but you don’t use the parentheses or quotes.
 * The location with the given short name. Same as, but you don’t use the parentheses or quotes.


 * A reference which can be used to get or set realm-level (instance) properties; e.g.,.
 * A reference which can be used to get or set realm-level (instance) properties; e.g.,.


 * The location (in this world) which the player was in before moving here. If the player arrived in this location by linking,  is.
 * The location (in this world) which the player was in before moving here. If the player arrived in this location by linking,  is.

"You might use to display a description conditionally as “Halfway up the stairs” or “Halfway down the stairs.”"


 * Set the current player’s focus to the given string. This must name a text or code property:, not.
 * Set the current player’s focus to the given string. This must name a text or code property:, not.


 * Set a given player’s focus, or the focus of every player in a location. If the  argument is , this sets the focus of every player in the current instance.
 * Set a given player’s focus, or the focus of every player in a location. If the  argument is , this sets the focus of every player in the current instance.
 * Set a given player’s focus, or the focus of every player in a location. If the  argument is , this sets the focus of every player in the current instance.

"The focus property must be accessible in the player’s location. So if you use the form, you’ll have to make sure the property is available realm-wide."


 * Clear the current player’s focus (if set).
 * Clear the current player’s focus (if set).


 * Clear the current player’s focus, but only if it’s currently set to the given (named) property.
 * Clear the current player’s focus, but only if it’s currently set to the given (named) property.


 * Clear the focus of the given player, or all players in a location, or all players in the instance.
 * Clear the focus of the given player, or all players in a location, or all players in the instance.
 * Clear the focus of the given player, or all players in a location, or all players in the instance.


 * Clear the focus of the given players, but only those whose focus is currently set to the given (named) property.
 * Clear the focus of the given players, but only those whose focus is currently set to the given (named) property.
 * Clear the focus of the given players, but only those whose focus is currently set to the given (named) property.


 * Schedule the given function to be called after a delay. The delay argument is the number of seconds, or a  value. The func argument must be a function or   property.
 * If the (optional) repeat argument is, the function will be called repeatedly, every N seconds, until the instance is abandoned.
 * If the (optional) cancel argument is given, the timer can be cancelled later by the  function.
 * If the (optional) cancel argument is given, the timer can be cancelled later by the  function.

"See the warning in “Timers” about scheduled code."


 * Cancel all upcoming events for this instance, if they were launched with the same cancel argument. If you call  with no arguments, all upcoming events for the instance are cancelled.
 * Cancel all upcoming events for this instance, if they were launched with the same cancel argument. If you call  with no arguments, all upcoming events for the instance are cancelled.

access module

 * Access level constants. These are integers, so they can be compared with  and.
 * Access level constants. These are integers, so they can be compared with  and.


 * Return the access level of the acting player to the current instance. The current implementation says that a player has  access to his personal instances, and to the global instance of a world he created. All other cases return.
 * (Planned feature: a way to give your friends access to your personal scope.)
 * (Planned feature: once group scopes are in, you will be able to give people various levels of access to the group.)
 * (Planned feature: once group scopes are in, you will be able to give people various levels of access to the group.)


 * Returns True if the player’s access level to the current instance is at least.
 * Returns True if the player’s access level to the current instance is at least.

players module

 * Returns the player object for the acting player, or the player with the given database key (an ObjectId). If the argument is a player object, this returns it unchanged.
 * Returns the player object for the acting player, or the player with the given database key (an ObjectId). If the argument is a player object, this returns it unchanged.
 * Returns the player object for the acting player, or the player with the given database key (an ObjectId). If the argument is a player object, this returns it unchanged.


 * Returns the name of the acting player, or the given player, as a string.
 * Returns the name of the acting player, or the given player, as a string.
 * Returns the name of the acting player, or the given player, as a string.


 * Returns the preferred pronoun of the acting player, or the given player. This will be one of the strings.
 * Returns the preferred pronoun of the acting player, or the given player. This will be one of the strings.
 * Returns the preferred pronoun of the acting player, or the given player. This will be one of the strings.


 * Same as.
 * Same as.
 * Same as.


 * Returns  if the acting/given player is in this instance.
 * Returns  if the acting/given player is in this instance.
 * Returns  if the acting/given player is in this instance.


 * Returns the focus of the acting/given player. This is normally a string (the name of a text property, if the player has it as a close-up window) or  (if the player has no close-up window). However, there are special cases where this will return a list. (When the focus is another player, a linking book, a bookshelf, etc.)
 * Returns the focus of the acting/given player. This is normally a string (the name of a text property, if the player has it as a close-up window) or  (if the player has no close-up window). However, there are special cases where this will return a list. (When the focus is another player, a linking book, a bookshelf, etc.)
 * Returns the focus of the acting/given player. This is normally a string (the name of a text property, if the player has it as a close-up window) or  (if the player has no close-up window). However, there are special cases where this will return a list. (When the focus is another player, a linking book, a bookshelf, etc.)


 * Returns the number of players in the given location. If  is , it’s the number of players in the entire instance.
 * Returns the number of players in the given location. If  is , it’s the number of players in the entire instance.


 * Returns a list of players in the given location. If  is , it’s the players in the entire instance.
 * Returns a list of players in the given location. If  is , it’s the players in the entire instance.

gentext module

 * Convert a Python string into a gentext data structure.
 * Convert a Python string into a gentext data structure.


 * Display a symbol (text, gentext, or code) with different printing parameters. The  flag (  or  ) controls auto-spacing and auto-capitalization. The   parameter controls the pseudo-random behavior of generated text. For details, see Writing:The Ways of Printing.
 * Display a symbol (text, gentext, or code) with different printing parameters. The  flag (  or  ) controls auto-spacing and auto-capitalization. The   parameter controls the pseudo-random behavior of generated text. For details, see Writing:The Ways of Printing.


 * Generate a break (or lack of break) in a cooked text stream.
 * Generate a break (or lack of break) in a cooked text stream.


 * Generate the word "a" or "an" in a cooked text stream, whichever matches the next printed word. (You may use either  or   -- they produce the same result.)
 * Generate the word "a" or "an" in a cooked text stream, whichever matches the next printed word. (You may use either  or   -- they produce the same result.)


 * Resolve a pending  or , as if a following word started with a consonant  or vowel.
 * Resolve a pending  or , as if a following word started with a consonant  or vowel.

pronoun module

 * Returns the appropriate pronoun for the acting player. You may supply a player argument to specify a different player. All of these functions also exist in capitalized form.
 * Returns the appropriate pronoun for the acting player. You may supply a player argument to specify a different player. All of these functions also exist in capitalized form.
 * Returns the appropriate pronoun for the acting player. You may supply a player argument to specify a different player. All of these functions also exist in capitalized form.


 * Returns the appropriate pronoun for the given or acting player. The  argument must be one of the strings  . (The third-person forms don’t work here.)
 * Returns the appropriate pronoun for the given or acting player. The  argument must be one of the strings  . (The third-person forms don’t work here.)
 * Returns the appropriate pronoun for the given or acting player. The  argument must be one of the strings  . (The third-person forms don’t work here.)

random module

 * A randomly-selected entry in the list.
 * A randomly-selected entry in the list.


 * A random number from A to B, inclusive. (That is,  will return either 4, 5, or 6, with equal probability.)
 * A random number from A to B, inclusive. (That is,  will return either 4, 5, or 6, with equal probability.)


 * A random number from 0 to A-1.
 * A random number from 0 to A-1.


 * A random number from A to B-1. (That is, the result will be at least A but always less than B.)
 * A random number from A to B-1. (That is, the result will be at least A but always less than B.)


 * A random number which is at least A, less than B, and a multiple of step above A. (That is,  will return 0, 2, 4, 6, or 8.)
 * A random number which is at least A, less than B, and a multiple of step above A. (That is,  will return 0, 2, 4, 6, or 8.)

datetime module

 * The current time, as a  object. Always in UTC.
 * The current time, as a  object. Always in UTC.


 * Create an object representing a date and time. (This can be stored in the database.)
 * A datetime object has these attributes:,  ,  ,  ,  ,  ,.
 * This differs from the Python datetime constructor in that the result is always timezone-aware and in UTC. If you try to pass in a  argument, it will be ignored.
 * This differs from the Python datetime constructor in that the result is always timezone-aware and in UTC. If you try to pass in a  argument, it will be ignored.


 * Create an object representing an interval of time. (Cannot be stored in the database. You may instead store, which is a float.)
 * A timedelta object has these attributes:,  ,  ,.
 * A timedelta object has these attributes:,  ,  ,.

Hooks
The  property (from our example with timers) is one type of hook: a specially-named property that the server invokes in certain circumstances. There are several of these.


 * (Realm property) Invoked exactly once when the instance is created, which is the first time a player ever links in. This is immediately followed by an  call.
 * (Realm property) Invoked exactly once when the instance is created, which is the first time a player ever links in. This is immediately followed by an  call.


 * (Realm property) Invoked when the instance is awakened; that is, if the instance is asleep (or freshly created) and a player links in.
 * (Realm property) Invoked when the instance is awakened; that is, if the instance is asleep (or freshly created) and a player links in.


 * (Realm property) Invoked when the instance has been uninhabited for ten minutes. After this call, all outstanding timers are cancelled.
 * (Realm property) Invoked when the instance has been uninhabited for ten minutes. After this call, all outstanding timers are cancelled.


 * Warning: the  does not occur if the server crashes or is rebooted by the administrator. In these cases, the server restarts with all instances “asleep” and immediately calls   for the inhabited ones. So you should regard the   hook as unreliable; you may see two   calls in a row with no   between them.


 * (Location property) Invoked when a player enters a room, either by moving or linking. The temporary variable  will be the previous location (or   for linking);   will be the new location.
 * (Location property) Invoked when a player enters a room, either by moving or linking. The temporary variable  will be the previous location (or   for linking);   will be the new location.


 * (Location property) Invoked when a player leaves a room, either by moving, linking, or panic-linking. The temporary variable  will be the current location;   will be the new location (or   for linking).
 * (Location property) Invoked when a player leaves a room, either by moving, linking, or panic-linking. The temporary variable  will be the current location;   will be the new location (or   for linking).

Debugging commands
The in-game chat prompt offers a few helpful debugging commands. With the exception of, these can only be used in worlds you created.


 * Displays the database keys (ObjectId) of your avatar, world, instance, scope, and location.
 * Displays the database keys (ObjectId) of your avatar, world, instance, scope, and location.


 * Teleport yourself to the location (in this instance) with the given short name.
 * Teleport yourself to the location (in this instance) with the given short name.


 * Check for a property named  in the current location. If found, display its value, and whether it was a world or instance property.
 * Check for a property named  in the current location. If found, display its value, and whether it was a world or instance property.


 * Display the value of a realm property named  (world or instance).
 * Display the value of a realm property named  (world or instance).


 * Display the value of a location property named  in the location named.
 * Display the value of a location property named  in the location named.

"Note that this syntax does not match script code. In script code, you’d be writing and."


 * Set a property in the current location, realm, or the named location. This sets an instance property, like script code would, not the world property. (Again, world properties are defined solely by the world-building interface.)
 * The value can be any simple Python literal:,  ,  , integers, quoted strings, lists, dictionaries.
 * To set a text property, you have to use the ugly spelled-out form:
 * Set a property in the current location, realm, or the named location. This sets an instance property, like script code would, not the world property. (Again, world properties are defined solely by the world-building interface.)
 * The value can be any simple Python literal:,  ,  , integers, quoted strings, lists, dictionaries.
 * To set a text property, you have to use the ugly spelled-out form:


 * Delete an (instance) property in the current location, realm, or the named location. If there is a world property with the same name, this will allow it to shine through again.
 * Delete an (instance) property in the current location, realm, or the named location. If there is a world property with the same name, this will allow it to shine through again.
 * Delete an (instance) property in the current location, realm, or the named location. If there is a world property with the same name, this will allow it to shine through again.
 * Delete an (instance) property in the current location, realm, or the named location. If there is a world property with the same name, this will allow it to shine through again.


 * Run the line of code in the current location, as if it were an action that you had clicked on.
 * Run the line of code in the current location, as if it were an action that you had clicked on.

"So is the same as, really." "Local variables in an (variables beginning with underscores, i.e.,  ) live in a special environment which will persist as long as your connection is active. These locals will never spill over from your   commands into running world code."


 * Kick everybody out of the current instance, including yourself. Then put the instance to sleep. The next time someone enters the instance, the  hook will run. (See the “Hooks” section for more details.)
 * Kick everybody out of the current instance, including yourself. Then put the instance to sleep. The next time someone enters the instance, the  hook will run. (See the “Hooks” section for more details.)