GTA2 Scripting Information by DMA Design

Here is my edited HTML version of the official Word documents. Over time, I am correcting thier examples re-arranging all the commands into logical sections. It’s formatted to match my website

This document provides an overview of what the game can do. For more detail, choose a mission coding tutorial from my site or search the GTAMP modding forum. If something won’t work when you’re sure that it should, check the scripting weirdness topic.

Started the conversion late on Xmas Day, 2010. Feedback is welcome in the GTAMP topic.

Table of Contents

GBHscript

  1. Please Note
  2. Compiling a Script

General Concepts

  1. Comments in the scriptfile
  2. Floats
  3. Integers
  4. Automatic z Calculating
  5. Triggers
  6. Doors
  7. General Characters

Overview & Examples

  1. Notes
  2. Predefined Types
  3. Programming Structures
  4. Multi-tasking
  5. Readability of Scripts
  6. On-screen Messages
  7. Example Mission

Mission Language Structures

  1. IF (…) THEN (…) ENDIF
  2. IF (…) THEN (…) ELSE (…) ENDIF
  3. Expressions
  4. COUNTER
  5. SET COUNTER
  6. FOR Loops
  7. WHILE Loops
  8. WHILE EXEC Loops
  9. DO WHILE Loops
  10. Subroutines & Jumping
  11. Threads
  12. PSX/PC IFDEF Blocks
  13. EXEC Blocks
  14. Multi Scripts

Constants

  1. Occupations
  2. Threat Searching
  3. Threat Reactions
  4. Objectives
  5. Character Remaps
  6. Shooting Skill
  7. Bravery
  8. Character Weapons
  9. Car Weapons
  10. Car Types
  11. Car Remaps
  12. Objects
  13. Powerups
  14. Shops
  15. Door Opening
  16. Door Closing
  17. Arrow Colours
  18. Car Locks
  19. Damage Types
  20. Sounds
  21. Messages which Play a Sound
  22. Radio Stations
  23. Slopes

Mission Language Commands (All 298 of them!)

Players

  1. PLAYER_PED
  2. ADD_SCORE
  3. ADD_SCORE_NO_MULT
  4. STORE_SCORE
  5. CHECK_SCORE_GREATER
  6. ADD_LIVES
  7. STORE_NUM_LIVES
  8. CHECK_NUM_LIVES_GREATER
  9. ADD_MULTIPLIER
  10. STORE_MULTIPLIER
  11. CHECK_MULTIPLIER_GREATER
  12. SET_ENTER_CONTROL_STATUS
  13. SET_ALL_CONTROLS_STATUS
  14. IS_POINT_ONSCREEN
  15. IS_ITEM_ACCURATELY_ONSCREEN

Weapons

  1. GENERATOR
  2. GIVE_WEAPON
  3. REMOVE_WEAPONS
  4. HAS_CAR_GOT_WEAPON
  5. STORE_LAST_CHAR_PUNCHED
  6. HAS_CHAR_PUNCHED_SOMEONE
  7. SWITCH_GENERATOR
  8. CHECK_CHAR_CURR_WEAPON
  9. CHECK_WEAPON_TYPE_HIT_CHAR
  10. CHECK_WEAPON_TYPE_HIT_CAR
  11. CHECK_ANY_WEAPON_TYPE_HIT_CAR
  1. DECLARE_POLICELEVEL
  2. CHANGE_POLICE_LEVEL
  3. CLEAR_WANTED_LEVEL
  4. ALTER_WANTED_LEVEL
  5. ALTER_WANTED_LEVEL_NO_DROP
  6. CHECK_HEADS_GREATER
  7. HAS_CHAR_BEEN_ARRESTED
  8. SET_DEATHARREST_STATE
  9. CHECK_DEATHARREST_EXECUTED
  1. Messages which Play a Sound
  2. DISPLAY_MESSAGE
  3. DISPLAY_BRIEF
  4. DISPLAY_BRIEF_SOON
  5. DISPLAY_BRIEF_NOW
  6. IS_BRIEF_ONSCREEN
  7. CLEAR_ALL_BRIEFS
  8. SET_BONUS_RATING_TEXT_ID
  1. ARROW_DATA
  2. POINT_ARROW_AT_SOMETHING
  3. SWITCH_OFF_ARROW
  4. SET_ARROW_COLOUR
  5. LEVEL_END_POINT_ARROW_AT
  1. ONSCREEN_COUNTER
  2. ADD_ONSCREEN_COUNTER
  3. CLEAR_ONSCREEN_COUNTER
  4. CLEAR_CLOCK_ONLY
  1. TIMER_DATA
  2. DISPLAY_TIMER
  3. CLEAR_TIMER
  4. ADD_TIME_TO_TIMER

Objects

  1. OBJ_DATA
  2. OBJ_DATA Declare
  3. CREATE_OBJ
  4. DELETE_ITEM
  5. CHECK_OBJ_MODEL
  6. EXPLODE
  7. EXPLODE_WALL
  8. EXPLODE_NO_RING
  9. EXPLODE_SMALL
  10. EXPLODE_LARGE
  11. IS_ITEM_ONSCREEN
  1. REMOVE_BLOCK
  2. ADD_NEW_BLOCK
  3. CHANGE_BLOCK TYPE
  4. CHANGE_BLOCK LID
  5. CHANGE_BLOCK SIDE
  6. LOWER_LEVEL
  7. SET_SHADING_LEVEL
  1. CRANE_DATA
  2. ENABLE_CRANE
  3. DISABLE_CRANE
  4. DECLARE_CRANE_POWERUP
  5. CONVEYOR
  6. CRUSHER
  7. DESTRUCTOR
  8. GENERATOR
  9. CREATE_DESTRUCTOR
  10. DECLARE_POWERUP_CARLIST
  11. DECIDE_POWERUP_FOR_CRANE
  12. GET_CAR_INFO_FROM_CRANE
  13. IS_CAR_CRUSHED
  14. IS_CAR_ON_TRAILER
  15. PUT_CAR_ON_TRAILER
  1. Doors
  2. DOOR_DATA
  3. DECLARE_DOOR_INFO
  4. UPDATE_DOOR_TARGET
  5. MAKE_DOOR_AUTOMATIC
  6. MAKE_DOOR_MANUAL
  7. OPEN_DOOR
  8. CLOSE_DOOR
  1. DECLARE_LIGHT
  2. Declare_&_Set_LIGHT
  3. CREATE_LIGHT
  4. CHANGE_INTENSITY
  5. CHANGE_COLOUR
  6. CHANGE_RADIUS
  1. SOUND
  2. SOUND
  3. CREATE_SOUND
  4. Messages which Play a Sound

Vehicles

  1. CAR_DATA
  2. CAR_DATA
  3. CREATE_CAR
  4. CREATE_GANG_CAR
  5. PARKED_CAR_DATA
  6. SET_CAR_NUMBER_GRAPHIC
  7. SET_CAR_EMERG_LIGHTS
  8. ARE_EMERG_LIGHTS_ON
  9. GIVE_CAR_ALARM
  10. CHANGE_CAR_LOCK
  11. CHANGE_CAR_REMAP
  12. CHECK_CAR_MODEL
  13. CHECK_CAR_REMAP
  14. CHECK_CAR_MODEL_AND_REMAP
  15. CHECK_CAR'S_DAMAGE_LEVEL
  16. CHECK_CAR_DAMAGE_POSITION
  17. CHECK_ANY_WEAPON_TYPE_HIT_CAR
  18. IS_TRAILER_ATTACHED
  19. IS_BUS_FULL
  20. STOP_CHARS_GETTING_OFF_BUS
  21. IS_CARBOMB_ACTIVE
  22. IS_CAR_IN_AIR
  23. HAS_CAR_JUST_SUNK
  24. IS_CAR_IN_BLOCK
  25. IS_CAR_WRECKED
  26. CHECK_CAR_WRECKED_IN_AREA
  27. SET_CAR_JAMMED_ACCELERATOR
  28. SET_CAR_BULLETPROOF
  29. SET_CAR_FLAMEPROOF
  30. SET_CAR_ROCKETPROOF
  31. SET_CAR_NO_COLLIDE
  32. CLEAR_CAR_NO_COLLIDE
  33. CHECK_PASSENGER_COUNT
  34. CHECK_WEAPON_TYPE_HIT_CAR
  35. CHECK_ANY_WEAPON_TYPE_HIT_CAR
  36. PARK
  37. PARK_NO_RESPAWN
  38. HAS_PARK_FINISHED
  39. SET_DIRECTION_OF_TV_VAN_DISHES
  40. SUPPRESS_THIS_CAR_MODEL
  41. SET_RECYCLE_MODEL_WANTED

Characters & Players

  1. CREATE_CHAR
  2. CHAR_DATA
  3. CHAR_DATA
  4. CREATE_CHAR_INSIDE_CAR
  5. MAKE_CHAR_DO_NOTHING
  6. KILL_CHAR
  7. CHANGE_CHAR_REMAP
  8. CHECK_CHARACTER_HEALTH
  9. HAS_CHARACTER_DIED
  10. HAS_CHAR_SPOTTED_PLAYER
  11. IS_CHARACTER_STOPPED
  12. IS_CHAR_FIRING_ONSCREEN
  13. IS_CHAR_IN_ZONE
  14. IS_CHAR_IN_GANG_ZONE
  15. IS_CHAR_FIRING_IN_AREA
  16. SET_PATROL_ROUTE_FOR_CHARACTER
  17. CHECK_CHAR_CURR_WEAPON
  18. IS_CHAR_FALLING
  19. IS_CHAR_STUNNED
  20. IS_CHAR_ON_FIRE
  21. HAS_CHAR_JUST_SUNK
  22. CHECK_CHAR_BEEN_PUNCHED_BY
  23. CHECK_WEAPON_TYPE_HIT_CHAR
  24. MAKE_ALL_CHARS_MUGGERS
  25. SET_CHAR_MAX_RUNSPEED
  26. SET_CHAR_INVINCIBLE
  27. SET_CHAR_GRAPHIC_TYPE
  28. WARP_FROM_CAR_TO_POINT
  1. CHECK_CAR_HAS_DRIVER
  2. HAS_CAR_GOT_DRIVER
  3. GIVE_DRIVER_AND_BRAKE
  4. MAKE_CAR_A_DUMMY
  5. MAKE_CAR_DRIVE_AWAY
  6. CREATE_CHAR_INSIDE_CAR
  7. ORDER_CHAR_TO_DRIVE_CAR
  8. SET_CHAR_DRIVE_AGGRESSION
  9. SET_CHAR_TO_STAY_IN_CAR
  10. SET_CHAR_TO_USE_CAR_WEAPON
  11. STOP_CHAR_DRIVING
  12. ORDER_DRIVER_OUT_CAR
  13. DELETE_GROUP_IN_CAR
  14. IS_CHARACTER_IN_CAR
  15. IS_CHARACTER_IN_ANY_CAR
  16. IS_CHARACTER_IN_MODEL
  17. STORE_CAR_THAT_CHARACTER_IS_IN
  18. IS_CHAR_PRESSING_HORN
  19. IS_CHAR_CAR_CAPACITY
  20. KILL_ALL_PASSENGERS
  21. ORDER_CHAR_TO_BACKDOOR
  22. CHECK_CAR_SPEED
  23. STORE_MAX_CAR_SPEED
  24. STORE_CAR_CURRENT_SPEED
  25. STORE_CHAR_CAR_CURRENT_SPEED
  26. SET_CHAR_MAX_DRIVESPEED
  27. SET_FAVOURITE_MODEL
  28. SWITCH_ROAD_OFF
  29. SWITCH_ROAD_ON
  30. TAKE_REMOTE_CONTROL_OF_CAR
  1. ADD_GROUP_TO_CHARACTER
  2. ADD_EXISTING_CHAR_TO_GROUP
  3. MAKE_NEW_LEADER_OF_GROUP
  4. SET_GROUP_TYPE
  5. CHECK_NUMBER_ALIVE_IN_GROUP
  6. SET_MIN_MEMBERS_BEFORE_GROUP_SPLITS
  7. IS_GROUP_IN_CAR
  8. DELETE_GROUP_IN_CAR
  9. DESTROY_GROUP
  10. REMOVE_CHAR_FROM_GROUP

Objectives

  1. SET_CHAR_OCCUPATION
  2. IS_CHAR_OBJECTIVE_PASSED
  3. IS_CHAR_OBJECTIVE_FAILED
  4. SET_CHAR_THREAT_SEARCH
  5. SET_CHAR_THREAT_REACTION
  6. SET_CHAR_OBJECTIVE
  7. SET_CHAR_SHOOTING_SKILL
  8. SET_CHAR_BRAVERY_LEVEL
  9. LOCATE_CHARACTER_ANY_MEANS
  10. LOCATE_CHARACTER_ON_FOOT
  11. LOCATE_CHARACTER_BY_CAR
  12. LOCATE_STOPPED_CHARACTER
  13. LOCATE_ANOTHER_CHARACTER_ON_FOOT
  14. LOCATE_ANOTHER_CHARACTER_BY_CAR
  15. LOCATE_ANOTHER_CHARACTER_ANY_MEANS
  16. IS_ITEM_ONSCREEN

Systems

  1. DECLARE_POLICELEVEL
  2. SET_AMBIENT_LEVEL
  3. SET_SHADING_LEVEL
  4. RADIO_STATION
  5. SET_STATION_INFO
  1. MAP_ZONE
  2. MAP_ZONE
  3. SET_MAP_ZONES
  1. SET_GANG_INFO
  2. ADD_CHAR_TO_GANG
  3. CHANGE_GANG_CHAR_RESPECT
  4. CHANGE_GANG_CHAR_RESPECT_AND_UPDATE
  5. SET_GANG_KILL_REACTION
  6. Gang Example
  7. CHECK_RESPECT_GREATER
  8. CHECK_RESPECT_LOWER
  9. CHECK_RESPECT_EQUAL
  1. LEVEL_START
  2. LEVEL_END
  3. FINISH_LEVEL
  4. DECLARE_FINISH_SCORE
  5. DECLARE_MISSION_FLAG
  6. LAUNCH_MISSION
  7. MISSION_HAS_FINISHED
  8. DECLARE_TOTAL_MISSIONS
  9. DECLARE_MISSIONS_PASSED_FLAG
  10. DECLARE_TOTAL_SECRETS
  11. DECLARE_SECRETS_PASSED_FLAG
  12. DECLARE_SECRETS_FAILED_FLAG
  13. DECLARE_GANG_MISSIONS_TOTAL
  14. DECLARE_GANG_MISSION_FLAG
  15. DECLARE_GANG_MISSIONS_PASSED_FLAG
  16. DECLARE_GANG_DEATH_BASE_BRIEF
  17. FORCE_CLEANUP
  1. ANSWER_PHONE
  2. ANSWER_PHONE_Example
  3. DO_PHONE_TEMPLATE
  4. DO_EASY_PHONE_TEMPLATE
  5. CHECK_ANSWERED_PHONE
  6. CHECK_FAIL_PHONE_TIMER
  7. SET_PHONE_DEAD
  8. STOP_PHONE_RINGING
  9. THREAD_WAIT_FOR_ANSWER_PHONE
  1. Reworked Kill Frenzies
  2. SET_KF_WEAPON
  3. CLEAR_KF_WEAPON
  4. START_BASIC_KF_TEMPLATE
  5. DO_BASIC_KF_TEMPLATE
  6. BASIC_KF_TEMPLATE_Example
  7. KF_TEMPLATE_BRIEFS
  8. BONUS_DECLARE
  9. START_BONUS_CHECK
  10. START_BONUS_CHECK_Example
  11. STORE_BONUS_COUNT
  12. HAS_BONUS_FINISHED
  13. HAS_BONUS_PASSED
  14. HAS_BONUS_FAILED
  15. MODELCHECK_Example
  16. SETUP_MODELCHECK_DESTROY
  17. HAS_MODELCHECK_HAPPENED
  1. SAVE_GAME
  2. SAVED_COUNTER
  3. SAVED_COUNTER
  1. THREAD_TRIGGER
  2. THREAD_ID
  3. CREATE_THREAD
  4. STOP_THREAD
  5. THREAD_WAIT_FOR_CHAR_IN_CAR
  6. THREAD_WAIT_FOR_CHAR_IN_BLOCK
  7. ENABLE_THREAD_TRIGGER
  8. DISABLE_THREAD_TRIGGER
  9. THREAD_WAIT_FOR_CHAR_IN_AREA
  10. THREAD_WAIT_FOR_CHAR_IN_AREA_ANY_MEANS
  11. THREAD_WAIT_FOR_ANSWER_PHONE

GBHscript

1998 DMA Design Ltd.

Please Note

This product is not a patch but rather a software utility which the user employs at his or her own risk. DMA provides no remedies or warranties, whether express or implied, for this utility. The software and documentation accompanying the tool are provided "as is". You acknowledge that due to the complexity of the software it is possible that use of the software could lead to the unintentional corruption or loss of data, limb and life. You assume all risks of such data loss or corruption.

In no case shall DMA be liable for any indirect, incidental, special, punitive, consequential or inconsequential damages or loss, including, without limitation, lost profits or the inability to use equipment or access data whether such damages are based upon a breach of express or implied warranties, breach of contract, negligence, strict tort, or any other legal theory.

This document and program is released UNSUPPORTED. It was designed for internal use only, under suitable guidance. The compiler, miss2.exe, is very particular about script layout & syntax. You must follow the examples otherwise your scripts will not compile. Note the example script will take a while to compile!

This document is an overview of the GTA2 scripting process, listing details of each command and the various parameters. Various tables of info such as remap values, car types etc, are also included.

Compiling a Script

(See also: Sektor’s list of GTA 2 Tools & Editors.)

  1. Create your basic script as a textfile using any text editor.
  2. Give it a name such as "text.mis" - all raw scripts must have a .mis extension
  3. Compile the mis file using the Miss2.exe compiler program.
  4. This will generate a .tmp file, a .txt file & a .scr file of your raw script.
  5. Once successfully compiled, copy the resulting .scr file into the …/gta2/data/ folder on your harddrive.

Mission Language Structures

IF … THEN …

A basic "If X is true, then do Y". Used to control flow, branching if certain events have happened, if certain states are true. X can be as complex or as simple as needed. It can contain arithmetic checks or state checks on characters, cars, etc: 

IF (IS_CAR_WRECKED(car_one))
     // handle car being wrecked
ENDIF

IF (missions_passed > 10)
 // end of level!
ENDIF

Should avoid trying to "do" things in the X part of the if statement, aim to just do state checks etc. You can use NOT to check if things haven't happened yet: 

IF (NOT (LOCATE_CHARACTER_ON_FOOT(charname, X,Y,Z, width,height)) )
 // not quite at location yet
ENDIF

The Y part can be any sort of normal command statement - it can be one or many. 

IF (expression)
 DO_NOWT
ENDIF

Parameters

Important to remember the number of brackets must be balanced, ie if there are 4 '(' brackets, there should be 4 ')' by the end of the line. There must be no surplus brackets; only the ones which are actually needed.

IF … THEN … ELSE …

Similar to the normal IF (X) THEN (Y) statement, except with an extra ELSE (Z). If the (X) evaluates to TRUE then it executes Y, if FALSE, it executes Z: 

IF (IS_CAR_WRECKED (car_one))
     // do message "You've wrecked the car!!"
ELSE
     // do message "Well done the car is safe!"
ENDIF
IF (expression)
 DO_NOWT
ELSE
 DO_NOWT
ENDIF

Expressions

But what exactly is a valid expression as mentioned above?? As mentioned, commands that check 'state' of things are valid: 

IS_CAR_WRECKED (car_one)
IS_CHAR_IN_BLOCK (char)
IS_CHAR_DEAD (char_two)

In addition, arithmetic expressions using counters are valid. This means you can check whether a counter has a certain value, less than, greater than etc. Valid arithmetic expressions are: 

counter <  value
counter <  counter
counter <= value
counter <= counter
counter >  value
counter >  counter
counter >= value
counter >= counter
counter  = value
counter  = counter

Example: 

IF (missions_completed > 10)
IF (time_delay <= 200)
IF (timer1 >= timer2)

Just to make things more flexible & complex, AND, NOT & OR can be used in expressions. NOT negates the result of an expression. AND evaluates both expressions, returning TRUE if both are TRUE. OR evaluates both expressions returning TRUE if either expression is TRUE. These can be used together: 

IF ((missions_completed > 10) AND (IS_CHAR_DEAD (player)) )
IF ( (timer < timer2) AND (NOT (timer2 = 0)))
IF (NOT (IS_CHAR_STUNNED (enemy_ped)) OR (IS_CHAR_DEAD (enemy_ped)) )
NOT (expression)
(expression1) AND (expression2)
(expression1) OR (expression2)

Parameters

These are all comparison expressions, = will not 'store' the given value in a counter.

COUNTER

Declares a counter variable & sets it to the default value for counters, 0. Counters can be used to keep track of mission counts etc as in GTA, or as simple On/Off flags. They can only store integer values. Fairly straightforward. Are also used in FOR loops etc to control program flow.

Counters have a range of values from -32768 to 32767. They have the value 0 by default. A different value can be given when they are declared. 

COUNTER name
COUNTER name = value // only when declaring - need to use SET afterwards

Can be displayed on-screen by using a separate ONSCREEN_COUNTER object and the ADD_ONSCREEN_COUNTER command.

Parameters
name any valid string - must be unique.
value integer - optional value for the COUNTER to start with

SET COUNTER

This allows you to change a counter's contents during the game. You can explicitly set it equal to a certain value, or equal to another counter. 

SET counter_name = value
SET counter_name = anothercounter
SET counter_name = (anothercounter + yet_another_counter)
SET counter_name = (anothercounter - yet_another_counter)
SET counter_name = (anothercounter / yet_another_counter)
SET counter_name = (anothercounter * yet_another_counter)
SET counter_name = (anothercounter MOD yet_another_counter)
SET counter_name = (anothercounter + value)
SET counter_name = (anothercounter - value)
SET counter_name = (anothercounter / value)
SET counter_name = (anothercounter * value)
SET counter_name = (anothercounter MOD value)
Parameters
countername Name of a previously declared counter
integervalue the value to store
anothercounter Name of another previously declared COUNTER to copy value from.
Yetanothercounter Name of yet another COUNTER to use….
Value integer value to use in this arithmetic operation.

FOR Loops

(This feature is not available and was never used.)

WHILE Loops

"While X Do Y" is another simple looping mechanism, with an expression check at the start of the block of commands. It will execute Y while X evaluates to TRUE. X can be any valid expression, Y is any valid block of commands: 

WHILE (NOT (IS_CHAR_DEAD(ped_one)) )
     // ped still alive
     --timer
ENDWHILE
WHILE (expression)
     DO_NOWT
ENDWHILE

WHILE_EXEC Loops

Similar to the standard WHILE loop except all of the code in the command block gets executed this processing cycle, ie instead of doing it one line at a time, it does all the lines. Very powerful but use carefully - too much use will slow down the game: 

WHILE_EXEC (IS_PED_ALIVE(player))
     IF (score > needed_score)
          // congrats message
     ENDIF
     IF (timer1 > endtimer)
          // different message
     ENDIF
ENDWHILE
WHILE_EXEC (expression)
     DO_NOWT
ENDWHILE

DO WHILE Loops

Another loop variant. However, this loop guarantees to execute the commands in the block once as the end check is at the end of the loop: 

DO
     SET counter = counter + 1
WHILE_TRUE (counter < 100)
DO
     DO_NOWT
WHILE_TRUE (expression)

Subroutines & Jumping

With the new script system, it's a lot easier to "jump" to other subroutines in a script file without the messy line numbers.

Instead, you label a section of commands. Later in the code you GOSUB to it (or use a THREAD_TRIGGER). When the subroutine code finishes processing, the game will return to the line after the GOSUB command. This effectively 'inserts' the code contained at the label. 

subroutine:
SEND_PED_TO_BLOCK (ped_one, location_one)
WHILE (NOT (IS_PED_IN_BLOCK(ped_one, location_one)))
     SET counter = counter + 1
ENDWHILE
RETURN

LEVELSTART

ped_one = PED (…)
GOSUB subroutine: // 'subroutine:' has to finish for us to move beyond this point

// to get here, the ped must have reached the location

LEVELEND

(Bad example.)

Parameters

Subroutines are very powerful, but be careful again with using them too much - they code make your code messy & difficult to follow. As you no longer need linenumbers, jumping about the file shouldn't be needed quite as much - just insert the new code!

PSX/PC IFDEF Blocks

With the latest version of V8.3 of GTA2, we have some new script commands to help keep using just the one set of scripts on both the PC & Playstation. You can now 'section off' certain blocks of commands, marking them to be only run on the PC or Playstation.

For instance, the number of parked cars could be reduced on the Playstation just by doing: 

// On all platforms:
PARKED_CAR …
PARKED_CAR …
PARKED_CAR …

#ifdef PC
 // Only on PC:
 PARKED_CAR …
 PARKED_CAR …
 PARKED_CAR …
#endif

(Bad example.)

This would create three cars on the PSX, but six on the PC. This works just as well doing something ONLY on the Playstation: 

#ifdef PSX
 DO_NOWT // only on the PSX!
#endif

The other construct available lets you do one block of commands on the PC, with another block executed on the Playstation: 

#ifdef PC
 DO_NOWT // PC specific
#else
 DO_NOWT // only on the PSX
#endif

Or, the other way around: 

#ifdef PSX
 DO_NOWT // only on the PSX
#else
 DO_NOWT // PC specific
#endif

Important Points

//#ifdef PC
 DO_NOWT // will now compile for any platform
//#endif

EXEC Blocks

Discovered by Trademark’s .scr decompiler, you can wrap commands in an EXEC block to make them all run immediately, in the same frame.

This is only used by the official scripts immediately after LEVELSTART. This trick ensures weapons are already present when a single-player game begins. Without it, the weapons only appear in single player after their min_delay time has finished.

Weapons spawn immediately in multiplayer, regardless of thier min_delay time. 

GENERATOR gen3 = (159.00,137.00) 000 COLLECT_01 300 300
PARKED_CAR_DATA fbicar = (094.5,076.5) -1 000 EDSELFBI
// PLAYER_PED and other objects

LEVELSTART

EXEC
 // Do everything in this block during the first frame:
 SET_AMBIENT_LEVEL (0.40, 0)
 SWITCH_GENERATOR (gen3, ON)
 // more weapons here
 SET_DIR_OF_TV_VANS (159.00,137.00)
 GIVE_CAR_ALARM (auto1)
ENDEXEC

// All other commands go here

LEVELEND

Multi Scripts

The game is now capable of handling 'multiscripts' - this is the ability for each individual mission to be contained within an individual script which is loaded in when the main script demands it. The mainscript stays in memory at all times, with one other 'multiscript' allowed to be running at any time.

A multiscript is a 'little' script - it has declarations at the top, separate functions & a main body flagged with 'MISSIONSTART' instead of LEVELSTART. It's at this MISSIONSTART that execution begins.

Be aware that you cannot create anything in the declarations, only reserve space for items - this is because there's no 'initialisation' phase in a multiscript, it just gets loaded. You're free to do CREATE_CAR etc though as normal. One thing to note: you cannot have a FORWARD as the very first command in a multiscript!

Multiscripts are stored in a subdirectory inside DATA. It should have the same name as the mainscript being executed, e.g. WIL, STE, BIL. Launch the script using LAUNCH_MISSION.

Mission Language Commands (grouped)

PLAYER_PED

  1. PLAYER_PED
  2. ADD_SCORE
  3. ADD_SCORE_NO_MULT
  4. STORE_SCORE
  5. CHECK_SCORE_GREATER
  6. ADD_LIVES
  7. STORE_NUM_LIVES
  8. CHECK_NUM_LIVES_GREATER
  9. ADD_MULTIPLIER
  10. STORE_MULTIPLIER
  11. CHECK_MULTIPLIER_GREATER
  12. SET_ENTER_CONTROL_STATUS
  13. SET_ALL_CONTROLS_STATUS
  14. IS_POINT_ONSCREEN
  15. IS_ITEM_ACCURATELY_ONSCREEN

Creates a player ped at a specific location with a specific remap & rotation.

If float Z is given as 255.0, the game will calculate the correct Z value for the (X,Y) position. 

PLAYER_PED player1 = (X,Y,Z) remap rotation
Parameters
player_name string to be used to refer to player throughout the script
X,Y,Z float coordinate to create player at

ADD_SCORE

Adds a score value to a given player. New alternative - add the value of a COUNTER to the player's score.

The value is multiplied by their current multiplier. 

ADD_SCORE (player_name, value)
ADD_SCORE (player_name, counter_name)
Parameters
player_name Name of player!
value integer score value. Can be positive or negative. (Unlimited size)
counter_name Name of a previously declared counter

ADD_SCORE_NO_MULT

This is a variation of the standard ADD_SCORE command, except it ignores the multiplier. (Does this support adding the value of a COUNTER?) 

ADD_SCORE_NO_MULT (player_name, value)
Parameters
player_name Name of player!
value integer score value. Can be positive or negative. Unlimited size.

STORE_SCORE

Stores the current score for this player in a previously declared COUNTER. This COUNTER can then be used in the normal arithmetic functions and other expressions. 

STORE_SCORE (player_name, counter_name)
Parameters
player_name Name of a player created using a PLAYER_PED command
counter_name Name of a valid counter

CHECK_SCORE_GREATER

Simply checks the current score for this player against a particular value. If greater than it returns TRUE, else FALSE. 

CHECK_SCORE_GREATER (player_name, value)
Parameters
player_name Name of a player created using a PLAYER_PED command
value Integer giving the value to check the score against.

ADD_LIVES

Quick & easy function that lets you give a player extra lives - it simply adds them to his total, without messing around with powerups etc. Note there is a maximum of 99 lives for each player. 

ADD_LIVES (player_name, value)
Parameters
player_name Name of a previously created player's character
value integer value, range 0–99, describing the number of lives to give to the player.

CHECK_NUM_LIVES_GREATER

Simply checks the number of lives for a player against a particular value. If greater than returns TRUE, else FALSE. 

CHECK_NUM_LIVES_GREATER (player_name, value)
Parameters
player_name Name of a previously declared player's character
value Integer describing the number of lives to check against

STORE_NUM_LIVES

Stores the number of lives for this player in a previously declared counter - this counter can then be used in the normal arithmetic functions. 

STORE_NUM_LIVES (player_name, counter_name)
Parameters
player_name Name of a previously declared player's character
counter_name Name of a previously declared counter

ADD_MULTIPLIER

Increases the player's multiplier level by a certain number. There is a maximum multiplier level of 99. 

ADD_MULTIPLIER (player_name, value)
Parameters
player_name Name of a previously created player's character
value integer value, 1–99, describing the number of lives to give to the player

STORE_MULTIPLIER

Stores the current multiplier for this player in a previously declared counter - this counter can then be used in the arithmetic functions. 

STORE_MULTIPLIER (player_name, counter_name)
Parameters
player_name Name of a previously declared player's character
counter_name Name of a previously declared counter

CHECK_MULTIPLIER_GREATER

Simply checks the current multiplier for this player against a particular value. If greater than it returns TRUE, else FALSE. 

CHECK_MULTIPLIER_GREATER (player_name, value)
Parameters
player_name Name of a previously declared player's character
value Integer describing the multiplier count to check against

SET_ENTER_CONTROL_STATUS

This allows you to switch off the player's 'enter' control at specific points in the missions. This is a DANGEROUS command that could cause problems. You MUST switch it back on as soon as you're ready to. It may affect replays if you don't!! 

SET_ENTER_CONTROL_STATUS (player_name, ON)
SET_ENTER_CONTROL_STATUS (player_name, OFF)
Parameters
player_name Name of the player's character!

Multiplayer Support

Requires vike’s GTA2 version 11.41 or newer.

SET ALL CONTROLS STATUS

This switches on/off all of the player's controls. This is HIGHLY HIGHLY DANGEROUS and should only be done when you DEFINITELY need to - e.g. during a warp command. Be very wary of doing this command!

You must switch the controls back on at the earliest possible opportunity. 

SET_ALL_CONTROLS_STATUS (player_name, ON)
SET_ALL_CONTROLS_STATUS (player_name, OFF)
Parameters
player_name Name of the player to act on. Usually just the local player.

Multiplayer Support

Requires vike’s GTA2 version 11.41 or newer.

OBJ_DATA

  1. OBJ_DATA
  2. OBJ_DATA Declare
  3. CREATE_OBJ
  4. DELETE_ITEM
  5. CHECK_OBJ_MODEL
  6. EXPLODE
  7. EXPLODE_NO_RING
  8. EXPLODE_LARGE
  9. EXPLODE_SMALL
  10. EXPLODE_WALL
  11. IS_ITEM_ONSCREEN

(See also: Tutorial about Objects and Vehicle Shops tutorial.)

Declares space for an object without creating it rightaway. Similar to the concept of 'future objects'. There's no need to worry about location or type at this point. 

OBJ_DATA name

OBJ_DATA

Declares & creates an object before LEVELSTART of type model at a location, with a specific rotation. Z value works as above for cars.

New features: 

OBJ_DATA name = (X,Y)   rotation MODEL
OBJ_DATA name = (X,Y,Z) rotation MODEL
OBJ_DATA name = (X,Y,Z) rotation MODEL value
OBJ_DATA name = (X,Y,Z) rotation MODEL SHOPTYPE
Parameters
name unique name for this object
rotation standard angle, 0–359 degrees
model string for either a generic object or a weapon type or a car shop type
value integer for weapon ammo or respray shop vehicle remap value
shoptype string detailing the shop type

CREATE_OBJ

(See also: Shop Types.)

Creates an object after LEVELSTART. The object must have been previously declared. Z value works as above.

New: certain commands must have an END at the end of the line. 

name = CREATE_OBJ (X,Y)   rotation MODEL END
name = CREATE_OBJ (X,Y,Z) rotation MODEL END
name = CREATE_OBJ (X,Y,Z) rotation MODEL value END
name = CREATE_OBJ (X,Y,Z) rotation MODEL SHOPTYPE END
Parameters
name unique name for this object
rotation standard angle, 0–359 degrees
model string for either a generic object or a weapon type or a car shop type
value integer for weapon ammo or respray shop vehicle remap value
shoptype string detailing the shop type - see bottom of document.

DELETE_ITEM

Orders the game to delete a previously created car/character/light/object/sound. This generic command replaces the DELETE_CAR/CHAR/OBJECT commands. 

DELETE_ITEM (name)
Parameters
name previously created character or car or object or light!

CHECK_OBJ_MODEL

This command, when used with a destructable object, lets you detect when it's been destroyed - these objects change model when blown up. See complete list of object types for details.

It returns TRUE if the object's current model matches the one listed, FALSE if not. 

CHECK_OBJ_MODEL (name, MODEL)
Parameters
name Name of a previously created object
MODEL string detailing the model name from the list at the bottom of the doc

EXPLODE

Destroy a car, object or character. Same explosion as a car reaching 100% damage.

You can creates an explosion at a particular (X,Y,Z) with this command, too.

If you don’t want to see the pressure wave, use EXPLODE_NO_RING. 

EXPLODE (name)
EXPLODE (X,Y,Z)
Parameters
name Name of a previously created character, object or car.
x,y,z float coordinates describing the EXACT position to create the explosion at. Explosion can be at any point in block!

EXPLODE_NO_RING

Same as the normal EXPLODE command, except this has no blast ring coming out of it. 

EXPLODE_NO_RING (name)
EXPLODE_NO_RING (X,Y,Z)

Parameters

See EXPLODE command for details.

EXPLODE_LARGE

Same as the EXPLODE command, except the explosion is like using a Vehicle Bomb. This explosion is a LARGE explosion!!!! A REALLY large explosion!!! 

EXPLODE_LARGE (name)
EXPLODE_LARGE (X,Y,Z)

Parameters

See EXPLODE command for details.

EXPLODE_SMALL

Same as the EXPLODE command, except the explosion is like using a Vehicle Mine. This explosion is smaller but still deadly! 

EXPLODE_SMALL (name)
EXPLODE_SMALL (X,Y,Z)

Parameters

See EXPLODE command for details.

EXPLODE_WALL

Creates a "wall explosion" at a particular (X,Y,Z) & in a certain direction. Same effect as a rocket hitting a wall at the moment. 

EXPLODE_WALL (X,Y,Z) FACE
Parameters
X,Y,Z must be floats, and must be "on" a wall, ie x or y is likely to be a whole value.
FACE which side of the location to explode: LEFT (West), RIGHT (East), TOP (North), BOTTOM (South)

Vehicles

  1. Vehicles
  2. CAR_DATA
  3. CAR_DATA
  4. CREATE_CAR
  5. CREATE_GANG_CAR
  6. PARKED_CAR_DATA
  7. SET_CAR_NUMBER_GRAPHIC
  8. SET_CAR_EMERG_LIGHTS
  9. ARE_EMERG_LIGHTS_ON
  10. GIVE_CAR_ALARM
  11. CHANGE_CAR_LOCK
  12. CHANGE_CAR_REMAP
  13. CHECK_CAR_MODEL
  14. CHECK_CAR_REMAP
  15. CHECK_CAR_MODEL_AND_REMAP
  16. CHECK_CAR'S_DAMAGE_LEVEL
  17. CHECK_CAR_DAMAGE_POSITION
  18. CHECK_ANY_WEAPON_TYPE_HIT_CAR
  19. IS_TRAILER_ATTACHED
  20. IS_BUS_FULL
  21. STOP_CHARS_GETTING_OFF_BUS
  22. IS_CARBOMB_ACTIVE
  23. IS_CAR_IN_AIR
  24. HAS_CAR_JUST_SUNK
  25. IS_CAR_IN_BLOCK
  26. IS_CAR_WRECKED
  27. CHECK_CAR_WRECKED_IN_AREA
  28. SET_CAR_JAMMED_ACCELERATOR
  29. SET_CAR_BULLETPROOF
  30. SET_CAR_FLAMEPROOF
  31. SET_CAR_ROCKETPROOF
  32. SET_CAR_NO_COLLIDE
  33. CLEAR_CAR_NO_COLLIDE
  34. CHECK_PASSENGER_COUNT
  35. CHECK_WEAPON_TYPE_HIT_CAR
  36. CHECK_ANY_WEAPON_TYPE_HIT_CAR
  37. PARK
  38. PARK_NO_RESPAWN
  39. HAS_PARK_FINISHED
  40. SET_DIRECTION_OF_TV_VAN_DISHES
  41. SUPPRESS_THIS_CAR_MODEL
  42. SET_RECYCLE_MODEL_WANTED

CAR_DATA Declare

Declares 'space' for one car, without creating it rightaway. It is similar to the idea of a FUTURECAR in GTA. Later on in the game, do CREATE_CAR to create it where/when you want it.

In addition, if you want a truck with a trailer attached, just give an additional trailermodel & the game will create an articulated vehicle - note that you're still giving the position/details of the cab at the front & make sure you have enough space!! 

CAR_DATA name
Parameters
name any valid string - must be unique

CAR_DATA Declare & Set

Declares & creates a car of model type "model" at a location, with a specific remap & rotation.

When no Z value is given, the game will calculate the correct value for this (X,Y) position

In addition, if you want a truck with a trailer attached, just give an additional trailermodel & the game will create an articulated vehicle - note that you're still giving the position/details of the cab at the front & make sure you have enough space!! 

CAR_DATA name = (X,Y)   remap rotation MODEL
CAR_DATA name = (X,Y)   remap rotation MODEL TRAILERMODEL
CAR_DATA name = (X,Y,Z) remap rotation MODEL
CAR_DATA name = (X,Y,Z) remap rotation MODEL TRAILERMODEL
Parameters
name any valid string - must be unique
X,Y,Z float coordinates for car creation - if Z if left out or set to 255.0, the game will calculate correct Z
remap Vehicle remap numbers - set this to -1 to have no remap applied
MODEL valid model name - an uppercase name. See bottom of file for list.
TRAILERMODEL The type of trailer to attach. Or, use MINI_CAR to make this a small 'remote control' style car.
rotation value between 0 to 359 giving the direction of rotation.

CREATE_CAR

This actually creates a car in game - the car must have been previously 'declared' using a CAR_DATA command. Needs a specific location, remap, rotation etc - behaves in the same way as a complete CAR_DATA. 

name = CREATE_CAR (X,Y)   remap rotation MODEL END
name = CREATE_CAR (X,Y)   remap rotation MODEL TRAILERMODEL END
name = CREATE_CAR (X,Y,Z) remap rotation MODEL END
name = CREATE_CAR (X,Y,Z) remap rotation MODEL TRAILERMODEL END

Parameters

See CAR_DATA for details.

CREATE_GANG_CAR

This new command is similar to the create_car command, but makes a 'gang car' instead. You must use one of the predefined gang car types, eg isetta, miura etc with it! It will automatically add the gang logo decal to the car. 

name = CREATE_GANG_CAR (X,Y)   remap rotation MODEL END
name = CREATE_GANG_CAR (X,Y)   remap rotation MODEL TRAILERMODEL END
name = CREATE_GANG_CAR (X,Y,Z) remap rotation MODEL END
name = CREATE_GANG_CAR (X,Y,Z) remap rotation MODEL TRAILERMODEL END

Parameters

See CAR_DATA for details.

PARKED_CAR_DATA

Declares & creates a 'parked car' of model type MODEL at a location, with a specific remap & rotation. When no Z value is given, the game will calculate the correct value for this (X,Y) position

A PARKED_CAR is different to a regular car. It just sit there, doing as little as possible until the player steals one. Additionally, they don't take up a slot reserved for mission cars. The maximum parked cars allowed is 48, with 8 on the PSX. These numbers are liable to change!

TRAILERMODEL does not work with this command. Use CAR_DATA or CREATE_CAR instead. 

PARKED_CAR_DATA name = (X,Y)   remap rotation MODEL
PARKED_CAR_DATA name = (X,Y)   remap rotation MODEL TRAILERMODEL
PARKED_CAR_DATA name = (X,Y,Z) remap rotation MODEL
PARKED_CAR_DATA name = (X,Y,Z) remap rotation MODEL TRAILERMODEL

To create a simple FBI Car: 

PARKED_CAR_DATA fbicar = (094.5,076.5) -1 000 EDSELFBI

Parameters

See CAR_DATA for full details.

MAKE_CAR_A_DUMMY

Takes an already existing car, gives it a dummy driver & switches it "on" to driving - allowing it to drive around the city. 

MAKE_CAR_A_DUMMY (name)
Parameters
name must be a valid, already existing car.

Doors

  1. Doors
  2. DOOR_DATA
  3. DECLARE_DOOR_INFO
  4. UPDATE_DOOR_TARGET
  5. MAKE_DOOR_AUTOMATIC
  6. MAKE_DOOR_MANUAL
  7. OPEN_DOOR
  8. CLOSE_DOOR

There are two types of doors:

Garage doors are more complex - they will open for the same set of conditions, but their actual operation is fiddly.

Garage doors are effectively "one way" - a car goes in, a ped comes out. They will open for the car the player is in as long as it meets the requirements for this door, say model/colour. The car must approach the door fairly straight, give or take a few degrees. When the front two corners if going forwards, the back two if reversing in) are over the "line" of the door, the game will suck in the car, and chuck out the ped in front of the door in a similar fashion to GTA.

However, if the player isn't lined up correctly, or has only one corner over the "line the game will not automatically pull him in - the car must be lined up straight. Once it's started to be "sucked" the game will switch off collisions with the car - things can bounce off the car, but the car will be unaffected by collisions. The invisible "line" across the doorway (a collidable object) will prevent any other cars/peds/weapons from crossing in under the door/building. The car is sucked in at a constant rate - if the player was accelerating fast, it will drop to that speed as it gets pulled in - may look a little strange, but necessary.

As soon as the car is being "pulled" the game will switch off the 'exit' key for the player, to prevent him exiting in a strange position. This will be switched back on when the movement is finished.

DOOR_DATA

(See also: Garages Tutorial.)

Doors in GBH are one way - their primary use is on buildings for 'garages'. They give the illusion of the player entering a building & dumping a car inside. They will usually be used in conjunction with a PARK command to take the player inside & dump his/her car.

These may appear to be a little fiddly to set up properly, but they give you a lot of different power. Doors must be declared & created at the top of your file outside any functions. At the moment, all doors are automatic & default to closed - barriers will come later. 

DOOR_DATA name = STYLE (X,Y,Z)
                       (check_X,check_Y,check_Z, check_width,check_height)
                        FACE gfx_id OPEN_TYPE CLOSE_TYPE delay FLIP REVERSE
DOOR_DATA name = STYLE (X,Y,Z)
                       (check_X,check_Y,check_Z, check_width,check_height)
                        FACE gfx_id OPEN_TYPE CLOSE_TYPE delay FLIP REVERSE second_item
DOOR_DATA name = STYLE (X,Y,Z)
                       (check_X,check_Y,check_Z, check_width,check_height)
                        FACE gfx_id OPEN_TYPE CLOSE_TYPE delay FLIP REVERSE value
Parameters
Value Description
name unique string Identifies this door so you can apply commands to it.
STYLE SINGLE One cube wide.
DOUBLE Two cubes wide. Second cube is added on the clockwise side.
X,Y,Z 0 to 255 Integer values of where to place the door.
check_X,check_Y,check_Z 0.0 to 255.99 Float values describing where the door check area will be.
check_width,check_height 0.0 to edge of level? Float value of the trigger position for when the door opens.
FACE TOP North
BOTTOM South
LEFT West
RIGHT East
gfx_id 0 to 999 Integer describing which DOOR_INFO to use for this door.
OPEN_TYPE ANY_PLAYER All human characters.
ANY_CAR All vehicles.
ONE_CAR Use second_item for the name of car.
ONE_MODEL Use second_item for the car type.
ONE_CHAR_ON_FOOT Use second_item for the name of character.
ANY_PLAYER_ONE_CAR Use second_item for the name of car driven by a player.
CLOSE_TYPE CLOSE_NEVER Does not shut after being opened.
CLOSE_TIME_DELAY Waits according to the value for delay.
CLOSE_WHEN_CLEAR Shuts when nothing will get trapped.
CLOSE_WHEN_OPEN_RULE_FAILS Shuts when the OPEN_TYPE rule is not being fulfilled.
delay 0 to 255 An integer value to wait before the door closes.
FLIP FLIP_RIGHT The right hand door images is graphically flipped.
NOT_FLIPPED Default display.
REVERSE REVERSED For when two separate doors are on one block.
NOT_REVERSED Normal.
second_item Name of an object Used when open_type is neither ANY_CAR nor ANY_PLAYER.
value 0 to 255 Reserved but not used - you do not need any sort of value for it.

Door FACE Types

Doors can either be SINGLE or DOUBLE. If you set style to DOUBLE, the game will position the first half of the door at your X,Y,Z. The other half will be placed like this:

Effect of FACE Values
FACEOther Half Position
TOP (North)Right (East)
BOTTOM (South)Left (West)
RIGHT (East)Bottom (South)
LEFT (West)Top (North)
DOUBLE
Opening logic defaults to being over both blocks immediately in front of the two doors, instead of the single block in front that happens with single doors. You can now change this easily through the 'check' values - this is a float (X,Y,Z) which is the centre of the range to check, plus the check_width,check_height giving the size of the area to check.
OPEN_TYPE
Rule for opening this door. See bottom of document for list. Basically, at the moment you can order doors to open for players, for any car, for particular cars you've created, for a particular model of car. If you want the door to open for a particular car, you need to give its name at the end of the line, see second_item. If you want the door to open for a particular model, you need to give this as second_item.
CLOSE_TYPE
Rule for closing the door. This is a little more straightforward. If you give the door a close never type, it will stay permanently open & will let anything go through. All other types will only let the 'type' that opened it through, e.g the player, a particular car. Another common close type will be 'delayed' which waits a certain number of game cycles & then attempts to close the door.

One word of warning: at the moment, the game will not close the door while whatever opens the door is still standing on the opening trigger in front of the door…

DECLARE_DOOR_INFO

Another new concept: this command allows you to set up the graphics used for doors. It requires a start frame, an end frame, and the speed to play the animation at.

The 'start frame' is effectively the 'closed' frame of the door. The 'end frame' is what the door will look like when it's opened. Speed is an integer value detailing the animation speed, usually 1 to wait one cycle between each frame…

These commands should be at the top of your script outside of any actual 'function', like your other declarations. Note that the order you place the DECLARE_DOOR_INFO commands in is important for when you actually make doors - don't go changing it! 

DECLARE_DOOR_INFO (startframe, endframe, speed)
Parameters
startframe Integer value giving the tile to give door initially
endframe Integer value giving the tile that door has when animation of opening is finished.
speed Integer value giving animation speed…

UPDATE_DOOR_TARGET

This allows you to use doors with 'future cars / characters', ie you can use a door with a car that doesn't yet exist when the game runs, only when you've stored its info.

You should call UPDATE_DOOR_TARGET once you have a 'proper' pointer to the car/character stored. 

UPDATE_DOOR_TARGET (name, target)
Parameters
name Name of a previously created DOOR_DATA
target Name of the character or car related to this door.

MAKE_DOOR_AUTOMATIC

Orders a door to behave 'normally' & automatically:

  1. Wait for its opening conditions to pass.
  2. Open itself.
  3. Wait for its closing conditions.
  4. Close itself.

This is the default mode for doors. 

MAKE_DOOR_AUTOMATIC (name)
Parameters
name Name of a previously created DOOR_DATA

MAKE_DOOR_MANUAL

The opposite of MAKE_DOOR_AUTOMATIC - this makes the door fully manual & under script control. It will do nothing unless you boss it around with OPEN_DOOR and CLOSE_DOOR. 

MAKE_DOOR_MANUAL (name)
Parameters
name Name of a previously created DOOR_DATA

OPEN_DOOR

This forces a door to open. Note, the door should be MAKE_DOOR_MANUALcontrolled for best effect. 

OPEN_DOOR (name)
Parameters
name Name of a previously created DOOR_DATA

CLOSE_DOOR

This forces a door to close. This waits for it to be clear of obstructions, though! 

CLOSE_DOOR (name)
Parameters
name Name of a previously created DOOR_DATA

Reworked Kill Frenzies

  1. Reworked Kill Frenzies
  2. SET_KF_WEAPON
  3. CLEAR_KF_WEAPON
  4. START_BASIC_KF_TEMPLATE
  5. DO_BASIC_KF_TEMPLATE
  6. BASIC_KF_TEMPLATE_Example
  7. KF_TEMPLATE_BRIEFS
  8. BONUS_DECLARE
  9. START_BONUS_CHECK
  10. START_BONUS_CHECK_Example
  11. STORE_BONUS_COUNT
  12. HAS_BONUS_FINISHED
  13. HAS_BONUS_PASSED
  14. HAS_BONUS_FAILED
  15. MODELCHECK_Example
  16. SETUP_MODELCHECK_DESTROY
  17. HAS_MODELCHECK_HAPPENED

As an optimisation, there's a new scheme for doing the basic kill frenzy of 'kill a within b with c', giving a reward of either score, multiplier or lives. In a similar fashion to the multiphones, we have two template commands that do most of the work, cutting down on the amount of space in the scriptfile as well as aiding execution speed.

A full example will be given below. It takes a lot of setup to make one frenzy work:

The level also needs some setup, otherwise the game will crash when the frenzy ends:

SET_KF_WEAPON

Use this to give the player an 'infinite' weapon to be used during a kill frenzy. You must clear this off when you're finished! The game will automatically remember the player's 'real' ammo count for this weapon. 

SET_KF_WEAPON (charname, WEAPON_TYPE)
Parameters
charname Name of a player controlled character
WEAPON_TYPE the type of weapon to give!

CLEAR_KF_WEAPON

This clears off a previous given SET_KF_WEAPON, and restores the value of ammo the player had before the start of it - which might be none at all. 

CLEAR_KF_WEAPON (charname)
Parameters
charname Name of a player controlled character

START_BASIC_KF_TEMPLATE

(See also: THREAD_TRIGGER and Objects.)

This 'sets up' the kill frenzy, doing the basic work in setting one up. It will disable the thread trigger, display a couple of messages, delete the item used to start the kill frenzy & switch on the kill frenzy weapon. It effectively does the work of five lines. 

START_BASIC_KF_TEMPLATE (thread_trigger_name, base_brief_id, start_item_name, player_name, WEAPON_TYPE)
Parameters
thread_trigger_name this is the name of the THREAD_TRIGGER used to start the KF.
base_brief_id An integer for the line in the text file which explains the objective of the KF.
start_item_name Name of the object used to 'start' the kill frenzy
player_name Name of the player's character
weapon_type Type of weapon to be used for this kill frenzy. Set to NO_WEAPON if you don't mind which weapon the player uses.

DO_BASIC_KF_TEMPLATE

This does most of the hard work for the kill frenzy. It sets up the timer & counter onscreen, and waits for the bonus to finish - updating the onscreen counter each cycle.

When the bonus is finished, it checks whether the player passed or failed, and updates the relevant 'secrets counted' as well as displaying the relevant brief/message - FRENZY PASSED! etc. In addition, if the player has passed, he will get a REWARD - either SCORE, LIVES or MULTIPLIER. 

DO_BASIC_KF_TEMPLATE (bonus_name, timer_name, time_limit, onscreen_counter_name, running_count_name, target_total, base_brief_id, player_name, REWARD_TYPE, reward_value)
Parameters
bonus_name Name of a BONUS, the one used in your START_BONUS_CHECK call.
timer_name Name of a TIMER_DATA item to use for the onscreen timer
time_limit integer value detailing the number of seconds for this kill frenzy
onscreen_counter_name Name of a ONSCREEN_COUNTER item to use for the onscreen counter
running_count_name Name of a counter to use for displaying the running count onscreen
target_total the target total of 'scores' for this kill frenzy
base_brief_id integer detailing the ID of the base brief for this KF in the text file
player_name Name of the player's character
reward_type string detailing NOTHING, SCORE, LIVES or MULT
reward_value the amount of the reward type to award! If NOTHING, set this to 0.

BASIC_KF_TEMPLATE Example

This is a fully working, fully tested example of the KF template in action, complete with a list of the relevant briefs you need to put in your textfile (and the order in which they need to be!).

This does a “Kill 20 people in 60 seconds with molotovs!” type bonus. It's a reworking of Willy's current KF example. 

THREAD_TRIGGER thr_molotov_kill_frenzy1 = THREAD_WAIT_FOR_CHAR_IN_BLOCK (player, 130,109,6, do_molotov_kill_frenzy1:)

do_molotov_kill_frenzy1:
 START_BASIC_KF_TEMPLATE (thr_molotov_kill_frenzy1, 6900, molotov_kill_frenzy1, player, MOLOTOV)
 killfrenzy1 = START_BONUS_CHECK (kill_any_means, 1800, 10, 0, CHAR, NOT_EXCLUSIVE, BY_MOLOTOV, NONE, NO_OCCUPATION, -2)
 DO_BASIC_KF_TEMPLATE (killfrenzy1, frenzy_timer_downtown, 60, kf_counter, kf_counter_total, 10, 6900, player, SCORE, 5000)
RETURN

Here’s the actual code for a tank kill frenzy, with all objects and "meta" commands collected into one place. It's from bil.mis uses the #ifdef PC sections, not the PSX ones: 

// global level setup stuff
COUNTER flag_secrets_passed = 0 //SAVED_COUNTER flag_secrets_passed = 0
COUNTER flag_secrets_failed = 0 //SAVED_COUNTER flag_secrets_failed = 0
DECLARE_TOTAL_SECRETS (2) // (20)
DECLARE_SECRETS_PASSED_FLAG (flag_secrets_passed)
DECLARE_SECRETS_FAILED_FLAG (flag_secrets_failed)


// player's normal start position
PLAYER_PED shaft = (44.5,102.0,2.0) 25 0
PARKED_CAR_DATA KF_1_tank = (3.0, 30.0, 3.0) 0 92 TANK
BONUS kill_frenzy_1
FORWARD do_kill_frenzy_1:
ONSCREEN_COUNTER kf_counter
SAVED_COUNTER kf_counter_total
TIMER_DATA kf_timer


// Other stuff...


// PC KILL FRENZY ONE 
THREAD_TRIGGER thr_kill_frenzy_1 = THREAD_WAIT_FOR_CHAR_IN_CAR (shaft, KF_1_tank, do_kill_frenzy_1:)


do_kill_frenzy_1:

     START_BASIC_KF_TEMPLATE (thr_kill_frenzy_1, 4310, KF_1_tank, shaft, TANK_GUN)

     kill_frenzy_1 = START_BONUS_CHECK (NO_ZONE, 3600, 30, 0, CHAR, NOT_EXCLUSIVE, BY_ROCKET_LAUNCHER, TANK, NO_OCCUPATION)

     DO_BASIC_KF_TEMPLATE (kill_frenzy_1, kf_timer, 120, kf_counter, kf_counter_total, 30, 4310, shaft, LIVES, 1)

RETURN


LEVELSTART


// Other stuff...


LEVELEND

KF_TEMPLATE_BRIEFS

The KF briefs have changed - the base brief you specify is now just the number of the one unique brief per frenzy. 

[6900] Kill 20 people with molotovs within 60 seconds!

These other briefs are in the e.gxt file, and you no longer need them in your own textfile. 

[kfstart] KILL FRENZY
[kfpass] FRENZY PASSED!
[kffail] FRENZY FAILED!

THREAD_TRIGGER

  1. THREAD_TRIGGER
  2. ENABLE_THREAD_TRIGGER
  3. DISABLE_THREAD_TRIGGER
  4. THREAD_WAIT_FOR_CHAR_IN_CAR
  5. THREAD_WAIT_FOR_CHAR_IN_BLOCK
  6. THREAD_WAIT_FOR_CHAR_IN_AREA
  7. THREAD_WAIT_FOR_CHAR_IN_AREA_ANY_MEANS
  8. THREAD_WAIT_FOR_ANSWER_PHONE
  9. THREAD_ID
  10. CREATE_THREAD
  11. STOP_THREAD

THREAD_TRIGGER is a new data type. It operates in a similar way to TRIGGER in GTA. It starts a new mission thread (like an old KICKSTART) when a particular condition has been met. Such as when a character enters a car, or the player enters a specific gang zone.

They have a slightly different behaviour to other data types in GTA2script. They are always declared & set at the same time, never mid-game. However, they can be disabled & enabled mid-game.

So it's possible to declare a THREAD_TRIGGER using a car that has yet to be physically created. As long as it has been declared & has been created before the trigger is used, the game will operate.

ENABLE_THREAD_TRIGGER

Switches on a previously created THREAD_TRIGGER item. Any car or character involved in the thread_trigger must have been created at this point. 

ENABLE_THREAD_TRIGGER (triggername)

DISABLE_THREAD_TRIGGER

Switches off a previously created THREAD_TRIGGER item. Any THREAD_TRIGGER that you've yet to 'create' the cars/chars involved with it should be disabled. 

DISABLE_THREAD_TRIGGER (triggername)

THREAD_WAIT_FOR_CHAR_IN_CAR

This creates a trigger that waits for the given character (usually the player but not necessarily) entering a given car. When this happens, a new mission thread (ie process) is started, running the function listed. When the new thread encounters its last RETURN command, it will end itself.

This is a 'declare' & should be outside any 'functions'. Note, there is a limit of about 30 of these in any one script. This should be more than enough. 

THREAD_TRIGGER triggername = THREAD_WAIT_FOR_CHAR_IN_CAR (
                             charname, car_name, labelname:)
Parameters
charname Name of a character or player. MUST be created before the trigger is enabled.
car_name Name of the specific vehicle to wait for. Must already exist when you enable the trigger.
labelname: Name of the subroutine which is 'fired' by the trigger. Note the : at the end!

THREAD_WAIT_FOR_CHAR_IN_BLOCK

This is similar to the above command, but waits for a particular character entering a block on foot. 

THREAD_TRIGGER triggername = THREAD_WAIT_FOR_CHAR_IN_BLOCK(
                             charname, X,Y,Z, labelname:)

Example: 

CHAR_DATA player
CAR_DATA dummycar
THREAD_TRIGGER charcarthread = THREAD_WAIT_FOR_CHAR_IN_CAR (player, dummycar, somecode:)
THREAD_TRIGGER charblock = THREAD_WAIT_FOR_CHAR_IN_BLOCK (player, 123,45,2, someothercode:)
Parameters
charname Name of a character or player. MUST be created before the trigger is enabled.
X,Y,Z Three integers declaring the block the character must enter on foot.
labelname: Name of the subroutine which is 'fired' by the trigger. Note the : at the end!

THREAD_WAIT_FOR_CHAR_IN_AREA

This is similar to the above command, but waits for a particular character entering a defined area on foot. 

THREAD_TRIGGER triggername = THREAD_WAIT_FOR_CHAR_IN_AREA (charname, X,Y,Z, width,height, labelname:)
Parameters
charname Name of a character or player. MUST be created before the trigger is enabled.
X,Y,Z Three floats describing the centre of area…
width,height Size of area to check for.
labelname: Name of the subroutine which is 'fired' by the trigger. Note the : at the end!

THREAD_WAIT_FOR_CHAR_IN_AREA_ANY_MEANS

This is similar to the THREAD_WAIT_FOR_CHAR_IN_AREA command, but waits for a particular character entering a defined area by any means! 

THREAD_TRIGGER triggername = THREAD_WAIT_FOR_CHAR_IN_AREA_ANY_MEANS (charname, X,Y,Z, width,height, labelname:)
Parameters
charname Name of a previously declared character. Again, does not need to have actually been created at this point…
X,Y,Z Three floats describing the centre of area…
width,height width & height of area to check for.
labelname the subroutine in the script that the game calls when the trigger action is fired. Note the labelname has a ':' at the end!

THREAD_WAIT_FOR_ANSWER_PHONE

This creates a trigger that waits for the given character (usually the player but not necessarily) nswering a given phone. When this happens, a new mission thread (ie process) is started, running the function listed.

When the new thread encounters its last RETURN command, it will shutdown itself. This is a 'declare' & should be outside any 'functions'. Note, there is a limit of about 30 of these in any one script. This should be more than enough. 

THREAD_TRIGGER triggername = THREAD_WAIT_FOR_ANSWER_PHONE
                              (charname, phonename, labelname:)
Parameters
charname Name of a character or player. MUST be created before the trigger is enabled.
phonename Name of a previously declared phone. Must be created when you go to use the trigger for real.
labelname: Name of the subroutine which is 'fired' by the trigger. Note the : at the end!

THREAD_ID

(This feature is not available and was never used.)

CREATE_THREAD

(This feature is not available and was never used.)

STOP_THREAD

(This feature is not available and was never used.)

On-screen Messages

  1. DISPLAY_MESSAGE
  2. CLEAR_ALL_BRIEFS
  3. DISPLAY_BRIEF
  4. DISPLAY_BRIEF_SOON
  5. DISPLAY_BRIEF_NOW
  6. IS_BRIEF_ONSCREEN

See also: Messages Which Play a Sound and Gang Heads for Messages.

Designers will be able to display text messages onscreen in a similar fashion to GTA, through a unique ID for each message. The actual text will be kept in a file separate from the mission script to allow easy translations & alterations to be made. There will be a number of different commands for displaying text, to handle the different methods, such as 'big message' & 'standard' message, e.g. 

MESSAGE (99)
          PAGER_MESSAGE (23)

CLEAR_ALL_BRIEFS

Clears all queued briefs currently waiting to be displayed. Do this after a DISPLAY_BRIEF_NOW & you will effectively be clearing all waiting text & any text that was getting displayed before the DISPLAY_BRIEF_NOW. 

CLEAR_ALL_BRIEFS

DISPLAY_MESSAGE

Displays a message in the large "bold" font in the centre of the screen. Used in GTA for the “WASTED!” messages. These messages MUST be all upper-case. We need some coordination with messages like “MISSION COMPLETE!” - these should be in the e.gxt file, shared between all three scripts, rather than specific to each one. No point duplicating text/effort. 

DISPLAY_MESSAGE (id)
Parameters
id message ID to display - IDs are the numbers in the text file (*.gxt).

DISPLAY_BRIEF

Displays a "briefing" message at the bottom of the screen. Used in GTA for most messaging. GTA2 queues message to display. Messages have a low priority. 

DISPLAY_BRIEF (id)
Parameters
id message ID to display - IDs are the numbers in the text file (*.gxt).

DISPLAY_BRIEF_NOW

Displays a "briefing" message at the bottom of the screen. Use this for important messages, as they have a high priority! 

DISPLAY_BRIEF_NOW (id)
Parameters
id message ID to display - IDs are the numbers in the text file (*.gxt).

DISPLAY_BRIEF_SOON

Another new brief command - use this for messages that are important more important than ordinary DISPLAY_BRIEF, but less important than DISPLAY_BRIEF_NOW. So, a DISPLAY_BRIEF_SOON will always get done before DISPLAY_BRIEF, but /after/ any SOONs already in the queue. A DISPLAY_BRIEF_NOW will always override anything in the queue, including other 'NOW's. 

DISPLAY_BRIEF_SOON (id)
Parameters
value an integer value describing the message ID from e.gxt to display soon.

Mission Language Commands (not grouped)

CRANE DATA

Declares & creates a crane. This declares a "basic crane": 

CRANE_DATA name = (X,Y) home_rotation homecrane

First crane picks up a car and drops it at the target (X,Y) with the given target_rotation: 

CRANE_DATA name = (X,Y) home_rotation HOMECRANE
            FIRST (targetX,targetY) target_rotation

Second crane picks up the crushed car and drops it at the target (X,Y) with the given target_rotation: 

CRANE_DATA name = (X,Y) home_rotation HOMECRANE
           SECOND (targetX,targetY) target_rotation

This declares a "two target crane" used to link with crushers/conveyors. The first target is the position cars are initially dropped at. The second target is the point that the crushed car will be dropped off on: 

CRANE_DATA name = (X,Y) home_rotation HOMECRANE
            FIRST (targetX,targetY) target_rotation
           SECOND (targetX,targetY) target_rotation
Parameters
name valid name string
X,Y float (X,Y) position to create the base of the crane on - the crane will automatically be placed at the correct Z. A crane cannot be placed 'underneath' a lid.
home_rotation This is the rotation the crane 'returns' to when it isn't picking up anything, i.e. the angle the crane points to normally.
HOMECRANE Name of another crane or NO_HOMECRANE. This allows you to make the crane wait for another crane nearby to return to its own home position before doing any processing. Use this to prevent two cranes from colliding with each other.
targetX,>targetY This declares a 'target point', where any cars picked up will be dropped
target_rotation Any car picked up will be rotated when lifted so that it has this rotation when crane is finished.

CONVEYOR

Declares & creates a conveyor. Conveyors move in a given direction any objects that are on its space. 

CONVEYOR name = (X,Y) (width,height) speedX speedY
CONVEYOR name = (X,Y,Z) (width,height) speedX speedY
Parameters
name any valid name string
X,Y,Z float coordinates to place conveyor. This is the centre of the conveyor. If Z is missed out, the game will place it automatically.
width,height The size of the conveyor, given as floats.
speedX this is an integer value describing how many pixels the conveyor will move objects horizontally each game cycle. To the right is positive, left is negative
speedY As speedX, but describing the vertical movment. Down is positive, up is negative.

GENERATOR

Declares & creates a generator. Generators create new objects of a given type at regular intervals. Ideally placed at the top of a conveyor belt… Multiple generators can be placed at the same position to give more than one object type created at a spot. Needs a coordinate & rotation where the objects get created, and two 'delays'. These give a minimum/maximum time between each object creation. If set the same, objects will be created at a regular interval.

Generators by default are switch OFF. 

GENERATOR name = (X,Y)   rotation WEAPON_TYPE mindelay maxdelay
GENERATOR name = (X,Y,Z) rotation WEAPON_TYPE mindelay maxdelay
GENERATOR name = (X,Y)   rotation WEAPON_TYPE mindelay maxdelay ammo
GENERATOR name = (X,Y,Z) rotation WEAPON_TYPE mindelay maxdelay ammo
Parameters
name valid name string
X,Y,Z Coordinate at which the objects will be positioned - if Z is missed out, the game will place it at the top Z level as normal.
rotation This is the rotation value all objects created will be given
OBJECT_TYPE A string listing one weapon type - this GENERATOR will create objects of this type
mindelay An integer describing the minimum length of game cycles between creation. Valid range is 0–65535 cycles
maxdelay An integer describing the maximum length of game cycles between creation
ammo If you're generating weapons, use this to specify a particular ammo value to give each generated weapon. Miss it out, and the game will use the 'default' value for this weapon.

DESTRUCTOR

Declares & creates a destructor. Destructors 'delete' any object that enters its space. Destructors now remove any cars/chars/objects that enters its space. Ideally placed at the end of a conveyor to remove any objects moving along.

Needs an (X,Y) or (X,Y,Z) coordinate plus width,height. 

DESTRUCTOR name = (X,Y) (width,height)
DESTRUCTOR name = (X,Y,Z) (width,height)
Parameters
name Valid name string
X,Y,Z Float coordinate for the centre of the destructor.
width,height Width & height of the destructor - given as floats.

CREATE_DESTRUCTOR (crashes the game)

Creates a destructor mid-game. 

name = CREATE_DESTRUCTOR (X,Y) (width,height) END
name = CREATE_DESTRUCTOR (X,Y,Z) (width,height) END

Parameters

See DESTRUCTOR for details.

LEVELSTART

This command lets the game know where the 'start' of the level processing should be. It will contain a group of commands that effectively "run" the level. 

LEVELSTART

LEVELEND

This flags the 'end' of the level commands. Should end the block of code after a levelstart. 

LEVELEND

CHECK_CHARACTER_HEALTH

Performs a check on this character's health. If health is greater or equal to the specified point value, returns TRUE otherwise FALSE. 

CHECK_CHARACTER_HEALTH (name, value)
Parameters
car_name any valid car_name. Must have been created beforehand
value Minimum amount of health to check - valid range is 0–255, see below for examples.
Examples for value
0 Character is dead
50 Dummy ped
100 Gang ped
255 Invincibility

Multiplayer

If you check for a player having 0 health, the command checks for “0 or more health”. In other words, this checks if the player exists. This is essential when making safe multiplayer scripts.

Many commands will crash the game if that player does not currently exist. However, you can wrap these parts of your code in an IF statement to CHECK_CHARACTER_HEALTH for that player. If the player is in the game, the commands inside it will run. If the player is not in the game, the commands will be skipped.

HAS CHARACTER DIED?

Performs a simple check on a character's health to see if they've just died. Returns TRUE if char is dead, FALSE if char is still alive.

The value will remain TRUE for about 1 second (30 frames) to allow lazy checking. 

HAS_CHARACTER_DIED (name)
Parameters
name any valid character name, including 'player_ped' for a check on the player.

CHECK CAR'S DAMAGE LEVEL

Performs a check on this car to see the percentage level of damage. If greater or equal to the specified value, returns TRUE otherwise FALSE. Note this works in percentages, *different* to how character health works: 

     IF (CHECK_CAR_DAMAGE_LEVEL (car_one, 50))
          // display message - "car is well bashed!"
     ELSE
          // display message - only a little dent!
     ENDIF

CHECK_CAR_DAMAGE_LEVEL (car_name, value)
Parameters
car_name any valid car_name. Must have been created beforehand
value percentage of damage to check. 0 is completely undamaged. 100% is completely wrecked.

CHECK CAR HAS DRIVER

Performs a check on this car to see if it has a valid driver. Returns TRUE if it does, FALSE if not. A car needs a virtual driver for it to be able to drive around the city.

This DOES work if a player is in the vehicle. 

CHECK_CAR_HAS_DRIVER (car_name)
Parameters
car_name any valid car_name. Must have been created beforehand

HAS CAR GOT DRIVER?

Simple quick check to see if a particular car currently has a driver - this can be any character driving it, whether scripted or a random dummy. Returns TRUE if so, FALSE if not.

This DOES NOT work if a player is in the vehicle. 

HAS_CAR_GOT_DRIVER (car name)
Parameters
car name Name of a previously created car

IS CHARACTER IN CAR?

Checks to see if a particular character is in a particular car. Returns TRUE if it is, FALSE if not.

This DOES work if a player is in the vehicle. 

IS_CHARACTER_IN_CAR (charname, car_name)
Parameters
charname Name of valid, existing character
car_name Name of valid, existing car

IS CHARACTER STOPPED?

Checks to see if a particular character is stationary (ie not moving!). If in a car/train, checks its speed, if on foot, checks ped's speed. Works with any valid character. Returns TRUE if stopped, FALSE if not. 

IS_CHARACTER_STOPPED (name)
Parameters
name Name of a valid existing character

ARROW_DATA

This command 'declares' space for an arrow to be later used in the game. Currently, you really only need one arrow for each possible colour, but it's possible to set up multiple arrows of the same colour. Current maximum is likely to be around 4 or 6, but this could be changed if necessary. 

ARROW_DATA name
Parameters
name a unique name string.

POINT_ARROW_AT

Sets an existing arrow to point towards either a location, character, car or object. All items must be valid existing items. If target is an object, the arrow must be cancelled before object gets deleted. 

POINT_ARROW_AT (arrow_name, name)
POINT_ARROW_AT (arrow_name, X,Y,Z)
Parameters
arrow_name Name of an arrow declared with an ARROW_DATA.
name Name of either a car, character or object.
X,Y,Z must be a valid float (X,Y,Z) coordinate.

SWITCH OFF ARROW

Clears a previously created arrow 

REMOVE_ARROW (arrow_name)
Parameters
arrow_name Name of an arrow declared with an ARROW_DATA

MAP ZONE DECLARE

Simple command to "declare" a mapzone with a name. This zone must exist in your map, otherwise an error will be given when the game tries to load the script. Using GTA2script, you can set some of the parameters for zones, such as densities, car ratios, gang affiliation etc. 

MAP_ZONE name
Parameters
name valid string that is in the map info (*.gmp).

MAP ZONE

Like the declare, but sets up values for each piece of info for this zone info structure. Essentially, ten pieces of info are needed, for densities & ratios for cars & character types. The fields are: 

MAP_ZONE name = (car_density,good_car_ratio,bad_car_ratio,police_car_ratio, ped_density,mugger_ratio,carthief_ratio,elvis_ratio,gang_char_ratio,police_ped_ratio, gang_car_ratio)

Example for an extremely busy city, taken from the Gang Cars tutorial: 

MAP_ZONE City01 = (1000,350,200,000, 1000,100,100,100,700,000, 450)
Parameters
car_density how busy the zone is for cars
good_car_ratio ratio of "good" quality models
bad_car_ratio ratio of "bad" below average quality models
police_car_ratio the chance of getting a patrolling police car driving around as a dummy
ped_density how busy the zone is for characters
mugger_ratio frequency of mugger peds
carthief_ratio frequency of car thieves
elvis_ratio frequency of elvis peds
gang_char_ratio frequency of getting random gang members
police_ped_ratio frequency of getting a policeman walking around as a dummy
gangcar_ratio how busy the zone is for gang cars

Densities work in a range of 0 to 1000. 0 guarantees no cars/peds are created, 1000 means the game will attempt to make 2 cars each cycle, 3 peds. 500 means 1 car each cycle, approx 1 or 2 peds.

Car Ratios:

All car ratios must add up to 1000 and again work on a sort of percentage style. If you have a good car ratio of 100, then 1 time in 10, a good car will be created. If that ratio was 500, then 1 in 2 would be "good". On top of the ratios listed, there is an "average car ratio" which is automatically calculated 

average ratio = 1000 - (goodcar ratio + badcar ratio + policecar ratio)

Thus, if you want no average cars, make sure all other ratios add upto 1000.

A high class neighbourhood with little crime: 

goodcar 600
badcar 0
policecar 300
(average thus 100)

A rundown, crimeridden neighbourhood: 

goodcar 0
badcar 700
policecar  0
(average thus 300)

Ped Ratios:

Again, ped ratios work in a range of 0 to 1000, with all ratios adding up to a total of 1000 again. Each ratio is the "chance" of getting a random ped in the zone of this occupation. This time, on top of the given ratios, there is a "dummy ped" ratio, calculated by 

dummyped ratio = 1000 - muggers + car thieves + elvis + gangpeds + police peds

GIVE WEAPON

Gives a previously existing character a weapon - used specifically for non-player characters. It gets given a certain amount of predefined ammo, and note each character can only use one weapon type at any time. Do not use the car_ types at this time.

To give player a weapon, you must specify the amount of ammo to give him! See second variant of command…

See bottom of document for list of weapon types. 

GIVE_WEAPON (charname, weapon_type)
GIVE_WEAPON (player_name, weapon_type, amount of ammo)
Parameters
charname any valid character name
weapon_type a name of a valid weapon type:
player_name Name of a valid existing player character
amount of ammo interger value listing the amount of ammo to give player for this weapon.

LOCATE CHARACTER ANY MEANS

Waits for a particular character to enter a particular 'location', ie an (X,Y,Z) with a (width,height) giving the ability to check a 'box' rather than just one particular block. This 'box' can be less than a block in width/height.

This is NOT a blocking function, it will return TRUE when this character enters the box whether on foot or driving a car, FALSE otherwise. If necessary, I can change it to return TRUE if a passenger inside a car - this will complicate the code however. 

LOCATE_CHARACTER_ANY_MEANS (charname, X,Y,Z, width,height)

Example: 

LOCATE_CHARACTER_ANY_MEANS (playerone, 123.5,45.5,2.0, 3.0,1.0)

This would check for the player entering the box (120.5,44.5,2.0) to (126.5,46.5,2.0).

Parameters
charname Name of a previously created character, including the player character.
X,Y,Z float centre point of 'box' to check
width,height float dimensions of box to check for character.

LOCATE CHARACTER ON FOOT

Waits for a particular character to enter a particular 'location', ie an (X,Y,Z) with a (width,height) giving the ability to check a 'box' rather than just one particular block. This 'box' can be less than a block in width/height.

This is NOT a blocking function, it will return TRUE ONLY when this character enters the box on foot, FALSE otherwise 

LOCATE_CHARACTER_ON_FOOT (charname, X,Y,Z, width,height)

This would check for the player entering the box 120.5, 44.5, 2.0 to 126.5, 46.5, 2.0 on foot only: 

LOCATE_CHARACTER_ON_FOOT (playerone, 123.5,45.5,2.0, 3.0,1.0)
Parameters
charname Name of a previously created character, including the player character.
X,Y,Z float centre point of 'box' to check
width,height float dimensions of box to check for character.

LOCATE_CHARACTER_BY_CAR

Waits for a particular character to enter a particular ‘location’, ie an (X,Y,Z) with a (width,height) giving the ability to check a box rather than just one particular block. This box can be less than a block in width or height.

This is not a blocking function, it will return TRUE only when this character enters the box driving a car, FALSE otherwise. As with ANY_MEANS, I may change this to return TRUE if the character is a passenger in a car. 

LOCATE_CHARACTER_BY_CAR (charname, X,Y,Z, width,height)

This would check for the player entering the box (120.5,44.5,2.0) to (126.5,46.5,2.0) but only if they are in a vehicle: 

LOCATE_CHARACTER_BY_CAR (playerone, 123.5,45.5,2.0, 3.0,1.0)
Parameters
charname Name of a previously created character, including the player character.
X,Y,Z float Centre point of 'box' to check.
width,height float Dimensions of box to check for character.

LOCATE STOPPED CHARACTER

These operate exactly like LOCATE_CHARACTER, except for one difference: the character must *stationary* inside the box, ie have zero speed. Returns TRUE when character fulfils condition, FALSE otherwise. 

LOCATE_STOPPED_CHARACTER_ANY_MEANS (charname, X,Y,Z, width,height)
LOCATE_STOPPED_CHARACTER_ON_FOOT (charname, X,Y,Z, width,height)
 LOCATE_STOPPED_CHARACTER_BY_CAR (charname, X,Y,Z, width,height)
Example
LOCATE_STOPPED_CHARACTER_ON_FOOT (dummychar, 253.0,12.0,3.0, 1.0,5.0)

This will return TRUE when the character dummychar stops in the box (252.0,7.0) to 254.0,17.0) at height 3.0

CHARACTER DECLARE

Declares 'space' for a single character 

CHAR_DATA (name)
Parameters
name any valid unique string.

CHAR_DATA

Declares & creates a character at the specified (X,Y,Z). If Z is missed out, the game will automatically place the character at the top 'Z' value, in the same way as cars' Z is handled. The character will have the remap & rotation listed, as well as the occupation listed. A list of ped remaps will be created. See bottom of document for valid occupations.

A character's occupation defines his behaviour. For instance a dummy ped will just wander around in the way a 'dummy' does, a 'mugger' will go attack a ped & run away. See below for a current list of valid occupations. 

CHAR_DATA name = (X,Y) remap rotation OCCUPATION
CHAR_DATA name = (X,Y,Z) remap rotation OCCUPATION
CHAR_DATA mugger_one =   (123.4,023.2,2.0) 0 180 MUGGER
CHAR_DATA just_a_dummy = (004.4,110.5,4.0) 3 045 DUMMY
Parameters
name a unique string that will be used to refer to this character.
X,Y,Z float valid coordinates that the character will exactly be positioned at.
remap an integer detailing what remap to apply to this character.
rotation an integer detailing the angle the character will face. Valid angles are 0 to 359
OCCUPATION a string detailing what 'occupation' or behavioud this character will start with.

CREATE CHAR

Creates a character mid-game using a previously declared character 'slot'. As with almost all 'creates', the Z value may be skipped, leaving the game to calculate the correct Z level. 

charname = CREATE_CHAR (X,Y) remap rotation OCCUPATION END
charname = CREATE_CHAR (X,Y,Z) remap rotation OCCUPATION END
CHAR_DATA  examplechar
CHAR_DATA  anotherchar

examplechar = CREATE_CHAR (123.4,005.6,2.0) 00 350 MUGGER END
anotherchar = CREATE_CHAR (034.5,003.9) 03 180 CAR_THIEF END
Parameters
charname a previously declared character, declared using CHAR_DATA charname.
X,Y,Z float valid gameworld coordinate, at which the character will be positioned.
remap remap given to the character on creation
rotation the rotation the character will face, valid values are 0 to 359
OCCUPATION the default 'job'/'behaviour to give the character - given as a string.

IS_CAR_IN_BLOCK

This command checks to see if a particular car is inside a particular block. Returns TRUE if so, FALSE if not. The car must have previously been created. 

IS_CAR_IN_BLOCK (car_name, X,Y,Z)
IS_CAR_IN_BLOCK (car_name, X,Y,Z, width,height)
IF (IS_CAR_IN_BLOCK (car_to_steal, 123.5,45.5,2.0))
 DISPLAY_BRIEF (8800)
ENDIF
Parameters
car_name string giving the name of a previously created, existing car
X,Y,Z float coordinates giving the block to check.
width,height width/height of location to check instead of 'just' one block. This is the TOTAL width/height - ie 1 will do it 0.5 in that direction…

This command allows you to set the details of the new 'threat' searching for a character. A threat is for instance another shooting at this one, a rival gang member, or the player's character. By setting the 'threat search' you alter how this character will look for possible threats - you can make him ignore some threats, or only look for threats in his 'line of sight'. 

SET_CHAR_THREAT_SEARCH (charname, SEARCH_TYPE)
CHAR_DATA guard_one = (123.4,45.5,2.0) 0 180 GUARD
SET_CHAR_THREAT_SEARCH (guard_one, LINE_OF_SIGHT_PLAYER_ONLY)
Parameters
charname A valid existing character.
SEARCH_TYPE One of the valid threat search types.

SET CHAR THREAT REACTION

A follow on command from 'SET_CHARACTER_THREAT_SEARCH', this command allows you to decide how a character reacts once he's found a threat. 

SET_CHAR_THREAT_REACTION (charname, reaction_type)

These two commands make the character 'mayor_char' run away from the player as soon as

the character sees the player: 

SET_CHAR_THREAT_SEARCH (mayor_char, LINE_OF_SIGHT_PLAYER)
SET_CHAR_THREAT_REACTION (mayor_char, RUN_AWAY)
Parameters
charname Name of a valid previously created character
reaction_type one of the valid threat reaction types

SET CHAR OBJECTIVE

This is a critical command that allows you to effectively order about characters. A character objective is a 'command' to its AI routines to do something, attempt something, go somewhere, kill something. Objectives will be used for character send-tos for example. They will take away a lot of the complexity involved with character missions in GTA, and give a flexibility as well that should allow for more detailed, more complex missions & pre-defined 'scenes'.

Each character can have one main objective at any time, but this may be changed as often as needed - there should be little overhead in doing this. Additionally, each character in the game has a secondary objective based on its gang affiliation - this is all 'under the surface' and you should never need to worry about it. This second objective is used to make the 'gang zones' work.

Objectives have different possible 'states' - executing & passed. Certain objectives have a further state - 'failed'. Two secondary commands allow you to check the status of objectives, see below for information.

Command

SET_CHAR_OBJECTIVE (charname, objective type)

The basic, straightforward command, taking in just the character's name & the new objective type. 

SET_CHAR_OBJECTIVE (charname, objective type, second_item)

This command contains an extra piece of info - a name of a previously declared item. Objectives that need this info are likely to work on a second character, car or possibly an object, ie follows, kills, etc. 

SET_CHAR_OBJECTIVE (charname, objective type, X,Y,Z)

This command is for objectives dealing with locations - ie 'send to' style objectives. In addition to the charname/objective type, it has a (X,Y,Z) coordinate detailed with floats.

There are likely to be future variants with different info…

Objective Types

The following objective types need no extra 'info' to work, so use the above command.

NO_OBJ Order's the character to pretend to be a dummy & just wander around doing nothing in particular. Useful for when you're no longer interested in a character. See also MAKE_CHAR_DO_NOTHING.
WAIT_ON_FOOT Orders the char to wait on his current 'spot'/location, ie the char will stand on his current spot until something else happens.
FLEE_ON_FOOT_TILL_SAFE The char 'flees' its current area until the char thinks he is safe. The size of the area is currently hardcoded to about 6 blocks, but this will change with future releases.
GUARD_SPOT Orders the character to 'guard' his current standing position. If another character 'attacks' him, ie shoots nearby, the guard will attemp to shoot back. Best to give him a weapon!
GUARD_AREA Similar to GUARD_SPOT, except the char guards his current area. At the moment, this is hardcoded to roughly 3/6 blocks, but this will be changed in the near future.
WAIT_IN_CAR Orders the character to just 'wait' inside his current car. He'll do nothing - won't drive off like a normal driver.

These Objective Types need a second 'item' to work on. The item must be of the correct type, ie char/car/obj and have been created previously in the script.

KILL_CHAR_ON_FOOT Orders the char to chase & kill this other particular character. To be effective, you should give the character a weapon, otherwise he'll hunt down the char & start punching him… Set second_item to be the name of the char to kill.
KILL_CHAR_ANY_MEANS Orders the char to chase & kill this other particular character. If target is offscreen, this character will chase by car. Character will warp so don't put an arrow on him!!! Set second_item to be the name of the char to kill.
FLEE_CHAR_ON_FOOT_TILL_SAFE Orders the character to runaway on foot from a second char until he feels 'safe'. When this happens, main objective gets flagged as 'passed', and the char will just start walking around normally. Change this behaviour by watching out for the objective getting passed, then give him a different objective. Set second_item to be the name of the character to flee.
FLEE_CHAR_ON_FOOT_ALWAYS Orders the character to runaway on foot from a second char forever. Set second_item to be the name of the character to flee.
GOTO_CHAR_ON_FOOT Orders the character to follow a second character. The char will run towards the second char, chasing after if necessary. As soon as the char 'catches up' with the second char, the objective is flagged as passed. IainR will be adding a 'goto_char_always' command that will continually follow a character. Set second_item to be the name of the character to go to.
LEAVE_CAR Orders the character to exit this car. Set second_item to be the name of the car the character is in.
ENTER_CAR_AS_PASSENGER Orders the character to enter this car as a passenger, via one of the car's passenger doors - NOT the backdoor! Set second_item to be the name of the car for the character to enter.
ENTER_CAR_AS_DRIVER Orders the character to enter this car as a driver, via the car's driver door if possible. Set second_item to be the name of the car for the character to enter.
FOLLOW_CAR_IN_CAR Orders the character to follow this second car in the car he is currently driving. The character must be in a car when you set this objective! Set second_item to be the name of the car to follow – this car must also have a driver.
FIRE_AT_OBJECT_FROM_VEHICLE Orders the character to fire from his current vehicle at a particular object. Really only useful when the character is inside a tank! Set second_item to be the name of the object to fire at. Only works with Tank at moment!!
DESTROY_OBJECT Orders the character to shoot & destroy a particular object. Set second_item to be the name of the object
DESTROY_CAR Orders the character to shoot & destroy a particular car. Again, set second_item to be the name of the car.

These Objective Types require a 'coordinate' - use: 

SET_CHARACTER_OBJECTIVE (name, TYPE, X,Y,Z)
GOTO_AREA_ON_FOOT Orders the character to run on foot to a particular spot on the map.
GOTO_AREA_IN_CAR Orders the character to go by car to a particular spot on the map. You must make sure character is inside a car!!!

FOLLOW_CAR_ON_FOOT_WITH_OFFSET

This requires a second_item, an integer rotation, and a floating point distance. Remember to limit the driver’s maximum speed so the characters can stay with it! Also remember you might need bigger distances for bigger cars when they turn, such as the Limosine. 

SET_CHARACTER_OBJECTIVE (name, FOLLOW_CAR_ON_FOOT_WITH_OFFSET, second_item, rotation,distance)

Example, following about 1 block away to the left: 

SET_CHARACTER_OBJECTIVE (bodyguard, FOLLOW_CAR_ON_FOOT_WITH_OFFSET, presidential_limo, 270,1.5)

Example, leading the car by a few blocks (might fall behind when the car turns): 

SET_CHARACTER_OBJECTIVE (bodyguard, FOLLOW_CAR_ON_FOOT_WITH_OFFSET, presidential_limo, 000,4.0)
FOLLOW_CAR_ON_FOOT_WITH_OFFSET Orders the character to follow the movements of a particular car 'on foot'. distance is measured from the centre of the car. rotation sets which side of the car. second_item is the name of the car to follow.

STORE CAR CHARACTER IS IN

Looks to see whatever car this specified character is in, and stores its info as a valid car_data. If the character is not in a car, it currently will generate an error, but in the final game it will proceed to the next command. 

STORE_CAR_CHARACTER_IS_IN (charname, car_name)
Parameters
charname Name of a valid existing character
car_name Name of a CAR_DATA slot. Will overwrite any info in it.

IS CAR WRECKED?

Checks to see if car's damage level means it's wrecked or if the car has just started sinking. Similar to the damage check, but simpler for speed. Returns TRUE if wrecked, FALSE if not. 

IS_CAR_WRECKED (car_name)
Parameters
car_name Name of a valid existing car…

CHANGE CHAR REMAP

Alters the remap of a character's ped graphic to a new value 

CHANGE_CHAR_REMAP (charname, new remap)
Parameters
charname Name of a previously created character, including the player
new remap an integer value describing the remap value - values will be given later.

CHANGE CAR REMAP

Alters the remap of a car to a new value. If the car is an artic vehicle, it handles remapping the attached 'truck'. 

CHANGE_CAR_REMAP (car_name, new remap)
Parameters
car_name Name of a previously created car.
new remap integer value describing the remap value to apply to the car. Legal values will be given at a later date.

CHECK CAR MODEL

Checks to see if this car has a specific model. Returns TRUE if so, FALSE if not. 

CHECK_CAR_MODEL (car_name, model)
Parameters
car_name Name of a previously created car
model Name of a valid carmodel, e.g rtype etc.

CHECK CAR REMAP

Checks to see if this car has a specific remap. Returns TRUE if so, FALSE if not. 

CHECK_CAR_REMAP (car_name, remap id)
Parameters
car_name Name of a previously created car
remap id integer value listing a valid remap value.

CHECK CAR MODEL AND REMAP

Checks to see if this car has a specific remap AND a specific model. Returns TRUE if so,, FALSE if not. Provided to ease checks & increase efficiency. 

CHECK_CAR_MODEL_AND_REMAP (car_name, MODEL, remap id)
Parameters
car_name Name of a previously created car
MODEL Name of a valid car model type
remap id integer value listing a valid remap value.

DELAY HERE

Waits for a given number of game cycles. This is a 'blocking' command - the game will not pass this line until the cycle count is passed. Should not be used inside 'exec' blocks or WHILE_EXEC commands. 

DELAY_HERE (count)
Parameters
count integer number of cycles to wait

DELAY

Waits for a given number of game cycles, but does not "block". Returns TRUE while timer hasn't run out, FALSE once it's passed its cycle check. 

DELAY (count)
Parameters
count integer number of cycles to wait…

SET GANG INFO

Declares & sets the information for a gang. Currently allows you to choose the colour of gang members & their weapon type to use, but this will eventually change to allow their 'gang car' type & any other info needed. 

SET_GANG_INFO (gang_name,remap, BASIC_WEAPON,ANGRY_WEAPON,HATE_WEAPON, arrow_colour,X,Y,Z, respect, MODEL,car_remap)

Gang names must match the gang names you use in the GANG ZONES set up inside your map. The first four characters of each gang must be unique as its those that are used to 'differentiate' between gang zones. Note gang names can be longer than 4 characters though!

This command can now also be called 'mid-game' to change the gang's details, ie use this mid-game to alter what weapon the gang members use… However, you should still do a SET_GANG_INFO for each gang near the top of your file, BEFORE your phones.

Here’s an example: 

SET_GANG_INFO (copgang,0, PISTOL,SHOTGUN,MACHINE_GUN, 4,12.5,6.5,2.0, 1, COPCAR,-1)

Do this for all your gangs. It’s a very long command and takes some explaining!

Parameters
gang_name Must match the gang zone names in your .gmp map file.
car_remap Colour of the gang members.
BASIC_WEAPON For killing other gangs’ members if they don’t like you (one or two bars).
ANGRY_WEAPON When you have butchered quite a few of them
HATE_WEAPON The gang really hates the player! This is when the bar is flashing on the negative side.
arrow_colour Colour of their arrow (further down page).
X,Y,Z Direct the player to one of their phones for info or something.
respect How much the bar changes when the player kills a gang member. Usually set to 1.
MODEL The name of a vehicle they use as a gang car.
car_remap The colour of the gang car.

SET GANG KILL REACTION

This sets the relationship between two gangs & how it affects the player when a gang member dies. 

SET_GANG_KILL_REACTION (firstgang, secondgang, value)

firstgang is the gang whose member has just died, so secondgang respect towards the player is adjusted by value. See example: 

SET_GANG_KILL_REACTION (firstgang, secondgang, 10) // secondgang HATES firstgang

When player kills a firstgang char, the gangs react:

Parameters
firstgang names of gang previously declared in a SET_GANG_INFO.
secondgang names of gang previously declared in a SET_GANG_INFO.
value integer listing the 'change' to happen

GANG EXAMPLE

To help with setting up the gangs, here's an example of relationships between three gangs: 

SET_GANG_INFO (rednecks, 1, MACHINE_GUN)
SET_GANG_INFO (corp, 2, MOLOTOV)
SET_GANG_INFO (commies, 5, MACHINE_GUN)

SET_GANG_KILL_REACTION (rednecks, corp, 10)
SET_GANG_KILL_REACTION (commies, rednecks, 10)
SET_GANG_KILL_REACTION (corp, commies, 10)

This sets up:

CHECK RESPECT GREATER

Checks the player's 'respect level' for this gang - if greater than required level, returns TRUE otherwise FALSE. 

CHECK_RESPECT_GREATER (player_name, gangname, requiredlevel)
Parameters
player_name Name of the character controlled by a player. MUST be player controlled!
gangname Name of a previously declared gang, e.g. rednecks
requiredlevel integer giving the value to check the player's 'respect' against, valid range is 100 to 0 to -100.

CHECK RESPECT LOWER

Checks to see if this player's respect level for this gang is *lower* than a certain level. Returns TRUE if so, FALSE otherwise. 

CHECK_RESPECT_LOWER (player_name, gangname  requiredlevel)
Parameters
player_name Name of the character controlled by a player. MUST be player controlled!
gangname Name of a previously declared gang, e.g. rednecks
requiredlevel integer giving the value to check the player's 'respect' against, valid range is 100 to 0 to -100.

CHECK RESPECT EQUAL

Checks the player's 'respect level' for this gang - if exactly equal to a certain level, returns TRUE otherwise FALSE. 

CHECK_RESPECT_EQUAL (player_name, gangname, requiredlevel)
Parameters
player_name Name of the character controlled by a player. MUST be player controlled!
gangname Name of a previously declared gang, e.g. rednecks
requiredlevel integer giving the value to check the player's 'respect' against,
valid range is 100 to 0 to -100.

ANSWER PHONE

This command starts a phone ringing, and sets a mechanism in motion that waits for a specific player to answer it. As soon as the specific player answers the phone, it stops ringing. You can make the phone ring for a specific number of game cycles then stop too.

There is a limit on how many ANSWER_PHONEs you can have running at any one time. Currently this is 5 - you can have more than this in total, just not at the ONE TIME. I can increase this if necessary. 

ANSWER_PHONE (char name, telephone name, timer value)
Parameters
char name Name of the player's character - this command ONLY works on players.
telephone name Name of the telephone - this is a declared & created OBJ_DATA.
timer value integer value for how many cycles the phone will ring. Setting this to -1 means the phone will ring until you command it to stop.

CHECK ANSWERED PHONE

Use this to check whether the player has answered the phone or not. Returns TRUE if so, FALSE if not. 

CHECK_ANSWERED_PHONE (telephone name)
Parameters
Telephone name the name of the telephone to check.

CHECK FAIL PHONE TIMER

Use this to check whether the timer on a phone has 'run out' - if you're using a timed answer_phone, you must call this command once each 'cycle', ie stick it inside a WHILE_EXEC or something similar. When the timer has run out, it returns TRUE. If the timer is still counting down, or there is no timer, the command returns FALSE. 

CHECK_FAIL_PHONE_TIMER (telephone name)
Parameters
telephonename Name of the telephone used in the original ANSWER_PHONE.

STOP PHONE RINGING

This makes a phone stop 'ringing', ie changes its animation to that of a 'normal' phone, stopping any sound playing etc. 

STOP_PHONE_RINGING (telephone name)
Parameters
telephone name Name of a telephone object.

ANSWER PHONE EXAMPLE

This is a detailed example of a working 'answer telephone'. It may be possible to streamline or alter it slightly… 

OBJ_DATA testphone = (108.5,151.5,2.0) 0 phone
PLAYER_PED player = (108.5,150.5,255.0) 0 1
COUNTER exit = 0

LEVELSTART
     ANSWER_PHONE player, testphone, 40

     WHILE_EXEC (exit = 0)
          IF (CHECK_ANSWERED_PHONE(testphone))
               DISPLAY_BRIEF (8012) // well done!
               ++ exit
          ENDIF
          IF (CHECK_FAIL_PHONE_TIMER(testphone))
               DISPLAY_BRIEF (8013) // failed!
               ++ exit
               ++ exit
          ENDIF
     ENDWHILE

     IF (exit = 1)
          // player answered phone…
     ELSE
          // player didn't answer phone…
     ENDIF
LEVELEND

IS CHAR FIRING ONSCREEN?

Checks to see if character is firing a weapon onscreen. Works with any character, though doesn't make sense for player's own character… returns TRUE if so, FALSE if not. Punching does NOT count as firing a weapon! 

IS_CHAR_FIRING_ONSCREEN (name)
Parameters
name Name of a valid existing character

IS ITEM ONSCREEN?

Checks to see if a particular character, car or object is on the player's screen. Works with any valid item that exists. Returns TRUE if so, FALSE if not. 

IS_ITEM_ONSCREEN (name)
Parameters
name Name of a valid existing character, car or object.

MAKE CAR DRIVE AWAY

Makes an already created car drive off around the city, like a DUMMY would. This command requires the car to already have a driver! 

MAKE_CAR_DRIVE_AWAY (car_name)
Parameters
car_name Name of a previously created car.

SET MAP ZONES

These next commands allow you to change the parameters of a 'map zone' mid-game, during the execution of a script. This should give quite a bit of power, letting you increase/decrease how busy certain areas are as a game progresses.

Note that the same constraints of a mapzone declare exist - all the number of car ratios must add up to 1000 etc. 

SET_CARDENSITY (zone name, new value)
SET_GOODCAR_RATIO (zone name, new value)
SET_BADCAR_RATIO (zone name, new value)
SET_POLICECAR_RATIO (zone name, new value)
SET_PEDDENSITY (zone name, new value)
SET_MUGGER_RATIO (zone name, new value)
SET_CARTHIEF_RATIO (zone name, new value)
SET_ELVIS_RATIO (zone name, new value)
SET_GANG_RATIO (zone name, new value)
SET_POLICEPED_RATIO (zone name, new value)
Parameters
zone name Name of a 'map_zone' declared previously.
new value a value between 0 & 1000, which will be stored in the map zone info.

ORDER DRIVER OUT CAR

Orders a character to stop driving a car & exit it. The character will end up standing beside the car's door. Character must be driving a car - it will give a fatal error mid-game otherwise. If you want to do something to the character once he's outside the car, check for his objective getting passed - this show's he is finished getting out. 

ORDER_DRIVER_OUT_CAR (charname)
Parameters
charname Name of a valid existing character - see above for details

ORDER CHAR TO DRIVE CAR

Orders a character to go to a specific car & enter it to become its driver. The character's objective will be set to passed when this is complete, which you can use for checks… 

ORDER_CHAR_TO_DRIVE_CAR (charname, car_name)
Parameters
charname Name of valid existing character
car_name Name of valid existing car.

HAS CAR JUST SUNK?

Checks to see if a car has just sunk under water. Returns TRUE if so, FALSE if not 

HAS_CAR_JUST_SUNK (car_name)
Parameters
car_name Name of a previously created car

IS CAR IN AIR?

Checks to see if a car is 'flying' through the air, ie left the ground. Be aware this may be triggered by going over the top of hills… returns TRUE if so, FALSE if not. 

IS_CAR_IN_AIR (car_name)
Parameters
car_name Name of a previously created car.

SET PATROL ROUTE FOR CHARACTER

Characters can be given 'patrol routes' that they follow, looking for any threats to react to. These routes are basically a big list of points that should 'loop round'. If the character sees a threat along the route, they will break off & attack it depending on their occupation/reaction etc. This gives you a more sophisticated guard ped system - eventually, you'll be able to set up guards that the player has to sneak around avoiding their line of sight Metal Gear Solid style.

Note that calling ADD_PATROL_POINT will override any objective previously given to this character, but will leave his occupation/threats etc intact. To give a character a patrol: 

ADD_PATROL_POINT (charname, X,Y,Z)
Parameters
charname Name of a valid existing character
X,Y,Z float coordinates detailing the block the character should walk to. Note that there is a degree of redundancy here, the game only uses it as 'whole blocks'.

TIMER DATA

New concept alert! On-screen timers, ie countdowns, now have their own data declaration. You cannot display or use an onscreen timer without declaring at least one timer_data item.

You should be able to get away with declaring maybe two or three at the top of your file. There's certainly no need to have individual timers for each separate mission. 

TIMER_DATA name
Parameters
name Unique name to give to this timer. Will be used elsewhere in script…

DISPLAY TIMER

Displays an timer on the screen which counts down in game seconds to 0. It needs to be linked to a TIMER_DATA item to store some extra info in. You can fake an upward timer.

If count is larger than 59, it will display minutes correctly.

It will handle up to 99 minutes and 59 seconds, a total of 5999 seconds, displayed as 99:59. Any more than that and the graphics around the pager will be swapped. It will count down for the right length of time. The graphics go back to normal when it reaches 99:59 and lower. 

DISPLAY_TIMER (timer_name, count)
Parameters
timer_name Name of a valid TIMER_DATA item.
count Number of cycles to count down towards zero from.

Multiplayer

You must wait 350 cycles from when the game starts until you display the first timer. This avoids conflicts with the game’s own Time Limit timer: it will delete your timer from the screen if you don’t wait!

CLEAR TIMER

Clears one onscreen timer that’s been created using a TIMER_DATA & a DISPLAY_TIMER. It clears only one timer. It will remove the clock and timer! 

CLEAR_TIMER (timer name)
Parameters
timer name Name of a valid TIMER_DATA item.

ADD TIME TO TIMER

Adds time to an existing onscreen timer. Takes the time in as seconds, and the timer must be onscreen. 

ADD_TIME_TO_TIMER (timername, seconds)
Parameters
Timer name Name of an existing TIMER
Seconds integer value detailing in seconds the time to add.

GIVE DRIVER AND BRAKE

Takes an existing car & gives it a dummy driver, but orders it to stop. So it will stay in the block it's in. 

GIVE_DRIVER_AND_BRAKE (name)
Parameters
name must be a valid already existing car.

IS CHAR IN GANG ZONE?

Straightforward check to see whether the given character is currently inside a particular gang's zones. Returns TRUE if so, FALSE if not. 

IS_CHAR_IN_GANGZONE (charname, gangname)
Parameters
charname Name of a previously created character, including player
gangname Name of a gang 'declared' using a SET_GANG_INFO. Name must match the name used in the zones inside the map…

SET AMBIENT LEVEL

Allows you to set the background ambient light level in your map. It can change instantly to this new level, or do it over time. This should be one of the very first commands after your LEVELSTART. 

SET_AMBIENT_LEVEL (float level, integer time)
Parameters
level New ambient level. 0.0 is black, 1.0 is 'normal' GTA without light.
time Number of cycles to do change over. Set to 0 to do instantly.

SET CAR NO COLLIDE

Sets a car so it will not be moved and can ram any other vehicle out of the way. There’s a lot of force from instantly shoving a heavy vehicle out of your way, so your vehicle will get damaged really fast. Also, if you bounce off walls or get stuck against poles, you will take a lot of damage.

You can use the handling file (*.gci to change the Damageable setting (called Fragile in CFG Studio 2. This make the vehicle stronger, so it can survive these big hits. There is no scripting command to make a vehicle stronger after the game has started.

If two vehicles with SET_CAR_NO_COLLIDE crash into each other, they get stuck together. Both take a lot of damage, especially if they are heavy. 

SET_CAR_NO_COLLIDE (car_name)
Parameters
car_name Name of a valid existing car…

CLEAR CAR NO COLLIDE

Resets the SET_AMBIENT_LEVEL property of cars. 

CLEAR_CAR_NO_COLLIDE (car_name)
Parameters
car_name Name of a valid existing car…

IS CHAR FIRING IN AREA

Checks to see if character is firing a weapon inside a specific location & width/height. Works with any character, including the player - use this to check if player is shooting inside an area of a map near a building etc.

Returns TRUE if so, FALSE if not. Need to decide if punching counts as firing weapon - it didn’t in GTA. 

IS_CHAR_FIRING_IN_AREA (name, X,Y,Z, width,height)
Parameters
name Name of a valid exising character - including player
X,Y,Z Centre point of location to check, floats for accuracy
width,height width & height of area to check

CHECK PASSENGER COUNT

Checks to see if this car has a passenger count greater or equal to a particular value. Returns TRUE if so, FALSE if not. 

CHECK_PASSENGER_COUNT (car_name, value)
Parameters
car_name Name of a valid existing car.
value number of passengers to check for - usually 0 to around 4 etc. Never negative.

CLEAR WANTED LEVEL

Resets the "wanted level" for a given character. This does not have to be the player character - other chars have crime levels now. 

CLEAR_WANTED_LEVEL (name)
Parameters
name Name of valid, existing character

CHECK CAR WRECKED IN AREA

Checks to see if a specific car has just been destroyed inside a specific area, Returns TRUE if so, FALSE otherwise. 

CHECK_CAR_WRECKED_IN_AREA (car_name, X,Y,Z, width,height)
Parameters
car_name Name of a valid exising car
X,Y,Z centre point of location to check, floats for accuracy
width,height width & height of area to check, again floats

CHECK NUMBER ALIVE IN GROUP

Useful character group command to check whether the number of members still alive is greater than or equal to a certain value.

Possible uses would be to change the objectives/behaviour of the group if someone gets killed… Returns TRUE if greater/equal, FALSE otherwise. 

CHECK_NUMBER_ALIVE_IN_GROUP (leader name, value)
Parameters
leader name Name of current group leader character
value value to check against

REMOVE CHAR FROM GROUP

Counter command to ADD_EXISTING_CHAR_TO_GROUP - this removes a previously created character from a group of characters, letting you manipulate him individually again. 

REMOVE_CHAR_FROM_GROUP (leadername, second char)
Parameters
leadername Name of the current group leader character
Second char Name of the character to remove from group.

SET CHAR SHOOTING SKILL

Sets the 'shooting skill' level for a character. Not currently activated, but you can still set this for the moment. See bottom of document for valid skill levels. 

SET_CHAR_SHOOTING_SKILL (char name, skill)
Parameters
charname Name of a valid previously created character. NOT the player
Skill string detailing the level to use. See below

SET CHAR BRAVERY LEVEL

Sets the bravery level for this character - this is implemented. Governs not a lot at the moment, threat reactions are more important. See bottom of document for valid bravery levels 

SET_CHAR_BRAVERY_LEVEL (char name, level)
Parameters
charname Name of a valid previously created character. NOT the player.
level string detailing the bravery level to use. See below.

ADD GROUP TO CHARACTER

(No description in official documentation.)

Instantly spawns several other characters near the "leader" character: 

ADD_GROUP_TO_CHARACTER (leader_name, group_size)

You should only use the leader of the group to manipulate things. 

CHAR_DATA  enemyleader = (123.5,34.5) 0 1 criminal
ADD_GROUP_TO_CHARACTER (enemyleader, 3)
Parameters
leader_name Name of the valid created character, currently with a group of chars
group_size number of characters to add to group

ADD EXISTING CHAR TO GROUP

After you've added a group to one character, you can use this command to add a second character to this group, one that you'd previously created. Best seen in an example. 

ADD_EXISTING_CHAR_TO_GROUP (leader name, second char)

Until the character gets removed from the group, you should only use the leader of the group to manipulate things. 

CHAR_DATA  enemyleader = (123.5,34.5) 0 1 criminal
CHAR_DATA bodyguard = (124.5,35.5) 0 1  criminal

ADD_GROUP_TO_CHARACTER (enemyleader, 3)
ADD_EXISTING_CHAR_TO_GROUP (enemyleader, bodyguard)

WHILE_EXEC (CHECK_NUMBER_ALIVE_IN_GROUP (enemyleader, 2))
     // do something
ENDWHILE

REMOVE_CHAR_FROM_GROUP (enemyleader, bodyguard)
SET_CHAR_OBJECTIVE (bodyguard, KILL_CHAR_ON_FOOT, player)
Parameters
leadername Name of the valid created character, currently with a group of chars
secondchar Name of the character to add to group…

IS CHARACTER IN MODEL?

Command to check whether a given character is currently driving a car with a particular model. Returns TRUE if so, FALSE if not. 

IS_CHARACTER_IN_MODEL (charname, MODEL)
Parameters
charname Name of a previously created character, including the player
MODEL car model type, listed at the bottom of the document.

IS CHARACTER IN ANY CAR?

Command to check whether a given character is currently driving anycar in the world. Returns TRUE if so, FALSE if not. 

IS_CHARACTER_IN_ANY_CAR (charname)
Parameters
charname Name of a previously created character, including the player.

DECLARE MISSION FLAG

This command is used to tell the game code which particular counter is used in the script to signify whether the player is currently on a mission or not. At the moment, it's mainly for the gang arrows to work properly, but more things may end up using it. This is a declaration command, to be used at the top of your script outside any labelled function - but make sure to put it after the actual COUNTER & PLAYER_PED declarations! 

DECLARE_MISSION_FLAG (player_name, counter_name)
PLAYER_PED player = (214.5,64.5,255.0) 1 1
COUNTER flag_on_mission = 0
DECLARE_MISSION_FLAG   player, flag_on_mission
Parameters
player_name Name of a previously declared player's character
counter_name Name of the counter used to 'flag' being on a mission.

IS TRAILER ATTACHED

Checks to see whether this particular car has a particular trailer attached to it. Returns TRUE if so, FALSE if not. Set trailer name to the same as car name, and the game will check for ANY trailer being attached, not just a particular one. 

IS_TRAILER_ATTACHED (car name, trailer name)
Parameters
car name Name of a previously created car
trailer name Name of a previously created car which is one of the trailer types…

IS CAR ON TRAILER

Checks to see whether a particular car is sitting on top of a particular car transporter. Returns TRUE if so, FALSE if not. 

IS_CAR_ON_TRAILER (car name, transport  name)
Parameters
car name Name of a previously created car
transport name Name of a previously creater car transporter.

ENABLE CRANE

This switches a crane 'on', letting it proceed with lifting cars etc. This is the default state for all cranes. You only need to worry about crane states if you want to switch them off for some reason… 

ENABLE_CRANE (crane name)
Parameters
crane name Name of a previously created crane

DISABLE CRANE

This switches off a crane, stopping it from lifting any cars etc. This will instantly stop the crane from working - if it is in the middle of lifting a car, it will stop mid-air. Use 'ENABLE_CRANE' to get it moving again. 

DISABLE_CRANE (crane name)
Parameters
crane name Name of a previously created crane

HAS CAR GOT WEAPON?

Checks whether a particular car currently has a weapon - use this to see if a car has a bomb on it!! returns TRUE if so, FALSE if not. 

HAS_CAR_GOT_WEAPON (car name, weapon type)
Parameters
car name Name of a previously declared car
weapon type one of the weapon types from the list at the bottom of doc.

IS CHAR IN ZONE?

Checks whether a character is in a particular named local navigation zone. If you want an irregular area of zones checked, make them all have the same name. Returns TRUE if so, FALSE if not.

Note that you must use NAVIGATION or LOCAL NAVIGATION zones for this to work! 

IS_CHAR_IN_ZONE (char name, zone name)
Parameters
char name Name of a previously created character, including the player
zone name Name of a local navigation zone.

IS CHAR PRESSING HORN?

Checks whether a given character is currently pressing the horn of the car he's driving. Returns TRUE if so, FALSE if not. 

IS_CHAR_PRESSING_HORN (char name)
Parameters
char name Name of a previously created character, including the player.

IS CHAR CAR CAPACITY?

This is a fiddly sounding command that's actually simple. It checks to see what the possible number of passengers that can fit in the car currently being driven by a particular character. If it's greater or equal to the value you decide, it returns TRUE, if not, returns FALSE.

This command is likely to be useful when the player has a group of guys with him & you want him to go steal a truck or something suitable for them all to fit in as passengers… 

IS_CHAR_CAR_CAPACITY (char name, passenger value)
Parameters
char name Name of a previously created character, including the player
passenger value integer describing the max passengers you want.

SET PHONE DEAD

This allows you to tell the game that a particular phone is 'dead', ie that it should no longer ring or give out missions etc. Use when the player has used up all the missions from a particular phone. 

SET_PHONE_DEAD (obj name)
Parameters
obj name Name of the phone object.

HAS CHAR SPOTTED PLAYER?

Check to see if this particular character has just spotted the player. Careful use of this command will let you do nice stealthy Metal Gear/Goldeneye missions… Note that this will work only on the player, not another character - it also shouldn't be used in multiplayer… 

HAS_CHAR_SPOTTED_PLAYER (charname)
Parameters
charname Name of the character to check…

STORE LAST CHAR PUNCHED

Variant on the old GTA 'store char' command. This looks at one character, sees which character he last punched & stores this dummy char in a 'CHAR_DATA' slot, letting you treat him as a normal mission character. At the moment, the character is still a dummy character, we can change this if necessary to make him a 'proper' mission char.

Additional note: you must make sure the character has just punched someone before calling this command, you'll cause game crashes otherwise! Use "HAS_CHAR_PUNCHED_SOMEONE" for this. 

STORE_LAST_CHAR_PUNCHED (char name, store name)
Parameters
char name Name of the character who did the punching
store name Name of the "CHAR_DATA" slot to store the new character in.

HAS CHAR PUNCHED SOMEONE?

Companion command to 'STORE_LAST..'. This returns TRUE if the character has just punched someone, FALSE if not. 

HAS_CHAR_PUNCHED_SOMEONE (charname)
Parameters
charname Name of the character to check.

KILL ALL PASSENGERS

Straightforward command to delete/kill every character who are currently passengers inside a car. The driver is left unharmed. One thing to be aware of is that your CHAR_DATA slots will not be wiped - these are invalid after you call this command… 

KILL_ALL_PASSENGERS (car name)
Parameters
car name Name of the previously created car

IS GROUP IN CAR?

Simple command to check whether all members of a group have finished entering a car. Returns TRUE if so, FALSE if not. 

IS_GROUP_IN_CAR (leader name)
Parameters
leader name Name of a previously created character who is leader of the group.

IS CHAR STUNNED?

Checks to see whether a character is stunned unconscious, ie lying on the ground stunned. Returns TRUE if so, FALSE if not. This will work on the player… 

IS_CHAR_STUNNED (char name)
Parameters
char name Name of a previously created character

ORDER CHAR TO BACKDOOR

Orders a character to go to car & enter it as a passenger. If character is leader of a group, they will attempt to enter car as well. 

ORDER_CHAR_TO_BACKDOOR (charname, car_name)
Parameters
charname Name of valid existing character
car_name Name of valid existing car.

SET MIN MEMBERS BEFORE GROUP SPLITS

This group management function allows you to tweak the minimum number of members left in the group before the group 'splits' back into individual characters. Default value is 0 for the moment. 

SET_MIN_MEMBERS_BEFORE_GROUP_SPLITS (leader name, value)
Parameters
leader name Name of the leader character
value integer value for the new minimum.

ADD CHAR TO GANG

Sets a character's gang allegiance, ie makes him a gang character… 

ADD_CHAR_TO_GANG  char name, gang name
Parameters
char name Name of a valid previously created character
gang name Name of a gang in this map.

DO NOWT

Simple, quick & straightforward command - it does nothing! Just proceeds onto the next line of your script. May be useful inside WHILE_EXEC blocks etc… 

DO_NOWT

Parameters

No parameters. Empty brackets are not required for this, either.

MAKE NEW LEADER OF GROUP

This command takes a previously created group & makes this particular character its new leader, replacing the old leader. The old leader is still part of the group, he just acts as an ordinary character in the group. 

MAKE_NEW_LEADER_OF_GROUP (old leader, new leader)
Parameters
old leader Name of the character who used to lead the group
new leader Name of the character who is to be the new leader (inc player).

IS CHAR OBJECTIVE PASSED?

This command allows you to check the state of a character/group's current objective. If the character has completed it, it will return TRUE. If not, it will return FALSE. This is highly useful for checking for character leaving/entering cars. 

IS_CHAR_OBJECTIVE_PASSED (charname)
Parameters
charname Name of a previously created character

IS CHAR OBJECTIVE FAILED?

This command is the complement of 'IS_CHAR_OBJECTIVE_FAILED?' - it returns TRUE if the character has failed to complete the objective, FALSE otherwise.

Why might an objective fail? Good example: if the character has to enter a car & the car gets destroyed, the objective will fail. 

IS_CHAR_OBJECTIVE_FAILED (charname)
Parameters
charname Name of a previously created character.

ALTER WANTED LEVEL

Alters the player's wanted level to a given level of heads. Effectively, you're now setting the number of heads the player should have. Valid values are between 1 & 6. Don't use this command to clear the wanted level! 

ALTER_WANTED_LEVEL (name, num heads)
Parameters
name Name of valid, existing character
num heads the new value of heads for the character

PARK

This command 'parks' a particular car inside a particular door. It may look simple, but there's a lot of pitfalls to be wary of. The door can be a single or double door, but the building should have a lot of room. It needs at LEAST one block free inside the building to each side of the door, and three blocks free in the direction of the door (on the inside of the building) for long vehicles to behave properly.

Parking works by waiting for the front two corners of the car being 'over' the edge of the door, at which point the code "pulls in" the car, until all corners are in & hidden from view. When this is finished, the car is flagged to destroy itself, all passengers are killed & the player is placed outside the closing door. During this process, the car cannot be collided with, the player's controls are disabled, and the car is 'pulled in' at a constant rate. When the parking is finished, all of this is reset to let play continue as normal. NOTE - only one park can run at any time!!!

Eventually, the character will 'run out' of the door rather than just being warped there as present. Nothing is done to the camera yet either - it doesn't get 'fixed' outside the garage like in GTA.

Parking has changed a bit. If you want to park long vehicles length >= 1 block!), you must ensure you have enough space around the door. If you don't, the game will ASSERT & generate an error when you do your PARK command.

What's enough space? For a double door facing north, you must have two blocks either side, and three blocks depth. In other words - six blocks by three blocks. You MUST have this amount of space inside the garage to handle acute angles of parking etc. 

PARK (car  name, door name)
Parameters
car name Name of a previously created car, or a car you've stored the info of.
door name Name of a door you previously declared.

HAS PARK FINISHED?

Simple check to see whether the current 'parking' has finished or not. Returns TRUE if so, returns FALSE if not. 

HAS_PARK_FINISHED ()

Parameters

No parameters. Empty brackets are required.

CRUSHER

Declares & creates a 'crusher' item in game. This item is usually linked up to a crane, and it will 'crush' any car within its centre square, which is the point you define. Be aware the crusher takes up one block in each direction from the centre spot.

Like the crane, the game automatically handles the z position for the crusher. 

CRUSHER name = (centreX,centreY)
Parameters
name unique name string for this crusher
centre X,Y Centre position of the crane. At the moment, it just uses the ‘block’ aspect of the coordinate…

CHANGE GANG CHAR RESPECT

This command lets you change the respect level that a character has with a particular gang - ie the levels that are displayed on screen. Bear in mind that valid respect levels are in the range of -5..0..5. To reduce the respect, use a negative number. Also, this command only makes sense on a player's character. 

CHANGE_GANG_CHAR_RESPECT (gang name, char name, difference)
Parameters
gangname Name of the gang…
char name Name of the player's character…
diference integer value to add to the respect. Can be negative!

SET_ARROW_COLOUR

Allows you to set the colour of non-gang arrows, ie the normal everyday mission arrow. Possibly more useful for multiplayer scripts. More colours are likely to be added. 

SET_ARROW_COLOUR (name, COLOUR)
Parameters
name Name of a previously declared & created ARROW_DATA
COLOUR String describing the colour you want the arrow to be!

REMOVE WEAPONS

Removes all weapons that this character has. Works on player too! 

REMOVE_WEAPONS (charname)
Parameters
charname Name of a previously created character.

REMOVE BLOCK

Physically removes a block from the map. You can decide whether you want any blocks above to logically 'fall' down one zblock, or to stay mid-air. Note that any faces now showing because of this drop will be empty… You may have to change their values to valid tiles. 

REMOVE_BLOCK (X,Y,Z, DO_DROP)
REMOVE_BLOCK (X,Y,Z, DONT_DROP)
Parameters
X,Y,Z integer coordinate describing the exact block to remove
DO_DROP this forces the game to make any blocks above fall down by one level.
DONT_DROP this makes the game keep the blocks above at their current level.

ADD NEW BLOCK

Physically 'adds' a block to the map at a specific (X,Y,Z). This new block will be completely clear & set to air - you will need to call CHANGE_BLOCK TYPE after this command to actually set its type, faces etc. 

ADD_NEW_BLOCK (X,Y,Z)
Parameters
X,Y,Z Integer coordinate describing the particular position to add this new block.

CHANGE_BLOCK TYPE

This allows you to alter the type & slope information for a block mid-game, i.e. you can make a block that was previously field into air, or change a block into a steep slope or one of the new fancy blocktypes. For a complete list of slopetypes, see bottom of document. 

CHANGE_BLOCK TYPE (X,Y,Z) SURFACE_TYPE slope
Parameters
SURFACE_TYPE String describing new blocktype: AIR, FIELD, ROAD or PAVEMENT
slope number describing the new particular slope type. 0 for no slope!

CHANGE_BLOCK LID

This lets you to alter the details for the lid of any block in the world mid-game. You can change the graphic & the properties of the lid. 

CHANGE_BLOCK LID (X,Y,Z)
                 FLAT_TYPE FLIP_TYPE FILTER
                 rotation tile
Parameters
X,Y,Z 0–255 Integer coordinate describing the particular block position to alter
FLAT_TYPE FLAT Enables transparency and fence effects
NOT_FLAT
FLIP_TYPE FLIP Uses a mirror image of the texture
NOT_FLIP
filter 0 Normal brightness
1Dark
2Darker
3Dark+Darker (darkest)
rotation 0 Rotation value for this new graphic:
90
180
270
tile 0–999 The new tile graphic id for this side!

CHANGE_BLOCK SIDE

This is the most complicated looking CHANGE_BLOCK command. It allows you to change all the abilities for one particular side of a block, from its graphic to its wall flag.

If you want to remove walls or add walls to block off particular sections of the map mid-game, this is the command to use. You can also create custom doors with this technique. 

CHANGE_BLOCK SIDE (X,Y,Z) FACE_TYPE
                  WALL_TYPE BULLET_TYPE FLAT_TYPE FLIP_TYPE
                  rotation tile
Parameters & Values
Value Effect
X,Y,Z 0–255 Integer coordinate describing the particular block position to alter
FACE_TYPE TOP Particular face to alter
BOTTOM
LEFT
RIGHT
WALL_TYPE WALL Make side act as wall
NOT_WALL
BULLET_TYPE BULLET Allows bullets and other weapons passing through
NOT_BULLET
FLAT_TYPE FLAT Enables transparency and fence effects
NOT_FLAT
FLIP_TYPE FLIP Uses a mirror image of the texture
NOT_FLIP
rotation 0 Rotation value for this new graphic:
90
180
270
tile 0–999 The new tile graphic id for this side!

SWITCH_GENERATOR

These commands allow you to manipulate a generator mid-game, switching its state or method of execution. You can switch it off completely, switch it on, or order it to create a certain number of items - after which it switches itself off. 

SWITCH_GENERATOR (name, ON)
SWITCH_GENERATOR (name, OFF)
SWITCH_GENERATOR (name, ammo)
Parameters
name Name of a previously declared GENERATOR item.
ON Begin creating items.
OFF Stop creating items and hide the visible item.
ammo integer value describing the number of items to create. The generator will create the type of item given in its declaration.

CHECK_CAR_DAMAGE_POSITION

This is a sneaky little command letting you do some clever things: it checks to see whether a particular car has 'damage' in a particular position.

This effectively checks whether the car has a graphic damage delta on one of its four corners or on its window. It returns TRUE if so, FALSE if not. 

CHECK_CAR_DAMAGE_POSITION (car_name, POSITION)
Parameters & Values
Value Effect
car_name Unique string Name of a previously created car
POSITION FRONT_LEFT A corner of the car or the windscreen.
FRONT_RIGHT
BACK_LEFT
BACK_RIGHT
WINDOW

SWITCH_ROAD OFF

This allows you to effectively 'turn off' a road mid-game, preventing the car routefinder from utilising it for routes. Note the coordinates must be a particular point on the road that is not inside the actual junctions. 

SWITCH_ROAD OFF (X,Y,Z)
Parameters
X,Y,Z Integer coordinate describing the road to turn off.

SWITCH_ROAD ON

The opposite of SWITCH_ROAD OFF, it turns a road back on again to allow the car routefinder to use it for any routes. As before, the coordinates must be a point on the road outside of any junctions. 

SWITCH_ROAD ON (X,Y,Z)
Parameters
X,Y,Z Integer coordinate describing the road to turn on.

CHECK_CHAR_BEEN_PUNCHED_BY

Checks to see whether a particular character was last punched by another particular character. Returns TRUE if so, FALSE if not. 

CHECK_CHAR_BEEN_PUNCHED_BY (victim, attacker)
Parameters
victim Name of the character to check if he's been punched
attacker Name of the character doing the punching!

GET_CAR_INFO_FROM_CRANE

This command essentially does two things - it returns TRUE if crane/whatever has successfully finished processing its current car, FALSE if not. If TRUE, it also sets car_name to point to the car it was processing. 

GET_CAR_INFO_FROM_CRANE (car_name, crane_name)
Parameters
car_name Name of a CAR_DATA slot
crane_name Name of a previously created CRANE.

DO PHONE TEMPLATE

This effectively takes over control of what happens when the player answers a particular phone. It checks mission states & respect, generating a BRIEF & action. It looks complicated. It is complicated. 

DO_PHONE_TEMPLATE (integer base brief,
                   MIS file 1,
                   MIS file 2,
                   counter passed mission 1,
                   counter failed mission 1,
                   counter played mission 2,
                   counter on mission for gang 1,
                   counter on mission for gang 2,
                   counter on mission for gang 3,
                   gang name this phone is for,
                   respect needed)

Example: 

DO_PHONE_TEMPLATE (1098, bil_ke1.mis,
                  WILL_KE2.MIS, flag_passed_yakuzagang_easy_phone1_m1,
                  flag_failed_yakuzagang_easy_phone1_m1, flag_played_yakuzagang_easy_phone1_m2,
                  flag_on_yakuzagang_mission, flag_on_looniegang_mission, flag_on_zaibgang_mission,
                  yakuzagang, 5)
Parameters
integer base brief, integer message ID for default briefing
MIS file 1 string name of file containing mission 1 from this phone
MIS file 2 string name of file containing mission 2 from this phone
counter passed mission 1 Name of counter stating if player has passed mission 1
counter failed mission 1 Name of counter stating if player has failed mission 1
counter played mission 2 Name of counter stating if player has played mission 2
counter on mission for gang 1 Name of counter showing player on mission for gang 1
counter on mission for gang 2 Name of counter showing player on mission for gang 2
counter on mission for gang 3 Name of counter showing player on mission for gang 3
gang name this phone is for Name of gang this phone is connected to
respect needed minimum integer value of the respect needed to start mission 0 - 5

TAKE REMOTE CONTROL OF CAR

Allows you to force a player to take control of another vehicle. The camera switches to viewing this car, and the player's character is immobilised. Note this character is still able to be killed/arrested. Control returns to the original character when the 'remote' vehicle is destroyed.

The vehicle doesn't have to be a MINI_CAR, it can be a normal sized car. 

TAKE_REMOTE_CONTROL_OF_CAR (char name, car name)
Parameters
char name Name of a previously created PLAYER_PED character.
car name Name of a previously created car. Can be a mini-car or normal sized.

SAVE GAME

Using this command 'forces' the game to save itself. Note this must be done "outside" of a mission, and it will only save certain information. The best way of ensuring the player is outside a mission is simply to check_Your 'on mission' flag… I would create a 'thread trigger' on the character entering a specific location, and when that happens - check the player's mission status, display a suitable 'SAVED GAME' brief, save game & then 'return', finishing the thread. 

SAVE_GAME

Parameters

No parameters! No brackets are required.

SAVED COUNTER DECLARE

Declares a 'counter' variable & sets it to the default value for counters, 0. A SAVED_COUNTER differs from a regular counter in that it gets 'stored' & restored in a savegame. Its value at the time of saving will be restored when a savegame is loaded. 

SAVED_COUNTER name
Parameters
name any valid string - must be unique.

CHANGE CAR LOCK

Allows you to alter the 'lock' on the doors on a particular car. The default lock for all mission cars is 'LOCKOUT_THIEF_ONLY'. Note that if you make a door 'LOCKED_PERMANENT', it will always be this state!! 

CHANGE_CAR_LOCK (car name, lock type)
Parameters
car name Name of a valid car
locktype string listing a valid lock type.

DECLARE LIGHT

This 'reserves' space for a single light, letting you create a light mid-game. 

LIGHT (name)
Parameters
name A valid, unique name for this light.

LIGHT

This declares & creates a stationary 'light' in the script, at a particular coordinate with particular characteristics. Set the delays & randomvalue to 0 for a constant light that doesn't flicker. 

LIGHT name = (X,Y,Z) radius intensity (red,green,blue)
          on_delay off_delay random_value
Parameters
name A valid unique name to refer to this light.
X,Y,Z float Coordinate detailing the exact position to place this light at.
radius Float exact radius of light to give out. Valid values are (0.0 to 7.999
intensity Integer integer value describing strength of light. Valid values are 0 to 255
red,green,blue These three are the colour components that make up the colour this light should have. Valid ranges for these values are (0–255) with 255 being the 'strongest'. 255,255,255 will give 'white light'.
on_delay integer value of how many game cycles (0–255) the light should stay on for.
off_delay integer value of how many game cycles (0–255) the light should then stay off for.
random_value integer value - if greater than 0, becomes the maximum random value to add to each on/off cycle.

Multiplayer

on_delay + random_value and off_delay + random_value should both be less than 255.

Very short delays seemed to cause desync on Dafe’s Death Valley and Tiny Hidden Surprise Arena. See further discussion about lights causing desync.

CREATE LIGHT

This command lets you create a light 'mid-game'. See LIGHT for full details. 

name = CREATE_LIGHT (X,Y,Z) radius intensity (red,green,blue)
                     on_delay off_delay random_value

Parameters

See LIGHT for full details.

Multiplayer

See LIGHT for full details.

CHANGE INTENSITY

Alters the intensity setting for a previously created light. 

CHANGE_INTENSITY (name, intensity)
Parameters
name Name of a previously declared & created light
intensity floating point value giving the new intensity value.

CHANGE COLOUR

Alters the colour setting for an existing light. 

CHANGE_COLOUR (name, red,green,blue)
Parameters
name Name of a previously created light
red,green,blue These three are the colour components that make up the colour this light should have. Valid ranges for these values are (0–255) with 255 being the 'strongest'. 255,255,255 will give 'white light'.

CHANGE RADIUS

Alters the radius for an existing light. 

CHANGE_RADIUS (name, radius)
Parameters
name Name of a previously created light
radius float value describing the new radius 0.0 to 7.9999

SAVED_COUNTER

As above, but sets the newly declared counter to a different value. If a savegame is getting loaded, whatever value in the samegame takes precedence & gets set, not this default value. 

SAVED_COUNTER name = value
Parameters
name unique string
value integer value for the 'default' for this SAVED_COUNTER.

PARK NO RESPAWN

Alternative version of PARK - this command doesn't respawn a character standing outside of the garage when the park has finished. This will be very useful for missions - you can make a mission character drive to a garage, drive in, and then 'end' the mission…

IMPORTANT: Do NOT use this command on the player!!!!!! 

PARK_NO_RESPAWN (car_name, door_name)
Parameters
car_name Name of a previously created car, or a car you've stored the info of.
door_name Name of a door you previously declared.

LOWER LEVEL

Physically 'drops' an area of the map by one level - it removes the very bottom z-level across the area specified. All columns are automatically shuffled down, ie it does a DO_DROP always.

To drop by more than one level, call this command multiple times. 

LOWER_LEVEL (minX,minY) (maxX,maxY)
Parameters
minX,minY integer coordinates describing the top left corner of the area.
maxX,maxY integer coordinates describing the bottom right corner of the area to drop.

IS POINT ONSCREEN?

Checks to see if a particular (X,Y,Z) is on any players' screen - will return TRUE if so, FALSE if not. If there are any 'remote control' cameras or anything similar, these are checked too.

This command is really only suitable for single player missions. 

IS_POINT_ONSCREEN (X,Y,Z)
Parameters
X,Y,Z float coordinates describing the exact point to check onscreen.

SET DIRECTION OF TV VAN DISHES

Simply sets the location that all TV van dishes point towards… This can be changed as often as you like mid-game. 

SET_DIR_OF_TV_VANS (X,Y)
Parameters
X,Y float coordinates describing the exact point the dishes should point to.

IS CHAR FALLING?

Checks to see if this character is 'falling' through the air, ie doing the 'falling' animation. Returns TRUE if so, FALSE if not. 

IS_CHAR_FALLING (name)
Parameters
name Name of a previously created character, including the player.

HAS CHAR JUST SUNK?

Checks to see if this character is sinking in water. Returns TRUE if so, FALSE if not. 

HAS_CHAR_JUST_SUNK (name)
Parameters
name Name of a previously created character, including the player.

RADIO_STATION

This command 'declares' & creates a new 'radio station' in the game world. Radio stations are positioned on a particular (X,Y) with a preset "range" of broadcast - you can't change these ranges unfortunately.

There is a maximum of four radio stations in the world - one should be 'global', with the other three related to your specific gangs. See the Radio Stations tutorial for a full list of TYPE values.

Radio stations can be deleted using the normal DELETE_ITEM command…

These declares should be in your 'general' script file, along with your other car/ped/counter declares. 

RADIO_STATION name = TYPE (X,Y)
Parameters
name unique name string for this radio station.
TYPE the radio station it broadcasts - see the Radio Stations tutorial.
X,Y float coordinate detailing the position on the map of the radio station.

STORE CAR CURRENT SPEED

Stores the current speed of this car in a counter. The values for this 'speed' is 0 (for stationary), 16384 for 1.0 speed… Normal car speeds are around 0 to 8192. You can then use the value in the counter as you would a normal counter - just check it against bigger values than normal! 

STORE_CAR_CURRENT_SPEED (car_name, counter)
Parameters
car_name Name of a previously declared car.
counter Name of a previously declared counter to store the speed in

STORE CHAR CAR CURRENT SPEED

Variant of the previous command - stores the speed of the car currently being driven by the specified character in this counter… Includes the player… 

STORE_CHAR_CAR_CURRENT_SPEED (charname, counter)
Parameters
charname Name of a previously declared character, inc. player
counter Name of a previously declared counter to store the speed in.

CHECK CAR SPEED

Checks to see if the speed of this car is above a certain level. Ranges for the speed are 0 for stationary to anything upto 16384 (for 1.0!). If car speed is GREATER than value, returns TRUE, otherwise FALSE. 

CHECK_CAR_SPEED (car name, value)
Parameters
car name Name of a previously created car
value value to check speed against. (0 - 16384)

STORE MAX CAR SPEED

Stores the maximum speed for the car specified in a counter. 

STORE_MAX_CAR_SPEED (car name, counter_name)
Parameters
car name Name of a previously declared car
counter_name Name of a previously declared counter to store maxspeed in.

DECLARE_POLICELEVEL

Sets the maximum police heads it's possible to achieve on this level. Valid values for this are 4, 5 or 6 heads. This should be 'outside' your missions, so put it beside your initial SET_GANG_INFO & other declarations. 

DECLARE_POLICELEVEL (heads)
Parameters
heads integer value giving the maximum amount of heads possible on this level.

SET_CAR_NUMBER_GRAPHIC

Sets the 'number' graphic on top of the GT24640 model of car. Valid numbers are 0 to 9. Call this command after you have done a CREATE_CAR. Only valid to call this command on this particular model!! 

SET_CAR_NUMBER_GRAPHIC (car name, number)
Parameters
car name Name of a previously declared & created car
Number integer value describing the new 'number' for on top of the car.

SETUP_MODELCHECK_DESTROY

This allows you to check to see if any vehicles of a particular model have been destroyed… You can have only one of these checks running at any time - call this command just before you want to do the check, and then call HAS_MODELCHECK_HAPPENED each cycle you want to check. 

SETUP_MODELCHECK_DESTROY (MODEL)
Parameters
MODEL Name of a particular model of car to check.

HAS_MODELCHECK_HAPPENED

This command is the partner to the 'setup' command - this looks to see if any of the model have been destroyed or sunk. It will return TRUE if so, FALSE if not. You must call this once a cycle, otherwise you will miss cars being destroyed! 

HAS_MODELCHECK_HAPPENED ()

Parameters

No parameters. Empty brackets are required.

MODELCHECK EXAMPLE

COUNTER num_destroyed = 0
COUNTER timer = 2000

SETUP_MODELCHECK_DESTROY (COPCAR)

WHILE_EXEC ( (timer > 0) AND (num_destroyed < 5) )
     IF (HAS_MODELCHECK_HAPPENED)
          ++ num_destroyed
     ENDIF
-- timer
ENDWHILE

IF (num_destroyed >= 5)
     DISPLAY_BRIEF (1001) // well done you passed the test!!!!
ELSE
     DISPLAY_BRIEF (1002) // you failed to kill all the cops!!!!
ENDIF

LAUNCH MISSION

This is a powerful new command that launches a mission mid-game from a different file to the current one. The new file must have a block of commands starting with a MISSIONSTART command & ending in a MISSIONEND command, similar to LEVELSTART … LEVELEND.

When the command is run, the game will load in the file & 'jump' to the MISSIONSTART line. Think of it making the script do a GOSUB to a label, it just so happens the jump is into a different file, with the label being the filename rather than the actual label… That make sense? 

LAUNCH_MISSION (filename)
Parameters
filename Name of the file…. Should end in .mis!

SET STATION INFO

This command "sets up" a railway station at the start of the game. Basically, using this you can decide which stations should have trains, which shouldn't, which are passenger trains, freight trains etc. Basically, you have control over the number of carriages of each type - the maximum number of total carriages is 4, and passenger carriages are always created right behind the engine.

A train of 2 passenger carriages + 2 freight carriages looks like: 

ENGINE-PASSENGER-PASSENGER-FREIGHT-FREIGHT

In addition, you can order a station to not have a train linked to it at the start of the game. Other trains will travel through the station & stop at it as normal though. 

SET_STATION_INFO (platform name, num passenger, num freight, num boxcar)
SET_STATION_INFO (platform name, NO_TRAIN)
Parameters
platform name Name of the platform linked to this station - this is how the game knows which station to work on.
num passenger integer value listing the number of passenger carriages for this train.
num freight integer value listing the number of freight carriages for this train.
num boxcar integer value listing the number of 'boxcar' carriages for this train.

SET CAR BULLETPROOF

Allows you to set & clear the 'bulletproof' status of a particular car. Bulletproof means the car will not take damage from bullets - it will however still be damaged from rockets & nearby explosions. 

SET_CAR_BULLETPROOF (car_name, ON)
SET_CAR_BULLETPROOF (car_name, OFF)
Parameters
car_name Name of a previously created car
ON/OFF string detailing whether to switch bulletproof on or off

SET CAR FLAMEPROOF

Allows you to set & clear the 'flameproof' status of a particular car. Flameproof means the car will not take damage from flames (e.g. flamethrower) - it will however still be damaged from rockets & nearby explosions, and bullets. 

SET_CAR_FLAMEPROOF (car_name, ON)
SET_CAR_FLAMEPROOF (car_name, OFF)
Parameters
car_name Name of a previously created car
ON/OFF string detailing whether to switch flameproof on or off

SET CAR ROCKETPROOF

Allows you to set & clear the 'rocketproof' status of a particular car. This means the car will not take damage from direct hits by rockets, molotovs or 'small explosions', e.g. grenades, nearby cars been wrecked etc. It will explode if a 'car bomb' blows up very close by. 

SET_CAR_ROCKETPROOF (car_name, ON)
SET_CAR_ROCKETPROOF (car_name, OFF)
Parameters
car_name Name of a previously created car
ON/OFF string detailing whether to switch rocketproof on or off

SET CHAR DRIVE AGGRESSION

This allows you to set whether this particular character should drive aggressively or not - if he does, he will ignore traffic lights etc, speed limits etc. This can be switched on & off at will. 

SET_CHAR_DRIVE_AGGRESSION (char_name, ON)
SET_CHAR_DRIVE_AGGRESSION (char_name, OFF)
Parameters
Char_name Name of a previously created character.
ON/OFF string detailing whether to switch agression on or off.

IS CARBOMB ACTIVE?

Checks to see whether there is a carbomb active in this particular car - active means the timer is currently 'counting down' towards detonation. Returns TRUE if so, FALSE if not. 

IS_CARBOMB_ACTIVE (car_name)
Parameters
car_name Name of a previously created car

SET CHAR MAX DRIVESPEED

Sets the 'max speed' that this character is allowed to drive at. Use this to tweak your chases/hunts etc. Sensible values are between 0.0 & 0.4 - the fastest car in the game travels around this speed. Note the character cannot drive faster than the top speed of the car he is in… 

SET_CHAR_MAX_DRIVESPEED (char_name, speed)
Parameters
Char_name Name of a previously created character
Speed Floating point value detailing the new 'max speed'.

GIVE CAR ALARM

Simply gives this particular car an alarm - it will ring if the car is stolen or if damaged by bullets etc. 

GIVE_CAR_ALARM (car_name)
Parameters
car_name Name of a previously created car.

PUT CAR ON TRAILER

This takes in two vehicles, one a "truktrns" - a trailer suitable for carrying cars, and another already created car. It places the car on top of the trailer & attaches it - effectively making the car on top of the trailer. This should never happen when the player is next to it, it will look STRANGE. 

PUT_CAR_ON_TRAILER (car name, trailer name)
Parameters
car name Name of the car to put on top of the trailer
Trailer name Name of a trailer - usually of "truktrns" model

CHECK HEADS GREATER

Useful command that allows you to quickly check what level of 'wanted heads' the player currently has. It returns TRUE if heads are GREATER than the value, FALSE if equal or less. 

CHECK_HEADS_GREATER (player_name, integer heads)
Parameters
player_name Name of the player's character to check
integer heads integer value of the heads to check - valid range is 0 to 5 effectively)

FINISH LEVEL

This command ends the current game & tells the 'frontend' that the player has successfully completed this level. The game will end rightaway! The new parameter is the bonus to award the player…

BONUS_1
Bonus level 1.
BONUS_2
Bonus level 2.
BONUS_3
Bonus level 3.
NO_BONUS
No extra level is to be awarded. 
FINISH_LEVEL (bonus_type)
Parameters
Bonus_type type of bonus from list above - BONUS_1 BONUS_2 BONUS_3 NO_BONUS

IS CAR CRUSHED?

Checks to see if this particular car has been crushed. Returns TRUE if so, FALSE if not. 

IS_CAR_CRUSHED (car name)
Parameters
car name Name of a previously created car

CHECK WEAPON TYPE HIT CHAR

Checks to see if a particular character has just been hit by a "bullet type" - these are roughly the same as weapon types, but not quite as precise. All machine guns & pistols fire the same type of bullets for instance. You'll have to keep this in mind… returns TRUE if the char has been hit, FALSE if not.

Another thing to remember with this is that you must call it before the weapon hits - it needs to set up some stuff internally to watch for the hit - so don't expect it to work on a char being hit /before/ you check it… Put it in a loop,getting called each cycle..

See bottom of document for a list of 'DAMAGE_TYPES'. 

CHECK_WEAPON_TYPE_HIT_CHAR (char name, damage type)
Parameters
char name Name of a previously created character, including the player
damage type string detailing the 'type' of damage to look out for.

IS CHAR ON FIRE?

Straightforward check to see if a particular character is on fire - ie has a little fire attached to him! returns TRUE if so, FALSE if not. 

IS_CHAR_ON_FIRE (char name)
Parameters
char name Name of a previously declared character

DO EASY PHONE TEMPLATE

This is an alternative version of the 'phone template', set up especially to handle just one mission coming from this phone. Use this for your new simpler 'easy phones'. The information that's changed between this & the other template is no 'name of file for mission 2' & no 'counter stating if player has played mission2'. 

DO_EASY_PHONE_TEMPLATE (integer,     // base brief
               string,     // name of file containing mission 1 from this phone
               counter,     // name of counter stating if player has passed mission 1
               counter,     // name of counter stating if player has failed mission 1
               counter,     // name of counter showing player on mission for gang 1
               counter,     // name of counter showing player on mission for gang 2
               counter,     // name of counter showing player on mission for gang 3
               gang,     // name of gang this phone is connected to
               integer     // the respect value needed to start mission (0-5)

Example: 

DO_EASY_PHONE_TEMPLATE (1098,
                        bil_ke1.mis,
                        flag_passed_yakuzagang_easy_phone1_m1,
                        flag_failed_yakuzagang_easy_phone1_m1,
                        flag_on_yakuzagang_mission,
                        flag_on_looniegang_mission,
                        flag_on_zaibgang_mission,
                        yakuzagang,
                        5)

IS BRIEF ONSCREEN?

Checks to see if any brief is being displayed onscreen at this moment. Returns TRUE if so, FALSE if not. Added for Willie's training mission. 

IS_BRIEF_ONSCREEN

Parameters

No parameters. Empty brackets are not required.

SOUND Declare

Declares 'space' for one sound object, without creating it right away. A 'sound object' is an item created at a particular (X,Y,Z) which plays a sound or sample. These 'sounds' behave like every other sound in the game - they have volume, get loud/quiet as the player approaches etc. At the moment, there are only two sound types - more will be added! 

SOUND (name)
Parameters
name unique name for this sound object

SOUND Declare & Set

For a list of sounds you can play see: Sounds Tutorial.

Declares & creates a 'sound object' of the type you specify at location (X,Y,Z). You can make it play once or make it can loop forever. You can stop any SOUND by using DELETE_ITEM on it. 

SOUND name = (X,Y,Z) SOUND_TYPE PLAYTYPE
Parameters
name unique name for this sound object
X,Y,Z Floats provide exact location to position this sound's centre point at.
TYPE the 'sound type' for this sound object - see bottom of document
PLAYTYPE the playback characteristic - PLAY_FOREVER or PLAY_INSTANT
Values for PLAYTYPE
PLAY_INSTANT Only makes the sound once.
PLAY_FOREVER Repeats the sound until a command makes it stop.

CREATE_SOUND

For a list of sounds you can play see: Sounds Tutorial.

This command lets you create a sound object mid-game at location (X,Y,Z). You can make it play once or make it can loop forever. You can stop any SOUND by using DELETE_ITEM on it. 

name = CREATE_SOUND (X,Y,Z) SOUND_TYPE PLAYTYPE END

Parameters

See: SOUND Declare & Set

DELETE GROUP IN CAR

This commands allows you to delete a group of characters - all of whom must be in a car. The leader is deleted as well. 

DELETE_GROUP_IN_CAR (char_leader)
Parameters
char leader Name of the leader of the group

CREATE CHAR INSIDE CAR

This creates a character inside of a pre-created car, setting him up to be the driver of this car. By calling this command, it means you do not need to create the char outside, send him to the char, wait for his objective & /then/ do what you really want to do - it's an effective 'shortcut' for cutting down the script complexity. 

char_name = CREATE_CHAR_INSIDE_CAR (car_name) remap OCCUPATION END
Parameters
char_name Name of a CHAR_DATA slot
car_name Name of a previously created & declared car
remap integer value describing the remap to give this character
OCCUPATION the occupation to give this character.

DECLARE FINISH SCORE

This signifies to the game what the 'target score' for this level is. The game does no checking for this yet - this info is for the 'pause screen'. This DECLARE & the others that follow should be places at the top of your main script, near your DECLARE_MISSION_FLAG - and /after/ the counters referred to (obviously). 

DECLARE_FINISH_SCORE (integer value)
Parameters
value integer declaring the score value

DECLARE TOTAL MISSIONS

This signals to the game the total number of missions on this level, not including 'secrets' like kill frenzies etc. Again, this is for the pause screen. 

DECLARE_TOTAL_MISSIONS (integer value)
Parameters
value integer declaring the number of missions in the script

DECLARE TOTAL SECRETS

This signal to the game the total number of hidden 'secrets' on this level. 

DECLARE_TOTAL_SECRETS (integer value)
Parameters
value integer declaring the number of missions in the script

DECLARE MISSIONS PASSED FLAG

This signals to the game the name of the counter containing the number of missions passed by the player. 

DECLARE_MISSIONS_PASSED_FLAG (counter name)
Parameters
counter_name string detailing the name of the previously declared counter

DECLARE GANG MISSIONS PASSED FLAG

This signals to the game the name of the counter containing the number of missions passed by the player for the first gang in your city - these declares should be after your SETGANGINFO commands. Gang One/Two/Three names are the order you do the setganginfo commands in. 

DECLARE_GANG_ONE_MISSIONS_PASSED_FLAG (counter name)
DECLARE_GANG_TWO_MISSIONS_PASSED_FLAG (counter name)
DECLARE_GANG_THREE_MISSIONS_PASSED_FLAG (counter name)
Parameters
counter_name string detailing the name of the previously declared counter

SUPPRESS THIS CAR MODEL

This lets you prevent the recycling from creating 'dummy vehicles' of a certain type. You can do this on only one type at any time, but you change this model as often as you like. If you want to finish suppressing a particular model, call the command with 'NONE' as the model. Willie's using this to prevent the game creating Isetta Limos until a particular mission involving one is done, there may be other uses for it, say prevent a specific model appearing during a specific mission. 

SUPPRESS_THIS_CAR_MODEL (MODEL)
Parameters
MODEL string detailing the car model name to suppress, NONE to stop suppressing.

DECLARE POWERUP CARLIST

This command is tied to the new 'powerup generator' template command: it basically details to the game a long list of 18 car models, to be used to decide what type of powerup to create when a crushed car is delivered by the crane system. This command should be placed at the top of your mainscript, beside the other 'declare' commands.

It requries 18 models, and it must be called if you plan on using DECIDE_POWERUP_FOR_CRANE. 

DECLARE_POWERUP_CARLIST (MODEL1, MODEL2, MODEL3, MODEL4, MODEL5, MODEL6,
                         MODEL7, MODEL8, MODEL9, MODEL10, MODEL11,
                         MODEL12, MODEL13, MODEL14, MODEL15, MODEL16,
                         MODEL17, MODEL18)
Parameters
MODELx string detailing a car model…

DECIDE POWERUP FOR CRANE

This is the 'partner' command to 'DECLARE_POWERUP_CARLIST'. It should be called when the player had delivered a car to the 'powerup crane system', the car has been crushed, and is on the conveyor belt to the point where it gets deleted. This command simply takes in the car & a generator, and decides what type of reward to give the player via the generator. It compares the model of this car against the models listed in the powerup carlist, and if it matches, creates the correct powerup. If there's no match, the player gets given a pistol powerup.

If the final type is a weapon, it tells the generator to make three of them, if it's a powerup, it will make only one. See Billy for details of this - he asked for it!! 

DECIDE_POWERUP_FOR_CRANE (car to check, generator name)
Parameters
car to check Name of a previously declared car - this is the crushed car
Generator name Name of the generator to use for the powerup

IS ITEM ACCURATELY ONSCREEN

Highly accurate 'screen check' - it checks each corner of the item's collision information. Returns TRUE if so, FALSE if not… 

IS_ITEM_ACCURATELY_ONSCREEN (name)
Parameters
name Name of a previously declared item - see 'is item onscreen'

WARP FROM CAR TO POINT

New 'warp' command asked by Steve. Takes a character who is driving a car, and warps him to a new position outside the car. He must be driving a car. And note, the player has control of the character in the time it takes the camera to update to his new position…… 

WARP_FROM_CAR_TO_POINT (name, X,Y,Z, rotation)
Parameters
name Name of the character to warp
X,Y,Z Float the new location to move to. Cannot use 255.0 for automatic z!
rotation Int the rotation to set the character to face once warped.

Multiplayer

Requires vike’s gta2.exe version 11.41 or better.

SET GROUP TYPE

This lets you manipulate groups of characters by letting you alter how they follow their leader. It's done through the leader's character - and he must have a group already added to him. Valid types at the moment are :

CHAIN
Follow the leader like the krishnas in GTA.
MOB
Follow the leader in a 'rabble' - this is the default behaviour. 
SET_GROUP_TYPE (leader name, type)
Parameters
Leader name Name of a previously created character, with a group
Type one of the two types listed above - CHAIN or MOB

MAKE CHAR DO NOTHING

This is an important new command, which should be used a lot in 'tidying up' mission characters. It effectively makes a character stop chasing another character, and stops him from doing most things. It should be used instead of setting a char to doing NO_OBJ for his character objective. 

MAKE_CHAR_DO_NOTHING (charname)
Parameters
charname Name of a previously created character

SET CAR EMERG LIGHTS

This lets you manipulate the lights on an 'emergency vehicle' that you've created, such as a copcar or firetruck. You can set the lights on or off as often as you like. If the car doesn't have these lights, it just does nothing… 

SET_CAR_EMERG_LIGHTS (car name, ON)
SET_CAR_EMERG_LIGHTS (car name, OFF)
Parameters
Car name Name of a previously created car

SET CHAR INVINCIBLE

Using this command, you can make a character 'invincible' to all bullets/flames/rockets/explosions. The only way to harm him is to run him over & stun him! You can set this on & off… 

SET_CHAR_INVINCIBLE (charname, ON)
SET_CHAR_INVINCIBLE (charname, OFF)
Parameters
charname Name of a previously created character, including the player

SET CHAR GRAPHIC TYPE

This lets you manipulate the 'graphic' of a particular character, as well as his remap. Use this to make a character look like a policeman or a gang member when he isn't… Valid graphic types are: 

SET_CHAR_GRAPHIC_TYPE (charname, graphic type, remap value)
Parameters
charname Name of a previously created character
graphic type one of the types listed above.
Remap value the remap value to apply to this new graphic type…

HAS CHAR BEEN ARRESTED?

Checks to see if this player character has been arrested. Returns TRUE if so, FALSE if not. It actually checks for you being thrown out the car by the police…. Bear that in mind. Only the player gets arrested - other characters are just killed by the police. 

HAS_CHAR_BEEN_ARRESTED (charname)
Parameters
charname Name of a player controlled character

CHECK_WEAPON_TYPE_HIT_CAR

This is the car equivalent of CHECK_WEAPON_TYPE_HIT_CHAR. Takes the name of a previously created car, and waits to see if a particular damage 'type' hits it.

See CHECK_WEAPON_TYPE_HIT_CHAR for full details. 

CHECK_WEAPON_TYPE_HIT_CAR (car_name, DAMAGE_TYPE)
Parameters
car_name Name of a previously created car
DAMAGE_TYPE string detailing the 'type' of damage to look out for.

CHECK ANY WEAPON TYPE HIT CAR

This sets up a check that looks for any weapon to hit a particular car. It will return TRUE if such a hit has happened, FALSE if not. If you do a CHECK_WEAPON_TYPE_HIT_CAR after this returns TRUE, you can check to see the particular type that's hit…. See bottom of doc for list of 'types'. 

CHECK_ANY_WEAPON_TYPE_HIT_CAR (car_name)
Parameters
car_name Name of a previously created car

LOCATE ANOTHER CHARACTER ON FOOT

Operates like the other locates, except with this the character must approach another character on foot. It continually updates a 'range' around the 'locate char', and returns TRUE if the char enters this, FALSE if not.

Use this basically to check for the player approaching another character, instead of an exact 'area'. 

LOCATE_ANOTHER_CHARACTER_ON_FOOT (main char, locate char, width,height)
Parameters
main char Name of the char that is doing the 'running around', ie the player
locate char Name of the char that is the 'target' for the locate
width floating point value detailing the total width of the check
height floating point value detailing the total width of the check

STOP CHAR DRIVING

Orders a particular character to 'stop driving'. It effectively makes him slam on the breaks & stop dead. At that point, you can then order him out of the car etc. He must be driving a car when you call this command! 

STOP_CHAR_DRIVING (charname)
Parameters
charname Name of the character

IS BUS FULL?

Checks to see if the bus that this character is driving is full or not. Returns TRUE if so, FALSE if not. Current max passengers for a bus is 10. 

IS_BUS_FULL (charname)
Parameters
charname Name of the player's character - must be driving a bus!

STOP CHARS GETTING OFF BUS

Setting this to ON prevents any passengers from getting off the public transport bus. Set it to OFF to switch it back to normal. 

STOP_CHARS_GETTING_OFF_BUS (charname, ON)
STOP_CHARS_GETTING_OFF_BUS (char name, OFF)
Parameters
charname just the name of the player.

KILL CHAR

Makes a character instantly 'die' - fall on the floor dead. Different to delete. You shouldn't do this on a player controlled character. 

KILL_CHAR (charname)
Parameters
charname Name of a previously created character.

SET SHADING LEVEL

Similar to the SET_AMBIENT_LEVEL command, this sets the shading 'contrast' for the level. Valid values are 0 - 31, with 15 being the 'normal' level. 

SET_SHADING_LEVEL (integer value)
Parameters
value integer value detailing what level to set.

SET CAR JAMMED ACCELERATOR

As requested by Steve, this allows you to force a car's accelerator to be permanently on - the player cannot slow the car down. You can switch this on/off on any car that the player is controlling. 

SET_CAR_JAMMED_ACCELERATOR (car name, ON)
SET_CAR_JAMMED_ACCELERATOR (car name, OFF)
Parameters
Car name Name of a previously created car, probably being driven by the player

START BONUS CHECK

This is a complicated command used to check for the player scoring repeatedly, e.g. for kill frenzies. It handles a lot of different cases, so it has a lot of parameters. These don't all need to be set - there are default values for each type, like -1 or NONE.

Basically, you're telling the game to look for the player causing a certain number of score 'events' in a certain period of time. These events can be killing certain peds, car models, peds with occupations, gang peds, peds with certain remap, certain car models with certain remaps, etc. On top of that you can make it so that only doing it with certain weapon types counts. 

Bonus = START_BONUS_CHECK (zone, time, count, score, type, MODE,
                           DAMAGE, MODEL, gang_name)

Bonus = START_BONUS_CHECK (zone, time, count, score, type, MODE,
                           DAMAGE, MODEL, gang_name, target remap)

Bonus = START_BONUS_CHECK (zone, time, count, score, TYPE, MODE,
                           DAMAGE, MODEL, OCCUPATION)

Bonus = START_BONUS_CHECK (zone, time, count, score, TYPE, MODE,
                           DAMAGE, MODEL, OCCUPATION, target_remap)

Bonus = START_BONUS_CHECK (zone, time, count, score, TYPE, MODE,
                           DAMAGE, MODEL, TARGET_MODEL)

Bonus = START_BONUS_CHECK (zone, time, count, score, TYPE, MODE,
                           DAMAGE, MODEL, TARGET_MODEL, target_remap)
Parameters
Bonus this is the name of a BONUS item used to store details about the Bonus check. This is new!!!!
time Integer number of cycles allowed for the check. The BONUS will fail if time runs out
count Integer number of 'scores' of this type the player must do to pass
score Integer number of points awarded if the BONUS is completed successfully. Set to 0 to give no 'extra' score
TYPE How the player must do the scores: on foot (CHAR) or by vehicle (CAR)
MODE Either EXCLUSIVE or NOT_EXCLUSIVE. Stops the player getting points from other types of activity
DAMAGE Only count a 'score' if it was caused by the given damage type. Set to BY_ANY_WEAPON for more flexible 'scoring'.
MODEL Only count a 'score' if player was using this type of vehicle. Set to NONE if the player can use any vehicle.
gang_name Only count a 'score' if affected this gang, as named in your SET_GANG_INFO command
TARGET_MODEL Only count a 'score' if it affected this type of vehicle. Set to NONE for char based attacks, or to avoid this restriction.
target_remap use this to make the check work on a particular 'remap' - only cars or chars with this remap will count for the check.
OCCUPATION use this to check for characters only with this occupation, e.g. ELVIS peds. Or NO_OCCUPATION if you don't care!
Zone Name of a zone that the check MUST happen in - put NO_ZONE if you don't care about the zone!!! This is NEW!!!!

HAS BONUS FINISHED

Checks to see whether the bonus has finished executing. If it has, use one of the other two commands to then see why. Returns TRUE if finished, FALSE if still executing. 

HAS_BONUS_FINISHED (name)
Parameters
name Name of a bonus item, used by a START_BONUS_CHECK

HAS BONUS PASSED

This is used to check whether the bonus you've setup has been 'passed' or completed by the player. Returns TRUE if so, FALSE if not. 

HAS_BONUS_PASSED (name)
Parameters
name Name of a bonus item, used by a START_BONUS_CHECK

HAS BONUS FAILED

This is used to detect if the bonus check has failed - ie the player has either ran out of time or if exclusive, commited some other score event. Returns TRUE if so, FALSE if not. 

HAS_BONUS_FAILED (name)
Parameters
name Name of a bonus item, used by a START_BONUS_CHECK

START BONUS CHECK EXAMPLE

This checks for the player killing 3 yakuzagang members…. 

START_BONUS_CHECK (KILL_ANY_MEANS, 3000, 3, 20000, CHAR,
                          NOT_EXCLUSIVE, BY_ANY_WEAPON, NONE, yakuzagang)

     DISPLAY_TIMER (timer, 3000)
     WHILE_EXEC (NOT (HAS_BONUS_FINISHED))
          DO_NOWT
     ENDWHILE

     CLEAR_TIMER (timer)
     IF (HAS_BONUS_PASSED(name))
          SET_AMBIENT_LEVEL (0.4, 100)
          DISPLAY_BRIEF (8001)
     ENDIF
     IF (HAS_BONUS_FAILED(name))
          SET_AMBIENT_LEVEL (1.0, 0)
          DISPLAY_MESSAGE (8002)
     ENDIF

SET BONUS RATING TEXT ID

This command is purely for the bonus levels - it allows the designers to pass a 'text id' denoting the rating of the player's performance in this bonus mission. The value passed should be a regular integer detailing the 'text id' in the e.gxt file. 

SET_BONUS_RATING_TEXT_ID (rating_id)
Parameters
rating_id integer value detailing the player's rating

SET CHAR MAX RUNSPEED

Allows you to set the maximum 'run speed' for a particular character. This controls the speed he runs at. 

SET_CHAR_MAX_RUNSPEED (charname, float speed)
Parameters
charname Name of the character's speed to set
Float speed floating point value detailing new max.

SET CHAR TO STAY IN CAR

This command forces a non-player character to stay inside his current car - he will not get out voluntarily. This can be toggled ON/OFF. 

SET_CHAR_TO_STAY_IN_CAR (charname, ON)
SET_CHAR_TO_STAY_IN_CAR (charname, OFF)
Parameters
charname Name of the character to stay inside his car

SET CHAR TO USE CAR WEAPON

This command forces a character to use any car weapon that is available to him in the car - use this to make "dummy" characters use gun jeeps, tanks etc properly. Again, this can be toggled ON/OFF 

SET_CHAR_TO_USE_CAR_WEAPON (charname, ON)
SET_CHAR_TO_USE_CAR_WEAPON (charname, OFF)
Parameters
charname Name of the character to use car weapon…

DECLARE GANG MISSIONS TOTAL

This tells the game the total number of missions available for each gang in your city. These declares should be after your SETGANGINFO commands. Gang One/Two/Three names are the order you do the setganginfo commands in. 

DECLARE_GANG_ONE_MISSIONS_TOTAL (integer value)
DECLARE_GANG_TWO_MISSIONS_TOTAL (integer value)
DECLARE_GANG_THREE_MISSIONS_TOTAL (integer value)
Parameters
value the number of available for this gang

DECLARE SECRETS PASSED FLAG

This tells the game a name of a counter containing a record of the number of secrets passed by the player so far in the game. Put it by your other DECLARE_… commands. 

DECLARE_SECRETS_PASSED_FLAG (counter name)
Parameters
counter_name Name of the counter containing the info required

DECLARE SECRETS FAILED FLAG

This tells the game a name of a counter containing a record of the number of secrets FAILED byt eh player so far in this game. Put it by your other DECLARE… commands. 

DECLARE_SECRETS_FAILED_FLAG (counter name)
Parameters
counter_name Name of the counter containing the info required.

MAKE ALL CHARS MUGGERS

Ignore the 'muggers' bit - this effectively makes new dummy characters "mad", as requested by Willie. Any hassles - bug IainR about it! 

MAKE_ALL_CHARS_MUGGERS (ON)
MAKE_ALL_CHARS_MUGGERS (OFF)

LOCATE ANOTHER CHARACTER BY CAR

Operates like the other locates, except with this the character must approach another character in a vehicle. It continually updates a 'range' around the 'locate char', and returns TRUE if the char enters this, FALSE if not.

Use this basically to check for the player approaching another character, instead of an exact 'area'. 

LOCATE_ANOTHER_CHARACTER_BY_CAR (main char, locate char, width,height)
Parameters
main char Name of the char that is doing the 'running around', ie the player
locate char Name of the char that is the 'target' for the locate
width floating point value detailing the total width of the check
height floating point value detailing the total width of the check

LOCATE ANOTHER CHARACTER ANY MEANS

Operates like the other locates, except with this the character must approach another character in a vehicle or on foot. It continually updates a 'range' around the 'locate char', and returns TRUE if the char enters this, FALSE if not.

Use this basically to check for the player approaching another character, instead of an exact 'area'. 

LOCATE_ANOTHER_CHARACTER_ANY_MEANS (main char, locate char, width,height)
Parameters
main char Name of the char that is doing the 'running around', ie the player
locate char Name of the char that is the 'target' for the locate
width floating point value detailing the total width of the check
height floating point value detailing the total width of the check

CHANGE GANG CHAR RESPECT AND UPDATE

This command lets you change the respect level that a character has with a particular gang - ie the levels that are displayed on screen. Bear in mind that valid respect levels are in the range of -5 to 0 to 5. To reduce the respect, use a negative number.

In addition, this command updates the other respects - increasing/decreasing depending on the gang relationships. 

CHANGE_GANG_CHAR_RESPECT_AND_UPDATE (gang name, charname, difference)
Parameters
gangname Name of the gang…
(name) Name of the player's character…
diference integer value to add to the respect. Can be negative!

MISSION HAS FINISHED

This is a straightforward command to signal to the game that the player has either failed/passed a mission. It forces the game to run the 'clean up' mission code - ie flag all peds/cars etc that were created in this mission to be deleted as soon as possible. 

MISSION_HAS_FINISHED

Parameters

No parameters. Empty brackets are not required.

BONUS DECLARE

This 'declares' space for the new 'bonus' info needed for interfacing with START_BONUS_CHECK. Basically, put it by your other declares. These can be re-used. 

BONUS (name)
Parameters
name unique name to give to this 'bonus' item.

STORE BONUS COUNT

This takes a currently executing bonus check & stores the current 'number' achieved by the player in a counter. In other words - it takes the current number of 'events' done by the player & stores it in a counter, letting you work & manipulate that value… 

STORE_BONUS_COUNT (bonus_name, counter_name)
Parameters
bonus_name Name of a BONUS object that's currently being used with a START_BONUS_CHECK command
counter_name Name of a counter to store the value in.

SET FAVOURITE MODEL

This allows you to make a character 'prefer' a favourite model for when he is doing a 'KILL_CHAR_ANY_MEANS'. If the char creates a car to use, it will be of this model. 

SET_FAVOURITE_MODEL (charname, model name)
Parameters
charname Name of a previously created character
Model name Name of a car model.

SET CHAR OCCUPATION

This lets you change a character's occupation mid-game. Not applicable to the player's char! 

SET_CHAR_OCCUPATION (charname, OCCUPATION)
Parameters
charname Name of the character
OCCUPATION string detailing the new occupation

ONSCREEN COUNTER

This is a 'declaration' of space to be used to store a 'hook' for onscreen counters. You must put this outside the normal functions, in a similar position to your other declares. You only need one of these really, i.e. one for every counter onscreen at any time - not in TOTAL.

This does not work like a COUNTER - it's just a space to store some info related to the onscreen counters/timers. 

ONSCREEN_COUNTER name

ADD ONSCREEN COUNTER

This takes a COUNTER variable & starts to display its contents onscreen, until your timer is removed, or you call CLEAR_ONSCREEN_COUNTER. As you change the value of this counter, it will be automatically updated onscreen. 

ADD_ONSCREEN_COUNTER (onscreen_counter_name, counter_name)
Parameters
Onscreen_counter_name Name of an ONSCREEN_COUNTER for referring to this command.
counter_name Name of the actual COUNTER to display onscreen.

CLEAR ONSCREEN COUNTER

This removes a counter from the screen, leaving the clock running if one is onscreen. 

CLEAR_ONSCREEN_COUNTER (onscreen_counter_name)
Parameters
onscreen_counter_name Name of the ONSCREEN_COUNTER holding the details for the one currently getting displayed

CLEAR CLOCK ONLY

This removes the 'timer' part of an onscreen display, leaving the counter to be displayed on its own. 

CLEAR_CLOCK_ONLY (timer name)
Parameters
Timer name Name of the 'timer data' containing the hook to the onscreen timer.

ARE EMERG LIGHTS ON?

Simple car check that looks to see if an emergency vehicle's lights are switched on. Returns TRUE if so, FALSE if not. 

ARE_EMERG_LIGHTS_ON (car name)
Parameters
car name Name of a previously declared/created car

CHANGE POLICE LEVEL

This command allows you to change the maximum level of heads in this level mid-game. Obeys the standard rules for maximum heads. 

CHANGE_POLICE_LEVEL (new maxheads)
Parameters
new maxheads integer value detailing the maximum level of heads.

DESTROY GROUP

This command effectively 'splits' or 'disbands' a group, making all the members wander off as individuals again. 

DESTROY_GROUP (leader name)
Parameters
leader name Name of a character

CHECK CHAR CURR WEAPON

This is a simple straightforward check - it looks at this character's currently selected weapon & returns TRUE if it matches a specific type, or FALSE if not.

You should only really do this command on PLAYER controlled characters! 

CHECK_CHAR_CURR_WEAPON (charname, weapon type)
Parameters
charname Name of a player controlled character
Weapon type type of weapon to check for

ALTER WANTED LEVEL NO DROP

Alters the player's wanted level to a given level of heads, but only if the player has less than this number of heads!. Effectively, you're now setting the number of heads the player should have. Valid values are between 1 & 6. With this command however, if the player has 4 heads, and you request 2, it will not change it - it will NOT drop the heads lower than the player's current count! 

ALTER_WANTED_LEVEL_NO_DROP (name, num heads)
Parameters
name Name of valid, existing character
num heads the new value of heads for the character

DECLARE GANG DEATH BASE BRIEF

This declares to the game the starting id of the first gang's 'death' base brief. There should be five death briefs followed by five 'arrest' briefs for each gang. Each gang's base brief must be declared for the death/arrest code to work correctly.

These are DECLARE commands, so they should be beside all your other flag declarations at the top of the mainscript. 

DECLARE_GANG_ONE_DEATH_BASE_BRIEF (player_name, integer base)
DECLARE_GANG_TWO_DEATH_BASE_BRIEF (player_name, integer base)
DECLARE_GANG_THREE_DEATH_BASE_BRIEF (player_name, integer base)
Parameters
player_name Name of the player associated with this brief
Integer base integer value detailing the 'base brief id' in the e.gxt file

DECLARE GANG MISSION FLAG

This declares to the game the 'COUNTER' variables used to store which gang the player is currently involved with doing a mission for. You already have these flags all set up - the game just now needs to know about them.

Do these commands AFTER you do the COUNTER declares. 

DECLARE_GANG_ONE_MISSION_FLAG (player_name, flag name)
DECLARE_GANG_TWO_MISSION_FLAG (player_name, flag name)
DECLARE_GANG_THREE_MISSION_FLAG (player_name, flag name)
Parameters
player_name Name of the player
Flag name Name of the 'counter' used to store the info.

SET DEATHARREST STATE

This allows you easy access to switching the death/arrest check on & off in your scripts. At the moment, it defaults to OFF, this will get changed to defaulting to ON. Make sure to switch it to OFF at the start of any missions you want to handle yourself, switching it back on during your cleanup! 

SET_DEATHARREST_STATE (player_name, ON)
SET_DEATHARREST_STATE (player_name, OFF)
Parameters
player_name Name of the player's character

PERFORM SAVE GAME

This new command handily wraps up all the details of saving the game. It checks whether the player is on a mission, checks whether he has enough of a score to pay, and handles subtracting the cost at the end of it. Use this instead of your current routine - it needs to be called from a THREAD_TRIGGER command as before - similar fashion to the kill frenzy templates you've already set up. There's an example below.

The coords/width/height are the area around the savegame spot that the player must leave before he can save again - these should be the same as the range for the THREAD_TRIGGER. 

PERFORM_SAVE_GAME (trigger_name, X,Y,Z, width,height)
Parameters
trigger_name Name of a THREAD_TRIGGER used to start the savegame thread.
X,Y,Z coordinates of the centre of the range to use for checking location
width,height area to check.

PERFORM SAVE GAME EXAMPLE

This is a working example of a new perform save game from willie's level. 

THREAD_TRIGGER thr_save_slot_one = THREAD_WAIT_FOR_CHAR_IN_AREA (player, 159.0, 137.0,2.0, 4.0,1.0, do_save_slot_one:)

do_save_slot_one:
     PERFORM_SAVE_GAME (thr_save_slot_one, 159.0,137.0,2.0, 4.0,1.0)
RETURN

DECLARE CRANE POWERUP

This is a new 'template style' command. It takes over the job of waiting for your 'background' cranes picking up a car & awarding a weapon/powerup as a result of the car model. It links into the powerup_carlist you declare to make the decision.

It needs the name of the second crane - the crane that places the crushed car on the conveyor belt. It also requires the name of the generator to use to create the reward, plus the coordinates to use to wait for the crushed car disappearing.

This is a 'declare' - so put it nearby the other declarations, outside of any functions. 

DECLARE_CRANE_POWERUP (crane name, generator name, X,Y,Z)
Parameters
crane name Name of a previously created crane
Generator name Name of a previously created generator
X,Y,Z Integer values describing the position inside the building.

LEVEL_END_POINT_ARROW_AT

Sets an existing arrow to point towards either a location, character, car or object, using the new special LEVELEND colouring. All items must be valid existing items. If target is an object, the arrow must be cancelled before object gets deleted. Use this only for the arrowing point towards the END OF LEVEL target! 

LEVEL_END_POINT_ARROW_AT (arrow_name, name)
LEVEL_END_POINT_ARROW_AT (arrow_name, X,Y,Z)
Parameters
arrow_name Name of an arrow declared with an ARROW_DATA
name Name of either a car, character or object
X,Y,Z must be a valid float (X,Y,Z) coordinate.

CHECK DEATHARREST EXECUTED

This is a new vital command to link with the new 'deatharrest' code - you must call this in your cleanup code to check whether the player FAILED the mission instead of checking your own internal 'failed' flag for the mission. That flag will not be set by the deatharrest code!

It returns TRUE if the deatharrest code executed & failed the mission, FALSE otherwise. 

CHECK_DEATHARREST_EXECUTED ()

Parameters

No parameters. Empty brackets are required.

SET RECYCLE MODEL WANTED

This is a PSX 'special command' that allows you to specify a ‘normal’ car model you need generated by the recycler for the player to pick up. Using this command means you can depend on an icecream van coming along just when you require in the mission without actually creating one explicitly.

Set the model to NONE if you no longer care - this is the default value. The cleanup code will ALWAYS set this to NONE just to be safe.

You shouldn't use this command for ambulances/copcars etc - they'll be created as normal when the player does stuff!

This command only works on the PSX - it just gets ignored on the PC. 

SET_RECYCLE_MODEL_WANTED (car model type)
Parameters
Car model type just a string detailing a particular model to use, e.g. HOTDOG

FORCE CLEANUP

This command is SPECIFICALLY for 'collectable' powerup type objects - it orders the game to add it to its internal 'cleanup' list - so that when the player passes/fails the mission, it will be deleted. Normally collectables are NOT in this list. The game will cope with the object being collected - just do this command & forget about it. 

FORCE_CLEANUP (object name)
Parameters
Object name Name of a previously declared & created object!

General Concepts

Angles

(See also: Angles Tutorial.)

All angles are given in degrees in range of 0 to 359. The angle system is: 

     N 180
W 270          E 90
     S 0

Comments in the Scriptfile

These can be done two ways: 

/* This is a comment */
     // This is another comment

The /* &hellip; */ system can wrap over multiple lines, but there must be a matching /* */ pair. The // system effectively 'comments out' the rest of the line it is on: 

     PED_DATA one_ped           // this ped is an example ped for simple demos
// or...
      /* send_player_to_phones
          This subroutine orders the player to the main phones &amp; waits for him to arrive there
     */

Floats

Floating point numbers are used extensively instead of the "fixed point" as in GTA. If you want say, the centre of a block, 123.5 is used. For a quarter, 123.25 is needed. One limit of the script language is that all floating point numbers must have a .0 at the end.

So the following are legal: 

0.0
12.35

Whole numbers are not: 

123

Integers

Integers are whole numbers in the range of -32767 to 32768. In GTA2script, they are mainly used in COUNTER as floats are used to represent coordinates in general.

Automatic z Calculating

As noted in many 'creation' commands, it's possible for the game to automatically calculate the correct Z value for a given item, such as cars.

This will only work in certain positions: effectively, the game will position the car at the highest Z value at this (X,Y). Any pipes or other structures will count. If something needs to be positioned in a block below a roof or an overhang etc, you will need to specify the correct Z manually.

Triggers

An array of trigger info 0–255 has details of type, action, state (ie true/false) etc. Whenever we create a trigger, say WAIT FOR PED IN BLOCK we store the id of its triggerinfo in the object's spare info byte. When the trigger gets collided with, it calls object_hit which then does the checking of ids/states etc as requested by the triggerinfo it has a link to. The mission script must check this each cycle to learn the state of the trigger, with designers aware of the fact that they will 'halt' until passed.

Certain triggers can be designed with the idea of 'starting' a new process at a certain line.

Example triggers:

WAIT_FOR_CHAR_TO_ENTER_BLOCK
Waits for any character, whether player or dummy, to arrive at a particular block.
WAIT_FOR_CHAR_TO_ENTER_BLOCK_ON_FOOT
As above, but character must be just a pedestrian with no car.
WAIT_FOR_CHAR_TO_ENTER_BLOCK_IN_CAR
As above, but character must be inside a car - can be any car, particular car, particular model.

General Characters

This is just a general overview of characters to be fleshed out in consultation with IainR. I need to discuss in depth actual access functions, objectives etc - this will be done next week.

Characters are created with a (X,Y,Z), a rotation, remap, graphic type, and an occupation - this will operate in a similar fashion to GTA, eg. Driver, bus passenger, psycho, mugger, elvis, medic.

Additionally, extra characteristics can be set: bravery & shooting skill - these affect how the character handles events in a group - say, a group gets wasted & only a few chars are left, a Coward will runaway. Shooting skill affects how accurate a shot this character has. The current levels for these are:

Parameters
bravery coward, average, loony
shooting skill crap, normal, crack.

Once a character is created, it can be given an objective - for example, kill a character, wait for a bus. Additional "commands for characters are ones such as sending to a local position on foot, sending to a faraway location by any means (ie by car, by taxi). Characters can be given "patrol zones" through a list of points, and they'll follow that path. The script command "CHECK_OBJECTIVE" will check the state of the objective, whether it's succeeded, still being done, or failed.

On top of all this, groups of characters can be created & accessed through the 'leader' character - a totally new group (with leader) can be made, a new group given to an existing character, or given to the player's character. When a leader is killed, another character in the group becomes leader, this will be automatically updated in the mission info by a mission callback function - designers do not need to worry about this. Groups can be given the same objectives/"commands" as normal characters can.

Overview & Examples

Notes

All commands listed in example are likely to change - do not expect this syntax to be final!!!

GTA2 will contain a mission scripting system much improved over GTA's. Instead of a constrained, linenumber/macro system where commands were hardcoded in a specific format, GTA2 uses a freeform scripting system, with a structure & syntax similar to Basic & "C". It provides predefined types for easy creation of characters, cars, objects, timers, triggers & the other items featured on a level.

The scripting language provides predefined types for easy creation of these 'items'

These can be created at startup or during the game. There is no concept of a 'future ped' or 'future car' in GTA2script as the scripting logic can now handle the difference. An example of creating a ped is 

CHAR_DATA testped = (10.0,5.0,255.0) 90 0

In this example, GTA2script automatically places the ped at the correct Z level if asked to by the designer using 255.0 as Z, any other value will place the ped at that Z level, easing the problem of handling different Z levels from GTA. The different numbers are, in order:

Cars, objects, etc all have similar create commands. If the designer tries to place a ped on a bridge or on a block with two heights of road or pavement, it will choose the higher Z level on top of the bridge. An alternative would be 

     CHAR_DATA anothertest
     …
     anothertest = CREATE_CHAR (10.0,5.5,255.0) 90  0 DUMMY END

This would 'reserve' the space for the ped at startup, but would create the ped later on mid-game when the CREATE_PED line is executed. A more detailed example of this will be shown later.

In addition, GTA2script will contain a number of predefined programming structures. These are: 

FOR (x = 0) DO …
WHILE (x) DO (y)
 (x) AND (y)
NOT (y)
IF (x) THEN y ENDIF
IF (x) THEN y ELSE z ENDIF

These can be used freely, and will lessen the need for designers to code these structures themselves. By having them predefined, also aids debugging - the designers can rely on them to work correctly. These can also be "mixed & matched: 

     IF x AND (y))
          FOR x = (0 to 10)
               do_something
          ENDFOR
     ENDIF

Multitasking

GTA2script allows 'multitasking' of mission commands in a similar fashion to GTA, but this is used less than it was in GTA1 - the ability to execute multiple lines in one cycle succeeds this. Separate "functions" are started as a new thread, running in sequence to the current thread. When the thread reaches the end of the function code, it kills itself. More control will be given to the designers over the timing & 'start/stop' of threads. A function looks like this in code: 

labelname:
     code
return

wait_for_ped:
     WHILENOTIS_CHAR_IN_LOCATIONped, target_location)))
INC(counter)
     ENDWHILE
return

In this example, the program waits until a ped has reached a given location, incrementing a counter each turn. Functions need not be called as a new thread, they can be 'jumped to' and run in sequence instead of parallel. The GOSUB label call acts 'in sequence'. There is no GOTO, only GOSUB so that the program *must* return out of the function. Example code:

In sequence (doesn’t work): 

target_location = SET_LOCATION (100.0,100.0,3.0) 1 1
ped = CREATE_CHAR (90.0,44.5,255.0) 90 1 BANK_ROBBER END
     GOSUB wait_for_ped:
     // here - ped has reached the target location
     KILL_PED (ped)

In parallel (doesn’t work): 

target_location = SET_LOCATION (100.0,100.0,3.0) 1 1
ped = CREATE_CHAR (90.0,44.5,255.0) 1 90 DUMMY
new_thread = CREATE_THREAD wait_for_ped:
     // do something else, at the same time as wait_for_ped

The designers will have functions that can check the current state of a thread they've started, allowing them to check it has completed properly or handle problems. One of the original scripts' biggest problem was timing of commands - designers had little control over the sequencing of multiple threads or the timing of completion. In GTA2script, designers can pinpoint exactly when commands should 'kick start', as well as marking sections of code to be executed all at once, rather than one command at a time. Used in the right places, this will lessen a lot of timing errors & aid more precise events in critical sections of missions.

Readability of Scripts

GTA2scripts are likely to be long & detailed. To help designers read & follow their scripts, comments can easily be added using two different C++ style constructs 

/* this is a comment
         spanning two lines */
// this is a single line comment

Judicious use of whitespace to break up functions, separate out sections of code will help the readability of GTA2script files.

Example Mission

(See also: Simplest Multiplayer Script.)

Here is the simplest single-player script possible: 

// player

PLAYER_PED player = (113.5,124.7,255.0) 25 1

LEVELSTART

LEVELEND

See also: simplest multiplayer script.

Now, here is a detailed GTA2script example (doesn’t work) of the structure & contents of a simple mission from beginning to end, with comments detailing what is happening. 

// Example script
// waits for played ped to cross a 'trigger point' & then sends a  'dummy' ped to a point, and the player
// has to kill him before his arrival at the destination.


// data - these are 'read through' when the script is loaded & ped under player control is created.

PLAYER_PED      player = (90.5,133.5,255.0) 180 0
PED_DATA     target_ped          // ped for the player to kill
LOC_DATA     target_location          // where we're going to send target_ped
THREAD_DATA threadinfo          // for storing new thread info

// trigger data - coords, width + height of trigger, and the function it 'starts'
TRIGGER     triggerpoint = (95.5,133.5,2.0) 1 1 assasin_mission:

// this is where we'll store the length of time it takes for ped to arrive
COUNTER     timer = 0

// general purpose 'flag'
COUNTER      flag = 0

/* send_and_wait_for_ped
 * ------------------------------
 * function      :     send target_ped to target_location & wait for his arrival
*                Will store the number of cycles it took in timer
*
*/

send_and_wait_for_ped:
     // send ped to block - travels by any means necessary to get there
     SEND_PED_TO_BLOCK (target_ped, target_location)
     // if ped hasn't arrived at target yet, inc counter + try again next cycle
     WHILE (NOT (IS_PED_IN_BLOCK(target_ped, target_location)) )
          INC (timer)
     ENDWHILE
return


//
// assasin_mission
// --------------------
// function     :     Player has to go kill a ped before ped reaches a target
//

assasin_mission:
     // order played to kill ped
     DISPLAY_BRIEF (23)
     // create second thread that will deal with sending the target_ped to target
     // while we continue working, checking for deaths etc
     threadinfo = CREATE_THREAD send_and_wait_for_ped:

     // while ped hasn't arrived - do this block. EXEC means it runs through ALL
     // the checks each cycle, rather than one line at a time
     WHILE_EXEC (finish == 0)
     {
          // check if target_ped has died
          IF (IS_PED_DEAD(target_ped))
               // check if player managed to kill him
               IF (DID_PLAYER_KILL_PED(target_ped))
                    // congratulate player!
                    DISPLAY_BRIEF (25) // "Well done, you've killed the target"
                    ADD_SCORE(10000)
                    MISSION_SUCCESS     // store that we've succeeded a mission
                    finish = 1
               ELSE
                    // player didn't kill ped, so mission failed
                    DISPLAY_BRIEF (26) // "You screwed up.. Still, he's dead."
                    MISSION_FAIL          // store that we've failed…
                    finish = 1
               ENDIF
          ENDIF

// if second thread has finished, ped reached target
IF (NOT (CHECK_THREAD_ALIVE(threadinfo)) )
          // failed!
          DISPLAY_BRIEF (27) // "He's reached the base! You've failed"
          MISSION_FAIL
          finish = 1
ENDIF
     ENDWHILE_EXEC

     // finished mission, do clear up

     // make sure thread is killed
IF (CHECK_THREAD_ALIVE(threadinfo))
     KILL_THREAD (threadinfo)
ENDIF
return

// main game loop
//
// there should only ever be one 'level_start … Level_end' loop in the scriptfile, and GBH will
// automatically start the program from this line.

level_start
     // first off, create dummy ped & target location
     target_ped = CREATE_PED (80.5,55.5,255.0) 90 4
     target_loc = CREATE_LOC (200.5,33.5,2.0) 1 1

     // switch on trigger - after this point, if player crosses this block, the
     // assasin_mission is started
     SWITCH_ON_TRIGGER (triggerpoint)

     // this is the main game 'loop' doing any basic work that needs done each cycle, or
     // general work.

     // here, as an example, the level keeps running until the player runs out of lives
     WHILE (GET_PLAYER_LIVES > 0)
          DO_NOWT // empty clause
     ENDWHILE
level_end

Constants

Character Occupation List

See: Character AI Tutorial.

That is a list of the currently valid character occupations. Please clarify with Iain Ross any queries over types, information, objectives.

Threats

See: Character AI Tutorial.

A character can only have one 'threat search' at any time, but this can be altered as often as you like.

Reactions

See: Character AI Tutorial.

Character Remap List

(See also: Characters Tutorial.)

Character Shooting Skill Levels

See also: Character AI Tutorial.

Character Bravery Levels

See also: Character AI Tutorial.

Ped Weapons:

See: Weapons Tutorial.

Car Weapons:

See: Weapons Tutorial.

Car Types

See: Vehicles Tutorial.

Car Remaps

See: Vehicles Tutorial.

Object Types

See: Objects Tutorial.

Powerups

See: Weapons Tutorial.

Shop Types

See: Shops tutorial, Weapons tutorial and Objects in GTA2.

Door Opening Types

See: DOOR_DATA and Garages Tutorial.

Door Closing Types

See: DOOR_DATA and Garages Tutorial.

Arrow Colour Types

Lock Types

NO_LOCK
LOCKED             // locks out everyone, including players
LOCKOUT_THIEF      // locks out only carthiefs
UNLOCKED           // unlocked
LOCKED_PERMANENTLY // ALWAYS locked for everyone!!
LOCKOUT_PLAYER     // locks out ONLY players!

Damage Types

Sound Object Types

(See also: Sounds Tutorial.)

Radio Station Types

(See also: Radio Stations Tutorial.)

Messages which Play a Sound

See also: play announcement using memory addres.

The narrator will speaks these out when they are shown using DISPLAY_MESSAGE. The only way to make “KILL FRENZY” announcements is to use the Kill Frenzies System.

IDDisplayed Text
1124JOB COMPLETE!
1125JOB FAILED!
5000YOUR TIME IS EXTENDED!
5015TIME'S UP, PAL!
5000YOUR TIME IS EXTENDED!
5015TIME'S UP, PAL! (duplicate)
5031Oh, sorry about that... Did that hurt?
5032Nice work!
5050CHOCTASTIC!
5051RASPBERRY RIPPLE!
5052YOU SHOT YOUR LOAD!
5053OOH… DID THAT HURT?
5054DEATH TO ICE-CREAM VANS!
5055CRISPY CRITTER!
5056YOU'RE TOAST, BUDDY!
5057EAT LEADEN DEATH, PUNK!
5058THAT'S GOTTA HURT!
5059SORRY ABOUT THAT!
5060XIN LOI, MY MAN!
5061DAMN SUNDAY DRIVERS!
5062SUCK IT AND SEE!
5063TASTE MY WRATH, ICE-CREAM BOY!
5031OH, SORRY ABOUT THAT… DID THAT HURT?
5032NICE WORK!
5015TIME’S UP PAL
5501RACE OVER!
5502SECOND LAP!
5503FINAL LAP!
5504RACE ON!
5505HEY! 30 PEOPLE DOWN! MULTIPLIER ×2
5506OOH! 60 PEOPLE DOWN! MULTIPLIER ×3
5507NICE! 90 PEOPLE DOWN! MULTIPLIER ×4
5508GREAT! 120 PEOPLE DOWN! MULTIPLIER ×5
5509OUTSTANDING! 150 PEOPLE DOWN! MULTIPLIER ×6
5510TIME OUT!
5532HEY! 15 PEOPLE DOWN! MULTIPLIER ×2
5532OOH! 30 PEOPLE DOWN! MULTIPLIER ×3
5532NICE! 45 PEOPLE DOWN! MULTIPLIER ×4
5532GREAT! 60 PEOPLE DOWN! MULTIPLIER ×5
5532OUTSTANDING! 75 PEOPLE DOWN! MULTIPLIER ×6

Gang Heads for Messages

In the .gxt file, a message can start with a special code to display an animated head. The code is a letter then an exclamation mark (!) at the start of the message. For example: 

[1010] y!Excellent, Kosai! Now bring the #car# back to the #Safehouse#.

The hash character (#) is not displayed by the game. It lets you highlight parts of the message, as shown.

Normal text is bronze and highlight text is blue. The first # changes from normal colour to highlight colour, the next # changes back to the normal colour. You can change the colour multiple times within a message.

If you start the text of a message with a # the first colour will be the highlight colour and the next colour will be the normal colour. For example: 

[1001] y!#Excellent! You have completed #all# the #Yakuza jobs#!#
Values for Gang Heads in .gxt Messages
Icon Gang Code Notes
Neutral n! Default. Also used when there is no .gxt code.
Krishna k!
Loonies l!
Police SWAT p! Not used in the official levels.
Rednecks r! Elvis!
Russian Mafia m!
Scientists s!
Yakuza y!
Zaibatsu z! Different name in each level but same picture.

(Adapted from Pyro’s GXT list with CarThief’s addition about p!. Icon collection exported from GTA2 by Cuban Pete.)

Highlight Words in Messages

The hash character (#) is not displayed by the game. It lets you highlight parts of the message, like this: 

[1010] y!Excellent, Kosai! Now bring the #car# back to the #Safehouse#.

Normal text is bronze and highlight text is blue. The first # changes from normal colour to highlight colour, the next # changes back to the normal colour. You can change the colour multiple times within a message.

If you start the text of a message with a # the first colour will be the highlight colour and the next colour will be the normal colour. For example: 

[1001] y!#Excellent! You have completed #all# the #Yakuza jobs#!#

Slope Types

The ranges of values mean the slope is made from several blocks, each using a different ID number. These ranges start at the lowest part of the slope and go upwards to the highest part.

IDAngleSizeDirectionDescription
00°1×1(None)Normal cube
1–226° slope2×1UpStairs and jumps
3–4 Down
5–6 Left
7–8 Right
9–167° slope8×1UpRoads
17–24 Down
25–32 Left
33–40 Right
4145° slope1×1UpSteep
42 Down
43 Left
44 Right
4545° wall1×1Facing up leftDiagonal vertical walls
46 Facing up right
47 Facing down left
48 Facing down right
4945° slope1×1Facing up leftDiagonal slopes, outer and inner
50 Facing up right
51 Facing down left
52 Facing down right
53Thin wall¼×1LeftCannot be solid
54 Right
55 Top
56 Bottom
57Tower¼×¼Top left
58 Top right
59 Bottom right
60 Bottom left
61 Centre
62Reserved for future useNever used
630°1×1Indicates slope in block aboveCreated automatically

Credits

Originally written by DMA Design/Rockstar North and released to the GTA 2 community. Formatted and edited by Ben “Cerbera” Millard.

See also: GTA 2 Credits, put together by Sektor.