tegwick
bf72a1863a
Some checks failed
ci / check (push) Failing after 4s
Provenance (tier S, one paragraph in lieu of survey and ADR): the human check that kept INTENT stage 1 open was run and the drag was broken. Root cause, worth more than the instance: drop targets were ids, and an id must be unique, so exactly one element could ever be seat-0. The relationship-graph circle took it and the seat card that every action card's own text points at -- 'drag Attack onto a seat' -- silently had none. A seat is drawn twice and both drawings are the seat; the document model could not express that. Drop keys are now data-drop. Any number of elements may carry the same key, so a seat is droppable on its card and on its graph node. Measured on a live server: seat-0/1/2 each appear twice, id survives only on cb-status which is the one element the script looks up, and down=action-attack&up=seat-1 returns ok. Second defect: a drop on nothing returned without posting and without touching the status line, so a broken target was indistinguishable from a working page. resolve already refuses rather than defaulting, which is right; refusing SILENTLY is not. The page now reports the raw fact -- 'took action-attack, let go over nothing droppable' -- which names elements, not moves, so ADR-0007 control 5 holds. And the honest part: the general check added here -- every offered affordance names a key that exists, driven through Policy::choose over four real bot games -- does NOT catch the reported defect. seat-0 did exist, on the graph circle. It is kept because a wholly absent target is a real class, and paired with a targeted regression test that does catch it. Three mutations, each red for its stated reason, including the reported defect reintroduced; only the targeted test fires on that one. A cb-play assertion matched id="action-ground" as a substring while describing itself as checking the page; rewritten through drop_keys. make all exits 0. Stage 1 stays open: verified by tests, mutation and a live server, not by a human dragging. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
103 lines
5 KiB
Markdown
103 lines
5 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. The first run of it (2026-08-02)
|
||
found the table legible and the drag **broken**: drop targets were
|
||
`id`s, an `id` must be unique, so the relationship-graph circle held
|
||
`seat-0` and the seat card the page points at had none. Fixed in
|
||
CB-WP-0016 — drop keys are `data-drop` — and verified by tests, by
|
||
mutation, and against a live server, but **not** by a human dragging,
|
||
which is the standard that found it. Run `cb-play --serve 0`, open the
|
||
printed URL, and drag an action onto a seat card.*
|
||
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.
|