The Datafile PD-CD 4

home *** CD-ROM | disk | FTP | other *** search

/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / games2 / trellis / Instructs / Part4 < prev next >

Wrap

Text File | 1994-09-16 | 21.7 KB | 548 lines

TRELLIS - The Adventure Interpreter (c) copyright 1991-4 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. --------------------------------------------------------------------------- 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$="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. (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' --------------------------------------------------------------------------- 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 always 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 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't 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. --------------------------------------------------------------------------- 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 ENTERED 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 ENTERED 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.