changeset 1354 7cfa7d94d014
child 1355 17fe62f4b3de
equal deleted inserted replaced
1353:48e52d3c6c85 1354:7cfa7d94d014
     1 #summary Lua library documentation: !SimpleMission
     2 #labels !LuaLibrary
     4 = Lua library: `SimpleMission` =
     5 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.
     7 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.
     9 This library has the following features:
    10  * Add teams, clans, hogs
    11  * Spawn gears
    12  * Sensible defaults for almost everything
    13  * Set custom goals or use the default one (kill all enemies)
    14  * Add non-goals to fail the mission
    15  * Checks victory and failure automatically
    17 To use this library, you first have to load it and to call `SimpleMission` once with the appropriate parameters.
    19 == `SimpleMission(params)` ==
    21 This function sets up the *entire* mission and needs one argument: params. The argument `params` is a table containing fields which describe the mission.
    23 ```
    24 Mandatory fields:
    25 - teams:		Table of teams. There must be 1-8 teams.
    27 Optional fields
    28 - ammoConfig		Table containing basic ammo values (default: infinite skip only)
    29 - initVars		Table where you set up environment parameters such as MinesNum.
    30 - wind			If set, the wind will permanently set to this value (-100..100). Implies gfDisableWind
    31 - gears:		Table of objects.
    32 - girders		Table of girders
    33 - rubbers		Table of rubbers
    35 AMMO
    36 - ammoType		ammo type
    37 - delay			delay (default: 0)
    38 - numberInCrate		ammo per crate (default: 1)
    39 - count			default starter ammo for everyone, 9 for infinite (default: 0)
    40 - probability		probability in crates (default: 0)
    42 TEAM DATA
    43 - hogs			table of hedgehogs in this team (must contain at least 1 hog)
    44 - name			team name
    45 - clanID		ID of the clan to which this team belongs to. Counting starts at 0.
    46 			By default, each team goes into its own clan.
    47 			Important: The clan of the player and allies MUST be 0.
    48 			Important: You MUST either set the clan ID explicitly for all teams or none of them.
    49 - flag			flag name (default: hedgewars)
    50 - grave			grave name (has default grave for each team)
    51 - fort			fort name (default: Castle)
    54 - id			optional identifier for goals
    55 - name			hog name
    56 - x, y			hog position (default: spawns randomly on land)
    57 - botLevel		1-5: Bot level (lower=stronger). 0=human player (default: 0)
    58 - hat			hat name (default: NoHat)
    59 - health		hog health (default: 100)
    60 - poisoned		if true, hedgehog starts poisoned with 5 poison damage. Set to a number for other poison damage (default: false)
    61 - frozen		if true, hedgehogs starts frozen (default: false)
    62 - faceLeft		initial facing direction. true=left, false=false (default: false)
    63 - ammo			table of ammo types
    65 GEAR TYPES:
    66 - type			gear type
    67 ALL types:
    68 	id		optional identifier for goals
    69 	x		x coordinate of starting position (default: 0)
    70 	y		y coordinate of starting position (default: 0)
    71 	dx		initial x speed (default: 0)
    72 	dy		initial y speed (default: 0)
    73 - type=gtMine		Mine
    74 	timer 		Mine timer (only for non-duds). Default: MinesTime
    75 	isDud		Whether the mine is a dud. default: false
    76 	isFrozen	Whether the mine is frozen. If true, it implies being a dud as well. Default: false
    77 	health 		Initial health of dud mines. Has no effect if isDud=false. Default: 36
    78 - type=gtSMine		Sticky mine
    79 	timer		Timer. Default: 500
    80 - type=gtAirMine	Air mine
    81 	timer		Timer. Default: (MinesTime/1000 * 250)
    82 - type=gtExplosives	Barrel
    83 	health		Initial health. Default: 60
    84 	isFrozen	Whether the barrel is frozen. Default: true with health > 60, false otherwise
    85 	isRolling	Whether the barrel starts in “rolling” state. Default: false
    86 - type=gtCase		Crate
    87 	crateType	"health": Health crate
    88 			"supply": Ammo or utility crate (select crate type automatically)
    89 			"supply_ammo_explicit": Ammo crate (not recommened)
    90 			"supply_utility_explicit": Utility crate (not recommededn)
    91 	ammoType	Contained ammo (only for ammo and utility crates).
    92 	health		Contained health (only for health crates). Default: HealthCaseAmount
    93 	isFrozen	Whether the crate is frozen. Default: false
    94 - type=gtKnife		Cleaver
    95 - type=gtTarget		Target
    97 GOALS:
    98 Note: If there are at least two opposing teams, a default goal is used, which is to defeat all the enemies of the
    99 player's team. If this is what you want, you can skip this section.
   101 The default goal is overwritten as if customGoals has been set. Set customGoals and other related parameters for
   102 defining your own special goals. In this case, the mission is won if all customGoals are completed.
   103 Note the mission will always fail if the player's hedgehogs and all their allies have been defeated.
   104 If there is only one team (for the player), there is no default goal and one must be set explicitly.
   105 - customGoals		Table of custom goals (see below). All of them must be met to win. Some goal types might fail,
   106 			rendering the mission unwinnable and leading to the loss of the mission. An example is
   107 			blowing up a crate which you should have collected.ed.
   108 - customNonGoals	Table of non-goals, the player loses if one of them is achieved
   109 - customGoalCheck	When to check goals and non-goals. Values: "instant" (default), "turnStart", "turnEnd"
   111 - missionTitle:		The name of the mission (highly recommended)
   112 - missionIcon:		Icon of the mission panel, see documentation of ShowMission in the Lua API
   113 - goalText:		A short string explaining the goal of the mission (use this if you set custom goals).
   115 GOAL TYPES:
   116 - type			name of goal type
   117 - failText		Optional. For non-goals, this text will be shown in the stats if mission fails due to this non-goal
   118 			being completed. For goals which fail, this text will be displayed at failure. Note that
   119 			all normal goals have sensible default fail texts.
   120 - type="destroy"	Gear must be destroyed
   121 	- id		Gear to destroy
   122 - type="teamDefeat"	Team must be defeated
   123 	- teamName	Name of team to defeat
   124 - type="collect"	Crate must be collected
   125 	FAIL CONDITION:	Crate taken by enemy, or destroyed
   126 	- id		ID of crate gear to collect
   127 	- collectors	Optional table of gear IDs, any one of which must collect the gear (but nobody else!).
   128 			By default, this is for the player's teams and allies.
   129 - type="turns"		Achieved when a number of turns has been played
   130 	- turns 	Number of played turns 
   131 - type="rounds"		Achieved when a number of rounds has been played
   132 	- rounds	Number of played rounds
   133 - type="suddenDeath"	Sudden Death has started
   134 - type="inZone"		A gear is within given coordinate bounds. Each of xMin, xMax, yMin and yMax is a sub-goal.
   135 			Each sub-goal is only checked if not nil.
   136 			You can use this to check if a gear left, right, above or below a given coordinate.
   137 			To check if the gear is within a rectangle, just set all 4 sub-goals.
   138 	FAIL CONDITION:	Gear destroyed
   139 	- id		Gear to watch
   140 	- xMin		gear's X coordinate must be lower than this
   141 	- xMax		gear's X coordinate must be higher than this
   142 	- yMin		gear's Y coordinate must be lower than this
   143 	- yMax		gear's Y coordinate must be higher than this
   144 - type="distGearPos"	Distance between a gear and a fixed position
   145 	FAIL CONDITION:	Gear destroyed
   146 	- distance	goal distance to compare to
   147 	- relationship	"greaterThan" or "lowerThan"
   148 	- id		gear to watch
   149 	- x		x coordinate to reach
   150 	- y		y coordinate to reach
   151 - type="distGearGear"	Distance between two gears
   152 	FAIL CONDITION:	Any of both gears destroyed
   153 	- distance	goal distance to compare to
   154 	- relationship	"greaterThan" or "lowerThan"
   155 	- id1		first gear to compare
   156 	- id2		second gear to compare
   157 - type="damage"		Gear took damage or was destroyed
   158 	- id		Gear to watch
   159 	- damage	Minimum amount of damage to take at a single blow. Default: 1
   160 	- canDestroy	If false, this goal will fail if the gear was destroyed without taking the required damage
   161 - type="drown"		Gear has drowned
   162 	FAIL CONDITION:	Gear destroyed by other means
   163 	- id		Gear to watch
   164 - type="poison"		Gear must be poisoned
   165 	FAIL CONDITION:	Gear destroyed
   166 	- id		Gear to be poisoned
   167 - type="cure"		Gear must exist and be free from poisoning
   168 	FAIL CONDITION:	Gear destroyed
   169 	- id		Gear to check
   170 - type="freeze"		Gear must exist and be frozen
   171 	FAIL CONDITION:	Gear destroyed
   172 	- id		Gear to be frozen
   173 - type="melt"		Gear must exist and be unfrozen
   174 	FAIL CONDITION:	Gear destroyed
   175 	- id		Gear to check
   176 - type="waterSkip"	Gear must have skipped over water
   177 	FAIL CONDITION:	Gear destroyed before it reached the required number of skips
   178 	- id
   179 	- skips		Total number of water skips required at least (default: 1)
   180 ```
   182 === Examples ===
   183 A couple of scenarios are using `SimpleMission`. Look into `Data/Missions/Scenarios` of your Hedgears installation. Check out the source code of the mission “Bazooka Battlefield” for a typical mission created with this library.