Home Screens Help F.A.Q. Armory Download

Tutorials

Reference

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

Weapon Scripting I

Requirements

This is a guide which explains how to script weapons for Carnage Contest with Lua. Programming/Lua knowledge is recommended for better understanding!
New to Lua? You can find some tutorials here! Or just search at Google!

I recommend you to use Notepad++ as editor for Lua scripts but you are free to use any text editor you like. Just make sure that you save your scripts as plain ANSI ASCII (never use UTF-8 or other encodings!) files with ".lua" as extension.

Analyzing a Carnage Contest Weapon

Weapons in Carnage Contest consist of 2 parts: the actual weapon and an arbitrary amount of different projectiles (0 to infinite).
First we will have a look at a simple "weapon", which does not have any projectiles. This is the original "Self-Healing" script with some comments/effects removed for simplicity.

You can find the original script in your Carnage Contest folder @ scripts/CC Original/movement/Self-Healing.lua

-- Setup Tables
if cc==nil then cc={} end
cc.selfhealing={}

-- Load & Prepare Ressources
cc.selfhealing.gfx_wpn=loadgfx("weapons/selfhealing.png")
setmidhandle(cc.selfhealing.gfx_wpn)
cc.selfhealing.sfx_heal=loadsfx("selfhealing.ogg")

cc.selfhealing.id=addweapon("cc.selfhealing","Self-Healing",cc.selfhealing.gfx_wpn,1,2)

function cc.selfhealing.draw()
	-- Do nothing!
end

function cc.selfhealing.attack(attack)
	if (weapon_shots<=0) then
		if (attack==1) then
			-- No more weapon switching!
			useweapon(0)
			weapon_shots=weapon_shots+1
			-- Heal
			playerheal(0,50)
			-- End Turn
			endturn()
		end
	end
end

So what does this script do?

Setup Tables

if cc==nil then cc={} end
cc.selfhealing={}

if cc==nil then cc={} end checks if the table called 'cc' already exists (if cc==nil). It creates a new empty table (cc={}) if it doesn't exist already. The table 'cc' (Carnage Contest) is used for all original weapons. When you write your own scripts, you should use your own 'main table' which contains all your weapon scripts. This is something like a namespace. So use something unique like your nick. Do NOT use the 'cc' table for your scripts!
cc.selfhealing={} creates the table for the weapon in our namespace. This table will be used to store weapon functions and variables. Using the name of the weapon as name of the table is best practice.

Load & Prepare Ressources

cc.selfhealing.gfx_wpn=loadgfx("weapons/selfhealing.png")
setmidhandle(cc.selfhealing.gfx_wpn)
cc.selfhealing.sfx_heal=loadsfx("selfhealing.ogg")

The following lines load an image which is then centered with setmidhandle. Afterwards a sound is loaded. The commands simply return an integer ID which can then be used to draw the loaded image or to play a loaded sound. These integer values are saved in variables within the weapon table ('gfx_wpn' and 'sfx_heal').

Add Weapon

cc.selfhealing.id=addweapon("cc.selfhealing","Self-Healing",cc.selfhealing.gfx_wpn,1,2)

After that we have a very important line. The addweapon command adds the weapon to the game. Without this line you wouldn't be able to use and select the weapon in-game.
The command has five parameters:
- table: the Lua table which contains all variables/functions for the weapon
- name: the name for you weapon which will be displayed in-game
- icon: the image which will be used as icon for your weapon
- amount: the default amount of uses, values from 0-99 or 100 for infinite amount, or leave for infinite amount
- first use: the first round in which this weapon can be used, values from 1-10, or leave for instant use

This command is essential as said before. It's important that you use it exactly ONCE in each weapon script!

Draw Function

function cc.selfhealing.draw()
	-- Do nothing!
end

Let's continue with our analysis! A function is created. It's simply called 'draw' and it is created in the weapon table 'cc.selfhealing'. Carnage Contest will call the 'draw'-function always when the player has selected this weapon. It is simply used to draw the weapon at the player. Never use it for something else. Don't let it change important values!
The function has no content in this case because the self-healing 'weapon' has no images which need to be drawn!

Attack Function

function cc.selfhealing.attack(attack)
	if (weapon_shots<=0) then
		if (attack==1) then
			-- No more weapon switching!
			useweapon(0)
			weapon_shots=weapon_shots+1
			-- Heal
			playerheal(0,50)
			-- End Turn
			endturn()
		end
	end
end

The next function is called 'attack'. It is not called always but only when the player has control. It has one parameter. It's called 'attack' as well but its name doesn't matter at all. You can give it whatever name you want. This parameter represents the current state of the attack-key (space). It's 1 if space is pressed and 0 if it's not pressed.
First the function checks if the global variable weapon_shots is less or equal zero. In other words it checks if the 'weapon' has been fired already.

Global Weapon Variables

weapon_shots is one of 7 global weapon variables which will be reset to 0 automatically by the game when you select another weapon or when the turn ends. Here's a short list:
- weapon_shots: commonly used for the amount of fired shots
- weapon_charge: used for the charge power value (for weapons like bazooka or grenade)
- weapon_mode: use it when your weapon has different modes or something like that
- weapon_timer: for timing stuff e.g. for the delay between two shots
- weapon_position: used by hudpositioning command. Is 1 if player specified a position on the map - else 0
- weapon_x: used by hudpositioning. X coordinate the player specified
- weapon_y: used by hudpositioning. Y coordinate the player specified

Attack / Use Weapon / End Turn

After checking if the weapon has been fired/used already, the script checks if space is pressed (if attack==1). So if the weapon has NOT been used yet AND if space is pressed, something will happen.
The command useweapon is called. It decreases the amount in the weapon inventory of the current team by 1 (if the amount is limited). The parameter 0 tells the game to close the weapon selection menu. You will not be able to use other weapons after using this one. Use 1 as parameter if you want to allow to use more weapons this turn.
Next weapon_shots is increased by 1. Together with the condition at the beginning of this function this will make sure that the weapon will only be used once.
Afterwards playerheal(0,50) is called. It gives 50 healtpoints to the player with ID 0. ID 0 is not a real ID but a shortcut. It is equal to the ID of the player who is currently controlled. Instead you could also use playercurrent() to get the ID of the current player. So remember: 0 as player ID in player functions always means that the command is used on the current player!
Finally the last command is endturn. This commands ends the turn. Ending a turn means that the backing time will start. The current player will not be able to attack anymore and soon the control will be given to the next player.

Continue to Part II