Puzzles: beams and circuits (puzzle.* kits) #

Two reusable puzzle engines written in Rust: light beams that bounce between mirrors, and signal graphs that open doors. They hold the rules only; your game owns the meshes, the colliders, the animation and the sounds. Readable offline: gripforge docs puzzles, or the MCP tool gripforge_docs (topic puzzles).

What it is for #

They compose: feed the active value of a receiver into an input node of a circuit, and let the circuit drive a door. There is no second physics world and no hidden tick: the game decides when to trace and when to step.

Turn it on #

gripforge_gamekit_install   { project_id: "gkp_…", id: "puzzle.circuits" }
gripforge_gamekit_install   { project_id: "gkp_…", id: "puzzle.beams" }

Both need no other kit. Each one is a service with up to 128 independent instances (one per room or mechanism): create(id, config), request(id, command), remove(id), ids(). A command is a small JSON object with an op. Rust is the only implementation: the same core runs as a native C library, as a WebAssembly module and inside the kit host, and JavaScript only carries the JSON.

puzzle.beams #

Configuration (all optional, unknown fields and out-of-range values are rejected):

Send the complete current optical scene every time something moves:

{ "op": "trace",
  "sources":  [{ "id": "laser", "position": [-4,1,0], "direction": [1,0,0], "power": [1,1,1] }],
  "surfaces": [
    { "id": "mirror", "kind": "mirror", "position": [0,1,0], "normal": [1,0,1], "radius": 1 },
    { "id": "sensor", "kind": "receiver", "position": [0,1,-4], "normal": [0,0,1], "radius": 0.5, "threshold": [0.5,0.5,0.5] } ] }

• 0 to 16 sources and 0 to 128 surfaces; ids are unique per category. Units are metres in one right-handed frame. power is an RGB triplet of a unitless gameplay quantity.
• Surface kinds: mirror (tint), prism (tint and reflect: a configurable splitter, for instance reflect: [1,0.5,0], not a physical refraction), receiver (threshold per channel; active when every positive threshold is met; it absorbs, it does not pass the beam on), blocker (absorbs; may be a sphere). Surfaces are finite disks by default (radius, normal, twoSided). Tint and splitting never amplify power.
• The answer holds segments (source, from, to, power, hit, depth), receivers (id, power, threshold, active), truncated and limits. If a budget is exhausted, truncated is true and EVERY receiver is reported inactive, so an incomplete trace never powers a door.
• Walls that must stop a beam have to be supplied as blockers: the kit does not query engine meshes. Use threshold margins, never equality of floating-point values.
• Other commands: status, config, reset, preview (runs on a clone), save (gripforge.beams/1) and load (the derived results are recomputed, never trusted). Damage from a beam is not applied by the kit: it is a game decision.

puzzle.circuits #

{} creates one input named switch and one output named door sourced from it. A configuration:

{ "nodes": [
    { "id": "left",  "kind": "plate", "threshold": 20 },
    { "id": "right", "kind": "plate", "threshold": 20 },
    { "id": "both",  "kind": "and", "inputs": ["left", "right"] },
    { "id": "held",  "kind": "delay", "inputs": ["both"], "seconds": 1 } ],
  "outputs": [{ "id": "door", "source": "held" }] }

1 to 128 nodes, 0 to 64 outputs, at most 16 inputs per gate, no cycles (a latch supplies memory). Node kinds: input (initial), plate (threshold in kg, true when the observed load reaches it), and / or / xor (2 to 16 inputs, xor is odd parity), not, delay (true after the input has been high for seconds, 1 by default), pulse (a rising edge starts a pulse of seconds), latch (inputs: [set, reset], reset wins). Durations are 0.001 to 3600 s.

The loop of the game, once per fixed tick:

1. { "op": "step", "dt": 0.016, "inputs": [{ "id": "left", "value": 25 }] }. dt is 0.000001 to 0.1 s; observations are absolute (a plate with nobody on it must be sent as 0) and input nodes take booleans.
2. { "op": "sync" } answers { state, action }. action is null or { token, effect } where the effect lists absolute boolean commands, for instance { "kind": "outputs", "changes": [{ "id": "door", "value": true }] }.
3. Apply the whole batch to the world once, then { "op": "resolve", "token": 1, "success": true }. If a door is blocked or an actuator is missing, undo any partial work and resolve with success: false; the signals stay committed and a later sync retries. sync with force: true sends every output, false ones included (use it right after creation).

While an action is pending, other changes and save/load are refused. Use the instance lifetime plus the token as your receipt key so a duplicate resolve cannot apply an effect twice. Other commands: status, config, reset, preview, save (gripforge.actions/1), load. Replay is exact with the same fixed tick and the same observations.

Hooks and modding #

These two kits are pure drivers: they declare no hooks, collections or moddable keys. The decisions are yours, in the code that calls them: when to trace, which engine objects become sources or blockers, how a receiver or an output is shown or sounded. Everything else of the game (rewards, doors, interactions) reacts to the answers through the ordinary events and scripts of the game.

Engines #

The Rust core is delivered as a native C library, a WebAssembly module and a kit-host adapter, so the same puzzle runs in the web player and the native player, and any engine can call the C library. The engine adapter converts positions and normals, owns the colliders and actuators, and renders the beams (lines, particles, sounds) from the returned segments.

When it does not do what you expect #