Mission Architecture

This is a short guide which describes the architecture of missions. It is recommended to read the weapon scripting guide first.

Creating a new Mission

A mission is basically a folder in the missions folder with some files in it.

• Go to the missions-folder of Carnage Contest
• Create a new empty folder in this folder - the name does not matter
• Create the required files for your mission (see list below)

Files for a Mission

• info.txt: a textfile containing up to three variables. title for the title of your mission and info for a short info text. Both will be displayed in-game. mode is about the mission mode. You can omit this variable or use the value standard for a standard mission mode. Use score if this mission is about a highscore (reaching as many points as possible). The reached score will then be displayed in the menu (use getscore and setscore to change the score).
  title=the title for your mission
  info=a short information that will be displayed
  mode=standard for a regular mission or score for a mission with highscore functionality
• icon.png: a png-image containing an icon for your mission. A default image will be used if there is no icon.png in your mission-folder!
• general.cfg: the general configuration file for all mission maps. It can be overwritten by map-specific configuration files. Configuration files are used to specify the weapons which are available, their cooldowns and their amounts. A weapon slot definition looks like this:
  w01=scripts/CC Original/weapons/RC Missile.lua,1000,5
  w01 defines the slot. There are 12 slots in singleplayer so you can use w01 to w12 (the number has always 2 digits, use a leading zero for 1-9). You can also use w (without a number) to load additional weapons/objects which will not be selectable by the player (in order to use them in your Lua scripts or map for example).
  scripts/CC Original/weapons/RC Missile.lua is the path to the script, always relative to the Carnage Contest folder.
  1000 is the cooldown in milliseconds (1000 milliseconds = 1 second). You will have to wait this time after using this weapon. You don't have to specify the cooldown. It will be 1000 by default if you don't enter it.
  5 is the amount for this weapon. It must be 0-99. Don't specify this value if you want an infinite amount (which is the default). Note that you always have to specify a cooldown if you want to specify an amount as well (otherwise Carnage Contest will think that your amount is the value for the cooldown)
  Additonal Game Settings: You can also specify game settings in this file. Open sys/gamesettings/Recent.cfg to see which settings are available. Default settings will be used if you don't specify anything. Start your own game and specify all settings as you want them to be. Afterwards copy the relevant lines of the Recent.cfg into your general.cfg!
• general.lua: the general Lua script for all mission maps. It can be overwritten by a map-specific script as well. The stuff in this file will be executed during the missions. There are 3 functions which have to be declared:
  function mission_start() will be called once when the mission starts. Use it to setup stuff.
  function mission_update() will be called each frame. Use it to do stuff during the game.
  function mission_draw() will be called each rendered frame. Use it to draw additional stuff during the game.
  You have to create this file with all 3 functions in it or a map-specific Lua file for each map (description below).
• XXX.ccm: the map files for your mission XXX starts with 000 for the first map (attention: NOT 001!) and can go up to (theoretically) 999. Note that the number has always 3 digits. So you have to add 1 or 2 leading zeros for lower numbers! Use the map editor to create and edit these maps. You should set a spawnpoint, otherwise your player will be spawned at a random position.
• XXX.cfg: map-specific configuration file (again: XXX=000,001,002,...,999). It works exactly like general.cfg. general.cfg will processed first and the map specific file will be processed afterwards. This way you can overwrite everything which needs to be different from the general.cfg and keep all the other stuff untouched. You do not have to create such a file for each map.
• XXX.lua: map-specific Lua script file (again: XXX=000,001,002,...,999). It works exactly like general.lua. general.lua will processed first and the map specific file will be processed afterwards. This way you can overwrite Lua functions and keep other stuff untouched. You do not have to create such a file for each map if you have a general.lua (otherwise you have to). It's important that all 3 functions (see general.lua) are declared (either in general.lua, the map-specific Lua or in both)!
• progress/score: These files are created automatically to save your progress/score. Please remove them before you share your mission with others!

Scripting

You can use all the Lua commands in missions to make them interactive (except AI commands which are for AI scripts only). One important command is win which needs to be called when the player finishes a map. It will automatically load the map (and cfg/lua) with the next number.
Keep in mind that the game tries to run at 50 FPS and always executes 50 updates per second. You can easily create timers by increasing a variable by one in the mission_update function.

Need samples? Take a look at existing missions!