Log inGet started
World

Verdigris Cloister

Branchmain
Branchesmain
Commit65770846aa

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

CallGives 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.