Back to homepage
LuaLibrarySimpleMission
History
Lua library documentation of SimpleMission; for creating simple missions
LuaLibrary
Updated Fri, 21 Jun 2019 23:15:11 +0100 by Wuzzy

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:

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 - isMissionTeam if true, this is the player's chosen team for this mission (default: false) - hogs table of hedgehogs in this team (must contain at least 1 hog) - 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. These arguments will be ignored if this is a mission team: - name team name - flag flag name (default: hedgewars) - grave grave name (has default grave for each team) - fort fort name (default: Castle) - voice voicepack (default: Default_qau) HEDGEHOG DATA: - id optional identifier for goals - health hog health (default: 100) - ammo table of ammo types - x, y hog position (default: spawns randomly on land) - 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) These arguments will be ignored if the hog is in a mission team: - name hog name - botLevel 1-5: Bot level (lower=stronger). 0=human player (default: 0) - hat hat name (default: NoHat) 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 "smallerThan" - 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 "smallerThan" - 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)

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 source code of the mission “Bazooka Battlefield” for a typical mission created with this library.