129 lines
11 KiB
YAML
129 lines
11 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
|
|
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
|
|
hdr_pbr_presentation: research/rendering/hdr-pbr-presentation.md
|
|
cube_sphere_fractal_brushes: research/rendering/cube-sphere-fractal-brushes.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.
|
|
- 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.
|
|
- 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, and an orbiting moon.
|
|
- 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.
|
|
- 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.
|
|
- 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.
|
|
- 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 docs/tsr-inspired-taa-spec.md when changing current temporal diagnostics.
|
|
- Promote future runtime knobs into typed CultCache documents before they become process folklore.
|
|
- 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.
|