tegwick
f768bc4a41
Some checks failed
ci / check (push) Failing after 4s
CB-EV-0012. Stage 1, deliverable by deliverable: relationship-graph visualization emitted and gated, NEVER SEEN drag-to-propose evidenced end to end debug inspector evidenced (CB-WP-0011) hot-seat play evidenced here Hot-seat was the one closest to being claimed on the strength of the code path existing. SeatPolicy hands every human seat a handle on one shared Server, so turn-taking "obviously" worked — and nothing drove more than one seat until now. The property that matters is not that two turns happen but that the same tab, asked twice, shows two different hands. Mutating the projection to serve P1's view to every seat turns it red. The stage stays open on ONE named blocker rather than a vague reservation: no browser is available to this loop, so the visualization is evidenced only as correctly emitted. Everything testable from here has been tested. What remains is `cb-play --serve 0`, open the URL, confirm the table reads and a drag works. INTENT carries that note now. The self-quoting rule from CB-EV-0011 §4 is ADOPTED: an evidence file quotes the previous pass's final cost and never its own. CB-WP-0013 reported itself at $5.78/34 mid-flight; final is $8.26/47, under by 43%. Four for four, always low. Meta budget 29% [OVER] soft 25%, driven by CB-WP-0013 in a trailing three with two cheap product passes; it was an instrument repair, which ADR-0006 D2 exempts. SH-1 at 347,720 [HARD] against a 300,000 ceiling. Compaction is the remedy and this session cannot do it for itself. CB-EV-0009's standing prediction is now live and testable for the first time in three passes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
100 lines
4.8 KiB
Markdown
100 lines
4.8 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 (CB-EV-0012 §4): the inspector,
|
||
drag-to-propose and hot-seat play are evidenced by executing code;
|
||
the visualization is evidenced only as correctly emitted, because no
|
||
browser is available to the loop. Run `cb-play --serve 0`, open the
|
||
printed URL, and confirm the table reads and a drag works.*
|
||
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.
|