________________________ Virtual Reality Studio Part 10 ________________________ FREESCAPE Command Language (FCL) Reference The FREESCAPE system contains a simple language definition allowing functions to be performed when certain conditions occur within the FREESCAPE environment. These commands can be used in any of 3 places: OBJECT CONDITIONS: These commands are executed when some sort of interaction with the specified object takes place. The interaction options are: SHOT? - the object is pointed to by the mouse cursor and the left mouse button pressed, a series of lines will be seen from the corners of the screen to the object being shot, these lines depict a weapon (laser). ACTIVATED? - the object is activated in a similar way to shooting an object except that the right mouse button is used and there is no visible effect. ( The object has to be within the Activate distance as defined in the Defaults). COLLIDED? - the object is collided with by either the player or an animated object. AREA CONDITIONS: These commands are executed each frame while the viewpoint is within the confines of the specified area. GENERAL CONDITIONS: These commands are executed every frame regardless of the viewpoint position. In the following list, P1, P2 and P3 refer to parameters 1, 2, and 3 respectively. These can be either a literal number or a variable. Variables are specified as followed by a variable number 0..255 (e.g. V23 for variable 23). In this case the contents of the variable will be used as the parameter value. e.g. LOOP (P1) can be, for example, LOOP (6) (or any other number) or LOOP (V23) which uses the value stored in variable 23. Parameters which must be variables are referred to as V1, V2, V3 : SETVAR (P1,V2) shows that the second parameter must be a variable. Optional parameters or commands are surrounded by square brackets[]. A list of the available commands follows along with a description of the required parameters and their functions. ---------- CONDITIONS ---------- ------------------------------------------------------------------- ACTIVATED? (ACT?) Class - Trigger Interrogator ------------------------------------------------------------------- Format: IF ACTIVATED? THEN commands... ELSE commands... ENDIF Functions: This command checks whether the selected object has been activated. This happens when the cursor is over the selected object and the right mouse button is pressed. Note: The selected object must be within the default activate range to be affected. This is set in the GENERAL menu, DEFAULT function. Example: IF ACTIVATED? THEN INVIS (4) ENDIF This condition simply informs the system that if the object is ACTIVATED then make object 4 invisible.. See Also IF, THEN, ELSE, SHOT?, COLLIDED? ------------------------------------------------------------------- ADVAR (ADD) Class - Variable Command ------------------------------------------------------------------- Format: ADDVAR (P1,P2) Function: This command performs an addition on the two supplied values, the P1 is added to the value P2, if P2 is a variable specifier then the result of the addition is stored in the variable otherwise the result is lost but the CCR flags are still altered according to the result of the addition. Meaning that if an ADDVAR command is preceded by an IF and followed by a THEN/ELSE ENDIF combination, conditions may be executed depending on whether the result was zero or not without altering the value of any variables. See also SUBVAR ------------------------------------------------------------------- AGAIN Class - Loop Command ------------------------------------------------------------------- Format: LOOP (P1) commands... AGAIN Function: This command serves to terminate a LOOP section. Upon reaching an AGAIN command the command processor will decrement the relevant LOOP counter and if the result is greater than zero, jump to the relevant LOOP address (the command immediately following the associated LOOP command). Example: INCLUDE(1) START LOOP (20) MOVE (40,0,0) AGAIN RESTART This is a simple example of using the LOOP command in animation. The rest of the commands will be explained fully later but for now the commands simply say: Include object 1 in the animation, Start the sequence when triggered, LOOP 20, move the object to the coordinates, AGAIN and restart. See also LOOP. ------------------------------------------------------------------- AND Class - Condition Command ------------------------------------------------------------------- Format: IF condition AND condition THEN commands... [ ELSE Commands...] ENDIF Function: This command combines the result of two or more condition checking commands and returns TRUE only if all of the specified checks are TRUE otherwise a FALSE result is returned. See also IF, THEN, ELSE, ENDIF, OR ------------------------------------------------------------------- ANDV Class - Variable Command ------------------------------------------------------------------- Format: ANDV (P1, P2) Function: This command performs a logical AND on the two values specified, the value P1 is ANDed with the value P2 and if P2 is a variable specifier the result is stored in the specified variable, CCR flags are set accordingly. See also ORV, NOTV ------------------------------------------------------------------- COLLIDED? (COL?) Class - Trigger Interrogator ------------------------------------------------------------------- Format: IF COLLIDED? THEN commands... [ ELSE command...] ENDIF Function: This command checks the COLLIDED flag in the status byte of the current object, a TRUE result is returned if a collision has occurred with this object since the last check, otherwise a FALSE result is returned. The COLLIDED flag on the current object is cleared upon executing this command. Example: IF COLLIDED? THEN INVIS (4) VIS (5) ENDIF In this condition the system checks if the object has been collided with. If it has then object 4 becomes invisible and object 5 becomes visible. This could be used to remove a door (object 4) and replace it with an open doorway (object 5). See also IF, THEN, ELSE, ENDIF, ACTIVATED?, SHOT> ------------------------------------------------------------------- DELAY Class - Time Command ------------------------------------------------------------------- Format: DELAY (P1) Function: This command halts all FREESCAPE functions for the specified time. The specified time (P1) is in 60ths of a second. Example: DELAY (60) would halt execution for 1 second. See also WAIT. ------------------------------------------------------------------- DESTROY Class - Object Command ------------------------------------------------------------------- Format: DESTROY (P1 [,P2]) { object[,area] } Function: This command sets the DESTROYED flag on the specified object (P1) in the specified area (P2). If no area is specified the command processor presumes that the specified object is in the current area. Note - Once an object has been destroyed it is then impossible to get the object back short of resetting. Example: IF SHOT? THEN DESTROY (4,2) ENDIF This simply asks if the current object has been shot and if so destroy object 4 in area 2. See also DESTROYED? ------------------------------------------------------------------- DESTROYED? Class - Object Interrogator ------------------------------------------------------------------- Format: IF DESTROYED? (P1 [,P2]) {object [,area]} THEN Commands... [ ELSE Commands...] ENDIF Function: This command checks the status of the specified object and returns a TRUE result if the object has been DESTROYED. See also IF, THEN, ELSE, ENDIF, DESTROY ------------------------------------------------------------------- ELSE Class - Conditional Statement ------------------------------------------------------------------- Format: IF condition THEN commands... ELSE Commands... ENDIF Function: This command exists only as part of an IF/THEN/ELSE/ENDIF combination. It marks the start of commands to execute only if the result of a previous condition was FALSE. The effectiveness of the command relies on the correct usage of the IF and THEN commands. For any Condition checking to work it is essential that the Condition be preceded by an IF command and followed by a THEN and (if required) an ELSE statement. See also IF, THEN, ENDIF ------------------------------------------------------------------- END Class - Condition Command ------------------------------------------------------------------- Format: IF condition THEN Commands... END [ELSE Commands] ENDIF Commands............ Functions: This command exits command processing before the end of the command list is reached, it allow the user to cut short the command execution on a particular condition being TRUE or FALSE. Used in the above format, if the result of the Condition is true only the commands following the THEN statement will be executed and upon reaching the END command the processor would stop processing commands from this list. Were there no END command the processor would continue executing from the command following the ENDIF statement. Note: If END is used within an animator the execution of the current animation frame is ENDed and execution continues on the next frame beginning with the command following the END command. See also IF, THEN, ELSE, ENDIF ------------------------------------------------------------------- ENDGAME Class - Player Command ------------------------------------------------------------------- Format: ENDGAME Function: This command serves to reset the environment. This can be executed on a particular condition being TRUE or FALSE, i.e. if a counter being used to store game time reaches zero then the game finishes. Example: IF COLLIDED? THEN ENDGAME ENDIF This condition simply states that if the player or another animated object collides with the selected object then end the game and reset all the flags etc. ------------------------------------------------------------------- ENDIF Class - Condition Statement ------------------------------------------------------------------- Format: IF Condition THEN commands... [ ELSE Commands...] ENDIF Function: This command terminates a conditional section. Upon reaching an ENDIF command, execution continues as normal before the IF/THEN/ELSE combination. If the result of a Condition is TRUE the commands after the THEN statement are executed and those between the ELSE statement and the ENDIF are ignored. If the result is FALSE the commands between the THEN and the ELSE are ignored and those between the ELSE and the ENDIF are executed. In either case unless an END command has been issued, command processing will continue after the ENDIF statement. See IF, THEN, ELSE ------------------------------------------------------------------- EXECUTE (EX) Class - Branch Command ------------------------------------------------------------------- Format: EXECUTE (P1) { object } Function: This command terminates command execution on the current object and continues with the command list on object (P1). The status flags and the position of the original object are still used for Object Interrogator commands. ------------------------------------------------------------------- GOTO Class - Player Command ------------------------------------------------------------------- Format: GOTO (P1 [,P2] ) (entrance [,area] ) Function: This command is used to allow player movement between the various defined area. Upon reaching this command the player will be moved to the ENTRANCE P1 in the AREA P2. If no area is specified the entrance is presumed to be in the current area. If a new area is specified, command processing will cease at this point otherwise normal command processing will continue. Example: IF COLLIDED? THEN GOTO (1,2) ENDIF The above example would be quite useful is it was desired that the player, upon colliding with a doorway (the object selected) would then be transported to Entrance 1 in Area 2 ------------------------------------------------------------------- IF Class - Condition Statement ------------------------------------------------------------------- Format: IF Condition THEN commands... [ ELSE Commands...] ENDIF Function: This command marks the start of a condition section. Immediately following the IF statement should be one or more condition commands separated by either AND or OR statements. The IF command simply serves to clear the CCR flags and prepare for the following condition. To have any effect at all the Condition should be followed by a THEN/ELSE combination otherwise execution will continue after the condition regardless of the result. See Also THEN, ELSE, ENDIF, AND, OR ------------------------------------------------------------------- INCLUDE Class - Animation Command ------------------------------------------------------------------- Format: INCLUDE (P1) {object} Function: This command is animation specific. Any attempt to execute it on an OBJECT or in LOCAL/GLOBAL conditions will have no effect. The command includes the specified object (if it is not already animated) into the animation list for the current animator. This command should be used at the very beginning of an animation before the START command so that is only called once at the start of the animation and never again until the environment is restarted. See also MOVE, START, RESTART ------------------------------------------------------------------- INVIS (IV) Class - Object Command ------------------------------------------------------------------- Format: INVIS (P1 [,P2) { object {,area] } Function: This command sets the INVISIBLE flag on object P1 in the specified area P2. if no area is specified the object is presumed to be the current area. Example: IF SHOT? THEN INVIS (9) ENDIF A simple condition which states that if the specified object is shot then object 9 will become invisible. See also INVIS? VIS? VIS ------------------------------------------------------------------- INVIS? Class - Object Interrogator ------------------------------------------------------------------- Format: IF INVIS? (P1 [,P2]) {object [, area] } THEN Command... [ ELSE Commands...] ENDIF Function: This command checks the INVISIBLE flag in the status byte of OBJECT P1 in AREA P2. If no area is specified then the object is presumed to be in the current area. The command returns a TRUE result if the specified object is INVISIBLE, otherwise a FALSE result is returned. See also INVIS, VIS, VIS? ------------------------------------------------------------------- LOOP Class - Loop Command ------------------------------------------------------------------- Format: LOOP (P1) {loop count} Function: This command marks the start of LOOP section. The commands between the LOOP and the corresponding AGAIN command will be executed P1 times. See also AGAIN ------------------------------------------------------------------- MODE Class - Player Command ------------------------------------------------------------------- Format: MODE (P1) { movement mode} Function: This command alters the current movement mode the player. In the game the player is restricted to WALK, FLY1 and FLY 2. The CAMERA modes and LOCK modes are only available in the EDITOR, therefore the value of the new mode P1 must be in the range 1-3. Any value above this will be interpreted as 3 and any less than 1 will be interpreted as 1. See also GOTO ------------------------------------------------------------------- MOVE Class - Animation Command ------------------------------------------------------------------- Format: MOVE (P1,P2,P3) {x,y,z coordinates} Function: This command is animation specific, any attempt to execute this command on an OBJECT or LOCAL/GLOBAL conditions will have no effect. The command MOVEs the members of the current animation (specified at the beginning using the INCLUDE command) by the specified amount in the X, Y and Z axis. See also INCLUDE, MOVETO ------------------------------------------------------------------- MOVETO Class - Animation Command ------------------------------------------------------------------- Format: MOVETO (P1, P2, P3) {x,y,z, coordinates} Function: This command is animation specific, any attempt to execute this command on an OBJECT or LOCAL/GLOBAL conditions will have no effect. The command MOVEs the members of the current animation (specified at the beginning using he INCLUDE command) to the specified position in the X, Y and Z area. Example: INCLUDE (3) START MOVETO (2900,0260,4760) RESTART This condition, when triggered will move object 3 to the coordinates specified in the brackets following the command MOVETO. See also INCLUDE, MOVE ------------------------------------------------------------------- NOTV Class - Variable Command ------------------------------------------------------------------- Format: NOTV (P1) Function: This command performs a logical NOT on the value specified, the value P1 and the result is stored in the specified variable. CCR flags are set accordingly. See also ANDV, ORV ------------------------------------------------------------------- OR Class - Condition Command ------------------------------------------------------------------- Format: IF Condition OR Condition THEN Commands... [ELSE Commands...] ENDIF Function: This command combines the result of two or more condition checking command and returns TRUE if any of the specified checks are TRUE otherwise a FALSE result is returned See also IF, THEN, ELSE, ENDIF, AND ------------------------------------------------------------------- ORV Class - Variable Command ------------------------------------------------------------------- Format: ORV (P1, P2) Function: This command performs a logical OR on the two values specified, the value P1 is ORed with the value P2 and if P2 is a variable specifier the result is stored in the specified variable. CCR flags are set accordingly. Example: IF SHOT? THEN ORV (2,V21) ENDIF This uses Bit 2 of Variable V21 as a flag to say that an object has been shot. Using this method it is possible to use a Variable to store a number of ON/OFF flags can be checked using the ANDV command. Example: IF ANDV (V21,2) THEN Commands.... [ ELSE Commands...] ENDIF By "ANDing" V21 with 2 and not the other way round the AND is executed without storing the result, therefore it is possible to check the state of the flags without affecting them. See also ANDV, NOTV ------------------------------------------------------------------- GETXPOS,GETYPOS,GETZPOS Class - Object Interrogator ------------------------------------------------------------------- Format: GETXPOS(V1,P2[,P3]) {variable, object[,area]} GETYPOS(V1,P2[,P3]) GETYPOS (V1,P2[,P3]) Function: These command stores the position of the specified object P2, in area P3 along the X, Y or Z axis in the specified variable V1. If no area is specified, the current area is assumed. Example: GETXPOS(V21,2) IF VAR=?(V21,1000) THEN SOUND (2) ENDIF This will get Object 2's X position and will perform a sound only if Object 2 is at position 1000 in the X axis. ------------------------------------------------------------------- PRINT Class - Instrument Command ------------------------------------------------------------------- Format: PRINT ("message..."P1) (Message, instrument) Function: This command allows the user to print a message to a defined TEXT WINDOW type instrument (see INSTRUMENTS). The message between the quotation marks is printed to the instrument number P1 if the instrument exists and if it is a TEXT WINDOW type. The message can be split into several lines (if the TEXT WINDOW is big enough) by using /N to begin a new line. ------------------------------------------------------------------- RESTART Class - Animation Command ------------------------------------------------------------------- Format: RESTART Function: The command is animation specific, any attempt to execute it on an OBJECT or in LOCAL or GLOBAL conditions will have no effect. After executing this command execution of the animation will continue at the position set by the START command. If no START command has been executed the RESTART command will set execution to continue from the start of the animation. See also START ------------------------------------------------------------------- REDRAW Class- Instrument Command ------------------------------------------------------------------- Format: REDRAW Function: This command will force an immediate redraw of the FREESCAPE view window. Any objects whose status have changed since the last frame update will be displayed in their new state. Example: LOOP (10) TOGVIS (2) REDRAW AGAIN This will toggle the visibility of Object 2 ten times and REDRAW the FREESCAPE view each frame. ------------------------------------------------------------------- REMOVE Class-Animation Command ------------------------------------------------------------------- Format: REMOVE (P1) (Object) Function: This command works in the opposite way to INCLUDE. The object specified P1 will be removed from the animation. This command can be incorporated into the animation controller, e.g. to remove objects from the animation one at a time during animation. This command may only be used in animation. ------------------------------------------------------------------- SOUND Class - Sound Command ------------------------------------------------------------------- Format: SOUND (P1) { sound number } Function: This command will immediately perform the sound P1. See also SYNCSND ------------------------------------------------------------------- SETVAR (SET) Class - Variable Command ------------------------------------------------------------------- Format: SETVAR (P1,V2) Function: This command sets the variable V2 to the value P1. If V2 is not a variable specified then the command has no effect. ------------------------------------------------------------------- SHOT? Class - Trigger Interrogator ------------------------------------------------------------------- Format: IF SHOT? THEN Commands... {ELSE Commands...} ENDIF Function: This command checks the SHOT flag in the status byte of the current object. If the object has been shot since the last time checked then the command returns a TRUE result otherwise a FALSE result is returned. Execution of this command also clears the SHOT flag on the current object. See also ACTIVATED?, COLLIDED? ------------------------------------------------------------------- START Class - Animation Command ------------------------------------------------------------------- Format: START Function: This command is animation specific, any attempt to execute it on an OBJECT or LOCAL or GLOBAL conditions will have no effect. The command marks the start of the animation command list. The instruction after the START command will be the point at which the RESTART command will continue execution from. The START command should be placed after any INCLUDE command as INCLUDEs after the START will be executed each time through the animation loop, this wastes time and has no useful effect. See also INCLUDE, RESTART ------------------------------------------------------------------- STARTANIM Class- Animation Command ------------------------------------------------------------------- Format: STARTANIM (P1[,P2}) { animator [,area]} Function: This command will start an animation controller going. At the beginning of a game all animation controllers are marked as STOPPED. To begin the animation a STARTANIM command must be executed. The STARTANIM command will also re-enable an animation controller which has been stopped using the STOPANIM command. Example: IF COLLIDED? THEN STARTANIM (2) This condition was placed on a selected object. If the object is collided by the player then start the second animation controller (2). See also STOPANIM, TRIGANIM, WAITTRIG ------------------------------------------------------------------- STOPANIM Class - Animation Command ------------------------------------------------------------------- Format: STOPANIM (P1[,P2]) { animator [,area]} Function: This command will stop an animation controller, no commands will be executed on the controller until it is started using the STARTANIM command. Upon receiving a STARTANIM command the animation controller will continue execution from the point at which the STOPANIM command was received. See also STARTANIM, TRIGANIM, WAITTRIG ------------------------------------------------------------------- SUBVAR (SUB) Class-Variable Command ------------------------------------------------------------------- Format: SUBVAR (P1, P2) Function: This command performs a subtraction on the two supplied values, the value P1 is subtracted from the value P2. If P2 is a Variable specifier then the result of the subtraction is stored in the variable otherwise the result is lost but the CCR flags are still altered according to the result of the subtraction. Therefore if a SUBVAR command is preceded by an IF and followed by a THEN/ELSE ENDIF combination, conditions may be executed depending on whether the result was zero or not without altering the value of any variables. See also ADDVAR, SETVAR ------------------------------------------------------------------- SYNCSND Class - Sound Command ------------------------------------------------------------------- Format: SYNCSND (P1) {sound number } Function: This command will execute the specified sound P1 in sync with the next complete frame update. Note the REDRAW command will also perform a synchronized sound. See also SOUND ------------------------------------------------------------------- THEN Class - Condition Statement ------------------------------------------------------------------- Format: IF Condition THEN Commands... [ELSE Commands... ] ENDIF Function: This command checks the status of the ZERO flag in the CCR. If the contents are TRUE then the commands following the THEN statement are executed until either an ELSE of ENDIF statement is found. If an ELSE is found the command s following it are ignored up until an ENDIF or the end of the command list. If an ENDIF is found then normal command execution will continue with the following command. The THEN command is the only command which examines the result of a condition, so an IF ELSE ENDIF combination without a THEN command will product incorrect results. See also IF, ELSE, ENDIF, AND, OR ------------------------------------------------------------------- TIMER? Class - Trigger Interrogator ------------------------------------------------------------------- Format: IF TIMER? THEN Commands... [ELSE Commands...] ENDIF Function: This command checks the Timer flag, the command returns a TRUE result if a timelapse of the amount specified in the defaults setup section has passed, otherwise a FALSE result is returned. This command is only really useful in LOCAL and GLOBAL conditions as these are the only conditions which are executed each frame, any TIME commands on OBJECTS will only be checked when some form of interruption takes place with the object. ------------------------------------------------------------------- TOGVIS (TOG) Class - Object Command ------------------------------------------------------------------- Format: TOGVIS (P1 [,P2]) { object [,area]} Function: This command toggles the status of the VISIBLE flag in the status byte of object P1 in area P2. If no area is specified the object is presumed to be in the current area. See also VIS, INVIS, VIS?, INVIS? ------------------------------------------------------------------- TRIGANIM Class - Animation Command ------------------------------------------------------------------- Format: TRIGANIM (P1) { animator } Function: This command sets the TRIGGER flag in the status byte of animation controller P1. A WAITTRIG command within the animation controller will register this trigger. If no WAITTRIG commands exist in the animation controller a TRIGANIM command will have no effect on this animator. See also STARTANIM, STOPANIM, WAITTRIG ------------------------------------------------------------------- UPDATE Class- Instrument Command ------------------------------------------------------------------- Format: UPDATE (P1) { instrument } Function: To Update Instrument (P1) in the Test Screen. ------------------------------------------------------------------- VAR=? (V=?) Class - Variable Command ------------------------------------------------------------------- Format: IF VAR=?(P1,P2) THEN Commands... [ELSE Commands...] ENDIF Function: This command will compare the values of P1 and P2 and return a TRUE result if the value of P1 is greater than that of P2, otherwise a FALSE value is returned. See also SETVAR, ADDVAR, SUBVAR, VAR>?, VAR? (V>?) Class - Variable Command ------------------------------------------------------------------- Format: IF VAR>? (P1,P2) THEN Commands... [ELSE Commands...] ENDIF Function: This command will compare the values of P1 and P2 and returns a TRUE result if the value of P1 is greater than that of P2, otherwise a FALSE result is returned. See also SETVAR, ADDVAR, SUBVAR, VAR>?, VAR=? ------------------------------------------------------------------- IF VAR?, VAR=? ------------------------------------------------------------------- VIS (V) Class - Object Command ------------------------------------------------------------------- Format: VIS (P1 [,P2]) { object [,area] } Function: This command clears the INVISIBLE flag on OBJECT P1 in the specified AREA P2, making it visible. If no area is specified the object is presumed to be in the current area. See also INVIS?, VIS?, INVIS, TOGVIS ------------------------------------------------------------------- VIS? Class - Object Interrogator ------------------------------------------------------------------- Format: VIS? (P1 [P2]) { object [area] } Function: This command checks the INVISIBLE flag in the status byte of OBJECT P1 in AREA P2. If no area is specified then the object is presumed to be in the current area. The command returns a TRUE result if the specified object is VISIBLE, otherwise a FALSE result is returned. See also VIS, INVIS, TOGVIS, INVIS? ------------------------------------------------------------------- WAIT Class - Time Command ------------------------------------------------------------------- Format: WAIT Function: This command halts processing of the current command list and stores information about the current command list on an internal stack. The FREESCAPE processing is then allowed to continue, processing any more required conditions, animations and player movements, when the next frame comes round execution of the command list will continue from the command following the WAIT command. See also DELAY ------------------------------------------------------------------- WAITTRIG Class - Animation Command ------------------------------------------------------------------- Format: WAITTRIG Function: This command is animation specific, any attempt to execute it on an 0BJECT or in LOCAL or GLOBAL conditions will have no effect. The command will check the TRIGGER flag in the status byte of the animation controller. If the flag has been set by use of the TRIGANIM command, the flag will be cleared and execution will continue as normal, otherwise execution will be stopped at the WAITTRIG command and the execution of the animation command list will be stopped. Upon reaching the current animation controller the next frame the WAITTRIG command is the first to be of the WAITTRIG command until a TRIGANIM command sets the TRIGGER flag. See also TRIGANIM, STARTANIM, STOPANIM *** END ***