diff -r 48e52d3c6c85 -r 7cfa7d94d014 LuaLibrarySimpleMission.wiki --- /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.