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}
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!)