dungeoncraft/docs/MISSION_SCRIPTING.md

Mission scripting with blocks

Missions of editor campaigns are scripted with blocks (like Blockly): coloured puzzle pieces put together in the block editor (see CAMPAIGN_EDITOR.md). There is no code: the game runs the blocks directly, inside its fixed simulation step, so a co-op match runs them identically on every computer.

Code: src/blocks.rs (blocks, values, checking), src/mscript.rs (run time, triggers, zones), src/campaign_doc.rs (MissionScripts, TriggerDoc, TriggerKind).

Scripts of a mission

Script	When it runs
Start	once, when the mission begins
Victory check	every second – use If ... Win the mission
Defeat check	every second – use If ... Lose the mission
Clock	every second
Triggers	whenever their condition is met (see below)

The normal goals of the mission still apply; scripts are for anything more complicated. Any script may call Win or Lose.

Triggers

Each trigger has a name, a kind with its condition, once (fires only the first time; switched on again by a Switch trigger block it may fire once more) and active (switched on at the start). Conditions are checked ten times a second.

Kind	Condition	The "trigger unit"
Zone entered	a unit of a side/kind comes into a zone	that unit
Zone left	a unit of a side/kind leaves a zone	that unit
Line crossed	a unit crosses a line zone (from one side to the other, within its ends)	that unit
Zone claimed	the player claims more tiles in a zone	–
Dug in the zone	fewer solid tiles in a zone (dug, caved in)	–
Units in the zone	the count of a side/kind in a zone becomes < <= = != >= > n	–
Timer	after n seconds, or every n seconds (repeat)	–
A unit falls	a unit of a side/kind dies (or the unit with this name, see Spawn)	the fallen unit (its place)
A tower falls	a tower of the dungeon / the knights / anyone is destroyed	–
A value is reached	gold, mana, creatures, heroes or a variable becomes op n	–
Room built	a room of a kind (or any) grows	–
Spell cast	a spell (or any) is cast	–
Creature slapped	the player slaps one of his creatures	–
Research done	the library finishes a discovery	–

"Becomes" means the trigger fires when the condition turns true, not every check while it stays true. Sides: player, heroes, Mossgrim, Lady Nightwell, rival 3, anyone. Kinds: any, or one of the 22 creatures and heroes.

Blocks

Category	Block	Fields
Speak	Message	text – {name} shows the value of variable name
	Objective	text (shown as the mission's objective)
	Crookfinger says	text (with a sound)
Units	Spawn	count, kind, level, side, where (the core, the trigger unit, a zone), optional name
	Hero wave	count (sent at once)
	Remove	side, zone (removes those units)
World	Change ground	zone → floor, earth, rock, water, lava, gold, mushroom grove (the core, portals, towers and the gate stay)
	Reveal	zone (lifts the fog of war)
	Show	zone (moves the camera there)
	Gold + / Mana +	amount (negative takes)
	Weather above ground	fair, rain, fog or storm, for seconds (0: until a block changes it); it fades in softly. Only maps with land above ground have weather
	Talent experience +	amount (experience for the player's master talents)
Logic	If / else	condition; blocks inside
	Repeat	times (0–100); blocks inside
	Repeat until	condition, checked before each run (already true: the inside never runs); blocks inside
	Repeat, then check: until	condition, checked after each run (the inside runs at least once); blocks inside
	Wait	seconds – the script pauses here and goes on with the next block later (also inside loops and "if")
	Switch trigger	trigger, on/off
Variables	Set	variable, value
	Change	variable, value to add
Mission	Win the mission / Lose the mission	–

Values

Every number field holds a value; the switch in front of it changes the value's kind:

• numbers: Number, Variable, Gold, Mana, Seconds played, Count (creatures of a side/kind), Count in a zone, Random (whole number between a and b, deterministic), Calculation (+ - * /, division by 0 gives 0),
• conditions (for If): Comparison (< <= = != >= >), and, or, not, Yes/no, Trigger unit is a (kind), Weather above ground is (fair, rain, fog, storm).

Variables are numbers the mission remembers (saved with the game); a variable is known once some script of the mission sets it.

Checking

The editor checks while you build and marks problems red: empty texts, unknown zones, triggers or creature kinds, variables never set, a condition where a number belongs (or the other way round). A trigger whose zone is missing is marked in the trigger list. Problems are also listed in the campaign file check (CampaignDoc::validate).

At run time (src/mscript.rs)

• Every run of a script (the start, each second's checks, each fired trigger) is a thread: the lists of blocks it is in and where. Wait parks a thread until its time; threads are saved with the game, so a waiting script goes on after loading.
• The victory check, defeat check and clock start every second, but not while their previous run is still waiting. A trigger that fires again while its last run waits starts a second run.
• Loops without a Wait run up to 2000 blocks per check (ten checks a second) and then go on at the next check – a script can never hang the game.
• Blocks act at once, in order: a Count after a Spawn already sees the new units. Variables, the random state, fired triggers, zone contents and waiting threads are part of ScriptState.
• Scripts always run from the first player's side; messages reach every player of a match.
• Test play shows the variables and the trigger log at the top right, and the zones on the map.

The demo

Open the demo in the campaign editor: mission 1 ("The Trial of Triggers") uses all 14 trigger kinds, all special scripts and every block (including both kinds of until loops and Wait) on a painted map with five zones (rectangle, circle, line, tiles); mission 2 is a random map behind a branch. Play it with Test play and watch the debug view.