Commands: all

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>

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)

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.

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.

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).

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.

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

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

Let the current player aim down (AI script only)

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

Move the current player left (AI script only)

Move the current player right (AI script only)

Let the current player change the weapon timer to VALUE. This is only possible if the currently selected weapon allows it (AI script only)

Let the current player aim up (AI script only)

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!

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.

Damages all players within RADIUS at the coordinate (X|Y). The maximum damage at the center is defined with DAMAGE.

Create some blood particles at the (X|Y) coordinate. The amount depends on AMOUNT and the gore settings.

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

Returns 1 if there is a sound playing in this channel or 0 if there is no sound playing.

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)

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.

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)

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

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!

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

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

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.

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!

Draws a rectangle at X|Y with the given WIDTH and HEIGHT.

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

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

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.

Frees the projectile with the given ID.

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

Returns the number of frames which are left in this turn before it ends.

Returns the current gravity value.

Returns the height of the map in pixels.

Returns the width of the map in pixels.

Returns the X coordinate/position of NODE.

Returns the Y coordinate/position of NODE.

Returns the type of OBJECT.

Returns the X coordinate/position of OBJECT.

Returns the x speed of OBJECT (flying speed).

Returns the Y coordinate/position of PLAYER.

Returns the y speed of OBJECT (flying speed).

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.

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):

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.

Returns the direction of PLAYER either as -1 for left or as 1 for right.

Returns the health of PLAYER.
Values smaller than 1 mean that PLAYER is dead.
A value of -2147483648 means that PLAYER drowned.

Returns the current weapon rotation angle of PLAYER.

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

Returns the TEAM of PLAYER.
The team ID can range from 0 to 7 (there's a maximum of 8 teams).

Returns a string with the weapon Lua table of the currently selected weapon of the active player.

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.

Returns the X coordinate/position of PLAYER.

Returns the x speed of PLAYER (flying speed).

Returns the Y coordinate/position of PLAYER.

Returns the y speed of PLAYER (flying speed).

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!

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.

Returns the TYPE of the projectile with the given ID.

Returns 0 if there is no projectile with that ID.

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.

Gets the current or the best high score of the current mission. High scores are always integers (no floats).

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!

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.

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).

Returns the count of a weapon for TEAM.

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

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

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.

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

Draws a 'ammo bar' HUD element which shows how many ammo is left.

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.

Draws a crosshair for the current player. Use X OFFSET and Y OFFSET to adjust the crosshair position.

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!

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).

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.

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)

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.

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)

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.

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

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

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

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.

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.

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.

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.

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.

Sets the position of an object to the (X|Y) coordinate.

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.

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.

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.

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

Changes the alpha value (transparency) of the last particle created with the particle command.

Changes the color of the last particle created with the particle command.

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.

Changes the rotation of the last particle created with the particle command.

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.

Changes the speed of the last particle created with the particle command.

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.

(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.

Returns the ID of the player who is currently controlled.

Decreases the health of PLAYER by DAMAGE.

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!

Increases the health of PLAYER by HEAL.

Sets the position of a player to the (X|Y) coordinate.

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)

Enables (SET=1) or disables (SET=0) a STATE of PLAYER.

States are:
state_poisoned
state_confused
state_frozen
state_sleeping
state_invisible

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.

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.

(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!

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 a text in the console. The console can be opened with tab.

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.

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.

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!)

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 effect which pushes back the weapon by STRENGTH pixels. This command only takes effect when the weapon is drawn with the command drawinhand.

Removes OBJECT.

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

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

Scroll the camera to the (X|Y)-coordinate on the map.

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

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).

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

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.

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.

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.

Changes the rotation for images. Affects drawimage and drawhud.
ROTATION 0 draws images without rotation.

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.

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.

Sets the count of a weapon for TEAM. Use COUNT 100 for an infinite weapon count.

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.

Stops the playback of a sound in a channel.

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!

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!

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.

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

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)

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!

Returns a 1 if the terrain shape has been modified recently, otherwise 0.

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.

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.

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).

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!

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