GRAC script commands -------------------- A GRAC script command has up to two parameters, which are always numbers. Most parameters can be set by pressing 'Help' after entering the command, so there is no need to memorise what they all mean. This list contains all commands available in this version. It isn't final: the easiest way to expand GRAC is to add new script commands. In the closest I can get to a logical order, here they are: Bell - - This command makes a bell sound. It is useful mainly when debugging, to make sure that part of a script is actually executing. Execute - - Used in verb scripts to carry out the script associated with the selected object. Script script - Execute the script, then return to the current position. Goto script line Continue execution from any line in any script. Does not return when the script ends. Link script line This is not quite the same as goto. The program continues from the stated script and line but will do so even if the link is in the middle of an if block which is not being executed. This command is used to effectively join scripts together to make a longer one. Timer script delay The script is executed after a delay of the stated number of frames. All activity continues as normal. Timer off - - Don't bother executing the script after all. No default - - As the first line of a script, this stops the verb script from being executed. For example, if the verb script tells the character to walk up to the object, and you don't want this to happen for a particular object, use this command. Print string - The specified string is printed in the text window. Remember that the parameter is is actually a number, which refers to a text string. -1 for the string indicates the description of the selected object. An '@' character indicates the start of a new line. Wait frames - Wait for the specified number of frames. A frame lasts one tenth of a second unless the game is slowed down by too many objects on screen. Wait click - - Waits for a mouse click. Freeze - - Stops all animation until an 'unfreeze' command is encountered. Note that 'wait' allows animation to continue, stopping only the script. This command freezes the display and lets the script continue. However, the 'paste' command cannot be frozen, only objects and characters. Unfreeze - - See above. Hide - - Both the mouse pointer and the control panel disappear. Show - - Brings back the control panel and mouse pointer. Go character - Also used by verb scripts to make the character walk to the selected object. As with all character parameters, -1 means the player's character. If the selected object is a character, the player's character will attempt to walk to a point in front of the other character. If an object does not have a base, it will be impossible to execute a 'go' command. Wait stop character - Wait for the character to reach the point they're heading to. If -1 is used to indicate the player's character, this command can be interrupted with a mouse click. Stop character - Stops the character moving. Place character character point Puts the character at the point. Hide character character - The character disappears. Walk character point The character walks to the point. Reach character height The character reaches at the chosen height, where 1=low, 2=middle, 3=high and -1 to use the default for the current object. Take character foreground object The character reaches for the object, the object disappears and is added to the characters inventory. -1 for the object indicates the currently selected object. For this to work the object must have a negative flag and the 'take' option must be set to the appropriate inventory item. Face character direction The character faces the specified direction. 1=right, 2=left, 3=in, 4=out Add item item character The chosen item is added to the characters inventory. Drop item item character As above, but the item is dropped. Actually it just vanishes. Character frame character image Change the animation frame of a character. The image as grabbed in the character editor. Body frame character image As above, but the image should have no head, which will be added separately. This is to allow characters to speak when not in a standing position. Character change character (a) character (b) Character (a) takes on the appearance of character (b). The effect is preserved until the characters are reloaded with a new object bank. This command is ideal for changes of clothing etc. Say character string The character says the string, which appears above the characters head while the characters head is animated. As with print, @ starts a new line. The text is also split at full stops, question marks and exclanation marks. This is because text looks very odd if it is not split at natural points in the string. Voice string point The string appears above the point, but it is not necessary to have a character there to say it. Set voice colour height This sets the colour of the voice text, and the height above the point, in pixels. Object frame f. object image The object's image is changed. Warning: this is not permanent. If the player leaves the room and returns, the object will change back to its original image. If you don't want this to happen, change the object in the rooms startup script. Amal f. object string The most versatile way to animate an object. If you use AMOS then you will probably be familiar with Amal. If not, this is how to use it. I can't cover everything; the AMOS manual has an entire chapter on Amal, but the basics are as follows: The object will be animated according to a set of instructions held in the string, separated with semi-colons ( ; ). Each instruction is a single upper-case letter, followed by some parameters. Any lower case letter are optional. Move across,down,steps Moves the object across and down the number of pixels specified in the number of steps selected. Each step takes one frame to perform. Anim number,(image+RZ,delay)(image+RZ,delay).... Animates the object by cycling through the images the set number of times. A value of zero for the number means to repeat continuously. Delay can be any number greater than zero and is the number of frames to wait before moving on to the next image. This command is ideal for adding background animations such as dripping taps and flashing lights. RZ is a register. Read the note below. Let register=expression The register is set according to the expression. The registers are: R0 to R9, internal registers which are different for every object, RA to RZ, global registers for passing information between objects, X, the objects X-position Y, the objects Y-position A, the objects image. This may be different to the image number used by GRAC. To get the actual image, add RZ to GRAC's image number. Example: L R0=3; sets internal register 0 to a value of 3. For register=start To end ;.....;Next register This is a For...Next loop similar to those used in scripts. The register begins at and is increased by 1 each loop until it reaches . Jump label Amal jumps to the specified label. A label is a single capital letter followed by a colon ( : ), which can be anywhere in the string. Pause Waits for one update. End Ends the Amal program. There are many more Amal commands. Refer to the AMOS manual for details. You should really only use repeating strings (with a Jump at the end) or continuous Anims to be compatible with the save/load feature. This is because when a game is loaded the Amal string is always started from the beginning. Paste b. object image Paste the image over the background object. This method of animation is quicker and uses less memory than with foreground objects. However, once pasted, the image cannot be deleted except by pasting another image over the top. Only one image may be pasted per frame, except in a startup- script when the display has not been faded in. This is not a permanent effect (see object frame). Load room room point Loads a room and positions the PC at the specified point. Show picture - - Loads and displays a picture. This is useful for title screens. Picture off - - Removes a picture displayed using 'Show picture'. Load palette picture - Loads the picture purely to use the palette. It is not displayed, but does use memory so it is best to use small screens for this purpose. Fade speed - Fades into the palette loaded as described above. The fade takes speed*15 50ths of a second. Fade in - - When a startup script begins, the display is not visible until either the end of the script, or this command. Compare flag flag (a) flag (b) This sets flags (a) and (b) for use with the 'if' instruction. WARNING: do not confuse this with 'compare value'. Compare value flag value Similar to the above instruction but sets a flag and a number. Compare item flag value The current inventory item and either the flag or the value (whichever is positive) are set. Compare entry flag value As above, but the point that the player entered the room from is compared. This is to have animations etc. dependent on which door the player came through. If expression not The expression compares the two values set with a 'compare' instruction. As with all parameters, the expression is represented by a number. 1 is 'greater than' 2 is 'greater than or equal to' 3 is 'equal to' 4 is 'less than or equal to' 5 is 'less than' The commands following the 'if' will only be executed if the expression is true. If the 'not' parameter is -1 the execution will continue only if the expression is false. This is all a bit complicated so here is an example. Suppose that flag (1) holds the value 4 and flag (2) holds 5. compare flag 1 2 if 3 0 bell end if Will the bell ring or not? The answer is no because expression 3 is 'equal to' and flag (1) is not equal to flag (2). If the following were used instead the bell would ring. compare flag 1 2 if 5 0 bell end if End if - - This marks the end of an if block. An if block begins with the command 'if' and ends with 'end if'. If blocks within if blocks are allowed. Else if expression not Used within an if block. 'Compare' commands are always executed regardless of if's, so 'else if' can use a different test to the original if. Else - - Used before the end of an if block, if no expressions have been true in the entire block then execution continues from here. Select flag lines Jump forward a number of lines equal to flag*lines. It will not jump past an 'end select' instruction. End select - - See above. For flag start value Next limit - The flag is set to the start value, and the commands between 'for' and 'next' are repeated, incrementing the flag by one each time, until the limit is reached. Choice string flag Adds a choice to the current selection if the flag is true (flag zero is always true, remember). The obvious use for this feature is to create multiple choice conversations. Choose flag character The player must choose between all available choices by clicking on the string which is printed in the text window. The flag is then set to whatever choice was made (ie. 1 for the first choice, 2 for the second etc.) All choices are then cleared. If the character parameter is not zero, that character will now say the selected string. Set flag flag value Sets the flag to the value. This may cause objects or walk zones to disappear if they are dependent on the flag. Any such change is permanent (until the flag is changed again). Random flag limit The flag is set to a random number, up to the allowed limit. If the limit is negative, the random number may be positive or negative. Otherwise it will always be positive. Add flag value Adds the value to the flag. Add flag flag (a) flag (b) Flag (b) is added to flag (a) Subtract flag flag (a) flag (b) Subtracts flag (b) from flag (a). Copy flag flag (a) flag (b) Flag (a) is set to the value of flag (b). Flag to string string flag The string is changed to the digits of the flag. See the note for 'Set string' below. Set string string (a) string (b) String (a) is set to string (b). Remember that the string will not actually be changed until the game runs and the script is executed. With the text editor you set the initial strings. Also, no text strings are saved with saved games, so don't use this command to change strings that you intend to use later, only in the same script. Clear string string - The string is cleared. See the note for 'Set string'. Add string string (a) string (b) String (b) is appended to string (a). See the note for 'Set string'. Sound left sample frequency The sample is played through the left speaker (channel 0) Sound right sample frequency As above but uses channel 1 Sound centre sample frequency Sound through channels 0 and 1 simultaneously. Sound back sample frequency Sound through channels 2 and 3, looped. This is intended for background noise. Load sample sample - Usually, samples are loaded when they are played. Use this command to load a sample in advance. Don't load too many samples as this uses memory. Erase sample sample - The sample is erased, saving memory. ST play pattern loop Starts soundtracker music playing from the specified pattern. The music will loop indefinitely (unless stated otherwise in the song itself) and is fully compatible with samples. Music is suspended on the necessary channels until the sample ends. If 'loop' is zero, the music is assumed to be looping continuously and will be restarted if a saved game is loaded. Otherwise, the music will not be restarted if a game is loaded. Med play song loop Starts med music. Med has a few limitations when compared to ST. It will stop whenever anything is loaded, such as a new screen or a sample, and also doesn't like samples playing if it is already using the channel. I include this command because I happen to like med, but you should think seriously about converting your music. 'loop' operates as described above. Music stop Stops music, ST or Med. Restart Starts the game again from the beginning.