LBA1:Life script
Life Script is much more sophisticated and powerful than Track Script, though not as advanced as today's programming languages. Life Script is the Main script that controls Actor behaviour.
Life Script is divided into so-called Comportments. Comportments are separated blocks of code, one of which is constantly executed in a loop. At any time one of the Comportments is executing (unless the Script has been stopped), and when the execution gets to its end (END_COMPORTMENT statement), it is looped back to the beginning (or to another comportment's beginning, if SET_COMPORTMENT(_OBJ) has been called), and so on. Execution can be moved to another Comportment with the SET_COMPORTMENT(_OBJ) statement, but the move occurs only at the end of the current comportment (or at the next RETURN command). Life Scripts of all Actors are run simultaneously.
Initially the first Comportment of Life Script is executed. Usually the Actor initial behaviour is set here, and then the execution is moved to another Comportment which perform interactions with other Actors and the Hero.
Each command code is one byte long, and after it there are parameters (or not), or other things. After command's parameters there is a next command byte, and so on. At the end of the script there is a 0x00 (END) command.
This document describes the commands and their parameters in a technical way. For more details on usage and effects see other sources (LBArchitect's help may contain some).
If the command does not have any additional bytes, next command starts immediately after the command byte.
Life Script commands are non-blocking, which means that each command executes immediately after previous one (there are no WAIT_ commands) and the whole script runs very fast. Special techniques must be used if a wait is necessary.
Some commands in the Life Script are virtual - this means that the command is present in decompiled script (text form), and does not serve any purpose in compiled (binary) form of the script, so it may or may not be there. Virtual commands still have opcodes associated to them.
Command macros[edit]
| Code | (dec) | Name | Description | Parameters |
|---|---|---|---|---|
| 0x00 | 0 | END | Marks end of the script | |
| 0x01 | 1 | NOP | No operation (never used) | |
| 0x02 | 2 | SNIF (IF-type) | negated SWIF (internal use only) | |
| 0x03 | 3 | OFFSET | jumps to specified offset (never used) | param1: 2 bytes (0..65535) - address (offset) in the script |
| 0x04 | 4 | NEVERIF (IF-type) | negated ONEIF (internal use only) | |
| 0x05 | 5 | unused | ||
| 0x06 | 6 | NO_IF (IF-type) | negated IF (probably not used) | |
| 0x07 | 7 | unused | ||
| 0x08 | 8 | unused | ||
| 0x09 | 9 | unused | ||
| 0x0A | 10 | LABEL | Marks point in the script (never used) | param1: 1 byte (0..255) - ID of the label |
| 0x0B | 11 | RETURN | returns to the beginning of current comportment | |
| 0x0C | 12 | IF (IF-type) | Tests if condition is true | |
| 0x0D | 13 | SWIF (IF-type) | Tests if condition is true and alternating | |
| 0x0E | 14 | ONEIF (IF-type) | Tests if condition is true once | |
| 0x0F | 15 | ELSE | Jumps to specified address (skips the next block) | param1: 2 bytes (0..65535) - address (offset) to go to |
| 0x10 | 16 | ENDIF (virtual) | Marks end of IF-type block | |
| 0x11 | 17 | BODY | Selects a new Body for the Actor | param1: 1 byte (0..255) - virtual index of the new Body |
| 0x12 | 18 | BODY_OBJ | Selects a new Body for another Actor |
|
| 0x13 | 19 | ANIM | Selects a new Animation for the Actor | param1: 1 byte (0..255) - virtual index of the new Animation |
| 0x14 | 20 | ANIM_OBJ | Selects a new Animation for another Actor |
|
| 0x15 | 21 | SET_LIFE | Same as SET_COMPORTMENT (never used) | param1: 2 bytes (0..65535) - address (offset) of the target COMPORTMENT |
| 0x16 | 22 | SET_LIFE_OBJ | Same as SET_COMPORTMENT_OBJ (never used) |
|
| 0x17 | 23 | SET_TRACK | Starts execution of the Actor's Track Script | param1: 2 bytes (-1..32767) - address (offset) in the Track Script; -1 causes stop of execution of the script |
| 0x18 | 24 | SET_TRACK_OBJ | Starts execution of another Actor's Track Script |
|
| 0x19 | 25 | MESSAGE | Displays dialogue text and plays associated speech sound | param1: 2 bytes (0..32767) - virtual index of the text entry to be displayed |
| 0x1A | 26 | FALLABLE | Controls gravity for the Actor | param1: 1 byte (0..1) - (boolean flag) 1 = Actor can fall, 0 = it cannot |
| 0x1B | 27 | SET_DIRMODE | Controls direction mode of the Actor |
|
| 0x1C | 28 | SET_DIRMODE_OBJ | Controls direction mode of another Actor |
|
| 0x1D | 29 | CAM_FOLLOW | Sets the camera to follow specified Actor | param1: 1 byte (0..255) - index of the Actor |
| 0x1E | 30 | SET_BEHAVIOUR | Sets hero's behaviour | param1: 1 byte (0..4) - behaviour ID (0 = normal, 1 = athletic, 2 = aggressive, 3 = discrete, 4 = proto-pack) |
| 0x1F | 31 | SET_FLAG_CUBE | Sets cube (local) flag |
|
| 0x20 | 32 | COMPORTMENT (virtual) | Marks beginning of the comportment block | param1: 1 byte (0..255) - probably ID of the comportment |
| 0x21 | 33 | SET_COMPORTMENT | Sets next comportment | param1: 2 bytes (0..65535) - address (offset) of the new comportment |
| 0x22 | 34 | SET_COMPORTMENT_OBJ | Sets next comportment for another Actor |
|
| 0x23 | 35 | END_COMPORTMENT | Marks end of comportment | |
| 0x24 | 36 | SET_FLAG_GAME | Sets game (global) flag |
|
| 0x25 | 37 | KILL_OBJ | Deletes an Actor and stops its scripts | param1: 1 byte (0..255) - ID of the Actor |
| 0x26 | 38 | SUICIDE | Deletes the Actor and stops its scripts | |
| 0x27 | 39 | USE_ONE_LITTLE_KEY | Removes one little key from hero's pocket | |
| 0x28 | 40 | GIVE_GOLD_PIECES | removes an amount of money from hero's pocket | param1: 2 bytes (0..999) - amount of money |
| 0x29 | 41 | END_LIFE | Stops executing the Actor's Life Script | |
| 0x2A | 42 | STOP_CURRENT_TRACK | Pauses Actor's Track Script | |
| 0x2B | 43 | RESTORE_LAST_TRACK | Resumes Actor's Track Script | |
| 0x2C | 44 | MESSAGE_OBJ | Displays dialogue text said by another Actor |
|
| 0x2D | 45 | INC_CHAPTER | Increases CHAPTER variable by one | |
| 0x2E | 46 | FOUND_OBJECT | Displays object found message | param1: 1 byte (0..255) - index of the inventory item |
| 0x2F | 47 | SET_DOOR_LEFT | Sets door position to the far-left | param1: 2 bytes (-32768..32767) - distance |
| 0x30 | 48 | SET_DOOR_RIGHT | Sets door position to the near-right | param1: 2 bytes (-32768..32767) - distance |
| 0x31 | 49 | SET_DOOR_UP | Sets door position to the far-right | param1: 2 bytes (-32768..32767) - distance |
| 0x32 | 50 | SET_DOOR_DOWN | Sets door position to the near-left | param1: 2 bytes (-32768..32767) - distance |
| 0x33 | 51 | GIVE_BONUS | Pops bonus from the Actor | param1: 1 byte (0..1) - (boolean) if bonus popping should be disabled on the Actor's death |
| 0x34 | 52 | CHANGE_CUBE | Changes the Scene | param1: 1 byte (0..255) - index of the target Scene |
| 0x35 | 53 | OBJ_COL | Controls the Actor's collisions with other Actors | param1: 1 byte (0..1) - (boolean) 1 = Actor collides with other Actors |
| 0x36 | 54 | BRICK_COL | Controls the Actor's collisions with Bricks (terrain) | param1: 1 byte (0..2) - 1 = Actor collides with Bricks, 2 = unknown |
| 0x37 | 55 | OR_IF (IF-type) | Tests if condition is true | |
| 0x38 | 56 | INVISIBLE | Controls visibility of the Actor | param1: 1 byte (0..1) - (boolean) 0 = Actor is visible, 1 = Actor is not visible |
| 0x39 | 57 | ZOOM | Controls the camera zoom | param1: 1 byte unsigned (0..1) - (boolean) 1 = enable zoom, 0 = disable zoom |
| 0x3A | 58 | POS_POINT | Immediately moves the Actor to the Point | param1: 1 byte (0..255) - index of the Point |
| 0x3B | 59 | SET_MAGIC_LEVEL | Sets the hero's magic level | param1: 1 byte (0..4) - target magic level |
| 0x3C | 60 | SUB_MAGIC_POINT | Subtracts from hero's magic points | param1: 1 byte (0..255) - amount of magic points to be subtracted |
| 0x3D | 61 | SET_LIFE_POINT_OBJ | Sets life points for an Actor |
|
| 0x3E | 62 | SUB_LIFE_POINT_OBJ | Subtracts from an Actor's life points |
|
| 0x3F | 63 | HIT_OBJ | Damages an Actor |
|
| 0x40 | 64 | PLAY_FLA | Plays a FLA movie | param1: null-terminated string - name of the fla file |
| 0x41 | 65 | PLAY_MIDI | Plays MIDI music | param1: 1 byte (0..255) - index of the MIDI track |
| 0x42 | 66 | INC_CLOVER_BOX | Increments number of hero's clover boxes | |
| 0x43 | 67 | SET_USED_INVENTORY | Marks inventory item as used | param1: 1 byte (0..255) - index of the inventory item |
| 0x44 | 68 | ADD_CHOICE | Adds a text line to the choice pool | param1: 2 bytes (0..32767) - virtual index of the text entry |
| 0x45 | 69 | ASK_CHOICE | Asks for the choice | param1: 2 bytes (0..32767) - virtual index of the question text entry |
| 0x46 | 70 | BIG_MESSAGE | Displays full screen text message | param1: 2 bytes (0..32767) - virtual index of the text entry |
| 0x47 | 71 | INIT_PINGOUIN | Initializes the Nitro-Mecha-Penguin Actor | param1: 1 byte (0..255) - probably index of the Actor to init as penguin |
| 0x48 | 72 | SET_HOLO_POS | Marks a Holomap position | param1: 1 byte (0..255) - index of the holomap position |
| 0x49 | 73 | CLR_HOLO_POS | Clears a Holomap position | param1: 1 byte (0..255) - index of the holomap position |
| 0x4A | 74 | ADD_FUEL | Adds to the hero's fuel | param1: 1 byte (0..255) - number of fuel units |
| 0x4B | 75 | SUB_FUEL | Subtracts from the hero's fuel | param1: 1 byte (0..255) - number of fuel units |
| 0x4C | 76 | SET_GRM | Merges an isometric Fragment with the Grid | param1: 1 byte (0..255) - index of the Fragment |
| 0x4D | 77 | SAY_MESSAGE | Displays floating text message | param1: 2 bytes (0..32767) - virtual index of the text entry |
| 0x4E | 78 | SAY_MESSAGE_OBJ | Displays text floating over another Actor |
|
| 0x4F | 79 | FULL_POINT | Maxes hero's life and magic points | |
| 0x50 | 80 | BETA | Immediately sets angle of the Actor | param1: 2 bytes (-32768..32767) - new angle |
| 0x51 | 81 | GRM_OFF | Hides all isometric Fragments | |
| 0x52 | 82 | FADE_PAL_RED | Fades from normal palette to the red one | |
| 0x53 | 83 | FADE_ALARM_RED | Fades from alarm palette to the red one | |
| 0x54 | 84 | FADE_ALARM_PAL | Fades from alarm palette to the normal one | |
| 0x55 | 85 | FADE_RED_PAL | Fades from red palette to the normal one | |
| 0x56 | 86 | FADE_RED_ALARM | Fades from red palette to the alarm one | |
| 0x57 | 87 | FADE_PAL_ALARM | Fades from normal palette to the alarm one | |
| 0x58 | 88 | EXPLODE_OBJ | Displays explosion animation over an Actor | param1: 1 byte (0..255) - index of the target Actor |
| 0x59 | 89 | BALLOON_ON | Enables comic-style dialogue balloons | |
| 0x5A | 90 | BUBBLE_OFF | Disables comic-style dialogue balloons | |
| 0x5B | 91 | ASK_CHOICE_OBJ | Asks for the choice from another Actor |
|
| 0x5C | 92 | SET_DARK_PAL | Sets darken palette | |
| 0x5D | 93 | SET_NORMAL_PAL | Sets normal palette | |
| 0x5E | 94 | MESSAGE_SENDELL | Displays the Twinsen with Zoe and Sendell screen | |
| 0x5F | 95 | ANIM_SET | Immediately sets a new animation | param1: 1 byte (0..255) - virtual index of the animation |
| 0x60 | 96 | HOLOMAP_TRAJ | Displays holomap travel animation | param1: 1 byte (0..255) - index of the holomap trajectory |
| 0x61 | 97 | GAME_OVER | Ends the game and displays Game over animation | |
| 0x62 | 98 | THE_END | Shows credits list sequence | |
| 0x63 | 99 | MIDI_OFF | Stops playing MIDI music | |
| 0x64 | 100 | PLAY_CD_TRACK | Plays a CD music track | param1: 1 byte (0..255) - index of the CD track |
| 0x65 | 101 | PROJ_ISO | Switches to isometric projection | |
| 0x66 | 102 | PROJ_3D | Switches to 3D projection | |
| 0x67 | 103 | TEXT | Displays message at the top of the screen | param1: 2 bytes (0..32767) - virtual index of the text entry |
| 0x68 | 104 | CLEAR_TEXT | Clears upper half of the screen | |
| 0x69 | 105 | BRUTAL_EXIT | Immediately exits to the main menu |
Conditional statements[edit]
Variables have opcodes and parameters, like regular commands, but they occur only after IF-type commands. The conditional construction is following:
In case the condition doesn't have any parameters:
| byte | 1 | 2 | 3 | 4 | 5 & 6 |
|---|---|---|---|---|---|
| Command: | IF-type | Condition | Operator | value to compare | address |
| Example: | 0x0C (IF) | 0x03 (ZONE) | 0x00 (==) | 0x03 | 0x002D |
The bytes 5 and 6 are the address (offset) to jump to when the condition result is false (if it is true, the execution will continue to the lines following the conditional construction (no jump)).
In case the condition has a parameter:
| byte | 1 | 2 | 3 | 4 | 5 | 6 & 7 |
|---|---|---|---|---|---|---|
| Command: | IF-type | Condition | parameter | Operator | value to compare | address |
| Example: | 0x0C (IF) | 0x04 (ZONE_OBJ) | 0x04 | 0x00 (==) | 0x03 | 0x002D |
OR_IF - special case[edit]
OR_IF can be used to execute a block of code if at least one of the conditions is met, its syntax is following:
OR_IF ANIM == 1 OR_IF ANIM == 3 IF ANIM == 6 ...code... ENDIF
All the OR_IF lines must precede the IF line. Their compiled syntax is following:
| byte | 1 | 2 | 3 | 4 | 5 & 6 |
|---|---|---|---|---|---|
| Command: | OR_IF | Condition | Operator | value to compare | address |
| Example: | 0x37 | 0x03 (ZONE) | 0x00 (==) | 0x03 | 0x002D |
The syntax is the same as for a regular IF statement, but this time the address bytes (5 and 6) contain an address where to jump when condition is TRUE. In case it is FALSE the execution will continue to the next line (no jump) (another condition should be there).
Variable macros[edit]
Each variable has a specified range of values it can be compared with. For example COL can be compared to 1-byte values only. One can imagine the comparison values as "function return" values, but it does not exactly work this way. For example ZONE conditional will be always false if the Actor is not inside any Zone, no matter what value it is compared with.
| Code | (dec) | Name | Description | Parameter | Return (compare) value |
|---|---|---|---|---|---|
| 0x00 | 0 | COL | Tests collision with another Actor | 1 byte (0..255) - Actor index | |
| 0x01 | 1 | COL_OBJ | Tests collision of two Actors | 1 byte (0..255) - target Actor index | 1 byte (0..255) - Actor index |
| 0x02 | 2 | DISTANCE | Tests distance to another Actor | 1 byte (0..255) - target Actor index | 2 bytes (0..32000) - distance in Scene units |
| 0x03 | 3 | ZONE | Tests if the Actor is inside a Zone | 1 byte (0..255) - Zone virtual index | |
| 0x04 | 4 | ZONE_OBJ | Tests if another Actor is inside a Zone | 1 byte (0..255) - target Actor index | 1 byte (0..255) - Zone virtual index |
| 0x05 | 5 | BODY | Tests Body of the Actor | 1 byte (0..255) - Body virtual index | |
| 0x06 | 6 | BODY_OBJ | Tests Body of another Actor | 1 byte (0..255) - target Actor index | 1 byte (0..255) - Body virtual index |
| 0x07 | 7 | ANIM | Tests Animation of the Actor | 1 byte (0..255) - Animation virtual index | |
| 0x08 | 8 | ANIM_OBJ | Tests Animation of another Actor | 1 byte (0..255) - target Actor index | 1 byte (0..255) - Animation virtual index |
| 0x09 | 9 | CURRENT_TRACK | Tests Actor's Track Script Label | 1 byte (0..255) - LABEL index | |
| 0x0A | 10 | CURRENT_TRACK_OBJ | Tests another Actor's Track Script Label | 1 byte (0..255) - target Actor index | 1 byte (0..255) - LABEL index |
| 0x0B | 11 | FLAG_CUBE | Tests Cube (local) flag value | 1 byte (0..255) - flag index | 1 byte (0..255) - value |
| 0x0C | 12 | CONE_VIEW | Tests Distance and angle to another Actor | 1 byte (0..255) - target Actor index | 2 bytes (0..32000) - distance in Scene units |
| 0x0D | 13 | HIT_BY | Tests hit by another Actor | 1 byte (0..255) - Actor index | |
| 0x0E | 14 | ACTION | Tests if player is using Action command | 1 byte (0..1) - boolean value | |
| 0x0F | 15 | FLAG_GAME | Tests Game (global) flag value | 1 byte (0..255) - flag index | 1 byte (0..255) - value |
| 0x10 | 16 | LIFE_POINT | Tests number of Actor's life points | 1 byte (0..255) - value | |
| 0x11 | 17 | LIFE_POINT_OBJ | Tests number of another Actor's life points | 1 byte (0..255) - target Actor index | 1 byte (0..255) - value |
| 0x12 | 18 | NUM_LITTLE_KEYS | Tests number of hero's little keys | 1 byte (0..255) - value | |
| 0x13 | 19 | NUM_GOLD_PIECES | Tests number of hero's gold pieces | 2 bytes (0..999) - value | |
| 0x14 | 20 | BEHAVIOUR | Tests hero's behaviour | 1 byte (0..4) - behaviour index (0 = normal, 1 = athletic, 2 = aggressive, 3 = discrete, 4 = proto-pack) | |
| 0x15 | 21 | CHAPTER | Tests CHAPTER variable value | 1 byte (0..255) - value | |
| 0x16 | 22 | DISTANCE_3D | Tests 3D distance to another Actor | 1 byte (0..255) - target Actor index | 2 bytes (0..65535) - distance in Scene units |
| 0x17 | 23 | unused | |||
| 0x18 | 24 | unused | |||
| 0x19 | 25 | USE_INVENTORY | Tests inventory item activation | 1 byte (0..255) - inventory item index | 1 byte (0..1) - boolean value |
| 0x1A | 26 | CHOICE | Tests player's choice | 2 bytes (0..32767) - chosen text entry index | |
| 0x1B | 27 | FUEL | Tests number of hero's fuel units | 1 byte (0..255) - value | |
| 0x1C | 28 | CARRIED_BY | Tests if the Actor is being carried by another Actor | 1 byte (0..255) - Actor index | |
| 0x1D | 29 | CDROM | Unknown | 1 byte (0..255) - unknown |
Operator codes[edit]
| Code | (dec) | Symbol | Description |
|---|---|---|---|
| 0x00 | 0 | == | Variable is equal to the comparison value |
| 0x01 | 1 | > | Variable is greater than the comparison value |
| 0x02 | 2 | < | Variable is less than the comparison value |
| 0x03 | 3 | >= | Variable is grater or equal to the comparison value |
| 0x04 | 4 | <= | Variable is less or equal to the comparison value |
| 0x05 | 5 | != | Variable is not equal to the comparison value |
Information provided by: alexfont and Zink