APDL Soft Rock Games/APDL_SOFTROCK.iso/trellis/docs/part05

Text File | 1999-04-02 | 22.4 KB | 585 lines

                        TRELLIS - The Adventure Interpreter
                      (c) copyright 1991-9 Soft Rock Software

                                 TScript Commands
                                 ----------------

In this section each of the TScript commands will be explained. Where
appropriate, examples will be given. For further examples, please see the
game that has been supplied free with the Trellis.

Following the command descriptions you will find some other general hints
for writing TScript programs.

Important - Commands in a TScript program *must* be seperated from their
parameters by one or more spaces.

ie, you can't do...

IFStore%(21)=42THENStore%(21)=43
or
PRINT"Hello"'

They *must* take the form...

IF Store%(21)=42 THEN Store%(21)=43
or
PRINT "Hello"'



---------------------------------------------------------------------------

STOP - this command stops execution of the script file, and returns
control  to the RISC OS desktop without going through the 'do you want to
play again' ritual.
---------------------------------------------------------------------------

LET - this command allows the software's variables to be changed. It has
the format:-

LET Variable=Equation

where Variable is one of the variables that can be redefined in the script
program. These are explained more fully in part 3, but to summarise, they
are:-

 Store%( )                 North%( )                 East%( )
 South%( )                 West%( )                  Up%( )
 Down%( )                  Room$( )                  Light%( )
 List$( )                  Examine$( )               Weight%( )
 Location%( )              Object$( )

The number that goes between the brackets with each of these variables can
be an Equation. Both this Equation, and the one following the '=' can
contain any of the above variables, manipulated in many ways. For example,
you can add the contents of two stores together:-
 LET Store%(54)=Store%(43)+Store%(44)
or redefine an exit, to close a door:-
 LET East%(12)=0
or change the short description of an object:-
 LET List$(4)="a broken stick"

Equations can also use all the functions made available by the Basic
Interpreter in your computer. For full details of these, please read the
BBC Basic Guide, supplied by Acorn. The one that is most likely to be
useful is RND( ) which can be used to get a random number. You could have
a line:-
 LET Store%(22)=RND(6)
which would be like rolling a dice, and putting the number on top in the
variable called Store%(22).

There are 4 important points to remember about variables and equations.

(1) The variables that have a percent sign (%) in their name are called
Integer variables. That means they can only contain whole numbers. If you
try to put 1.43 into an integer variable, it will only hold 1. If you try
to put letters or words in, the program will not work properly.

(2) The variables that have a dollar sign ($) in their name are called
String variables. That means they contain letters, words and other text.
This is usually enclosed inside speech marks ("). If you try to put 1.43
into a sting variable the program will not work properly. However, you
could put "1.43" in - but remember that is *not* a number.

(3) On a line that starts off with LET, if the Variable on the left of the
equals sign is an Integer one, all the variables used in the equation on
the right should also be integer variables. The reverse is true for
Strings.

(4) Wherever there is a variable with an equation in its brackets, any
variables used in that equation must all be Integer variables - even if
the variable itself is a string. This is true for variables on the left of
the equals, and the right.

Points 3 and 4 might seem to contradict each other. So this example should
help:-

LET Room$(Store%(3))="The holographic scenery depicts a desert, far and
wide. It is very hot."

The variable Room$( ) is a string variable, but in the brackets should be
a number, so an integer variable is used. This is correct. Equally correct
would be:-

LET Room$(Store%(3))=Room$(Store%(3))+" It is very hot."
---------------------------------------------------------------------------

:text - this marks a label, which is used by the GOTO command.

eg: :start - if the command 'GOTO start' is encountered execution will
jump  to the line following ':start'

Note: the label marker (:) *MUST* be at the very start of a line, not
indented.
---------------------------------------------------------------------------

GOTO text - this jumps to the label 'text'

eg: GOTO start - see above.
---------------------------------------------------------------------------

CLS - this command clears the screen.
---------------------------------------------------------------------------

LOOK - this command displays the current location, including exits and
objects visible to the player.
---------------------------------------------------------------------------

INPUT - this tells Trellis to prompt the player for a command.
---------------------------------------------------------------------------

COMMAND - this command tells Trellis to try and act on the players
command.  Please note that if Trellis will need help carrying out the
command, this  must be done before 'COMMAND' is reached.

Commands which can normally be dealt with by Trellis are: GET, DROP, INV,
EXAMINE, LOOK, QUIT and the direction commands. However, you may wish to
'intercept' these commands and act on them yourself in some cases. For
example, when creating Doors, which are explained elsewhere.
---------------------------------------------------------------------------

RESTART - this command will stop the game and ask the player if he/she
wants  to start again. If Y is pressed the TScript program will be started
again  from the top. If not, control returns to the desktop.
---------------------------------------------------------------------------

QUIT - this command asks the player if he/she is sure about quitting the
game.  If Y is pressed, control is passed to the RESTART command (see
above). If N  is pressed the game continues as if nothing happened.
---------------------------------------------------------------------------

IF condition THEN - this command is quite complicated. It has two forms, a
single line or block. In both cases the condition is evaluated to be
either  TRUE or FALSE, and determines if the rest of the line (or the
block) will be  executed.

The single line version takes this form:-

IF condition THEN command - where 'condition' is the condition to evaluate
and 'command' is the command to execute if the condition is found to be
true.

IF Store%(3)=42 THEN PRINT"It is very cold here."

Note: the command can't be a label (:) since the label will never be found,
regardless of the condition.

The block version takes this form:-

IF condition THEN
 commands 1
END IF

or this form:-

IF condition THEN
 commands 1
ELSE
 commands 2
END IF

If the condition is true, in both cases the block of program designated by
'commands 1' is executed followed by the commands that come after the 'END
IF'. If the condition is false, in the first case program execution jumps
to the command after the END IF and in the second case after the ELSE (ie:
commands 2).

The conditions you can use are similar in structure to the equations that
can be used with the LET command, just a little more complex. You can use
 IF Variable=Equation THEN
which is very similar to the LET statement. In the case of IF, however,
this is more correctly described as:-
 IF Equation 1 Comparison Equation 2 THEN
The equals sign can be replaced by a number of 'Comparisons' which are as
follows:-
   =    check if equation 1 equals equation 2
   >    check if equation 1 is higher than equation 2
   <    check if equation 1 is lower than equation 2
   >=   check if equation 1 is higher than or equal to equation 2
   <=   check if equation 1 is less than or equal to equation 2
   <>   check if equation 1 is not equal to equation 2

You can also have more than one condition in an IF ... THEN line by using
AND and OR. For example:-
 IF Store%(3)=10 AND Location%(6)=0 THEN

The basic rules for the equations used in IF ... THEN statements are the
same as those described above for LET.

With conditions, another variable is available for your use. You can't
change what it contains, but you can check it. The variable is called
Moved% and contains either 0 (FALSE) or TRUE (-1). If the last command the
player entered was a direction, and Trellis moved the player as a result,
Moved% will contain -1. If the player wasn't moved by Trellis, Moved% will
contain 0.

Therefore you can find out if the player has moved with the simple IF
statement:-
 IF Moved% THEN

Or you can check that he/she /hasn't/ moved with...
 IF NOT(Moved%) THEN

This can, of course, be combined with other conditions:-
 IF Moved% AND North%(12)=22 THEN

You also have a special function available in conditions. This is called
FNSaid and it is used to find out if the player entered a word defined in
the words file, or one defined already by Trellis. The function returns
either 0 if the word wasn't entered, or -1 if it was. To use it, you put
the appropriate keyword inside speech marks and brackets straight after
the FNSaid:-
 IF FNSaid("SWORD") THEN

Again, you can combine this with other conditions using AND/OR. For
example:-
 IF FNSaid("READ") AND FNSaid("TEXT") THEN

Note: The IF block structure is very limited. Firstly, it CAN'T be nested. This
means you can *NOT* have an IF block inside another IF block, like this:-

IF Store%(3)=14 THEN
 PRINT"This room is very dark. "
 IF Store%(42)=1 THEN
  PRINT" You can hear a ghostly wail."
 END IF
END IF

You can, however, put single line IFs inside an IF block. So the above
would  become:-

IF Store%(3)=14 THEN
 PRINT"This room is very dark."
 IF Store%(42)=1 THEN PRINT" You can hear a ghostly wail."
END IF

This example was quite straightforward to correct. There will, however, be
cases when the 'inner' IFs will need more than one line, making an IF
block  necessary. Since this can't be done, you must use an IF with a
GOTO, to jump  to the relevant block of code.

This brings to light a further problem. If you use a GOTO within an IF
block,  you must jump OUTSIDE the block. The following code will not work
properly:-

IF Store%(3)=14 THEN
 IF Store%(27)<>0 THEN GOTO nextbit
  PRINT"Do this."'
  PRINT"Do something else."'
  PRINT"But only if store 27 contains zero."'
:nextbit
 PRINT"Do this every time the player is in room 14."
END IF

Having encountered a GOTO, Trellis will think it is no longer inside an IF
block and report an error when it encounters END IF. This, however, would
work:-

IF Store%(3)=14 THEN
 IF Store%(27)<>0 THEN GOTO nextbit
 PRINT"Do this."'
 PRINT"Do something else."'
 PRINT"But only if store 27 contains zero."'
END IF
:nextbit
IF Store%(3)=14 THEN PRINT"Do this every time the player is in room 14."

This may, at first, seem strange - the GOTO command shouldn't have any
effect on the status of the conditional block. However, it was done for a
reason: If it didn't affect the block you would not be able to jump out of
it because, if you did, the program wouldn't be able to enter another IF
block - an error would occur. This would be very restrictive and,
considering there is already a limitation in the form of no nesting of
these blocks, writing adventures would be very difficult. This is a
deficiency I hope to address in a later version.
---------------------------------------------------------------------------

GET object - this command will make the player pick up the specified
object,  if possible (if it is available, and light enough to carry).

eg: GET SWORD - if the sword is available and not too heavy it will be
picked  up.

Note: unless you are forcing the player to pick up an object, perhaps as a
result of a puzzle being solved ('You say the magic word and a sword
magically appears in your hand.'), you would probably not use this
command. (If the player enters GET it can be dealt with automatically)
---------------------------------------------------------------------------

DROP object - this drops an object if it is being carried, leaving it in
the  current location. It has the same format as GET, and the same note
applies.
---------------------------------------------------------------------------

PRINT list - this command will print the 'list' on the screen. The list
can  contain a variety of items, as follows:-

text, enclosed in speech marks (""). Everything between them will appear
on  the screen. eg: PRINT "This is text enclosed in speech marks and will
appear on the  screen."

[equation], where equation will result in an integer number. The number
will be displayed. eg: PRINT [Store%(21)] - will print the contents of
store 21.

' - the computer will print a carriage return and line feed. (The next
thing  to appear will be at the left of the next line.

Any or all of the above can be combined in the PRINT command.

eg: PRINT'"This will be printed on one line,"'''"and this three lines
below."

eg: PRINT'"You are in room "[Store%(3)]"."'

eg: PRINT'"The total weight you are carrying is "[Store%(2)]"."

The ' parameter is very useful for missing lines, as can be seen with the
first of the three examples above, but is also useful for another reason:-

Many of the commands that automatically put information on the screen do
not output a carriage return themselves, so anything else displayed will
continue  on immediately from them. This is done so that additional data
can be added  by the player, so overcoming limits in line lengths.

When you have added the  appropriate text with the PRINT command, use a
single PRINT' (or add the ' to  the end of your PRINT line) to start a
fresh line.

You will probably find that sometimes you are starting new lines when you
don't want to, and not starting them when you do. It is easier to use the
first method given above (PRINT') since you can just use this once after
ALL the additional data is displayed.

For example. If the description for room 13 was 'You are on a dark forest
path.' and you wanted to add, via the script file, 'The sunlight shines
through the gaps in the trees above, making the damp cobwebs sparkle and
shimmer as they blow in the breeze.' You would add it, somewhere after the
LOOK command, like this:-

IF AT 13 THEN PRINT " The sunlight shines through the gaps in the trees
above, making the damp cobwebs sparkle and shimmer as they blow in the
breeze."

and, after all the similar commands to do the same for other rooms, use:-

PRINT'

After this has been displayed, the description for the location will be
complete, and the carriage return can be output. Hence the PRINT' The
final description that might appear on the screen for this location, then,
night be:-

You are on a dark forest path. Exits lead North and South. You can see a
tree  stump. The sunlight shines through the gaps in the trees above,
making the  damp cobwebs sparkle and shimmer as they blow in the breeze.
---------------------------------------------------------------------------

REM anything - this command and everything on the line following it is
ignored. It can therefore be used for comments. Blank lines are also
ignored - these can be used to space out the script.
---------------------------------------------------------------------------

SPACE list - this command waits for the player to press the space key.
'list'  is printed to the screen first - it has the same format/structure
as  PRINT list (see above).
---------------------------------------------------------------------------

INV - displays a list of what the player is carrying.
---------------------------------------------------------------------------

EXAMINE object - this displays the more detailed description of an object.

eg: EXAMINE SWORD - this would give a more detailed description of the
sword  (if such a description has been included in the objects file.)
---------------------------------------------------------------------------

Please note that certain commands would not normally be needed, since the
COMMAND instruction would normally deal with them automatically. These
commands are: LOOK, GET, DROP, INV and EXAMINE. They have been included as
available commands because there may be times when you would want to deal
with their operations manually. For example, you may decide to always list
the objects a player has as part of your HELP facility:-

IF FNSaid("HELP") THEN
 PRINT'
 INV
 PRINT'
 REM rest of help code here...
 GOTO what_next
END IF
---------------------------------------------------------------------------

"It's all very well knowing how each of the commands work," I hear you
cry, "but how do they fit together to make a TScript program. I think we
should be told."

Okay - but this is not going to be very deep, just a general overview,
maybe with some hints thrown in for good measure.

Think of your TScript program in sections. Simplistically, these are:-

 1: Initialisation

    Set the whole thing up. Put starting values in the stores you are
    going to use, and put the player in the first location.

 2: Describe Location

    This is done by the software. At the simplest level, all this section
    of your TScript program will consist of is a label and the LOOK
    command:-

    :movement_loop
     LOOK

    However, if you are adding more complex descriptions by way of
    IF/PRINT commands, these will follow the LOOK command in this section.

 3: Conditions 1

    These are 'Priority 1 status red emergency conditions' in that they
    will check for important things, such as whether the player has done
    something that means he/she has won (or died) - such as reached a
    certain location. Obviously, that location needs to be described
    first, which is why these are located after the Description section.
    In the event of winning/dying appropriate text must be displayed, and
    the program must either end or start again. (ie RESTART). GOTOs can be
    used to put the routines to do what is necessary in sections 9 or 10
    (see below).

    This section could also be used for checking for changes in a
    location, such as a door closing, or a roof collapsing - but these
    could just as easily be part of the section above.

 4: Player Input

    This is done by the software. It should generally look something like
    this:-

    :input_loop
     INPUT
     IF FNSaid("QUIT") THEN
      QUIT
      GOTO input_loop
     END IF

    The reason for the IF structure is to ensure the software correctly
    handles the QUIT command if the player has entered it. If so, the
    software will enter the IF block, prompting if the player is sure. If
    N is pressed, control returns to TScript and the GOTO command will
    jump back to the prompt for player input. (If Y is pressed the
    software will automatically deal with restarting the game or
    returning to RISC OS.)

    In a slightly more complex version, you may have one or two more
    conditions that need to be checked as part of the input loop, but
    before anything is actually entered by the player. If so, they would
    be included after the label/before INPUT.

 5: Conditions 2

    These are 'Priority 2 status not very urgent (but still quite
    important) conditions.' in that they more or less deal with the
    player's input in cases where the software either can't deal with it,
    or might need help.

    For example, the player might want to drop an object in a certain
    place, rather than just 'in the room' - eg. a pen onto a desk.

    Also, if you know that certain commands can be dealt with
    automatically, with no intervention from your script (see the section
    on speed for a more detailed explanation of this) you can check for
    them at the start of this section and jump to the next section,
    straight past all the other conditions.

 6: Act on Player Input

    Once all the commands that your program needs to handle have been
    dealt with in the section above, the software can deal with the
    remainder. This section would consist of little more than a label and
    COMMAND:-

    :do_command
    COMMAND

    If the command can be carried out by Trellis, it will be, otherwise an
    appropriate error message will be displayed.

 8: Loop.

    This section should do one of two things. If the player has moved
    (that is, his/her location has changed as a result of the last command
    that was entered) it should jump to section 2, above. If not, it
    should jump to section 4. The script to do this, using the labels
    given above, is:-


    IF Moved% THEN
     GOTO movement_loop
    ELSE
     GOTO input_loop
    END IF

    This could be simplified to two lines by not using the IF/END IF
    structure:-

    IF Moved% THEN GOTO movement_loop
    GOTO input_loop

 9: Return Control To RISC OS

    When a game ends the player should be asked if he/she wants to play
    again. If so the game should restart, if not control should return to
    RISC OS. Most of the work in this can be handled by Trellis.

    As a part of section 3 of your program you would have told the player
    if he/she has won, died or whatever. These should be followed by a
    jump to this section of the script with 'GOTO game_end' This section
    will then contain the following two lines:-

    :game_ends
    RESTART

10: Routines

    In some TScript programs you may find it suitable to put whole
    sections of your script here. This would make the sections above look
    somewhat less messy, though the overall picture would be much messier
    since it could increase the number of GOTOs.

    Do not mistake this for the concept of subroutines. Each and every
    section of program here would need a GOTO command to take control back
    into the main sections of the TScript file. Therefore, only one point
    in the main file can be accessed from each routine here, so such
    routines can only be called from immediately before that point.

    This should only be done to make the higher sections look tidier and
    easier to follow.

The above should be considered nothing more than a guideline. Depending on
the game you write, you might drop entire sections from the above, or add
others of your own devising. Indeed, if you look at the script files for
the example games, you will see that they don't fit the sections described
above 100% - there are no hard and fast rules about this. When you are
more experienced you might prefer to do things a little differently, and
that's fine.

Important - Commands in a TScript program *must* be seperated from their
parameters by one or more spaces.

ie, you can't do...

IFStore%(21)=42THENStore%(21)=43
or
PRINT"Hello"'

They *must* take the form...

IF Store%(21)=42 THEN Store%(21)=43
or
PRINT "Hello"'