Add INTENT.md and archive initial exploration notes
Distills the architectural exploration into a top-level intent doc per the repo's own proposed structure.
This commit is contained in:
parent
8b66604235
commit
705496a677
2 changed files with 1051 additions and 0 deletions
87
INTENT.md
Normal file
87
INTENT.md
Normal file
|
|
@ -0,0 +1,87 @@
|
|||
# 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.
|
||||
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.
|
||||
|
||||
## 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue