tickets system: add basic ticket accounting system

This adds support for DCT to track a side's number of remaining tickets.
There is also the ability to limit a campaign to a fixed period of time.
In addition the campaign designer can select from 4 preset difficulties
or specify their own difficulty. If a preset difficulty is selected
this will override any custom changes you have made.

Closes: #88

data/mission/theater/theater.goals

@@ -1 +1,22 @@
-theatergoals = {}
+blue = {
+	["flag"] = 45,
+	["tickets"]     = 100,
+	["player-cost"] = 1,
+	["modifier-reward"] = 0.5,
+	["modifier-loss"]   = 0.2,
+}
+
+neutral = {
+	["flag"] = 20,
+	["tickets"] = 0,
+	["difficulty"] = "realistic",
+}
+
+red = {
+	["flag"] = 60,
+	["tickets"]     = 200,
+	["difficulty"] = "easy",
+	["player-cost"] = 1,
+	["modifier-reward"] = 0.5,
+	["modifier-loss"]   = 0.2,
+}

doc/04-api/settings/theater.md

@@ -5,7 +5,153 @@ specific aspect of DCT on a theater wide level.
 
 ## Theater Goals
 
-	Currently not implemented
+Theater goals define the way in which DCT will evaluate the completion
+of the campaign. It is a simple ticket system much like what is present
+in many AAA FPS titles.
+
+### Example
+
+**file location:** `<theater-root>/theater.goals`
+
+	time = 43200  -- 12 hours in seconds
+	blue = {
+		flag            = 45,
+		tickets         = 100,
+		player-cost     = 1,
+		modifier-reward = 0.5,
+		modifier-loss   = 0.2,
+	}
+
+	neutral = {
+		flag    = 20,
+		tickets = 0,
+	}
+
+	red = {
+		flag       = 60,
+		tickets    = 200,
+		difficulty = "easy",
+	}
+
+### Configuration Options
+
+#### `time`
+
+The total time, in seconds, the campaign will run before a winner is
+determined and a new state is generated. Set to zero to disable the
+timer.
+
+#### `red`, `blue` and `neutral`
+
+Each faction definition is required and can have the following
+possible entries;
+
+##### `flag`
+
+ * required
+
+Defines the flag number used in the associated .miz which will trigger
+an end of the mission.
+
+DCT relies on the associated mission to provide 3 triggers (one per
+faction), with each trigger being conditional on the specified flag
+number being true. With the action of the trigger being the mission-end
+action with the values of the mission end action representing a winning
+condition. This means that the flag for the red faction, if set to true,
+will result in a mission end event stating the red team has won.
+
+##### `tickets`
+
+ * required
+
+Number of tickets the side's ticket pool starts with. The Neutral
+faction can start with zero tickets all others must have above zero.
+
+Ticket loss and reward:
+
+Tickets are lost by the owning side each time an asset dies. A side may
+gain tickets for completing missions. The calculations are as follows:
+
+	tickets-lost = asset.cost * owner.modifier-loss
+
+	tickets-gained = tgtasset.cost * mission.owner.modifier-reward
+
+An example; suppose a flight of two players (blue) attacked and destroyed
+a factory (red) which was part of their mission. During the mission one
+of the players is shot down.
+
+Point values and modifiers:
+
+ * factory worth 10 tickets
+ * player cost worth 2 tickets
+ * red modifiers; ticket = 50, modifier-reward = .5, modifier-loss = .5
+ * blue modifiers; tickets = 30, modifier-reward = 1, modifier-loss = 1
+
+Red Tickets:
+
+	red tickets = 50 - (factory.cost * red.modifier-loss)
+	            = 50 - (10 * .5)
+	            = 45
+
+Blue Tickets:
+
+	blue tickets = 30 - (player.cost * blue.modifier-loss) + mission success
+	             = 30 - (2 * 1) + mission success
+	             = 28 + (factory.cost * blue.modifier-reward)
+	             = 28 + (10 * 1)
+	             = 38
+
+Therefore even though blue lost a plane they were able to net 8 tickets.
+While red lost a net of 5 tickets. It is up to the campaign designer to
+assign costs to each asset, via their .dct file.
+
+##### `difficulty`
+
+ * _default:_ `custom`
+ * _value:_ limit set of strings (`easy`, `normal`, `hard`, `realistic`,
+  `custom`)
+
+Defines some predefined settings for player-cost, modifier-reward, and
+modifier-loss. If this is set to anything other than `custom` any
+explicitly defined values for player-cost, etc will be overwritten.
+
+`easy`:
+
+ * player-cost: 1
+ * modifier-reward: .5
+ * modifier-loss: 1.5
+
+`normal`:
+
+ * player-cost: 1
+ * modifier-reward: 1
+ * modifier-loss: 1
+
+`hard`:
+
+ * player-cost: 1
+ * modifier-reward: 1.5
+ * modifier-loss: .5
+
+`realistic`:
+
+ * player-cost: 1
+ * modifier-reward: 1
+ * modifier-loss: 0
+
+##### `player-cost`
+
+Defines the cost of each player slot.
+
+##### `modifier-reward`
+
+Defines the multiplicative modifier that is applied to all rewards the
+given faction receives.
+
+##### `modifier-loss`
+
+Defines the multiplicative modifier that is applied to all losses the
+given faction takes.
 
 ## Defined Weapon Categories