Aquarium/state/map.yaml
2026-05-18 04:15:24 +01:00

158 lines
18 KiB
YAML

project:
name: Aquarium Engine
root: E:\Projects\Aquarium-Engine
upstream: https://github.com/GameCult/Aquarium-Engine
purpose: >
Native C# runtime and renderer core for Aquarium clients. The engine owns
the Win32 host, D3D12 renderer, input loop, client reload boundary, debug UI,
audio host, persistent-state transport, and future render graph
abstractions. Epiphany is the current first-party client: it owns frontend
intent, agent visuals, CultCache/CultNet semantics, and render-plan
configuration through the engine contracts.
current_model:
host:
solution: Aquarium.Engine.sln
window: src/Aquarium.Engine/Platform/Win32Window.cs
renderer: src/Aquarium.Engine/Render/D3D12Renderer.cs
height_field_shader: src/Aquarium.Engine/Render/Shaders/D3D12HeightField.hlsl
scene_shader: src/Aquarium.Engine/Render/Shaders/D3D12Scene.hlsl
sdf_common_include: src/Aquarium.Engine/Render/Shaders/D3D12SdfCommon.hlsli
sdf_proxy_include: src/Aquarium.Engine/Render/Shaders/D3D12SdfProxy.hlsli
sdf_math_include: src/Aquarium.Engine/Render/Shaders/D3D12SdfMath.hlsli
post_shader: src/Aquarium.Engine/Render/Shaders/D3D12Post.hlsl
overlay_text: src/Aquarium.Engine/Render/DirectWriteOverlay.cs
debug_ui: src/Aquarium.Engine/Render/Ui/DebugUi.cs
synth_host: src/Aquarium.Engine/Audio/AquariumSynthHost.cs
wasapi_audio_device: src/Aquarium.Engine/Audio/WasapiAudioDevice.cs
faust_toolchain_sync: scripts/sync-faust-toolchain.ps1
synth_package_update: scripts/update-synth-package.ps1
local_package_feed: packages
runtime_loader: src/Aquarium.Engine/Runtime/ClientRuntimeLoader.cs
dev_reload: scripts/dev-reload.ps1
dev_watch: scripts/dev-watch.ps1
epiphany_client:
contracts: src/Aquarium.Engine.Contracts
implementation: src/Aquarium.Epiphany
render_plan: src/Aquarium.Epiphany/EpiphanyRenderPlan.cs
scene_builder: src/Aquarium.Epiphany/EpiphanySceneBuilder.cs
agent_preview: src/Aquarium.Epiphany.AgentPreview
shaders: src/Aquarium.Epiphany/Shaders
state_store: src/Aquarium.Epiphany/State/AquariumCultStateStore.cs
state_document: epiphany.aquarium.live_state
graphics_settings_document: epiphany.aquarium.graphics_settings
zyphos_client:
implementation: src/Aquarium.Zyphos
render_plan: src/Aquarium.Zyphos/ZyphosRenderPlan.cs
scene_builder: src/Aquarium.Zyphos/ZyphosSceneBuilder.cs
shaders: src/Aquarium.Zyphos/Shaders
worldbuilding_sync: docs/zyphos-eusocial-sync.md
setting_authority: E:\Projects\Eusocial Interbeing
purpose: >
Non-Epiphany planetary-scale rendering demo using the shared Aquarium host,
D3D12 renderer, reload transport, UI contracts, bloom, and SDF proxy path.
samples:
minimal_client: src/Aquarium.Sample.Minimal
dependencies:
cult_math: E:\Projects\CultMath
cult_lib: E:\Projects\CultLib
aqua_synth_faust: NuGet package AquaSynth.Faust 0.1.0-alpha.2 from repo-local packages feed
aqua_synth_core: transitive NuGet package AquaSynth.Core 0.1.0-alpha.2 from repo-local packages feed
docs:
doctrine: docs/aquarium-engine-doctrine.md
engine_client_boundary: docs/engine-client-boundary.md
epiphany_extraction_render_api_plan: docs/epiphany-extraction-render-api-plan.md
renderer: docs/hlsl-renderer.md
agent_sdf_visual_language: docs/epiphany-agent-sdf-visual-language.md
runtime_surface: docs/cult-runtime-surface.md
native_spine: docs/vortice-spine.md
tsr_inspired_taa_spec: docs/tsr-inspired-taa-spec.md
input: docs/input.md
zyphos_eusocial_sync: docs/zyphos-eusocial-sync.md
hdr_pbr_presentation: research/rendering/hdr-pbr-presentation.md
cube_sphere_fractal_brushes: research/rendering/cube-sphere-fractal-brushes.md
fractal_brush_architecture_plan: research/rendering/fractal-brush-architecture-plan.md
fractal_brush_implementation_roadmap: research/rendering/fractal-brush-implementation-roadmap.md
invariants:
- The camera target is the Grid center on the global XY plane.
- Grid radius follows twice the clamped camera zoom distance, then clamps to [20, 80]; pitch/yaw/projection do not resize it.
- Body anchors remain world-space and independent of the moving Grid window.
- Visible scene lighting is diegetic; no default ambient/global fill.
- Overlay text is DirectWrite final-pixel UI; scene text needs renderer-owned billboards.
- CultCache persists live app state through reload.
- Global GraphicsSettings persists renderer debug/HDR presentation knobs through restart and live reload.
- Failed shader/live-runtime reloads must leave the last good frame alive.
- Closed visible dev windows can be reopened from the last good slot without rebuilding.
renderer_state:
current:
- D3D12 default renderer behind IAquariumRenderer with explicit device/queue/swapchain, command allocators, fences, descriptor arenas, upload ring constants, tracked render targets, command events, resize rebuild, HDR/bloom/present, temporal diagnostics, and DirectWrite overlay bridge.
- Deferred scalar Grid height target rendered from additive brush passes.
- Epiphany owns its client surface brush list, SDF object table, SDF light table, shader manifest, and cursor projection policy through Aquarium.Engine.Contracts; the engine consumes those as generic rendering data.
- Direct-traced height-field surface is a terminating reflective surface over the scalar height field, sampling Studio2 PMREM mip 0.
- Fullscreen scene pass owns background and height-field surface only; each client-declared SDF shader owns a separate proxy pipeline, with shared proxy plumbing factored into generic engine HLSL includes. Proxy marching evaluates only sdfDistance; sdfSurface runs once at the refined hit and returns only PBR material values.
- Reusable SDF primitives live in engine D3D12SdfMath.hlsli; current Epiphany role character organs live under src/Aquarium.Epiphany/Shaders.
- Epiphany's cursor is a luminous five-petal hibiscus SDF centered one cursor radius above the XY plane so its contact tip reaches Grid z=0 without projecting to the Grid surface.
- SDF/analytic Epiphany role visuals upload current centers, previous centers, and state scalars through the public `AquariumSdfObject` contract.
- Agent SDF visual language is documented against Epiphany's published CultNet surfaces: identity from agent memory, motion from heartbeat, posture from role/coordinator/result surfaces, pressure from reorient/pressure surfaces, and expression through bounded orbit wandering plus CPU-visible gravity-well pulses.
- Life is a memory-nautilus seed-shell SDF: a protective revolved seed/cardioid shell owns the silhouette, a visible ember sits inside the aperture, and the logarithmic spiral domain owns seam, bead trail, pressure breathing, rupture scar, and surface masks. Nautilus references inform the coordinate mapping, not the object silhouette.
- SDF light buffer feeds Self emission and direct object lighting; future other Selves should join this light lane, not a generic field-instance table.
- Studio2 PMREM and irradiance DDS cubemaps are loaded as D3D12 TextureCubes; PMREM serves roughness-mip specular, irradiance serves Lambertian diffuse IBL for non-metal bodies.
- DirectWrite/Direct2D unified debug panel with tabs for Aquarium renderer controls, client-declared debug panels, terminal commands, and engine/client tooling surfaces.
- DirectWrite/Direct2D debug panels own body scrolling and clipping; overflowing client controls must stay inside the panel with a visible scrollbar.
- Aquarium exposes an optional synth/audio hosting boundary through AquariumSynthDocument; Aquarium consumes AquaSynth.Faust as a pinned repo-local NuGet package so synth-agent construction cannot break Aquarium builds until the package is intentionally updated. AquaSynth.Core arrives transitively for patch editor/parser surfaces.
- Aquarium now exposes a generic queued PCM audio lane through AquariumAudioDocument. Epiphany Face voice uses it to play streamed Codex realtime output without reaching into the engine's WASAPI internals.
- Epiphany owns the first native Face realtime voice session controller. It stores loopback app-server URI, thread id, voice, and speech prompt in CultCache live state; starts `thread/realtime/start` with audio output over the experimental Codex app-server WebSocket JSON-RPC edge; sends text utterances; reflects ephemeral transcript/error/audio counters in the debug UI; and treats speech as transient Face surface, not durable memory or project authority.
- Face voice routing is no longer a singleton. Epiphany persists typed FaceVoiceEndpoint rows with id, display name, thread id, voice, prompt, enabled flag, and XY proximity anchor; FaceVoiceRouter selects the active endpoint from cursor/listener proximity when auto-route is enabled, while terminal commands can add, select, move, remove, start, stop, and speak through endpoints.
- Global GraphicsSettings document feeding render debug, exposure, bloom intensity, and bloom veil.
- Temporal resolve uses scene color, metadata, and control history only; dormant event history lanes are cut until a real producer and consumer contract exists.
- Isolated Epiphany agent preview renders run through the real D3D12 renderer from src/Aquarium.Epiphany.AgentPreview; preview isolation is owned by a preview-only scene shader, while the engine exposes only final-frame PNG capture.
- Zyphos is the first nontrivial non-Epiphany client: a planetary-scale demo with spherical-domain terrain, atmospheric rim lighting, night-side glints, fixed-sky Umbros, and first-pass eclipse cadence.
- Zyphos/Umbros render-scale binary constants live in src/Aquarium.Zyphos/ZyphosUmbrosSystem.cs: Umbros is modeled as a 0.9-radius mutually tidally locked twin at 8 Zyphos radii, while the dim primary star phase moves through the Zyphos-local frame.
- Zyphos simulates the neighboring Eusocial Interbeing setting; the vault at E:\Projects\Eusocial Interbeing owns canon, while Aquarium owns demo rendering constraints and feeds worldbuilding questions back through the vault's Zyphos Simulation Brief.
- Future planetary terrain and fractal body detail should use a cube-sphere/QSC-family address space: six quadtree cube faces projected to the sphere with a measured low-distortion warp, avoiding lat-long pole singularities.
- Fractal world patches can declare nested semantic domains before terrain tiles. The first .aquageo patch declares solar, orbital, planetary, and lat/long domains for Zyphos so DSL nodes can attach to explicit reference frames before backend lowering.
- The fractal grammar layer validates nested domain topology through FractalDomainGraph: duplicate keys, missing parents, cycles, and root-to-leaf paths are grammar concerns, not renderer folklore.
- Aquarium frames now carry a 3D camera target in addition to the legacy 2D ViewFrame center. Zyphos uses a camera composer to separate tracked subject, parent composition anchor, and camera orbit distance.
- SceneState can disable the legacy height-field surface trace and request a procedural starfield background; Zyphos uses this for space views so the old Grid does not leak into planetary rendering.
- Future multiscale terrain and agent/body detail should come from bounded IFS brush grammars using shared shaped anisotropic envelopes; texture/material detail can be abundant, but traced SDF form detail must be proxy-bounded, LOD-gated, and measured.
- The IFS brush grammar should preserve a semantic ownership tree before backend lowering: local frames, deterministic seeds, named fields/captures, tags, payload bindings, LOD/cost tiers, and boolean-style union/subtract/common nodes should survive even if the first renderer path flattens them into fixed brush tables or SDF shader code.
- IFS LOD should be driven by cached node contribution summaries: each node carries bounds, projected error/material delta, coverage, cost, estimator state, residency, and summary/child payload handles so traversal can choose a stable hierarchy cut and render parent summaries while child details stream or fade in.
- Contribution weights cannot all be refreshed every frame; the cache needs a probabilistic online estimator that samples nodes under budget, updates mean/uncertainty/sample age/confidence, preserves nonzero exploration for visible or near-threshold nodes, and can later become a learned predictor without replacing conservative SDF bounds.
- The consolidated fractal brush architecture plan defines the intended pipeline: client intent -> domain roots -> semantic IFS brush grammar -> ownership tree -> node summaries -> contribution cache/residency scheduler -> backend packets -> renderer passes -> debug/evidence, with explicit module boundaries and mockable unit-test seams.
- The actionable fractal brush implementation roadmap lives in research/rendering/fractal-brush-implementation-roadmap.md and is the execution authority for the first pass.
- Bundled blue-noise texture assets are retained for future dithering/noise work even though the removed medium path no longer samples them.
- D3D11 scene renderer, runtime volumetrics, cloud/fog research, medium/froxel render targets, and the SDF-field renderer plan are shelved and removed from live repo state.
next:
- Extend explicit renderer debug modes for hits, normals, depth, bins, and lighting.
- Replace the current legacy fixed D3D12 pass execution with the declared AquariumRenderPlan graph compiler and executor.
- Keep src/Aquarium.Sample.Minimal building and launchable as the non-Epiphany boundary proof.
- Replace fixed fallback role motion with real CultNet-derived AgentVisualState.
- Build each agent role body from one coherent low-cost SDF form model before adding ornamental or state-reactive detail.
- Prototype cube-sphere projection candidates for Zyphos: tangent warp, fifth-order odd polynomial warp, and COBE/QSC-style bivariate warp. Measure area error, inverse lookup cost, and shader cost before committing the terrain address space.
- Define the first shaped brush envelope contract as a compact-support anisotropic kernel with rotation, radii/inverse covariance, falloff, shape controls, payload type, and explicit bounds shared by 2D terrain brushes and 3D SDF/body brushes.
- Design the first Aquarium IFS/CSG brush DSL as semantic claims plus an ownership tree, informed by VibeGeometry's `vg_grammar` and `vg_csg` tree: the tree is durable design; flattened shader packets are backend output.
- Define the first IFS LOD node-summary and contribution-cache layout before rendering recursive detail: stable domain keys, projected-error scoring, stochastic update priority, mean/variance/confidence estimator state, hysteresis fade weights, resident/missing child states, and debug views for score/uncertainty/sample-age/depth/cache/cost.
- Replace the legacy height-field plane with explicit 2D SDF domain surfaces. Aquarium's Grid should become a dynamic gravity-updated domain surface; Zyphos' terrain surfaces can stay static and should flow through the same cache-friendly surface-domain path.
- Follow the step-by-step roadmap in research/rendering/fractal-brush-architecture-plan.md before implementing recursive terrain or agent-body detail; first slice is cube-face projection harness, shaped 2D brush envelope, semantic claim/tree structs, flattening to the current height brush pass, and debug overlays.
- Begin fractal brush implementation with the first work packet from research/rendering/fractal-brush-implementation-roadmap.md: add Aquarium.Engine.Fractal plus tests, cube-face/tile keys, identity/tangent projection candidates, area distortion sampler, face-edge tests, and a projection report.
- Add diegetic labels and object-local menus after renderer and text contracts are stable.
- Continue replacing legacy fixed D3D12 pass execution with client-declared render targets, cameras, shaders, passes, resources, and features.
next_actions:
- Keep main as the live development branch.
- Keep scripts/verify-boundaries.ps1 green: Aquarium.Engine and Aquarium.Engine.Contracts must not contain Epiphany/client policy nouns such as grid, agent, body, or epiphany.
- Verify publish output after every packaging-affecting change.
- Update AquaSynth.Faust/Core only by packing new versions into packages and changing the pinned PackageReference version deliberately.
- Grow renderer debug controls through the Direct2D/DirectWrite overlay path.
- Use scripts/render-agent-preview.ps1 for multi-view isolated SDF review before asking the user to judge another agent body iteration.
- Follow research/rendering/hdr-pbr-presentation.md before changing HDR exposure, bloom, tonemapping, or display transforms.
- Follow research/rendering/cube-sphere-fractal-brushes.md before replacing planetary terrain addressing, height brushes, or agent/body detail grammars.
- Follow research/rendering/fractal-brush-architecture-plan.md before implementing the fractal brush DSL, IFS LOD cache, recursive detail residency, or learned contribution scoring.
- Use research/rendering/fractal-brush-implementation-roadmap.md as the actionable execution checklist for fractal brush work.
- Follow docs/zyphos-eusocial-sync.md and E:\Projects\Eusocial Interbeing\Eusocial Interbeing\World\Zyphos Simulation Brief.md before turning Zyphos visual choices into setting claims.
- Follow docs/tsr-inspired-taa-spec.md when changing current temporal diagnostics.
- Promote future runtime knobs into typed CultCache documents before they become process folklore.
- Next Face voice slice: replace text-only input with microphone/WebRTC or a native capture bridge, bind endpoint anchors to real Face/body spatial projections instead of manual XY rows, then move the transport contract from Codex JSON-RPC compatibility toward a typed CultNet FaceVoiceSession once Epiphany advertises that surface.
- Keep Aquarium and Epiphany in one repo until the contracts and graph API are stable enough for Epiphany to move out without carrying engine policy or reload folklore with it.