#summary Lua library documentation of !SimpleMission; for creating simple missions

#labels !LuaLibrary

= Lua library: `SimpleMission` =

This is a simple library intended to make setting up simple missions an easy task for Lua scripters. The entire game logic and coding is abstracted away in a single function which you just need to feed a large definition table in which you define gears, goals, etc.

This is ideal for missions in which you set up the entire scenario from the start and don't need any complex in-mission events. BUT! This is *not* suited for missions with scripted events, cut-scenes, branching story, etc.

This library has the following features:

 * Add teams, clans, hogs

 * Spawn gears

 * Sensible defaults for almost everything

 * Set custom goals or use the default one (kill all enemies)

 * Add non-goals to fail the mission

 * Checks victory and failure automatically

To use this library, you first have to load it and to call `SimpleMission` once with the appropriate parameters.

== `SimpleMission(params)` ==

This function sets up the *entire* mission and needs one argument: params. The argument `params` is a table containing fields which describe the mission.

This is the definition of the `params` table:

<code>

Mandatory fields:

- teams:		Table of teams. There must be 1-8 teams.

Optional fields

- ammoConfig		Table containing basic ammo values (default: infinite skip only)

- initVars		Table where you set up environment parameters such as MinesNum.

- wind			If set, the wind will permanently set to this value (-100..100). Implies gfDisableWind

- gears:		Table of objects.

- girders		Table of girders

- rubbers		Table of rubbers

AMMO

- ammoType		ammo type

- delay			delay (default: 0)

- numberInCrate		ammo per crate (default: 1)

- count			default starter ammo for everyone, 9 for infinite (default: 0)

- probability		probability in crates (default: 0)

TEAM DATA

- hogs			table of hedgehogs in this team (must contain at least 1 hog)

- name			team name

- clanID		ID of the clan to which this team belongs to. Counting starts at 0.

			By default, each team goes into its own clan.

			Important: The clan of the player and allies MUST be 0.

			Important: You MUST either set the clan ID explicitly for all teams or none of them.

- flag			flag name (default: hedgewars)

- grave			grave name (has default grave for each team)

- fort			fort name (default: Castle)

HEDGEHOG DATA:

- id			optional identifier for goals

- name			hog name

- x, y			hog position (default: spawns randomly on land)

- botLevel		1-5: Bot level (lower=stronger). 0=human player (default: 0)

- hat			hat name (default: NoHat)

- health		hog health (default: 100)

- poisoned		if true, hedgehog starts poisoned with 5 poison damage. Set to a number for other poison damage (default: false)

- frozen		if true, hedgehogs starts frozen (default: false)

- faceLeft		initial facing direction. true=left, false=false (default: false)

- ammo			table of ammo types

GEAR TYPES:

- type			gear type

ALL types:

	id		optional identifier for goals

	x		x coordinate of starting position (default: 0)

	y		y coordinate of starting position (default: 0)

	dx		initial x speed (default: 0)

	dy		initial y speed (default: 0)

- type=gtMine		Mine

	timer 		Mine timer (only for non-duds). Default: MinesTime

	isDud		Whether the mine is a dud. default: false

	isFrozen	Whether the mine is frozen. If true, it implies being a dud as well. Default: false

	health 		Initial health of dud mines. Has no effect if isDud=false. Default: 36

- type=gtSMine		Sticky mine

	timer		Timer. Default: 500

- type=gtAirMine	Air mine

	timer		Timer. Default: (MinesTime/1000 * 250)

- type=gtExplosives	Barrel

	health		Initial health. Default: 60

	isFrozen	Whether the barrel is frozen. Default: true with health > 60, false otherwise

	isRolling	Whether the barrel starts in “rolling” state. Default: false

- type=gtCase		Crate

	crateType	"health": Health crate

			"supply": Ammo or utility crate (select crate type automatically)

			"supply_ammo_explicit": Ammo crate (not recommened)

			"supply_utility_explicit": Utility crate (not recommededn)

	ammoType	Contained ammo (only for ammo and utility crates).

	health		Contained health (only for health crates). Default: HealthCaseAmount

	isFrozen	Whether the crate is frozen. Default: false

- type=gtKnife		Cleaver

- type=gtTarget		Target

GOALS:

Note: If there are at least two opposing teams, a default goal is used, which is to defeat all the enemies of the

player's team. If this is what you want, you can skip this section.

The default goal is overwritten as if customGoals has been set. Set customGoals and other related parameters for

defining your own special goals. In this case, the mission is won if all customGoals are completed.

Note the mission will always fail if the player's hedgehogs and all their allies have been defeated.

If there is only one team (for the player), there is no default goal and one must be set explicitly.

- customGoals		Table of custom goals (see below). All of them must be met to win. Some goal types might fail,

			rendering the mission unwinnable and leading to the loss of the mission. An example is

			blowing up a crate which you should have collected.ed.

- customNonGoals	Table of non-goals, the player loses if one of them is achieved

- customGoalCheck	When to check goals and non-goals. Values: "instant" (default), "turnStart", "turnEnd"

- missionTitle:		The name of the mission (highly recommended)

- missionIcon:		Icon of the mission panel, see documentation of ShowMission in the Lua API

- goalText:		A short string explaining the goal of the mission (use this if you set custom goals).

GOAL TYPES:

- type			name of goal type

- failText		Optional. For non-goals, this text will be shown in the stats if mission fails due to this non-goal

			being completed. For goals which fail, this text will be displayed at failure. Note that

			all normal goals have sensible default fail texts.

- type="destroy"	Gear must be destroyed

	- id		Gear to destroy

- type="teamDefeat"	Team must be defeated

	- teamName	Name of team to defeat

- type="collect"	Crate must be collected

	FAIL CONDITION:	Crate taken by enemy, or destroyed

	- id		ID of crate gear to collect

	- collectors	Optional table of gear IDs, any one of which must collect the gear (but nobody else!).

			By default, this is for the player's teams and allies.

- type="turns"		Achieved when a number of turns has been played

	- turns 	Number of played turns 

- type="rounds"		Achieved when a number of rounds has been played

	- rounds	Number of played rounds

- type="suddenDeath"	Sudden Death has started

- type="inZone"		A gear is within given coordinate bounds. Each of xMin, xMax, yMin and yMax is a sub-goal.

			Each sub-goal is only checked if not nil.

			You can use this to check if a gear left, right, above or below a given coordinate.

			To check if the gear is within a rectangle, just set all 4 sub-goals.

	FAIL CONDITION:	Gear destroyed

	- id		Gear to watch

	- xMin		gear's X coordinate must be lower than this

	- xMax		gear's X coordinate must be higher than this

	- yMin		gear's Y coordinate must be lower than this

	- yMax		gear's Y coordinate must be higher than this

- type="distGearPos"	Distance between a gear and a fixed position

	FAIL CONDITION:	Gear destroyed

	- distance	goal distance to compare to

	- relationship	"greaterThan" or "lowerThan"

	- id		gear to watch

	- x		x coordinate to reach

	- y		y coordinate to reach

- type="distGearGear"	Distance between two gears

	FAIL CONDITION:	Any of both gears destroyed

	- distance	goal distance to compare to

	- relationship	"greaterThan" or "lowerThan"

	- id1		first gear to compare

	- id2		second gear to compare

- type="damage"		Gear took damage or was destroyed

	- id		Gear to watch

	- damage	Minimum amount of damage to take at a single blow. Default: 1

	- canDestroy	If false, this goal will fail if the gear was destroyed without taking the required damage

- type="drown"		Gear has drowned

	FAIL CONDITION:	Gear destroyed by other means

	- id		Gear to watch

- type="poison"		Gear must be poisoned

	FAIL CONDITION:	Gear destroyed

	- id		Gear to be poisoned

- type="cure"		Gear must exist and be free from poisoning

	FAIL CONDITION:	Gear destroyed

	- id		Gear to check

- type="freeze"		Gear must exist and be frozen

	FAIL CONDITION:	Gear destroyed

	- id		Gear to be frozen

- type="melt"		Gear must exist and be unfrozen

	FAIL CONDITION:	Gear destroyed

	- id		Gear to check

- type="waterSkip"	Gear must have skipped over water

	FAIL CONDITION:	Gear destroyed before it reached the required number of skips

	- id

	- skips		Total number of water skips required at least (default: 1)

</code>

Source: https://hg.hedgewars.org/hedgewars/raw-file/tip/share/hedgewars/Data/Scripts/SimpleMission.lua

=== Examples ===

A couple of scenarios are using `SimpleMission`. Look into `Data/Missions/Scenarios` of your Hedgewars installation. Check out the [https://hg.hedgewars.org/hedgewars/raw-file/tip/share/hedgewars/Data/Missions/Scenario/Bazooka_Battlefield.lua source code of the mission “Bazooka Battlefield”] for a typical mission created with this library.