Commands: load

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.

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.