Help Home

Tutorials

Weapon Scr. I
Weapon Scr. II
Missions

Reference

All Commands
General
Load/Add
Graphics
HUD
Sounds
Player
Terrain
Projectiles
Particles
Collision
Objects
AI
Nodes
Missions

Commands: all

Legend

  • X - X is a number
  • 'X' - X is a string (a letter/word/text)
  • [X=0] - X is an optional parameter with value 0 when omitted (NEVER add [] to your script!)
  • hard sync - command is hard synced

addgameender('PREFIX', 'NAME')

Parameters:
'PREFIX' - a unique Lua game ender function prefix (or a name of a built-in game ender)
'NAME' - in-game name for the game ender
Adds a new game ender to the game. Game enders are executed to end the game if it takes too long. They normally destroy the terrain or kill/damage players.

Game ender Lua files have to be saved in the folder "scripts/Game Enders". The name of the files does not matter. Carnage Contest will display the game enders sorted by their file name though.

Each game ender (excluding the built-in game enders) has to implement a Lua function, otherwise you will receive Lua errors (PREFIX has to be replaced with the unique prefix for your game ender):

PREFIX_ge_run(endstep)
Execute the game ender. This function will be called ONCE after each turn as soon as the game ender started. Carnage Contest automatically passes the parameter "endstep" which is just a simple counter which is increased after each game ender call (starts at 0).

There are also some built-in game enders which do not have to implement this function. You can use the following values as PREFIX to use built-in game enders (all built-in game enders start with < and end with >):

<flood>
<flood+laser-top>
<laser-top>
<laser-left>
<laser-right>
<laser-left+right>
<laser-random>

addgamemode('PREFIX', 'NAME', [SCORESYSTEM=0])

Parameters:
'PREFIX' - a unique Lua game mode function prefix (or an empty string if you want to create a game mode which does nothing)
'NAME' - in-game name for the game mode
[SCORESYSTEM=0] - use a score system (1) or not (0)?
Adds a new game mode to the game. Game modes can be used to modify the game and the way it is played.

Game mode Lua files have to be saved in the folder "scripts/Game Modes". The name of the files does not matter. Carnage Contest will display the game modes sorted by their file name though.

Set SCORESYSTEM to 1 if you want to display and use an additional score value for your game mode.

Each game mode (excluding the ones with empty string as PREFIX) has to implement ALL following functions, otherwise you will receive Lua errors (PREFIX has to be replaced with the unique prefix for your game mode):

PREFIX_gm_start()
Called once when the game starts. Use it to initialize variables, to modify the map or to spawn objects.

PREFIX_gm_draw()
Draw additional stuff (executed each frame).
Attention: Do NOT use this function to perform actions! It's for drawing only!

PREFIX_gm_update()
Perform additional actions (executed each frame).

PREFIX_gm_playerdamage(victim,damage)
This function is executed whenever a player receives damage.
Parameters:
- victim: ID of the victim player
- damage: the damage value
Return:
- nothing/nil: proceed normally
- -1: do not cause any damage
- positive value X: cause X damage

PREFIX_gm_endturn()
This function will be called whenever a turn ends. Use this function to decide if the game is over or not and who is the winner.
ATTENTION: This function will be executed on the server/host side only! Therefore it is not recommended to perform additional actions in it. It might lead to asynchronism!
Return:
- nothing/nil: do not let the game end (or draw when everyone is dead)
- -1: end the game with a draw
- -2: let the game decide automatically (last living team wins)
- alliance X (1-8): end the game with alliance X as winner (alliance = team color)

addobject('TABLE', [IMAGE=0])

Parameters:
'TABLE' - Lua table which holds the object functions
[IMAGE=0] - ID of an image which will be used for collisions (0 for 0 collision)
Returns:
ID - object ID, required for createobject
Adds an object type to the game.
This command can be used several times in a single Lua script file.
A weapon does not have to have an object. It also can have multiple different objects.

Objects are pretty much like projectiles. The difference is that they can exist longer than just one turn. They normally do not prevent that the turn ends (but they can prevent it).

TABLE has to have at least 4 functions:
setup(ID,PARAMETER) - called by createobject once after creation
draw(ID) - draw the object with ID
update(ID) - update the object with ID
damage(ID,DAMAGE) - damage the object with ID

Use return 1 in the update function of an object if you do not want the turn to end!

You can also specify a collision image. Players and other stuff will collide with your object when you use a collision image. Otherwise nothing will collide with your object.

addprojectile('TABLE', [FLAGS=""])

Parameters:
'TABLE' - Lua table which holds the projectile functions
[FLAGS=""] - string containing flags for this projectile (comma separated)
Returns:
ID - projectile ID, required for createprojectile
Adds a projectile type to the game.
This command can be used several times in a single Lua script file.
A weapon does not have to have projectiles. It also can have multiple different projectiles.

A turn never ends when there are still projectiles. So you have to ensure that all projectiles are deleted properly. Use objects instead if you need to create things which can exist longer than one turn.

TABLE has to have at least 2 functions:
draw(ID) - draw the projectile with ID
update(ID) - update the projectile with ID

FLAGS is an optional parameter with a comma separated list of string flags. See addweapon for details. A projectile automatically inherits all flags from its parent weapon.

addweapon('TABLE', 'NAME', ICON, [AMOUNT=100], [FIRST USE=1], [FLAGS=""], [LOCKED=0])

Parameters:
'TABLE' - Lua table which holds the weapon functions
'NAME' - in-game name for the weapon
ICON - ID of an image which will be used as icon
[AMOUNT=100] - default amount, 0 to 99 or 100 for infinite amount
[FIRST USE=1] - first use in this round, 1-10, 1 for instant use
[FLAGS=""] - string containing flags for this weapon (comma separated)
[LOCKED=0] - is this weapon locked at the beginning (1) or not (0)?
Returns:
ID - weapon ID
Adds a weapon to the game.
Please use this command exactly ONCE per Lua weapon script file!

TABLE is the Lua table which holds the weapon draw and attack functions. For example 'cc.grenade'.
draw() - draws the weapon
attack(ATTACK) - updates the weapon and contains the attack-code. ATTACK is 1 when the attack key is pressed, else 0.

NAME is the name for your weapon which will be displayed in-game.

ICON is the ID of a previously loaded image which will be used as inventory weapon icon. The image will be scaled if necessary so it fits the inventory slot.

AMOUNT is the amount of uses as number from 0 to 99 or 100 for an infinite number of uses. You can use a weapon infinite times by default.
Note: This setting can be changed in the in-game weapon set editor!

FIRST USE is the first round in which this weapon can be used. You can use values from 1 (first round) to 10 (tenth round). The weapon is available in the first round by default.
Note: This setting can be changed in the in-game weapon set editor as well!

FLAGS is an optional string. Weapons do not have any flags by default. Flags do not influence how weapons work, but other Lua scripts can read the flags of a weapon. So these flags can be used to control the behavior of a weapon in combination with other scripts.
The following flags are used for the standard weapons:
- airborne - for all weapons dropped from the sky
- shortrange - for all close combat weapons
- ballistic - for all weapons with ballistic projectiles (excluding airborne weapons)

LOCKED is an optional parameter to lock a weapon from the beginning. Use the value 1 to lock it. In that case the weapon has to be unlocked by another weapon or game script before you can use it. Use the value 0 for an unlocked weapon (default).

addweaponinfo('INFO')

Parameters:
'INFO' - weapon info text
Adds an info text to a weapon which will be visible in the weapon selection menu when you hover with the mouse pointer over that weapon.

The info will automatically be added to the weapon which has been added latest with the addweapon command. This command has no effect if no weapon has been added before it is called.

You can call addweaponinfo multiple times to add multiple lines of weapon info text. Note that Carnage Contest will also automatically break lines in long info texts.

hard sync ai_attack()

Let the current player attack - like hitting space (AI script only)

hard sync ai_backjump()

Let the current player perform a backjump (AI script only)

hard sync ai_down()

Let the current player aim down (AI script only)

hard sync ai_jump()

Let the current player perform a jump (AI script only)

hard sync ai_left()

Move the current player left (AI script only)

hard sync ai_right()

Move the current player right (AI script only)

hard sync ai_settimer(VALUE)

Parameters:
VALUE - timer value from 1 to 10
Let the current player change the weapon timer to VALUE. This is only possible if the currently selected weapon allows it (AI script only)

hard sync ai_up()

Let the current player aim up (AI script only)

hard sync ai_weapon(WEAPON)

Parameters:
WEAPON - name of a weapon
Returns:
SUCCESS - 1 if the weapon is available, else 0
Let the current player switch to WEAPON (AI script only).

The command returns 1 if switching is currently possible and if WEAPON is available.

Attention: Do NOT execute ai_attack in the same script call. Otherwise the player will attack with the old weapon and switching will fail!

angledelta(ANGLE A, ANGLE B)

Parameters:
ANGLE A - an angle
ANGLE B - an angle
Returns:
ANGLE DELTA - difference between two angles
Returns the shortest of the two possible differences between the two angles ANGLE A and ANGLE B.
It's either a positive or a negative value depending on the rotation direction.

arealdamage(X, Y, RADIUS, DAMAGE)

Parameters:
X - x coordinate
Y - y coordinate
RADIUS - radius of damage
DAMAGE - maximum damage
Damages all players within RADIUS at the coordinate (X|Y). The maximum damage at the center is defined with DAMAGE.

blood(X, Y, [AMOUNT=5])

Parameters:
X - x coordinate
Y - y coordinate
[AMOUNT=5] - particle amount
Create some blood particles at the (X|Y) coordinate. The amount depends on AMOUNT and the gore settings.

hard sync changeturntime(TIME)

Parameters:
TIME - time in seconds
Increases (or decreases in case of negative values) the turn time by TIME in seconds.

channelplaying(CHANNEL)

Parameters:
CHANNEL - sound channel from 0 to 9
Returns:
PLAYING - 1 if sound is still playing, else 0
Returns 1 if there is a sound playing in this channel or 0 if there is no sound playing.

collision(IMAGE, X, Y, [TERRAIN=1], [PLAYERS=1], [OBJECTS=1], [IGNORE PLAYER=-1], [IGNORE OBJECT=-1])

Parameters:
IMAGE - image ID for collision check
X - x coordinate
Y - y coordinate
[TERRAIN=1] - check col. with terrain
[PLAYERS=1] - check col. with players
[OBJECTS=1] - check col. with objects
[IGNORE PLAYER=-1] - ignore this player, 0 for current, -1 for none
[IGNORE OBJECT=-1] - ignore this object, -1 for none
Returns:
COLLISION - 1 if a collision occurred, else 0
Checks if IMAGE at the (X|Y) coordinate collides.
Use TERRAIN 0 if you do NOT want to check for collision with the terrain.
Use PLAYERS 0 if you do NOT want to check for collision with players.
Use OBJECTS 0 if you do NOT want to check for collision with objects.

Use IGNORE PLAYER to ignore the collision with a certain player. You can also use the value -1 to ignore no player or 0 to ignore the current player.

Use IGNORE OBJECT to ignore the collision with a certain object. Use the value -1 to ignore no object.

You can use the commands terraincollision, playercollision and objectcollision afterwards to get details about the collision.

Moreover Carnage Contest has some built in collision images. You can use the following values for IMAGE to use them:
col1x1
col2x2
col3x3
col4x4
col5x5
col10x10
col20x20
col30x30
colplayer

(the X x X col images are boxes with these sizes in pixels. the colplayer image is the collision image for the player)

cooldown()

This command is relevant for weapons which are used in missions only. It starts the weapon cooldown which resets the weapon state and allows usage of more weapons.
The cooldown is also triggered by the command "endturn". So you do not need to care about it in most cases.
Some weapons though might need an extra call of this command to work properly in the mission mode.

The cooldown times can be specified in the mission cfg-files (where you specify the weapons for the mission). The default cooldown time is 1000 ms (1 second).

Please note that all mission commands like this one do only work in the mission mode! This command does not do anything in multiplayer modes.

hard sync createobject(TYPE, X, Y, [PARAMETER=0])

Parameters:
TYPE - object type
X - x coordinate
Y - y coordinate
[PARAMETER=0] - setup parameter
Creates a Carnage Contest game object at the (X|Y) coordinate.

Valid built-in object types are:
o_fire - a fire which hurts players
o_supply - a supply crate (for non random content: PARAMETER = return value of addweapon)
o_mine - a mine which explodes when a player is close
o_beartrap - a trap
o_medikit - a medikit which heals you
o_node - a node (typically created in the editor only for mission scripting, invisible)
o_item - creates an item (PARAMETER = return value of addweapon)

Moreover you can use IDs returned by the addobject-command. This allows you to create and use your own custom objects.

It is recommended to use the Lua table "objects" as an array to store your custom object data. The array index is the ID of the object. Carnage Contest will reset this table each time a game is started.
Example:
objects[id].myvariable

Attention: This command does NOT return the ID of the new object!
Instead it calls the Lua setup-function of the object (if it is a custom object). It also passes the new ID and the PARAMETER:
setup(ID,PARAMETER)

createprojectile(TYPE)

Parameters:
TYPE - projectile type ID (return value of addprojectile)
Returns:
ID - unique projectile ID
Creates a new instance of a projectile of the given TYPE.
This projectile will then automatically call the corresponding draw and update Lua functions.
The turn will not end until it has been deleted with freeprojectile.

It is recommended to use the Lua table "projectiles" as an array to store your projectile data. The array index is the ID of the projectile. Carnage Contest will reset this table for each turn.
Example:
projectiles[id].myvariable

cutscene()

Enable the cutscene mode which hides the user interface and disables player control.
Call this command in each frame were you want the cutscene mode to be enabled. Also use update functions to call this command, NOT draw functions!

Please note that all mission commands like this one do only work in the mission mode!

drawhud(IMAGE, X, Y, [MODE=0])

Parameters:
IMAGE - ID of an image
X - x coordinate
Y - y coordinate
[MODE=0] - rendering mode
Draws IMAGE at the (X|Y) coordinate. The position is NOT affected by scrolling.
Use this function to draw your own interface elements.

MODE can be used to switch between different rendering modes:
0 - draw always, standard
1 - only draw when all menus are closed
2 - draw as normal image, just ignore scrolling

drawimage(IMAGE, X, Y)

Parameters:
IMAGE - ID of an image
X - x coordinate
Y - y coordinate
Draws IMAGE at the (X|Y) coordinate on the map. The Position is affected by scrolling.

There are some built-in images which can be used. Just insert one of the following variables as IMAGE:
gfx_crater25
gfx_crater50
gfx_crater75
gfx_crater100
gfx_crater125
gfx_crater150
gfx_crater175
gfx_crater200
gfx_blood25
gfx_blood50
gfx_blood75
gfx_fire
gfx_flare1
gfx_flare2
gfx_flare3

drawinhand(IMAGE, [X OFFSET=0], [Y OFFSET=0], [SIZE=1.0])

Parameters:
IMAGE - ID of an image
[X OFFSET=0] - x offset value
[Y OFFSET=0] - y offset value
[SIZE=1.0] - size modification
Draws IMAGE in the hand of the current player.
The weapon is automatically rotated into the right direction. Moreover you can use the recoil command to easily create a recoil effect.
Use X OFFSET and Y OFFSET to change the position relative to the player position. Use SIZE to change the size of the image.
Moreover note that the weapon is always drawn with a vertical (Y) base offset of 3 pixels. This is important to know for spawning projectiles / drawing a crosshair.

drawline(X1, Y1, X2, Y2, [WIDTH=1])

Parameters:
X1 - start x coordinate
Y1 - start y coordinate
X2 - end x coordinate
Y2 - end y coordinate
[WIDTH=1] - line width/thickness
Draws a line from X1|Y1 to X2|Y2 with the given width (1 pixel by default).

This command is affected by setblend, setcolor and setalpha.

Attention: It is NOT affected by setscale and setrotation! It actually RESETS the scale factors to 1 and the rotation to 0!

drawrect(X, Y, WIDTH, HEIGHT)

Parameters:
X - x coordinate
Y - y coordinate
WIDTH - rectangle width
HEIGHT - rectangle height
Draws a rectangle at X|Y with the given WIDTH and HEIGHT.

This command is affected by setblend, setcolor, setalpha, setrotation and setscale.

endturn()

Ends the current turn and starts the backing time. It's not possible to use or switch the weapon after ending the turn.

firecollision(IMAGE, X, Y)

Parameters:
IMAGE - image ID for collision check
X - x coordinate
Y - y coordinate
Returns:
FIREOBJECT - ID of collided fire object if a collision occurred, else 0
Checks if IMAGE at the (X|Y) coordinate collides with fire.

The returned value is either the ID of a fire object or a 0 if no fire collides.

hard sync freeprojectile(ID)

Parameters:
ID - unique projectile ID (return value of createprojectile)
Frees the projectile with the given ID.

getframe()

Returns:
FRAME - frame of this turn
Returns the current frame of this turn. The game runs with 50 FPS. 50 frames = 1 second.

getframesleft()

Returns:
FRAMES LEFT - number of frames left until turn ends
Returns the number of frames which are left in this turn before it ends.

getgravity()

Returns:
GRAVITY - current gravity
Returns the current gravity value.

getmapheight()

Returns:
HEIGHT - map height in pixels
Returns the height of the map in pixels.

getmapwidth()

Returns:
WIDTH - map width in pixels
Returns the width of the map in pixels.

getnodex(NODE)

Parameters:
NODE - name of a node
Returns:
X - x coordinate of node
Returns the X coordinate/position of NODE.

getnodey(NODE)

Parameters:
NODE - name of a node
Returns:
Y - y coordinate of node
Returns the Y coordinate/position of NODE.

getobjecttype(OBJECT)

Parameters:
OBJECT - ID of object
Returns:
TYPE - type of object
Returns the type of OBJECT.

getobjectx(OBJECT)

Parameters:
OBJECT - ID of object
Returns:
X - x coordinate of object
Returns the X coordinate/position of OBJECT.

getobjectxspeed(OBJECT)

Parameters:
OBJECT - ID of object
Returns:
X SPEED - x speed of object
Returns the x speed of OBJECT (flying speed).

getobjecty(OBJECT)

Parameters:
OBJECT - ID of object
Returns:
Y - y coordinate of object
Returns the Y coordinate/position of PLAYER.

getobjectyspeed(OBJECT)

Parameters:
OBJECT - ID of object
Returns:
Y SPEED - y speed of object
Returns the y speed of OBJECT (flying speed).

getplayeraction(PLAYER)

Parameters:
PLAYER - ID of player, 0 for current
Returns:
ACTION - action state of a player
Returns the action state of a player.
ACTION 0 means that the player is standing on the ground or walking. Other action states mean that he is either jumping or flying through the air.

getplayeralliance(PLAYER)

Parameters:
PLAYER - ID of player, 0 for current
Returns:
ALLIANCE - an alliance from 1 to 8
Returns the ALLIANCE (= color) of PLAYER.
ALLIANCE is a value from 1 to 8. All players with the same ALLIANCE are friends, players with different ALLIANCE are enemies.

The command returns 0 if it failed to get the alliance (for example if PLAYER does not exist).

Each alliance has its own color (R,G,B):
1 - 0,255,0
2 - 255,255,0
3 - 255,0,0
4 - 80,200,255
5 - 180,60,255
6 - 255,180,0
7 - 0,180,0
8 - 50,100,255

getplayercontrol()

Returns:
CONTROL - control active (1) or not (0)
Returns if the player can be controlled (1) or not (0). Default is 1. It will only be 0 if the command playercontrol has been used to deactivate player control.

getplayerdirection(PLAYER)

Parameters:
PLAYER - ID of player, 0 for current
Returns:
DIRECTION - player direction
Returns the direction of PLAYER either as -1 for left or as 1 for right.

getplayerhealth(PLAYER)

Parameters:
PLAYER - ID of player, 0 for current
Returns:
HEALTH - health of player
Returns the health of PLAYER.
Values smaller than 1 mean that PLAYER is dead.
A value of -2147483648 means that PLAYER drowned.

getplayerrotation(PLAYER)

Parameters:
PLAYER - ID of player, 0 for current
Returns:
ANGLE - current weapon rotation angle
Returns the current weapon rotation angle of PLAYER.

getplayerstate(PLAYER, STATE)

Parameters:
PLAYER - ID of player, 0 for current
STATE - a state
Returns:
ACTIVE - 1 if state is active, else 0
Checks if a STATE of a PLAYER is active or not. Returns either 1 for an active state or 0 for an inactive state.

States are:
state_poisoned
state_confused
state_frozen
state_sleeping
state_invisible

getplayerteam(PLAYER)

Parameters:
PLAYER - ID of player, 0 for current
Returns:
TEAM - team ID of this player
Returns the TEAM of PLAYER.
The team ID can range from 0 to 7 (there's a maximum of 8 teams).

getplayerweapon()

Returns:
'TABLE' - Lua table which holds the weapon functions
Returns a string with the weapon Lua table of the currently selected weapon of the active player.

getplayerweaponswitch()

Returns:
SWITCH - allow weapon switching (1) or not (0)
Returns if the player can switch the weapon (1) or not (0). Default is 1. It will only be 0 if the command playerweaponswitch has been used to deactivate weapon switching.

getplayerx(PLAYER)

Parameters:
PLAYER - ID of player, 0 for current
Returns:
X - x coordinate of player
Returns the X coordinate/position of PLAYER.

getplayerxspeed(PLAYER)

Parameters:
PLAYER - ID of player, 0 for current
Returns:
X SPEED - x speed of player
Returns the x speed of PLAYER (flying speed).

getplayery(PLAYER)

Parameters:
PLAYER - ID of player, 0 for current
Returns:
Y - y coordinate of player
Returns the Y coordinate/position of PLAYER.

getplayeryspeed(PLAYER)

Parameters:
PLAYER - ID of player, 0 for current
Returns:
Y SPEED - y speed of player
Returns the y speed of PLAYER (flying speed).

getprojectileid()

Returns:
ID - unique projectile ID
Returns the unique ID of the current projectile.
This function only works properly when called within the draw or update Lua function of a projectile!

getprojectileinfo(TYPE, 'VALUE')

Parameters:
TYPE - projectile type ID (return value of addprojectile/getprojectiletype)
'VALUE' - Value you want to get ('table','flags','weapon')
Returns:
VALUE - The requested value of a projectile (string)
Gets information from a certain projectile type. TYPE must be the projectile type ID which is returned by the commands addprojectile and getprojectiletype.

VALUE has to be one of the following values:

'table' - returns the Lua table which holds the projectile functions (same table as specified in addprojectile)
'flags' - returns the flags as string (note: projectiles also inherit flags of their parent weapon)
'weapon' - returns the Lua table which holds the parent weapon of this projectile

An empty string is returned if the projectile type does not exist.

getprojectiletype(ID)

Parameters:
ID - unique projectile ID (= return value of createprojectile)
Returns:
TYPE - projectile type ID (= return value of addprojectile)
Returns the TYPE of the projectile with the given ID.

Returns 0 if there is no projectile with that ID.

getround()

Returns:
ROUND - current round
Returns the current round. A game starts with round 1. The round is increased when every living character in the game had at least one turn.
Note that some characters may have multiple turns in one round. This happens when one team has more players than another.

getscore([BEST=0])

Parameters:
[BEST=0] - get the best score (1) or the current score (0)
Returns:
SCORE - the current/best high score
Gets the current or the best high score of the current mission. High scores are always integers (no floats).

getterraincolor(X, Y, [FORMAT=0])

Parameters:
X - x coordinate
Y - y coordinate
[FORMAT=0] - result format (0=a,r,g,b integers, 1=argb in one integer)
Returns:
4 Integers (each 0-255): Alpha,Red,Green,Blue
OR
1 Integer containing all values
Gets the color of the terrain at a certain coordinate.

The result can be returned as 4 integers or as a one integer which contains all 4 values (depending on FORMAT).
Use the one integer format if you want to use the color with commands like terrainrect or terraincircle.

ATTENTION: This color value is not necessarily the same on each client (due to random effects like blood and craters)! Do not use it for important conditions. Use it for visual effects only!

getturn([MODE=0])

Parameters:
[MODE=0] - define the turn data you want to get (0=absolute turn number, 1=current turn of round, 2=turns in round)
Returns:
TURN - current turn (or -1 when being in "manual positioning"-mode)
With MODE 0 (default) it returns the current turn. A game starts with turn 1. The turn is increased when a player finishes a turn.

There is one special case for this command:
It will always return -1 when being in the "manual positioning"-mode (this mode will be active when manual player positioning is activated and players need to be placed).

There are also 2 other modes:

In mode 1 you will get the current turn of the current round.

In mode 2 you will get the total number of turns of the current round.

getwatery()

Returns:
Y - y-coordinate where the water starts
Returns the height (y-coordinate) of the water.

The initial water y-coordinate equals getmapheight-10. This is also the highest possible value for the water (=lowest possible water level).

getweaponcount('TABLE', TEAM)

Parameters:
'TABLE' - Lua table which holds the weapon functions
TEAM - Team ID
Returns:
COUNT - The weapon count for the specified team
Returns the count of a weapon for TEAM.

getweaponinfo('TABLE', 'VALUE')

Parameters:
'TABLE' - Lua table which holds the weapon functions
'VALUE' - Value you want to get ('name','flags','image','x','y','group','firstuse')
Returns:
VALUE - The requested value of a weapon (can be an integer or string)
Gets information from a certain weapon. TABLE must be the table of an existing weapon ('cc.axe' for example).

VALUE has to be one of the following values:

'id' - returns the internal weapon ID (same as the value returned by addweapon)
'name' - returns the name of the weapon as string
'flags' - returns the flags as string
'image' - returns the image icon id as integer
'x' - returns the X position in the weaponset as integer, ranging from 0 to 13
'y' - returns the Y position in the weaponset as integer, ranging from 0 to 8
'group' - returns the weapon menu group as integer, ranging from 0 to 2
'firstuse' - returns the round were you are able to use this weapon the first time as integer

getweaponlist()

Returns:
WEAPON TABLE - A Lua table containing weapon table names
Returns a table/array which contains the table names of all loaded weapons. The index starts at 1!

You can use the table names with the command getweaponinfo to get more weapon details.

Sample:
w=getweaponlist()
for i=1,#w do
print(w[i])
end

getweaponlock('TABLE', TEAM)

Parameters:
'TABLE' - Lua table which holds the weapon functions
TEAM - Team ID
Returns:
LOCKED - boolean, true if weapon is locked, else false
Returns the lock-state of a weapon for TEAM.

true if the weapon is locked.
false if the weapon is not locked.

Locked weapons can not be selected by the player.

getwind()

Returns:
WIND - current wind speed/direction
Returns the current wind speed and direction.
Positive values indicate that the wind blows rightwards. Negative values stand for wind blowing leftwards.

-0.1 = maximum wind to the left
0.0 = calm (no wind)
+0.1 = maximum wind to the right

hudammobar(AMMO, TOTAL)

Parameters:
AMMO - left ammo value
TOTAL - total ammo value
Draws a 'ammo bar' HUD element which shows how many ammo is left.

hudchargebar(CHARGE, TOTAL)

Parameters:
CHARGE - current charge value
TOTAL - maximum charge value
Draws a 'charge bar' HUD element which shows the charge power of your weapon.
CHARGE has to be <= TOTAL. The bar is full as soon as CHARGE equals TOTAL.

hudcrosshair([X OFFSET=0], [Y OFFSET=0])

Parameters:
[X OFFSET=0] - crosshair x offset
[Y OFFSET=0] - crosshair y offset
Draws a crosshair for the current player. Use X OFFSET and Y OFFSET to adjust the crosshair position.

hudinfo('TEXT', [CURRENT ONLY=1], [RED=255], [GREEN=255], [BLUE=255])

Parameters:
'TEXT' - info text
[CURRENT ONLY=1] - show for current player only?
[RED=255] - color red (0 to 255)
[GREEN=255] - color green (0 to 255)
[BLUE=255] - color blue (0 to 255)
Displays TEXT at the screen.
By default this message is only displayed for the current player. All other players don't see it. Use 0 for CURRENT ONLY if you want everyone to see the message.
The color of TEXT is white by default. You can use the RED, GREEN and BLUE parameters to change this color.

Attention: The weapon selection menu has to be closed to see TEXT!

hudmapborder([MODE=0] , [OFFSET=0])

Parameters:
[MODE=0]
[OFFSET=0]
Draws a red border around the map (the same border is also displayed in certain positioning modes)

You can also use a yellow border which is only displayed at the top of the map by setting the MODE parameter to 1! In this case you can also specify a drawing OFFSET from the actual top map border (positive values: lower than actual border, negative values: higher).

hudpositioning(MODE, [IMAGE=0], [RANGE=100], [TERRAIN=1], [PLAYERS=1], [OBJECTS=1])

Parameters:
MODE - positioning mode
[IMAGE=0] - optional ID of image which will be positioned
[RANGE=100] - positioning range around the player
[TERRAIN=1] - check col. with terrain
[PLAYERS=1] - check col. with players
[OBJECTS=1] - check col. with objects
Lets the player define a position by left-clicking the map. A valid click will then set some Lua variables.
There are different modes availabe:

pos_normal: free positioning, RANGE doesn't matter, an X marks the position

pos_invisible: same as pos_normal but without the X

pos_build: positioning within RANGE around the player, also displays the borders of the map + positions close to enemies may be blocked depending on host settings

pos_build_noblock: same as pos_build but positions close to enemies are not blocked

pos_range: positioning within RANGE around the player, doesn't show borders of the map

pos_drop: same as pos_invisible but with a yellow border which marks the top of the map. RANGE is 0 by default when using this mode. It can be used to specify a vertical position offset for the yellow border.

This command affects 3 global weapon variables. As soon as the player clicks a valid position it will set:
weapon_position = 1
weapon_x = clicked X coordinate
weapon_y = clicked Y coordinate

Use IMAGE to define an image which will check collisions at the clicked position. The position will only be accepted when this image does not collide with terrain/players/objects (depending on TERRAIN, PLAYERS and OBJECTS). The image will also be drawn at the players mouse position when using pos_build as MODE. Just use 0 for IMAGE if you do not want to use an image.

hudtext('TEXT', X, Y, [RED=255], [GREEN=255], [BLUE=255], [ALIGN=0])

Parameters:
'TEXT' - info text
X - x coordinate
Y - y coordinate
[RED=255] - color red (0 to 255)
[GREEN=255] - color green (0 to 255)
[BLUE=255] - color blue (0 to 255)
[ALIGN=0] - text alignment (0=left, 1=center, 2=right)
Draws a text on the HUD (covers all regular graphics on the screen). All players can see this text. Use the commands screenwidth and screenheight if you want to show the text at the right side/bottom of the screen.

Note: This command can be used multiple times to draw multiple different texts at different spots (not like hudinfo which will always only display one text at a time)

hudtimer(INITIAL, [MIN=1], [MAX=5])

Parameters:
INITIAL - initial timer value
[MIN=1] - minimum timer value (1-10)
[MAX=5] - maximum timer value (1-10)
Draws a 'timer bar' HUD element which shows the current weapon timer setting. The setting can be changed in-game with the numeric keys (1,2,3,4,5,6,7,8,9,0[=10]) on the keyboard and will be saved in the global Lua variable weapon_timer.
By default the timer ranges from 1 (minimum) to 5 (maximum).
It will be automatically set to the initial value on each turn/weapon change.

imagecollision(IMAGE1, X1, Y1, IMAGE2, X2, Y2)

Parameters:
IMAGE1 - image ID for collision check
X1 - x coordinate of IMAGE1
Y1 - y coordinate of IMAGE1
IMAGE2 - image ID for collision check
X2 - x coordinate of IMAGE2
Y2 - y coordinate of IMAGE2
Returns:
COLLISION - 1 if a collision occurred, else 0
Checks if IMAGE1 at (X1|Y1) collides with IMAGE2 at (X2|Y2). It returns 1 if a collision occurred, otherwise 0.

Carnage Contest has some built in collision images. You can use the following values for IMAGE1 and IMAGE2 to use them:
col1x1
col2x2
col3x3
col4x4
col5x5
col10x10
col20x20
col30x30
colplayer

(the X x X col images are boxes with these sizes in pixels. the colplayer image is the collision image for the player)

inmission()

Returns:
MISSION - 1 if in a mission, else 0
Returns 1 if player is currently in a mission (playing single player missions) and otherwise 0. Can be useful for certain weapons which need to have another behavior in missions.

keydown(KEY)

Parameters:
KEY - a key ID
Returns:
DOWN - 1 if key is pressed down, else 0
Returns 1 if KEY is currently pressed down, else 0.

Valid values for KEY are:
key_up
key_down
key_left
key_right
key_jump
key_backjump
key_attack

keyhit(KEY)

Parameters:
KEY - a key ID
Returns:
HIT - 1 if key has just been hit, else 0
Returns 1 if KEY has just been hit (was not pressed down before but is now), else 0.

Valid values for KEY are:
key_up
key_down
key_left
key_right
key_jump
key_backjump
key_attack

keyrelease(KEY)

Parameters:
KEY - a key ID
Returns:
RELEASED - 1 if key has just been released, else 0
Returns 1 if KEY has just been released (was pressed down before but isn't anymore now), else 0.

Valid values for KEY are:
key_up
key_down
key_left
key_right
key_jump
key_backjump
key_attack

loadgfx('PATH')

Parameters:
'PATH' - path to an image file (bmp,png,jpg) relative to the 'gfx'-folder of Carnage Contest
Returns:
ID - ID for the image which can be used with other commands
Loads an image file relative to the 'gfx'-folder of Carnage Contest and returns an ID.

Note: You can use the variable $MISSION in your PATH to load files relative to the mission folder of the current mission. Always use it at the beginning of the path!
Example: $MISSION/sample.bmp will load sample.bmp in the folder of the current mission.

Attention: Always use this function at the beginning of your script. NEVER use it in draw/update functions!

Attention: You can only load bmp, png or jpg/jpeg files. Other image formats are not supported.

loadsfx('PATH')

Parameters:
'PATH' - path to a sound file (wav,ogg) relative to the 'sfx'-folder of Carnage Contest
Returns:
ID - ID for the sound which can be used with other commands
Loads a sound file relative to the 'sfx'-folder of Carnage Contest and returns an ID.

Note: You can use the variable $MISSION in your PATH to load files relative to the mission folder of the current mission. Always use it at the beginning of the path!
Example: $MISSION/sample.wav will load sample.wav in the folder of the current mission.

Attention: Always use this function at the beginning of your script. NEVER use it in draw/update functions!

Attention: You can only load wav and ogg files. Other sound formats are not supported.

nodetable()

Returns:
NODE TABLE - a table containing node names
Returns a table/array which contains the names of all nodes in the game. Nodes can be placed with the map editor and are invisible in-game. They are commonly used for missions and they allow mission creators to easily specify positions on maps right in the editor.

You do not have to specify a name for nodes. Nodes without a name will automatically get a name consisting of their X and Y position, separated with "|".
Example: A node with X position 2 and Y position 5 and without a name would automatically get the name "2|5"

NOTE: Nodes which have been created with the command createobject will NOT be listed by this command! Those nodes don't have a name either. So this command only works for nodes which have been set in the editor.

objectcollision()

Returns:
OBJECT - id of a object which collided, or 0
Returns the ID of an object which collided. It returns 0 if no object collided. This command has to be used after the collision command.

hard sync objectdamage(OBJECT, DAMAGE)

Parameters:
OBJECT - ID of an object
DAMAGE - damage value
Calls the damage function of OBJECT with the same parameter values.

This command is for custom objects only. It has no effect on built-in objects.

hard sync objectposition(OBJECT, X, Y)

Parameters:
OBJECT - ID of object
X - x coordinate
Y - y coordinate
Sets the position of an object to the (X|Y) coordinate.

hard sync objectpush(OBJECT, PUSH X, PUSH Y, [ABSOLUTE=0])

Parameters:
OBJECT - ID of object
PUSH X - x push value
PUSH Y - y push value
[ABSOLUTE=0] - set absolute (1) or add to current values (0)
Pushs a certain object with the speeds PUSH X and PUSH Y.
Use ABSOLUTE 1 to set the values. Use ABSOLUTE 0 to add the values to the current speed values.

objecttable([TYPE=0])

Parameters:
[TYPE=0] - list objects of this type only (0 for all types)
Returns:
OBJECT TABLE - a table containing object IDs
Returns a table/array which contains the IDs of objects in the game.

By default all object types are included. Use another value for TYPE to get a table which only contains objects of a certain type.

outofscreenarrow(X, Y)

Parameters:
X - x coordinate
Y - y coordinate
Checks if the (X|Y) coordinate is outside of the screen (the currently displayed area). If this is the case it will draw an arrow at the border of the screen which will point at the (X|Y) coordinate.

particle(TYPE, X, Y)

Parameters:
TYPE - particle type
X - x coordinate
Y - y coordinate
Creates a new particle at the (X|Y) coordinate.
The particle can be modified with other particle commands right after creation.

Possible TYPE values are:
p_smoke
p_lightpuff
p_fragment
p_blood
p_bigblood
p_muzzle
p_bubble
p_waterray
p_waterhit
p_bodypart
p_ring
p_firefragment
p_explosion
p_dust
p_flare
p_spark
p_bullet
p_dirtfall
p_lightray
p_explosionring
p_scaleflare
p_feather
p_blooddrop
p_meat
p_splatterbeam

particlealpha(ALPHA)

Parameters:
ALPHA - alpha from 0.0 to 1.0
Changes the alpha value (transparency) of the last particle created with the particle command.

particlecolor(RED, GREEN, BLUE)

Parameters:
RED - red value from 0 to 255
GREEN - green value from 0 to 255
BLUE - blue value from 0 to 255
Changes the color of the last particle created with the particle command.

particlefadealpha(FADE ALPHA)

Parameters:
FADE ALPHA - a (positive) fade value
Changes the alpha fade value of the last particle created with the particle command.
The alpha value of the particle will be decreased by this value each frame in order to create a fadeout effect.

particlerotation(ROTATION)

Parameters:
ROTATION - rotation angel
Changes the rotation of the last particle created with the particle command.

particlesize(SIZE X, SIZE Y)

Parameters:
SIZE X - x size factor
SIZE Y - y size factor
Changes the size of the last particle created with the particle command.

Attention: The original size scale factor of many particles is NOT 1.0! You have to try around a bit to find the right size.

particlespeed(SPEED X, SPEED Y)

Parameters:
SPEED X - x speed
SPEED Y - y speed
Changes the speed of the last particle created with the particle command.

playercollision()

Returns:
PLAYER - id of a player who collided, or 0
Returns the ID of a player who collided. It returns 0 if no player collided. This command has to be used after the collision command.

playercontrol(CONTROL)

Parameters:
CONTROL - control active (1) or not (0)
(De-)activates the player control. The player will only be controlled if playercontrol is set to 1. The game sets playercontrol to 1 automatically on the start of each turn.
Disable playercontrol if you want to create weapons which can be controlled after launching.

playercurrent()

Returns:
PLAYER - ID of player who is currently controlled
Returns the ID of the player who is currently controlled.

hard sync playerdamage(PLAYER, DAMAGE)

Parameters:
PLAYER - ID of player, 0 for current
DAMAGE - damage value
Decreases the health of PLAYER by DAMAGE.

playerforceframe(PLAYER, FRAME)

Parameters:
PLAYER - ID of player, 0 for current
FRAME - player frame (0-11)
Forces the game to render the player with a certain frame, no matter if he is falling/walking/standing/...

Most important frames are:
0 - standing (with arms)
1 - walking frame 1 / standing (no arms)
2 - walking frame 2 (no arms)
3 - jumping (with arms)
4 - falling (with arms)

Note: The frame will be forced for the next render only. You have to call this command continuously to keep that frame. Therefore you should call this command in a draw-function!

hard sync playerheal(PLAYER, HEAL)

Parameters:
PLAYER - ID of player, 0 for current
HEAL - heal value
Increases the health of PLAYER by HEAL.

playerposition(PLAYER, X, Y)

Parameters:
PLAYER - ID of player, 0 for current
X - x coordinate
Y - y coordinate
Sets the position of a player to the (X|Y) coordinate.

playerpush(PLAYER, PUSH X, PUSH Y, [ABSOLUTE=0], [PUSH OTHERS=1])

Parameters:
PLAYER - ID of player, 0 for current
PUSH X - x push value
PUSH Y - y push value
[ABSOLUTE=0] - set absolute (1) or add to current values (0)
[PUSH OTHERS=1] - push players on contact (1) or not (0)
Pushs a certain player with the speeds PUSH X and PUSH Y.
Use ABSOLUTE 1 to set the values. Use ABSOLUTE 0 to add the values to the current speed values.
Use PUSH OTHERS to control if this push is able to move other players on contact or not.

For comparison:
A normal jump equals a push with X=3, Y=-3.
A back jump equals a push with X=1,Y=-5.
(the X speed depends on the player direction of course and can also be -3 or -1 for that reason)

hard sync playerstate(PLAYER, STATE, SET)

Parameters:
PLAYER - ID of player, 0 for current
STATE - a state
SET - enable(1) or disable(0)
Enables (SET=1) or disables (SET=0) a STATE of PLAYER.

States are:
state_poisoned
state_confused
state_frozen
state_sleeping
state_invisible

hard sync playerswitch(PLAYER)

Parameters:
PLAYER - ID of player
Passes the control to PLAYER.
PLAYER has to be a player who is in the same team as the current player and who is still living.

playertable([MODE=0], [INC DEAD=1])

Parameters:
[MODE=0] - list mode
[INC DEAD=1] - include dead players (1) or not (0)?
Returns:
PLAYER TABLE - a table containing player IDs
Returns a table/array which contains the IDs of players in the game. The index starts at 1!

For MODE you can use these values:
0 - list of all players
1 - list of team-members of current player
2 - list of allied players of current player (same and other teams)
3 - list of enemies of current player

Note that all modes - besides mode 0 - exclude the current player (this means that the current player will not appear in the list).

By default all dead players are included. You can exclude them by setting INC DEAD to 0.

playerweaponswitch(SWITCH)

Parameters:
SWITCH - allow weapon switching (1) or not (0)
(De-)activates the possibility to switch the weapon. Weapon switching is only possible if this is set to 1. The game sets playerweaponswitch to 1 automatically on the start of each turn.
This command can be very useful for game modes or missions!

playsound(SOUND, [CHANNEL=-1], [VOLUME=1.0])

Parameters:
SOUND - sound ID
[CHANNEL=-1] - channel for sound control, 0 to 9, or -1 for no channel
[VOLUME=1.0] - sound volume from 0.0 to 1.0
Plays a sound.
You can also use one of 10 channels (0-9) which allows you to check when the playback is finished and to stop the sound. Use -1 as CHANNEL if you do not want to use a channel.

Use the VOLUME parameter to change the volume of the sound. You can use values from 0.0 (silent) to 1.0 (loud).

Moreover Carnage Contest has some built in sounds. You can insert the following values for SOUND to use them:
sfx_explosion1, ..., sfx_explosion7
sfx_hitwater1, ..., sfx_hitwater5
sfx_splatter1, ..., sfx_splatter5
sfx_ricochet1
sfx_waterstep
sfx_steam
sfx_turn_next
sfx_turn_you
sfx_turn_roundgong

print('TEXT')

Parameters:
'TEXT' - a text you want to print
Print a text in the console. The console can be opened with tab.

projectileid()

Returns:
ID - unique projectile ID
Returns the unique ID of the current projectile.
This function only works properly when called within the draw or update Lua function of a projectile!

ATTENTION: This command is obsolete. It's recommended to use "getprojectileid" instead.

quake([POWER=15])

Parameters:
[POWER=15] - quake power from 0 to 30
Creates a quake effect. POWER controls the quake strength and duration. Use POWER 0 to stop the quake effect instantly.

Attention: This is just a visual effect. It does not move players or objects.

random(V1, [V2])

Parameters:
V1 - minimum (or maximum) value
[V2] - maximum value
Returns:
RANDOM FLOAT - a random floating point value in the specified range
Returns a cross-platform synchronous random number.

Don't forget to use randomseed with synchronous values first!

Always use this command if you need synchronous random values. The built in random function of Lua (math.random) does NOT deliver the same random values on different platforms and is therefore not recommended.

There are 3 ways to call this function:

- no parameters: a random float between 0.0 and 1.0
- one parameters: a random float between 1.0 and V1
- two parameters: a random float between V1 and V2

(All mentioned values are INCLUSIVE. The "no paramters" case can also deliver 1.0 and 0.0 for instance!)

randomseed(SEED)

Parameters:
SEED - a number to setup the random number generator
Sets up the cross-platform synchronous random number generator. Use the random command afterwards.

IMPORTANT: Use synchronous values to synchronize the random generator on all systems. Good values are:
getframe()*CONSTANT
getround()*CONSTANT
(with CONSTANT beeing a constant value like -123 or 652 or 3773)

All random-command calls will generate the same random numbers on all platforms afterwards.

Do not use other commands in between because they may confuse the random number sequence.

You can still use math.random and math.randomseed which are the native random functions of Lua - but these functions will deliver different values on different platforms. So you should only use them for unimportant stuff like particle effects.

recoil(STRENGTH)

Parameters:
STRENGTH - recoil strength in pixels
Recoil effect which pushes back the weapon by STRENGTH pixels. This command only takes effect when the weapon is drawn with the command drawinhand.

hard sync removeobject(OBJECT)

Parameters:
OBJECT - ID of object
Removes OBJECT.

screenheight()

Returns:
HEIGHT - height of the screen in pixels
Returns the height of the screen (in-game screen resolution) in pixels.

screenwidth()

Returns:
WIDTH - width of the screen in pixels
Returns the width of the screen (in-game screen resolution) in pixels.

scroll(X, Y)

Parameters:
X - x coordinate
Y - y coordinate
Scroll the camera to the (X|Y)-coordinate on the map.

setalpha(ALPHA)

Parameters:
ALPHA - 0.0 to 1.0 alpha value
Sets the alpha value. Affects drawimage, drawhud and drawline.
The alpha value defines the transparency.
1.0 = 100% visible
0.0 = 0% visible (=invisible)

setbgcolor(RED, GREEN, BLUE, [ALPHA=1.0], [FADE=0.1])

Parameters:
RED - red value (0 to 255)
GREEN - green value (0 to 255)
BLUE - blue value (0 to 255)
[ALPHA=1.0] - 0.0 to 1.0 alpha mixing value
[FADE=0.1] - 0.001 to 1.0 fade-out speed
Sets the color for the background. The color consists of red, green and blue values.
ALPHA defines how much these colors will be mixed with the original/default background color. It ranges from 0.0 to 1.0.

Examples:
0.0 = 100% original background color
0.5 = 50% original / 50% custom colors
1.0 = 100% custom colors

The command should be called every frame you want the background to have another color. Call it with ALPHA 0.0 or FADE 1.0 to instantly remove the custom background color.

If you don't call it anymore the background will fade back to the original color with the speed of FADE (ALPHA will be decremented by FADE each frame until it reaches zero).

setblend(BLENDMODE)

Parameters:
BLENDMODE - a blend mode you want to use
Changes the blend mode. Affects drawimage, drawhud and drawline.
Possible blendmodes are:
blend_mask - don't draw magenta pixels
blend_solid - draw complete image
blend_alpha - draw transparent
blend_light - draw bright
blend_shade - draw dark

setcolor(RED, GREEN, BLUE)

Parameters:
RED - red value (0 to 255)
GREEN - green value (0 to 255)
BLUE - blue value (0 to 255)
Set the color for an image. The color consists of red, green and blue values which are mixed. Affects drawimage, drawhud and drawline.
Use 255 for RED, GREEN and BLUE (=white) in order to draw images with their original color.

sethandle(IMAGE, X, Y)

Parameters:
IMAGE - ID of an image
X - x handle coordinate
Y - y handle coordinate
Sets the handle (origin for drawing) of IMAGE to the coordinate (X|Y).

Attention: It will lead to problems when you load the same image several times and set different handles for it right after loading. In this case you have to set the handles always before drawing in order to avoid problems.

setmidhandle(IMAGE)

Parameters:
IMAGE - ID of an image
Sets the handle (origin for drawing) of IMAGE to its center.

Attention: It will lead to problems when you load the same image several times and set different handles for it right after loading. In this case you have to set the handles always before drawing in order to avoid problems.

setrotation(ROTATION)

Parameters:
ROTATION - rotation angle (360 degrees)
Changes the rotation for images. Affects drawimage and drawhud.
ROTATION 0 draws images without rotation.

setscale(X SCALE, Y SCALE)

Parameters:
X SCALE - x scale factor
Y SCALE - y scale factor
Changes the scale factor for images. Affects drawimage and drawhud.
Use 1 for X SCALE and Y SCALE in order to draw images at their original size. Use negative values to mirror images.

setscore(SCORE, [SAVE=0])

Parameters:
SCORE - the high score
[SAVE=0] - force to save this as new best score (1) or not (0)
Sets the new high score. You can use SAVE to force the game to save that score as new best high score - no matter if the current best score is actually lower or higher!

Note: The high score will automatically be saved as best high score when the mission ends and if it is better then the current best high-score.

hard sync setweaponcount('TABLE', TEAM, COUNT)

Parameters:
'TABLE' - Lua table which holds the weapon functions
TEAM - Team ID
COUNT - The new weapon count (0-99 or 100 for infinite count)
Sets the count of a weapon for TEAM. Use COUNT 100 for an infinite weapon count.

hard sync setweaponlock('TABLE', TEAM, LOCKED)

Parameters:
'TABLE' - Lua table which holds the weapon functions
TEAM - Team ID
LOCKED - The lock state, 1 (or true) to lock, 0 (or false) to unlock
Sets the lock-state of a weapon for TEAM.

1 (true) to lock a weapon.
0 (false) to unlock a weapon.

Locked weapons can not be selected by the player.

stopchannel(CHANNEL)

Parameters:
CHANNEL - sound channel from 0 to 9
Stops the playback of a sound in a channel.

hard sync terrainalphaimage(IMAGE, X, Y, [ALPHA=1.0], [RED=-1], [GREEN=-1], [BLUE=-1], [ROTATION=0])

Parameters:
IMAGE - ID of an image
X - x coordinate
Y - y coordinate
[ALPHA=1.0] - alpha value
[RED=-1] - use another red value
[GREEN=-1] - use another green value
[BLUE=-1] - use another blue value
[ROTATION=0] - rotation angle?
Mixes IMAGE with the terrain at the (X|Y) coordinate. IMAGE then becomes part of the terrain.
The image will only by drawn on pixels which are terrain and the ALPHA value will be used.
Use the RED, GREEN and BLUE parameters to influence the color. -1 means that the original colors will be used. Values between 0 and 255 mean that these colors will be used instead.
Change ROTATION to draw the image rotated. Attention: Rotating the image is slow and reduces the quality!

hard sync terrainbackimage(IMAGE, X, Y, [RED=0], [GREEN=0], [BLUE=0], [ROTATION=0])

Parameters:
IMAGE - ID of an image
X - x coordinate
Y - y coordinate
[RED=0] - modify red value
[GREEN=0] - modify green value
[BLUE=0] - modify blue value
[ROTATION=0] - rotation angle?
Draws IMAGE on the terrain at the (X|Y) coordinate. IMAGE then becomes part of the terrain.
The image will only by drawn on pixels which are sky (looks like it is drawn in the background).
Use the RED, GREEN and BLUE parameters to influence the color. These values will be added to the image pixel colors. 0 means no modification.
Change ROTATION to draw the image rotated. Attention: Rotating the image is slow and reduces the quality!

hard sync terraincircle(X, Y, RADIUS, COLOR)

Parameters:
X - x coordinate
Y - y coordinate
RADIUS - radius of the circle
COLOR - color (0xAARRGGBB)
Draws a circle. The (X|Y) coordinate is the center of the circle.

COLOR is a hexadecimal number with
0xAARRGGBB = alpha (sky/terrain)
0xAARRGGBB = red
0xAARRGGBB = green
0xAARRGGBB = blue

You can use values from 00 (0) to FF (255). For the alpha value please only use 00 (sky) or FF (terrain).

Commonly COLOR 0x00000000 is used to erase the the terrain.

terraincollision()

Returns:
COLLISION - 1 if a collision with terrain occured, else 0
Returns 1 if a collision with the terrain occured, else 0. This command has to be used after the collision command.

hard sync terrainexplosion(X, Y, RADIUS, [EFFECT=0])

Parameters:
X - x coordinate
Y - y coordinate
RADIUS - explosion radius
[EFFECT=0] - effect type
Destroys the terrain at the (X|Y) coordinate and creates some effects and sounds.

Available effects are:
0: gun impact
1: explosion
2: digging
3: explosion fx without terrain destruction (FX equals 1)

hard sync terrainimage(IMAGE, X, Y, [IGNORE MASK=0], [ROTATION=0])

Parameters:
IMAGE - ID of an image
X - x coordinate
Y - y coordinate
[IGNORE MASK=0] - ignore mask?
[ROTATION=0] - rotation angle
Draws IMAGE into the terrain at the (X|Y) coordinate. IMAGE then becomes part of the terrain.
Use IGNORE MASK 1 if you want to draw the full image including the masked areas / alpha channel.
Change ROTATION to draw the image rotated. Attention: Rotating the image is slow and reduces the quality!

terrainmodification()

Returns:
MODIFICATION - 1 if a terrain modification occurred recently, else 0
Returns a 1 if the terrain shape has been modified recently, otherwise 0.

hard sync terrainrect(X, Y, WIDTH, HEIGHT, COLOR)

Parameters:
X - x coordinate
Y - y coordinate
WIDTH - width
HEIGHT - height
COLOR - color (0xAARRGGBB)
Draws an rectangle. The (X|Y) coordinate is the upper left corner of the rectangle.

COLOR is a hexadecimal number with
0xAARRGGBB = alpha (sky/terrain)
0xAARRGGBB = red
0xAARRGGBB = green
0xAARRGGBB = blue

You can use values from 00 (0) to FF (255). For the alpha value please only use 00 (sky) or FF (terrain).

Commonly COLOR 0x00000000 is used to erase the the terrain.

useweapon([ALLOW MORE=0])

Parameters:
[ALLOW MORE=0] - allow to use more? 0/1/2
Uses the current weapon and decreases its amount.
ALLOW MORE defines if you are allowed to use other weapons afterwards (1/2) or not (0).

ALLOW MORE 2 also allows you to decrease the amount of a weapon several times without the need to select it again from the weapon menu.

hard sync watery(Y)

Parameters:
Y - y-coordinate where the water starts
Changes the height (y-coordinate) of the water.

Attention: You have to DECREASE the value to RAISE the water level. INCREASE the value to LOWER the water level!


The initial water y-coordinate equals getmapheight-10. This is also the highest possible value for the water (=lowest possible water level).

win()

End the current mission-map and load/unlock the next map of that mission (if there is any).

Please note that all mission commands like this one do only work in the mission mode!

hard sync wind(WIND)

Parameters:
WIND - wind speed and direction
Sets the wind speed and direction. WIND has to be a floating point value between -0.1 and 0.1

-0.1 = maximum wind to the left
0.0 = calm (no wind)
+0.1 = maximum wind to the right