x_Speed - 3D Construction Kit Manual

3D CONSTRUCTION KIT

15. THE FREESCAPE COMMAND LANGUAGE

The Freescape system contains a simple language definition allowing functions to be performed when certain conditions occur within the Freescape environment. The commands can be used in any of three places;

GENERAL Conditions : These commands are executed every frame regardless of the area currently occupied. Note that General Condition number one is only called after a RESET.

LOCAL Conditions : Only the Local Conditions defined in the currently occupied area are processed. These commands are executed each frame.

PROCEDURE Conditions : These commands are only called from other conditions by using the CALL command.

In the following list P1, P2 and P3 or V1, V2 or V3 refer to parameters 1, 2 and 3 respectively. These can either be a literal number (referred to as P1, P2 or P3) or a variable number. In this case the contents of the variable will be used as the parameter value. Parameters which must be Variables are referred to as V1, V2, V3 e.g.

SETV (P1,V2)

shows that the second parameter must be a variable and the first is an absolute value

Optional parameters or commands are surrounded by square brackets [].

A list of the available commands follows with a description of the required parameters and their functions.

CONDITIONS

ADCV

Full Name: Add to Variable with Carry

Class: Variable Manipulation

Format: ADCV P1 V2

Function:
This adds the absolute value P1 to variable V2. If the carry flag was set before the execution of this instruct, one (the carry) is also added to the result. If the result is greater than 255 then the value wraps around (becoming the would-be result minus 256) and the carry flag is set.

See also: ADDV, SUBV, SBCV

ADDV

Full Name: Add to Variable

Class: Variable Manipulation

Format: ADDV P1 V2

Function:
This adds the absolute value P1 to V2. If the result is greater than 255, then the value wraps around (becoming the would-be result minus 256) and the carry flag is set.

See also: ADCV, SUBV, SBCV

AND

Full Name: And

Class: Conditional Instruction

Format:

   IF -xx-
   AND
   IF -xx-
   THEN
   <commands>
   [ELSE
   <commands>
   ENDIF

Function:
This command combines the result of two or more condition checking commands and returns true only if all the specified checks are true otherwise a false result is returned.

See also: IFEQ, IFLT, IFGT, THEN, ELSE, ENDIF, OR

ANDV

Full Name: AND Variable

Class: Variable Manipulation

Format: ANDV P1 V2

Function:
This command performs the logical AND on the absolute value P1 and Variable number V2 and the result is stored in Variable number V2. This instruction requires some understanding of Binary and Logical functions.

See also: ORV, XORV

CMPV

Full Name: Compare Variable with Absolute Value

Class: Variable Manipulation

Format: CMPV P1 V2

Function:
This command compares the value of P1 with V2. The value held in the variable specified as V2 is subtracted from the constant P1. The zero and carry flags are set accordingly. The contents of V2 remain unchanged. CMPV usually precedes an IFEQ, IFLT or IFGT instruction, as these act on the result of the comparison.

Example: Variable 23 holds a count of objects collected in a game.
No more than 5 objects are allowed to be carried at any one time. To see if an object may be picked up would require a check to see if less than five objects are carried. This could be performed with the following:

   CMPV 5 23 (compare contents of V23 with 5)
   IFLT      (if V3 is less than 5)
   THEN      (then)
   <Pick up object>
   ELSE
   <Object cannot be carried>
   ENDIF

See also: IFEQ, IFLT, IFGT, THEN, ELSE, ENDIF, OR

CALL

Full Name: Call Procedure

Class: Miscellaneous Instruction

Format: CALL P1

Function:
This calls the Procedure number P1. Processing will continue from the next instruction in the current condition list when the procedure exits.

Note: Do not call a procedure from within itself or the computer will lock up!

CROSS

Full Name: Cross

Class: Miscellaneous Instruction

Format: CROSS P1 (either 0 or 1)

Function:
Turns the centre cross ON or OFF (0 is off and 1 is on). It defaults to 0 (on).

COLOUR

Full Name: Colour

Class: Miscellaneous Instruction

Format: COLOUR P1 P2

Function:
To change the colour of the 3D View window.

Amstrad CPC & Commodore 64

P1 refers to the colour number (0-3)

P2 refers to the palette value (CPC 0-26, C64 0-15)

Spectrum

P1 refers to the attribute type;
0 = Ink
1 = Paper
2 = Bright
3 = Flash

P2 refers to the relevant attribute value;
Ink 0 - 7
Paper 0 - 7
Bright 0 - 1
Flash 0 - 1

DELAY

Full Name: Delay

Class: Miscellaneous Instruction

Format: DELAY P1

Function:
This command halts all Freescape functions for the specified time. The specified time P1 is in 50ths of a second.

Example: DELAY 50 (would halt execution for 1 second.)

DESTROY

Full Name: Destroy Object

Class: Object Manipulation

Format: DESTROY P1 [P2] (object [area] )

Function:
This command marks the given object as destroyed. If no area is specified then it is assumed the object is in the current area.

Example:

   IFSHOT 4 2
   THEN
   DESTROY 4 2
   ENDIF

This simply asks if object 4 in area 2 has been shot and if so destroy object 4 in area 2.

ELSE

Full Name: Else

Class: Conditional Instruction

Format:

   IF -xx-
   THEN
   <commands>
   [ELSE
   <commands...]>
   ENDIF

Function:
This command exists only as part of an IF -xx-/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 -xx- command and followed by a THEN and (if required) an ELSE statement.

See also: THEN, ENDIF

END

Full Name: End Command Processing

Class: Miscellaneous Instruction

Format:

   IF -xx-
   THEN
   /lt;commands...>
   END
   [ELSE
   <commands...]>
   ENDIF
   <commands...>

Function:
This command exits command processing before the end of the command list is reached. It allows 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 the commands from this list. Were there no END command the processor would continue executing from the command following the ENDIF statement.

Note:
If used in a procedure then processing returns to the command after the CALL instruction (in the condition list which called it).

ENDGAME

Full Name: End Game

Class: Miscellaneous Instruction

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 and a RESET of the environment is performed.

Example: In this example variable 10 has been assigned to store game time.

   CMPV 0 10
   IFEQ
   THEN
   ENDGAME
   ENDIF

ENDIF

Full Name: End If Condition

Class: Conditional Instruction

Format:

   IF -xx-
   THEN
   <commands...>
   [ELSE
   <commands...]>
   ENDIF

Function:
This command terminates a conditional section. Upon reaching an ENDIF command, execution continues as normal before the IF -xx-/THEN/ELSE combination. If the result of a Condition is true the commands after the THEN statements 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 statements 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 also:
IF -xx-, Interrogators, THEN, ELSE

GOTO

Full Name: Go To Entrance/Area

Class: Vehicle Instruction

Format: GOTO P1 [P2] (entrance [area] )

Function:
This command is used to allow player movement between the various defined areas and/or entrances. 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:

   IFSHOT 9
   THEN
   GOTO 1 2
   ENDIF

The above example would be quite useful if it was desired that the player, upon shooting a doorway (object 9) would then be transported to Entrance 1 in Area 2.

IFACTIVE

Full Name: If Object Active

Class: Conditional Instruction (Interrogator)

Format:

   IFACTIVE P1 [P2]
      (P1 is an object number and
       P2 is an optional area number)
   THEN
   <commands...>
   ENDIF

Function:
This command checks whether the selected object has been activated.

Example:

   IFACTIVE 4
   THEN
   INVIS 4
   ENDIF

This condition simply informs the system that if object 4 is activated then make object 4 invisible.

Note: IF's cannot be nested!

IFCRUSH

Full Name: If Crush Occurring

Class: Conditional Instruction (Interrogator)

Format:

   IFCRUSH
   THEN
   <commands...>
   ENDIF

Function:
This Interrogator checks to see if the player occupies the same space as an object in the same area. If so, a true is returned allowing the result of the check to be dealt with by a THEN/[ELSE]/ENDIF construct. A positive result from the interrogator is usually obtained when an object is VISiblised and that object's bounding cube encloses the player's view point. It can also occur when the view point is moved (via a GOTO) to a space currently occupied by another object.

IFEQ

Full Name: If Equal

Class: Conditional Instruction

Format:

   IFEQ
   THEN
   <commands...>
   [ELSE
   <commands...]>
   ENDIF

Function:
This command returns a true result if the preceding command had a zero result. This instruction will normally follow a CMPV, ADDV, ADCV, SUBV or SBCV instruction and act on the result of it. A THEN/[ELSE]/ENDIF construct should follow this instruction.

Note: IF's cannot be nested!

IFFALL

Full Name: If Fallen

Class: Conditional Instruction (Interrogator)

Format:

   IFFALL
   THEN
   <commands...>
   [ELSE
   <commands...]>
   ENDIF

Function:
This Interrogator returns true if the player has fallen past the safe fall height, specified as FALL ABILITY in the SETUP menu. The result of the check can then be dealt with by a THEN/[ELSE]/ENDIF construct.

IFGT

Full Name: If Greater Than

Class: Conditional Instruction

Format:

   IFGT
   THEN
   <commands...>
   [ELSE<commands...]>
   ENDIF

Function:
This command returns a true result if the preceding command had: (i) set the carry flag and (ii) unset the zero flag. This instruction will normally follow a CMPV, ADDV, ADCV, SUBV or SBCV instruction and act on the result of it. A THEN/[ELSE]/ENDIF construct should follow this instruction.

Note: IF's cannot be nested!

IFHIT

Full Name: If Object Hit

Class: Conditional Instruction (Interrogator)

Format:

   IFHIT P1
   THEN
   <commands...>
   [ELSE
   <commands...]>
   ENDIF

Function:
This command checks if an object P1 has been collided with (or walked on). A true or false is returned.

Example:

   IFHIT 4
   THEN
   INVIS 4
   VIS 5
   ENDIF

In this condition the system checks if object 4 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).

Note: IF's cannot be nested!

See also: IFACTIVE, IFSHOT

IFLT

Full Name: If Less Than

Class: Conditional Instruction

Format:

   IFLT
   THEN
   <commands...>
   [ELSE
   <   commands...]>
   ENDIF

Function:
This command returns a true result if the preceding command had: (i) unset the carry flag and (ii) unset the zero flag. This instruction will normally follow a CMPV, ADDV, ADCV, SUBV or SBCV instruction and act on the result of it. A THEN/[ELSE]/ENDIF construct should follow this instruction.

Note: IF's cannot be nested!

IFSENSED

Full Name: If Sensed

Class: Conditional Instruction (Interrogator)

Format:

   IFSENSED
   THEN
   <commands...>
   [ELSE
   <commands...]>
   ENDIF

Function:
This Interrogator returns true if the player is occupying space that is detectable by a sensor. The result of the interrogator is then acted upon bu a THEN/[ELSE]/ENDIF construct placed after it. The effectiveness of a sensor can be set by altering it's ATTRIBUTES.

IFSHOT

Full Name: If Shot

Class: Conditional Instruction (Interrogator)

Format:

   IFSHOT P1   (P1 is an object)
   THEN
   <commands...>
   [ELSE
   <commands...]
   ENDIF

Function:
Checks if you have just shot object P1, returning a true or false.

IFTIMER

Full Name: If Timer

Class: Conditional Instruction (Interrogator)

Format:

   IFTIMER
   THEN
   <commands...>
   [ELSE
   <commands...]>
   ENDIF

Function:
This command checks the TIMER flag, the command returns a true result if a time lapse of the amount specified in the SETUP section has passed, otherwise a false result is returned. Use the TIMER command to set TIMER frequency.

IFVIS

Full Name: If Object Visible

Class: Conditional Instruction (Interrogator)

Format:

   IFVIS P1 [P2]
      (P1 is an object number and
       P2 is an optional area number.)
   THEN
   <commands...>
   [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 visible, otherwise a false result is returned.

Example 1:

   IFHIT 12
   THEN
   ELSE     (if object 12, a door say,
             is not hit then end)
   END
   ENDIF    (if it is then process the following)
   IFVIS 4  (if object 4, a switch perhaps,
             is visible)
   THEN     (then)
   GOTO 1 5 (go to entrance 1 in area 5)
   ENDIF

Example 2: To check if an object is invisible, check to see if it is visible but act on a false outcome.

   IFVIS 4
   THEN
   ELSE
   Insert your commands here...
   ENDIF

INVIS

Full Name: Invisiblise Object

Class: Object Manipulation

Format: INVIS P1 [P2]

Function:
Makes the object P1 in area P2 (optional) invisible. If the area is not specified, then object P1 in the current area is made invisible.

Example:

   IFSHOT 8
   THEN
   INVIS 9
   ENDIF

A simple condition which states that if object 8 is shot then object 9 will become invisible.

See also: VIS

MODE

Full Name: Movement Mode

Class: Vehicle Instruction

Format: MODE P1 (P1 = movement mode code)

Function:
This command alters the current movement mode of the player in the game. The player is restricted to CRAWL, WALK, RUN, FLY1 and FLY2. The value of the new mode P1 must be in the range of 0-4. Any value above this will be interpreted as 4 and any value less than 0 will be interpreted as 0. The parameter and what it represents are listed below:

0 = Crawl
1 = Walk
2 = Run
3 = Fly1
4 = Fly2

OR

Full Name: Or

Class: Conditional Instruction

Format:

   IF -xx-
   OR
   IF -xx-
   THEN
   <commands...>
   [ELSE
   <commands...]>
   ENDIF

Function:
This command combines the result of two or more condition checking commands and returns true if any of the specified checks are true otherwise a false result is returned.

See also: IFEQ, IFLT, IFGT, THEN, ELSE, ENDIF, AND

ORV

Full Name: OR Variable

Class: Variable Manipulation

Format: ORV P1 V2
Function:
This command performs the logical OR on the two values specified. The value P1 is ORed with the variable V2 and the result is stored in variable V2. Flags are set accordingly. This instruction requires some understanding of Binary and Logical functions.

Example 1:

   IFSHOT 8 (object)
   THEN
   ORV 2 21
   ENDIF

This uses bit 2 of variable V21 as a flag to say that object 8 has been shot. Using this method it is possible to use a variable to store a number of on/off flags. The flags can be checked using the ANDV command, e.g.

Example 2:

   ANDV 2 21
   IFEQ
   THEN
   <commands...>
   [ELSE
   <commands...]>
   ENDIF

PRINT

Full Name: Print Message

Class: Miscellaneous Instruction

Format: PRINT P1 xx yy

Function:
This command will print the specified message number P1 from the message list at the X (xx) and Y (yy) co-ordinates specified. These co-ordinates are in characters.

Note: You must use a TEXTCOL command to set the colour.

REDRAW

Full Name: Redraw View Window

Class: Miscellaneous Instruction

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 will be displayed in their new state.

SETV

Full Name: Set Variable Value

Class: Variable Manipulation

Format: SETV P1 V2

Function:
Sets the variable V2 to the value P1.

SOUND

Full Name: Sound

Class: Miscellaneous Instruction

Format: SOUND P1

Function:
This command will immediately perform the sound number P1. The parameter P1 must be in the range 0-12, the sounds corresponding to the value of the parameter are listed in the Appendix.

SBCV

Full Name: Subtract with Carry

Class: Variable Manipulation

Format: SBCV P1 V2

Function:
This subtracts the absolute value P1 from the variable V2. If the carry flag was set before the execution of this instruction, then the result is decremented further by 1.

See also: ADDV, ADCV, SUBV

SUBV

Full Name: Subtract

Class: Variable Manipulation

Format: SUBV P1 V2

Function:
This subtracts the absolute value P1 from the variable V2.

See also: ADDV, ADCV, SBCV

SYNCSND

Full Name: Synchronise Sound

Class: Miscellaneous Instruction

Format: SYNCSND P1

Function:
This command will execute the specified sound P1 in sync with the next complete frame update. The parameter P1 must be in the range 0-12, the sounds corresponding to the value of the parameter are listed in the Appendix.

See also: SOUND

TEXTCOL

Full Name: Text Colour

Class: Miscellaneous Instruction

Format: TEXTCOL P1

Function:
This command is used to set the text and background colour for printing messages. P1 is calculated thus:

Spectrum
P1 = (ink) + (paper x 8) + (64 if Bright required) + (128 if Flash required)

Amstrad CPC
P1 = (ink) + (paper x 4)

Commodore 64
P1 = (ink) + (paper x 16)

THEN

Full Name: Then

Class: Conditional Statement

Format:

   IF -xx-
   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 or ENDIF statement is found. If an ELSE is found the commands 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 -xx-, ELSE, ENDIF combination without a THEN command will produce incorrect results.

TIMER

Full Name: Timer Set Frequency

Class: Miscellaneous Instruction

Format: TIMER P1

Function:
The TIMER instruction sets the frequency at which the timer flag is set, for detection by an IFTIMER instruction. P1 is the interval time, and is in 50ths of a second.

TOGVIS

Full Name: Toggle Visibility

Class: Object Manipulation

Format: TOGVIS P1 [P2] (object [area] )

Function:
This command will make an invisible object visible or a visible object invisible. If no area is specified the object is presumed to be in the current area.

VIS

Full Name: Visiblise

Class: Object Manipulation

Format: VIS P1 [P2] (object [area] )

Function:
This command makes an object visible.

See also: INVIS, IFVIS, TOGVIS

XORV

Full Name: XOR Variable

Class: Variable Manipulation

Format: XORV P1 V2

Function:
This command performs the logical EXCLUSIVE OR (EOR/XOR) on the two values specified. The value P1 is XORed with the variable V2 and the result is stored in variable V2. Flags are set accordingly. This instruction requires some understanding of Binary and Logical functions.

Example 1:

   IFACTIVE 12
    (object)
   THEN
   XORV 8 21
   ENDIF

This uses bit 3 (the fourth bit) of variable V2 as a flag to say that object 12 has been activated or deactivated. This allows us to toggle a flag using only one bit. Possible uses include keeping track of switches which toggle between on and off. Using this method it is possible to use a variable to store up to eight on/off flags. The flags can be checked using the ANDV command, e.g.

Example 2:

   ANDV 8 21
   IFEQ
   THEN
   <commands...>
   [ELSE
   <commands...]>
   ENDIF