Commands: all

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

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!

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)

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 with random item
o_mine - a mine which explodes when a player is close
o_beartrap - a trap
o_medikit - a medikit which heals you

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

Draws IMAGE at the (X|Y) coordinate. The position is NOT affected by scrolling.
Use this function to draw your own interface elements.

Draws IMAGE at the (X|Y) coordinate on the map. The Position is affected by scrolling.

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!

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

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

Returns the TEAM of PLAYER.

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 current round. A game starts with round 1. The round is increased when every living character in the game had one turn.

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

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

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

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

Returns 1 if KEY is pressed, 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.

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.

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

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.

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

States are:
state_poisoned
state_confused
state_frozen
state_sleeping

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.

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.

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.

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!

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.

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.

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.

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

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) or not (0).

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

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