Verdigris Cloister
README.md
game.rules — the law and the referee
The whole genre grammar of Verdigris Cloister: the grid, initiative, action points, path cost, line of sight, three-state directional cover, flanking, elevation, an honest itemised hit chance, overwatch, movement undo, damage, death, and the mission's outcome.
local Rules = require("game.rules")
This module writes Core.state(). Nothing else does. Read the board through
it, or better, through the Director component, which is the copy that is
actually running in the scene.
Reading the board
| Call | Gives you |
|---|---|
Rules.snapshot(opts?) | the whole board as plain data. opts.tiles = false leaves the 80 tiles out |
Rules.queue(count?) | the next several turns, for the portrait strip |
Rules.tileInfo(x, y) | terrain, cover, elevation, occupant — and what the tile becomes next round |
Rules.reachable(unitId) | every tile the unit can walk to, with cost, AP, cover and danger |
Rules.pathTo(unitId, x, y) | the previewed path, its AP cost, and the cover at the end |
Rules.hitChance(a, b, opts?) | the honest percentage with every modifier named |
Rules.targets(unitId) | every enemy with its full hit chance, best first |
Rules.abilities(unitId) | the ability bar: each action, legal or not, and why not |
Rules.overwatchCone(unitId) | the tiles an armed overwatch covers |
Rules.coverVsThreats(x, y, side) | the cover a tile really buys against the enemies that can see it |
Doing things
Rules.move · Rules.undoMove · Rules.attack · Rules.overwatch ·
Rules.garden(unitId, "sow"\|"burn"\|"flood", x, y) · Rules.hold ·
Rules.endTurn · Rules.startMission(idOrDef, carried?) · Rules.aiStep
Every one of them is refused in plain words by its matching predicate:
canMove, canAttack, canOverwatch, canGarden, canUndo. They return
(false, "Too far — that is 2 action points and 1 remains."), so a screen can
print the reason without inventing one.
The rules themselves
Action points. Two per unit per turn. A move spends
ceil(pathCost / movePerAP); every other action spends one. Overwatch ends the
turn. Hold spends nothing and is always legal.
Path cost is not tile count. A plain step costs 1; pushing through growth at stage 2 or more costs 1 more; wading a flooded tile costs 1 more; climbing an elevation step costs 1 more per step. That is why the previewed path shows a cost and an AP, and why they are not the same number.
Cover is directional and has three states. A tile does not "have" cover —
its neighbours give cover, and only against a shot coming from that side. A step
up beside you is half cover, two steps is full. hitChance measures the cover
between the shooter and the target, so the same tile is full cover against one
enemy and open ground against another.
That is why reachable() and pathTo() report two numbers:
cover/coverName— what the tile actually buys against the enemies that can currently see it, worst case."unseen"when nothing can see it at all. This is the number the cover indicator should show.bestCover— the best cover the tile holds facing any direction, which is usually a more flattering number and usually a lie.
Flanking reads the target's facing. From behind: +30 and cover is ignored entirely. From the side: +12 and cover drops one state. From the front: nothing. Facing updates when a unit moves and when it attacks.
Elevation gives +15 to hit and +1 tile of reach from above, −10 from below.
Line of sight is a walk between tile centres. Lightwood at stage 3 takes the sightline with it; so does a tile heaved higher than both ends. Blight crystal is full cover but does not blind the shot, which is what makes full cover reachable at all — a blocker that both hides a target and blocks the shot just means there is no shot.
Overwatch arms a cone (about 56° each side, out to the unit's own reach) and fires the moment an enemy steps into a covered tile during that enemy's turn, resolved from the tile they just entered. A reaction shot is hurried: −15.
Undo. Movement pushes onto a per-turn undo stack and can always be taken
back — until something is committed. An attack, an overwatch shot and a garden
action all set committed, and from then on canUndo refuses with "The shot is
away — that cannot be taken back."
Death and the mission. A unit at zero hit points stops being alive, releases
its tile, and drops out of the initiative queue. The mission is lost when the
squad is wiped or the Blight reaches its share of the floor; it is won by the
mission's own objective (hold, reach, survive, cleanse).
Dice. Seeded and stored in the board, so a sequence of rolls repeats exactly.
Rules.setSeed(n).
How the other slices plug in
The garden phase. When the initiative queue wraps, the referee closes the
round, sets the phase to garden, and emits phaseChanged. If the garden slice
has registered a handler it is called; if it has not, the referee carries on by
itself, so this slice is provable alone and never deadlocks waiting for a
slice that is not there.
Rules.setPhaseHandler("garden", function(state)
-- grow everything, then either return nothing (the round carries on)
-- or return "defer" and call Rules.phaseDone("garden") when the
-- animation has finished.
end)
The same door exists for the gardening actions, so the garden owns what happens to a tile while the referee keeps owning legality and the AP:
Rules.setActionHandler("sow", function(state, unit, x, y) ... end)
Damage belongs to the referee. The garden decides what grew and who was standing in it; it reports the consequence rather than writing a unit:
Director:gardenEffect({ unitId = "anselm", amount = 2, cause = "thornbed" })
Director:gardenEffect({ unitId = "cassian", amount = 2, heal = true })
The referee also resolves the ground's own end-of-turn effects — a thornbed bleeds, fire burns, an open bloomstalk mends a neighbour — because those are health, and health is the referee's.
Signals fired (all from Core.SIGNAL): phaseChanged, roundBegan,
roundEnded, unitSelected, unitMoved, unitActed, unitDamaged,
unitDied, tileChanged, missionEnded, cameraFocus, plus playSfx and
playBark for the audio slice.
unitActed carries action = "attack" | "overwatch" | "overwatchFired" | "hold" | "sow" | "burn" | "flood".
The units
Four monks from Core.MONKS, plus three Blight forms this module owns —
mote (fast, brittle), shard (ranged, keeps its distance) and hulk (slow,
heavy). Rules.BLIGHT_FORMS carries each one's stats, its note and the tint
that identifies it; the monks slice builds bodies for those ids.
Rules.TUNING holds every number in one table.
Missions
Rules.MISSIONS ships the Propagation Hall so the game plays out of the box.
The campaign slice replaces and extends it:
Rules.registerMission({ id = "brass_nave", name = "The Brass Nave",
objective = { kind = "reach", x = 4, y = 10, text = "Reach the seed vault." },
blightThreshold = 0.45,
monks = { { id = "anselm", x = 3, y = 2 }, ... },
enemies = { { kind = "hulk", x = 5, y = 10 }, ... },
plants = { { kind = "lightwood", x = 2, y = 6, stage = 2 }, ... },
blight = { { x = 1, y = 10, stage = 2 } },
elevation = { { x = 6, y = 5, elev = 1 } } })
Objectives: hold / survive (rounds), reach (x, y), cleanse.
Director:carried() hands the survivors' wounds to the next mission.
One thing the engine does that the spec does not
execute shares the module registry with the components. A
require("game.core") from an execute call returns the same Core, and the
same board, that the running Director is using — so an experiment run from
execute mutates the live game. Reach for Director:snapshot() to read, and
call Director:startMission(...) afterwards to put the board back.