tegwick
a55e878bf0
Some checks failed
ci / check (push) Failing after 4s
Provenance (tier M, structural S, chaos d4=4 -> OVERRIDE drawn M): the maintainer could drag after CB-WP-0016 but could not tell what was pickable, held, or droppable. Underneath that, the page was WRONG about which moves exist: 9 legal commands rendered as 5 cards each claiming all three target kinds, from a const string in the emitter. Investigate is legal on problems 2 and 3 but not 1; Solve on 1 but not 2 or 3. The live page now says 'Solve onto problem 1'. ADR-0010 restates control 5, which this work would otherwise have outgrown in silence: every game fact the page acts on must arrive from Rust as data; the script may read, match and render it, never compute, infer, filter or default one. The survey's real finding is that the permitted and forbidden designs are indistinguishable from outside, so the vocabulary grep is demoted to a cheap first line and two behavioural properties become the controls -- the highlighted set EQUALS the set Rust emitted, and anything the page marks legal must resolve. Both mutation-proven; the derive-legality mutation produces a plausible highlight (seat-0,1,2 where only seat-1 is legal) and is caught. Visible now: .pick resting shadow, .held on the grabbed element, .dropok on every legal target including BOTH drawings of a seat, and a ghost following the pointer. Nothing perceptual is verified and ADR-0010 D5 says so. The DOM stub now models classList/querySelectorAll/createElement and builds its node set from the real emitted page. Trap recorded: QuickJS fixes its stack limit at Context creation relative to that frame, so a helper returning a Context makes every later eval report 'SyntaxError: stack overflow'. CHAOS WINDOW CLOSED, 12 declarations, 2 overrides, one each way. Both changed the outcome, so the retirement condition is not met. Verdict: keep, and recommend d4 -> d8 with a second window of 12 -- that is a change to the loop's own constraints and is owed to the next declaration as tier-M work, not made here. CB-EV-0014 corrected: it quoted CB-WP-0015 at $15.14/136 and called it the first settled figure quoted. Now $22.70/166. The number had been read during CB-WP-0015 itself, so there are two defects -- the boundary, and quoting from memory instead of re-running the instrument. make all exits 0. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
106 lines
5.2 KiB
Markdown
106 lines
5.2 KiB
Markdown
# Intent
|
||
|
||
Clay-Borg is a rebuild-from-scratch simulation and games engine framework: it
|
||
assimilates and optimizes techniques and implementations useful for games,
|
||
simulations, and robotics.
|
||
|
||
It is not another monolithic game engine. It is a capability-assimilating
|
||
development engine with three distinct properties:
|
||
|
||
1. **Clay** — its canonical models, contracts, rules, and tools remain malleable.
|
||
2. **Borg** — mature, optimized libraries are assimilated behind controlled
|
||
interfaces rather than copied or exposed directly.
|
||
3. **Product-driven evolution** — abstractions are extracted from working
|
||
games, beginning with **GROUND — A Game of Bonds and Rivalry: DARVO
|
||
Edition**, rather than invented in isolation.
|
||
|
||
The central rule:
|
||
|
||
> **Own the semantics; assimilate the implementation.**
|
||
|
||
Clay-Borg owns what an entity, object, command, event, card, zone,
|
||
relationship, game, simulation, asset, plugin, and capability *mean*.
|
||
External libraries (wgpu, Rapier, Bevy ECS, Wasmtime, Quinn, egui, Serde,
|
||
tracing, …) provide optimized implementations of rendering, physics,
|
||
networking, serialization, and similar functions behind canonical ports. No
|
||
external library type should leak across a canonical interface.
|
||
|
||
## Why GROUND first
|
||
|
||
GROUND requires modest physics but sophisticated social state, simultaneous
|
||
decisions, and constrained sequences (a binding DARVO deny/attack/reverse
|
||
state machine, a typed relationship graph, commit/reveal simultaneous
|
||
resolution). It must stay playable headless — no rendering, no rigid-body
|
||
simulation required to run or test the rules. The 3D tabletop is a
|
||
projection and interaction surface for the game, not the definition of the
|
||
game.
|
||
|
||
## The most important design decisions
|
||
|
||
1. Build GROUND first, not a general engine first.
|
||
2. Keep rules independent from rendering and physics.
|
||
3. Use commands and events as the authoritative mutation mechanism.
|
||
4. Provide null, reference, and optimized implementations of important
|
||
capabilities.
|
||
5. Never leak assimilated-library types into canonical interfaces.
|
||
6. Use server-authoritative physics and deterministic semantic rules.
|
||
7. Treat player visibility as a projection, not a UI afterthought.
|
||
8. Make every defect reproducible as a scenario and replay.
|
||
9. Give coding agents bounded work packets and stable commands.
|
||
10. Attach TargetRevenue phases to versioned improvements and evidence
|
||
bundles.
|
||
|
||
## First product
|
||
|
||
> A headless, replayable, and agent-readable GROUND rules engine that can be
|
||
> projected onto an increasingly physical virtual tabletop, while every new
|
||
> capability remains replaceable, measurable, and financeable through
|
||
> TargetRevenue.
|
||
|
||
## Implementation order
|
||
|
||
0. **Headless GROUND** — full authoritative state, 2–6 players,
|
||
commit/reveal, relationships, DARVO, GROUND practice, CLI player, replay
|
||
and scenario tests, simple bots. No rendering, no physics.
|
||
1. **Inspectable 2D table** — card/token/hand/relationship-graph
|
||
visualization, drag-to-propose, debug inspector, hot-seat play.
|
||
*Open on one human verification, and every run of it so far has found
|
||
something no test could. 2026-08-02, run 1: the drag was broken — drop
|
||
targets were `id`s, which must be unique, so the graph circle held
|
||
`seat-0` and the seat card had none (CB-WP-0016). Run 2: the drag
|
||
worked but the page was **wrong about which moves exist**, showing 5
|
||
cards each claiming all three target kinds where 9 specific commands
|
||
were legal, with no way to see what was pickable, held, or droppable
|
||
(CB-WP-0017). Both fixed. What remains is perceptual and unreachable
|
||
from here by construction (ADR-0010 D5): run `cb-play --serve 0` and
|
||
confirm you can see what can be picked up, what you are holding, and
|
||
where it may go.*
|
||
2. **Physical 3D tabletop** — wgpu renderer, Rapier-backed physics, camera
|
||
and pointer controls, snap zones, asset importer.
|
||
3. **Networked sessions** — authoritative host, private projections,
|
||
commit/reveal protocol, reconnection, replay verification, spectator mode.
|
||
4. **Game creation framework** — object prototypes, scene/zone editors,
|
||
card/deck importer, package validation, Wasm game components.
|
||
5. **Prove generality** — implement one deliberately different fixture game;
|
||
only then promote duplicated GROUND abstractions into the stable Clay
|
||
Canon.
|
||
|
||
> No concept becomes canonical merely because it looks general. It becomes
|
||
> canonical after surviving a second concrete use.
|
||
|
||
## Sister repositories
|
||
|
||
- **`ground-game`** — the authoritative home of the GROUND boardgame itself
|
||
(rules, editions, content). Clay-Borg implements the engine that simulates
|
||
it; game-semantics questions defer to that repo.
|
||
- **`target-revenue`** — the canonical home of the Target Revenue Framework
|
||
and the TRSL license text this repo is released under.
|
||
|
||
## Provenance
|
||
|
||
This intent is distilled from the fuller architectural exploration in
|
||
[`history/260730-InitialExploration.md`](history/260730-InitialExploration.md),
|
||
which also covers the runtime substrate, simulation kernel, physics
|
||
subsystem, world-building layer, tabletop domain framework, networking
|
||
architecture, the agentic inner loop (work packets, CLI surface, quality
|
||
gates), and the TargetRevenue business-control model in full detail.
|