Mercurial Mercurial > hwkb / diff
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
LuaLibrarySimpleMission.wiki
changeset 1354 7cfa7d94d014
child 1355 17fe62f4b3de 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/LuaLibrarySimpleMission.wiki	Thu May 03 00:07:59 2018 +0200
@@ -0,0 +1,183 @@
+#summary Lua library documentation: !SimpleMission
+#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.
+
+```
+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)
+```
+
+=== Examples ===
+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.
hwkb