STYCHES documentation

Command Reference

CALL

Reads and processes another paragraph and then returns to the current paragraph. The name of the new paragraph is given and it can be the content of a variable.
e.g.

paragraph1:{CALL|paragraph2} I am paragraph 1.
paragraph2: I am paragraph 2.
Will output: I am paragraph 2. I am paragraph 1.

CANCELTIMEOUT

Takes no arguments and cancels any pending timeout actions. See the TIMEOUT command.
e.g.
{CANCELTIMEOUT}

CASE

The CASE command takes a variable as its first parameter followed by a list of options, separated by the ‘|’ character. The list of options correspond to the numeric values 0, 1, 2 etc. The option that matches the value of the first parameter is actioned. If the value of the first parameter is greater than the length of the subsequent list, the last option is actioned. Please note that the options list can be commands and/or text; if you want to process another paragraph, you have to use the {CALL|…} command.
e.g.
{CASE|2|I am option 1|I am option 2|I am option 3|I am option 4}
will output: I am option 3 (remember, CASE starts counting from 0)

If $foo is 6, then
{CASE|$foo|I am option 1|I am option 2|I am option 3|I am option 4}
will output: I am option 4 (remember, the last option is actioned if the value is greater than the list of options)

CEASE

Sets a given object as ‘not being used’. The single parameter specifies the ID of the object affected and can be either the literal object ID or a variable containing the object ID. There is no output from this command. This is the opposite of the ‘USE’ command
e.g.
{CEASE|hat}
will set the BEINGUSED attribute of the ‘hat’ object to ‘N’

CEASECLASS

In the same way that CEASE above, this command also sets the BEINGUSED attribute to ‘N’ BUT for all objects that have the given class where the BEINGUSED attribute is already ‘Y’. Unlike CEASE above, this command will call the paragraph defined by ‘CEASEPARAGRAPH’ for each matching object and if the object is visible, the text generated (if any) is output.
e.g.
{CEASECLASS|clothing}

CHOICE

The CHOICE command displays a popup dialog box. The first parameter given is the title of the popup box and is followed by a series of text and paragraph pairs, separated by a colon. The command then displays a popup dialog with the text element displayed as a button. When the player selects one of the options, then the associated paragraph is processed. Since screen size is a limiting factor, you should make sure that your choice test isn’t too long and also that the number of options is limited to a maximum of 5. Remember to give the player a chance to cancel by having one of your options labelled as ‘Cancel’ or similar if that is what you want. If you do this, you will need to give a dummy paragraph name that does nothing. You do not have to give a cancel option if you want to force the player to make a choice.
e.g.
{CHOICE|My popup title|Choice 1:paragraph1|Choice 2:paragraph2|Choice 3:paragraph3}

COMPLETE

This command takes no parameters and tells Styches that the game is over. COMPLETE removes the option to save the game and also hides the ‘Inventory’ button as they no longer make sense.

CONCAT

takes 2 arguments as strings and concatenates them. The result is stored in the first argument. Therefore the first argument must always be a variable.
e.g.
{CONCAT|$fred| which is open.} if the value of $fred was ‘You see a chest’ before this command, after it the value of $fred is ‘You see a chest which is open.’

CONFIRM

Displays a popup which gives the player a ‘yes/no’ choice. The command takes 3 or 4 parameters which define the title of the popup, the text to display inside the popup body and then a paragraph to process if the player selects ‘Yes’. The 4th parameter is optional and defines a paragraph to process if the player selects ‘No’; by default if there isn’t a paragraph defined for ‘no’ then the current location paragraph is processed.
e.g.
{CONFIRM|My title|Are you sure you want to?|theypickedyes|theypickedno}

CREATE

Creates an object in the game and sets a whole heap of attributes for that object. The first parameter is the object ID and must be unique within the game. This is optionally followed by a number of parameters which define attributes. Most attributes have default values which can be overridden by explicitly setting them inside the CREATE command. Each attribute pair defines the attribute and its value separated by a colon.
NOTE: since you can define your own attributes for objects, you must be very careful will spelling if you mean to override a standard attribute. Styches won’t know if you are defining a new attribute or not, so it will simply create a new one which may well not be what you meant to happen. If your objects are behaving strangely, check your spelling!
Here is a list of all of the standard attributes and their default values:
NAME : same as the object ID
TOUCHED : "N"
KEEPUSING : "N"
BEINGUSED : "N"
TAKEPARAGRAPH : 'take'
EXAMINEPARAGRAPH : 'examine'
USELABEL : 'Use'
USEPARAGRAPH : 'use'
USEVERB : 'using'
DROPLABEL : 'Drop'
DROPPARAGRAPH : 'drop'
LOCATION : “”
COUNT : 1;
You can simply override these by giving the attribute, a colon and then a new value as a parameter in the CREATE command. You can give mutiple parameters to override as many of the defaults as you wish.
e.g.
{CREATE|sword|NAME:shining sword|USEPARAGRAPH:usesword|DROPPARAGRAPH:dropsword|LOCATION:#Treasure_Room}

DEBUG

This command takes no parameters and turns on debugging mode, which lists out all objects and all variables on each page as you play. It is a testing tool that can assist in finding logic errors in your script.
e.g.
{DEBUG}

DESCRIBE

The DESCRIBE command takes a single argument. This argument is a location, and Styches will process the paragraph and list any objects at that location BUT none of the links or clickable actions will be output. The location you give as the parameter can be a variable. The DESCRIBE command can be used to describe a remote location, such as (for example) allowing the player to look at a CCTV camera. Since the parameter can be a variable, you can use this to drop a remote camera maybe?

DESTROY

DESTROY deletes an object from the game completely. The object to destroy can be contained in a variable.
e.g.
{DESTROY|helm}
or
{DESTROY|$myobject}

DROP

Sets an objects location to the current location; it does not have to be in the players inventory. If the object is currently being used AND the KEEPUSING attribute isn’t set to ‘Y’ then set the BEINGUSED flag to ‘N’. If there is a CEASEPARAGRAPH defined for this object, then process it. If there is a duplicate object at the current location, then add the ‘count’ of the dropped object to the ‘count’ of the duplicate. The parameter given can be a variable.
e.g.
{DROP|hat}
or
{DROP|$myobject}

FINISH

Tells Styches that we do not want it to automatically display the ‘Continue…’ or (or return…) links on the page. Sometimes in your script, you may find you don’t want these automatically added.

FOREACH

Styches will cycle through all of the objects that currently exist in the game and will set the $this variable to the object ID and then call the given paragraph. It does this for all objects, regardless. The parameter MUST be the name of a paragraph.
e.g.
{FOREACH|MyProcessObjectRoutine}

IF

This is Styches way of testing logic conditions and taking different actions depending on the outcome. The IF command has 3 parameter; the first is the test condition, the second is the text to process if the result of the test is true and the third parameter is the test to process if the test condition is false. The third parameter can be blank and if you wish, the second parameter can be ‘empty’ by which we mean that there is no test for Styches to process, which results in no output. If you know some existing programming, this is the same as IF….THEN…ELSE
The first parameter, which is the logic condition to test is formed by giving a variable or literal value followed by the test you want to apply, followed by another variable or literal value. These arguments are separated by a single space character. Thus the format is:
<value1> <test> <value2>
Tests allow you to compare the 2 values in a variety of ways such as are they equal or is one less than another and so on. In addition to this, some tests are specific to Styches and test things like whether an object is in the players inventory or visible. For some of these tests, the second value in the test is not required. This will be pointed out against each test type below.
Styches has many logical tests that can be applied and they are as follows:

EQUAL/EQUALS

Compares 2 strings of characters and returns true is they are the same. Please be aware that this is a case sensitive test (i.e. ‘Water’ is NOT equal to ‘water’).

=

Compares the 2 values as if they were integer numbers; if a string is given, it will be converted to a number if possible and if not, a 0 is used. Comparing 2 text strings in this way almost always is true as they are both converted to 0. If you have a test that doesn’t seem to be working, make sure that you are using = and not EQUAL and vice versa.

<

If value1 (as an integer) is less than value2 (as an integer), the result is true.

<=

If value1 (as an integer) is less than or equal to value2 (as an integer), the result is true.

>

If value1 (as an integer) is greater than value2 (as an integer), the result is true.

>=

If value1 (as an integer) is greater than or equal to value2 (as an integer), the result is true.

!=

If value1 (as an integer) is not equal to value2 (as an integer), the result is true.

EXISTS

Only value1 is needed for this test. Value1 is an object and if it exists somewhere in the game (i.e. it has been CREATED at some point and not DESTROYed) then this test returns true.

CLASSEXISTS/EXISTSCLASS

Only value1 is needed for this test. Value1 is a class of object and if any object exists somewhere in the game with the CLASS attribute set to the same as value1, then this test returns true.

ISVISIBLE/VISIBLE

Only value1 is needed for this test. If value1 is an object and it is either in the players inventory OR in the current location, this test returns true.

CLASSISVISIBLE/VISIBLECLASS

Only value1 is needed for this test. If any object with the given CLASS is either in the players inventory OR in the current location, this test returns true.

ISLOCATEDAT/LOCATED

Tests whether the location of the object given as value1 is set to the location given as value2. Value2 doesn’t have to exist in the game; all that happens is a text comparison of the objects location and value2 is undertaken and if they are the same, this test returns true.

CLASSISLOCATEDAT/LOCATEDCLASS

Tests whether the location of any object with a CLASS of value1 is set to the location given as value2. Value2 doesn’t have to exist in the game; all that happens is a text comparison of each objects location and value2 is undertaken and if they are the same, this test returns true.

ISPOSSESSED/POSSESS

Only value1 is needed for this test. If the object given as value1 is in the players inventory, this test returns true.

CLASSISPOSSESSED/POSSESSCLASS

Only value1 is needed for this test. If any object with a CLASS of value1 is in the players inventory, this test returns true.

ISBEINGUSED/USING

Only value1 is needed for this test. If the object given as value1 has BEINGUSED set to ‘Y’, this test returns true.

USEDISVISIBLE/VISIBLEUSING

Only value1 is needed for this test. If the object given as value1 is either in the players inventory or at the current location AND has BEINGUSED attribute set to ‘Y’, this test returns true.

CLASSISBEINGUSED/USINGCLASS

Only value1 is needed for this test. If any object with a CLASS of value1 has BEINGUSED set to ‘Y’, this test returns true.

USEDCLASSISVISIBLE/VISIBLEUSINGCLASS

Only value1 is needed for this test. If any object with a CLASS of value1 is either in the players inventory or at the current location AND has BEINGUSED attribute set to ‘Y’, this test returns true.

IFINITIAL

This command will see whether the given object has been ‘touched’ by the player before and if it hasn’t, the initial description of the object will be output, otherwise nothing is printed. When the player picks up the object, the TOUCHED is set to ‘Y’ by default. You can override this is you with by programmatically setting object.TOUCHED to a value of your choosing.
e.g.
{IFINITAL|brasskey}

INITIAL

Outputs the initial description of the given object.
e.g.
{INITIAL|smallrug}

LIST

Outputs a list of objects that are at the given location, just like a location description does, complete with selectable links for the objects. The location does not have to be a defined paragraph in our script; it can be any string of text. All Styches does is look at all objects and see if their location equals the one given in this command; it could be ‘PLAYER’ is you wish.
e.g.
{LIST|#Treasure_Room}

MATHFLOOR

This command takes 3 arguments. It subtracts argument 2 from argument 1. If the result is less than argument 3, the result is set to argument 3 otherwise the result is whatever was calculated. The result is stored in argument 1. Therefore argument 1 MUST ALWAYS BE A VARIABLE.
e.g.
{MATHFLOOR|$fred|1|10} will subtract 1 from the current value of $fred. If the value of $fred is less than 10, set it to 10.

MATHCEILING

This command takes 3 arguments. It adds argument 2 to argument 1. If the result is greater than argument 3, the result is set to argument 3 otherwise the result is whatever was calculated. The result is stored in argument 1. Therefore argument 1 MUST ALWAYS BE A VARIABLE.
e.g.
{MATHCEILING|$fred|2|15} will add 2 to the current value of $fred. If the value of $fred is more than 15, set it to 15.

MOVE

Takes 2 arguments and changes the location of the object given as argument 1 to be argument 2. No other processing is done.
e.g.
{MOVE|sword|#Armoury}

PRINT

Takes a single variable as an argument and prints out the current value. If the argument value is the same as an object, then the output will be ‘plural’ if the object COUNT is greater than 1.
e.g.
{PRINT|$fred}

RANDOM

Takes 2 arguments. The first is the lowest value of a range, the second is the highest value. A random number is returned that is within that range, inclusive.
e.g.
{RANDOM|1|100}

RESTART

Deletes all the objects and variables in a game and then processes the #start paragraph. This is exactly what happens when the player begins the game. This allows you to programmatically reset the game.
e.g.
{RESTART}

RESTORE

Takes the saved game state (if any) and resets all of the game objects and variables to that state. Allows you to programmatically restore a saved game.
e.g.
{RESTORE}

SAVE

Saves the current state of all objects and variables, overwriting any previous saved game.
e.g.
{SAVE}

STOP

Tells Styches that we do not want to continue processing the current paragraph or any further paragraphs. In addition, the default list of objects at a location, if applicable is NOT displayed and the ‘alwaysafter’ paragraph (if defined) is not processed. This command is used when you want to restrict the players actions, although the ‘inventory’ button and the ‘restore game’ options are still active. Compare this to the COMPLETE command.
e.g.
{STOP}

SWITCH

The SWITCH function will try to match the passed string with the subsequent list of elements. Each element is a string that is the match followed by a colon (:) and then the output if it does match.
For example, lets say the variable $fred contains "angry". If we use this switch function:
{SWITCH|$fred|glad:pleased to see you|sad:unhappy about this|angry:pretty upset|happy:content with it}
it would output "pretty upset" since the content of $fred matches "angry".

TAKE

Sets an objects location to ‘PLAYER’. If the player already has an object with the same name then the ‘count’ attribute will be incremented and the taken object destroyed. The TOUCHED flag is also set to ‘N’, so that the default initial description is no longer given.
e.g.
{TAKE|sword}

TIMEOUT

This command takes several parameters and waits a given amount of time before processing the given paragraph. The arguments are:
Paragraph to process after the time given has expired
How long to wait, in seconds
An optional argument which will be placed in the variable ‘$this’ when the timeout expires
An optional argument which defines whether the output from the paragraph processed at the end of the timeout is added to the existing test OR whether the new output is placed on a new page. The values for this argument are ‘REPLACE’ or ‘ADD’. If no argument is given, the text will be added to the existing output.
Whilst waiting for a timeout, the inventory and File… buttons are disabled; however, any links you have defined in your output are still selectable by the player. If they select a link, while the timeout is in operation, this will stop the pending timeout. You can only have one timeout in operation at any one time. Starting a new timeout command cancels any pending one.
e.g.
{TIMEOUT|mytimedparagraph|1|myobject|REPLACE}

USE

Sets the BEINGUSED flag for the given object to ‘Y’.
e.g.
{USE|hat}

=

Sets the value of a variable to be either a literal value or the value of another variable. Please note the you can use this to set the value of a variable to a string as well as a numeric value.
e.g.
{=|$fred|28} no matter what value $fred had before this command, after it, the value of $fred is 28

+

takes 2 arguments and adds them together. The result is stored in the first argument. Therefore the first argument must always be a variable.
e.g.
{+|$fred|101} if the value of $fred was 99 before this command, after it the value of $fred is 200

-

takes 2 arguments and subtracts the second argument from the first. The result is stored in the first argument. Therefore the first argument must always be a variable.
e.g.
{-|$fred|25} if the value of $fred was 100 before this command, after it the value of $fred is 75

*

takes 2 arguments and multiplies them together. The result is stored in the first argument. Therefore the first argument must always be a variable.
e.g.
{*|$fred|10} if the value of $fred was 3 before this command, after it the value of $fred is 30

/

takes 2 arguments and divides argument 1 by argument 2. The result is stored in the first argument. Therefore the first argument must always be a variable.
e.g.
{/|$fred|2} if the value of $fred was 25 before this command, after it the value of $fred is 12 (integer maths remember!)