TeatroStageEngine.git · AGENTS.md

revision 07feb1fda2022948ce2bf3435f09c5f71e850ccb · complete file

TeatroStageEngine is the canonical engine for the Teatro puppet stage. The Swift module `TeatroPhysics` currently holds a small, in‑house rigid‑body solver and puppet rig; the `spec/` tree describes camera, room, rig, style, authoring UX, and interchange in prose; and the `Demos/` tree shows how the same stage behaves in Three.js. Other repos (FountainKit, web frontends, tools) should treat the *specs* in this package as the source of truth and keep their implementations aligned with those documents.

Important: the Swift solver in `TeatroPhysics` is a **minimal reference backend**, not a full professional physics engine. The web implementation runs on Cannon‑ES, and, per the FountainAI hard rule, Three.js + Cannon.js is the only approved 3D/physics stack for hosts. Do not introduce Bullet/Metal/SDL or other 3D stacks here; keep the Swift solver small, deterministic, and spec‑driven.

Working rules for agents:
- Spec‑first: when behaviour changes, update the relevant document under `spec/` (camera, physics, rig‑puppet, stage‑room, style, authoring, interchange) and then adjust Swift and JS implementations to match. The Three.js/Cannon demos are historical references and remain the only approved 3D host stack.
- Deterministic physics (Swift backend): keep the pure‑Swift integrator semi‑implicit Euler with explicit gravity and damping (`spec/physics/world-and-timestep.md`). Do not introduce randomness in the Swift core. Backends like Cannon or Bullet may have their own numeric quirks but should still respect the high‑level invariants in the specs.
- Narrow constraint set: constraint types are explicit (`TPDistanceConstraint` today). Add new constraints only when a real Teatro use‑case requires them, and document them under `spec/physics/constraints.md` before coding.
- Tests as guardrails: extend the test suite beyond unit math to cover rig behaviour (energy not exploding, strings staying near rest length, rig remaining within reasonable bounds over long runs). Treat failing tests as blockers for visual tweaks.

Implementation norms:
- Prefer small value types (`TPVec3`) and thin reference types (`TPBody`, `TPPuppetRig`) only where identity is required.
- Keep the Swift package renderer‑agnostic and reusable; visual choices belong in demos and host apps.
- Maintain the mapping between Swift, TS, and specs: field names and units must line up so snapshots can flow between the engine, web demo, and FountainKit without adapters that “fix” mismatches on the fly.

For a higher‑level view of how this engine is carved into instruments and tools in FountainKit (Stage World, Puppet, Camera, Style, Recording), see `docs/TeatroStage-Instruments-Map.md` in this repo and the matching `Design/TeatroStage-Instruments-Map.md` document in the FountainKit repository.