Mechanism reference

The ./engine package is a set of deterministic, product-neutral building blocks for turn-based grid games. Each page in this section describes one mechanism family: the state it expects, the ordering it guarantees, the policy the product must inject, and the edge cases an integration should test.

Every mechanism page also ends with a Zonoid example. Zonoid is the first production consumer of this engine: its universal grid reducer supplies the board, characters, abilities, authored levels, and presentation policy while the SDK supplies the deterministic algorithm.

How the pieces fit together

submitted action
    │
    ├─ reducer validates product rules
    │
    ├─ simultaneous movement / push / transport proposal
    │
    └─ settlement waves
          ├─ arrival rules
          ├─ resource claims
          ├─ gates and triggers
          ├─ projectiles, rays, and chain reactions
          └─ linked-state interlocks
                 │
                 └─ stable turn view, score, transcript

The SDK does not prescribe that exact pipeline. A product composes only the mechanisms it needs and explicitly schedules their causal relationships through the settlement kernel.

Pages

Family	What the SDK guarantees
Grid model	Coordinates, action shapes, observations, and the reducer boundary
Simultaneous movement	Collision, priority, footprints, chains, rotations, and swaps
Geometry and FOV	Cardinal paths, nearest reachable cells, lines, sight, and cones
Turn settlement	Multi-wave consequence scheduling, duplicate policy, traces, and limits
Chain reactions	Breadth-first, once-per-identity propagation
Projectiles and flight	Snapshot-safe microsteps and bounded full-flight passes
Push chains	Mutation-free planning and safe commit order
Arrival rules	Stable dispatch of tile-entry effects
Resource claims	Neutral all-fail arbitration for contested resources
Resource transactions	Product-defined balances and atomic requirements/effects
Gates	Latching and occupancy-safe automatic transitions
Latched triggers	Authored-order, one-shot conditions and effects
Rays	Ordered traversal with explicit stop or exhaustion
Behavior trees	Product-schema-neutral selectors, conditions, and leaves
Transport and interlocks	Directed proposals, repeated passes, linked components, and stabilization
Deterministic randomness	Seeded streams, event-keyed rolls, and permutations
Scoring and budgets	Threshold scoring, failure precedence, and threshold suggestions
Solver	Breadth-first minimum-action search over an injected reducer
Replay verification	Transcript permutation checks and deterministic re-simulation

Product integration showcases

These focused boards show how Zonoid composes several SDK mechanisms into player-facing interactions while retaining the normal game UI.

Simultaneous movement

Multiple rival NPCs and the player resolve their movement together from the same turn snapshot.

NPC conversation

The player starts a conversation and selects a dialogue response through Zonoid’s normal interaction UI.

Rival battle

The player and a rival exchange actions in a focused battle board with health and equipment visible.

Shared conventions

• Stable identities are data. Entity, job, trigger, claim, and rule ids must be stable across replay.
• Lower priority values run first. Where priorities tie, the documented stable input or id order decides the result.
• Bounds are authored. Maximum steps, passes, reactions, nodes, and cycles are safety limits supplied by the product; they are not balance rules chosen by the SDK.
• Callbacks own meaning. Tokens, terrain, damage, abilities, objectives, animation events, and persistence stay in the product.
• Determinism includes ordering. Do not feed unordered database results or locale-dependent comparisons into a mechanism without normalizing them.

Import all mechanisms from the dedicated subpath:

import {
  resolveMoves,
  runSettlementCascade,
  shortestGridPath,
} from '@yugao-gaos/turn-based-grid-sdk/engine';