Add Zyphos planetary demo client

This commit is contained in:
Meta Vens 2026-05-17 23:37:20 +01:00
commit e4c90498a8
13 changed files with 497 additions and 14 deletions

View file

@ -33,6 +33,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Aquarium.Engine.Tests", "te
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Aquarium.Epiphany.AgentPreview", "src\Aquarium.Epiphany.AgentPreview\Aquarium.Epiphany.AgentPreview.csproj", "{F12A367A-8D8E-490D-B60E-3FDBEA3E07E2}"
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Aquarium.Zyphos", "src\Aquarium.Zyphos\Aquarium.Zyphos.csproj", "{801B1913-6AE1-4B8C-8030-4669AC4FE25E}"
EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|Any CPU = Debug|Any CPU
@ -199,6 +201,18 @@ Global
{F12A367A-8D8E-490D-B60E-3FDBEA3E07E2}.Release|x64.Build.0 = Release|Any CPU
{F12A367A-8D8E-490D-B60E-3FDBEA3E07E2}.Release|x86.ActiveCfg = Release|Any CPU
{F12A367A-8D8E-490D-B60E-3FDBEA3E07E2}.Release|x86.Build.0 = Release|Any CPU
{801B1913-6AE1-4B8C-8030-4669AC4FE25E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
{801B1913-6AE1-4B8C-8030-4669AC4FE25E}.Debug|Any CPU.Build.0 = Debug|Any CPU
{801B1913-6AE1-4B8C-8030-4669AC4FE25E}.Debug|x64.ActiveCfg = Debug|Any CPU
{801B1913-6AE1-4B8C-8030-4669AC4FE25E}.Debug|x64.Build.0 = Debug|Any CPU
{801B1913-6AE1-4B8C-8030-4669AC4FE25E}.Debug|x86.ActiveCfg = Debug|Any CPU
{801B1913-6AE1-4B8C-8030-4669AC4FE25E}.Debug|x86.Build.0 = Debug|Any CPU
{801B1913-6AE1-4B8C-8030-4669AC4FE25E}.Release|Any CPU.ActiveCfg = Release|Any CPU
{801B1913-6AE1-4B8C-8030-4669AC4FE25E}.Release|Any CPU.Build.0 = Release|Any CPU
{801B1913-6AE1-4B8C-8030-4669AC4FE25E}.Release|x64.ActiveCfg = Release|Any CPU
{801B1913-6AE1-4B8C-8030-4669AC4FE25E}.Release|x64.Build.0 = Release|Any CPU
{801B1913-6AE1-4B8C-8030-4669AC4FE25E}.Release|x86.ActiveCfg = Release|Any CPU
{801B1913-6AE1-4B8C-8030-4669AC4FE25E}.Release|x86.Build.0 = Release|Any CPU
EndGlobalSection
GlobalSection(SolutionProperties) = preSolution
HideSolutionNode = FALSE
@ -210,5 +224,6 @@ Global
{7564E6C2-FF01-4B5B-8C2B-F9CD796858BA} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
{37363FC6-5AA3-49B4-A3B1-E4AB2CC986EB} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
{F12A367A-8D8E-490D-B60E-3FDBEA3E07E2} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
{801B1913-6AE1-4B8C-8030-4669AC4FE25E} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
EndGlobalSection
EndGlobal

View file

@ -51,6 +51,8 @@ Epiphany client while the client API is still being carved into its final shape:
audio host, and engine-owned assets.
- `src/Aquarium.Epiphany`: Epiphany Aquarium runtime, state interpretation,
render-plan configuration, and agent shaders.
- `src/Aquarium.Zyphos`: planetary-scale rendering demo client with its own
runtime, controls, scene state, and SDF planet shaders.
- `src/Aquarium.Sample.Minimal`: tiny non-Epiphany client that proves the host
can run something other than Epiphany.
@ -89,6 +91,11 @@ repo.
engine boundary honest. It references only `Aquarium.Engine.Contracts`, declares
an `AquariumRenderPlan`, and boots through the same host/client loader path.
`src\Aquarium.Zyphos` is the first nontrivial non-Epiphany demo. It renders a
rotating spherical planet, procedural continents, atmospheric rim light,
night-side city glints, and an orbiting moon through the same host, renderer,
reload, UI, bloom, and SDF proxy machinery used by Epiphany.
For iteration while an Aquarium window is already open, use the dev reload
runner instead of `dotnet run`:
@ -104,6 +111,13 @@ The previous script-owned process is stopped only after the replacement build
succeeds. This keeps MSBuild away from the locked normal `bin\Debug` output
while a live window is still open.
Run a different client project through the same slot machinery with
`-ClientProject`:
```powershell
.\scripts\dev-reload.ps1 -ClientProject src\Aquarium.Zyphos\Aquarium.Zyphos.csproj
```
If the visible dev window was closed but the last slot is still present, reopen
it without rebuilding:
@ -120,6 +134,12 @@ For automatic rebuild/restart on source changes, use the watcher:
.\scripts\dev-watch.ps1
```
Watch a specific client project the same way:
```powershell
.\scripts\dev-watch.ps1 -ClientProject src\Aquarium.Zyphos\Aquarium.Zyphos.csproj
```
The watcher polls source files, waits for writes to settle, builds into a new
slot, and only replaces the running Aquarium after the new build succeeds. If a
build fails, the previous good process keeps running and that same broken source
@ -135,10 +155,11 @@ run the watcher with:
```
Shader edits do not restart the process. The dev watcher fingerprints
`.hlsl`/`.hlsli` files under both the engine and Epiphany shader roots, copies
them into the running apphost slot, and lets the renderer rebuild the active
D3D12 pipelines from its current shader source root. A bad shader edit leaves
the previous working shaders bound and writes the compiler failure to stderr.
`.hlsl`/`.hlsli` files under both the engine and selected client shader roots,
copies them into the running apphost slot, and lets the renderer rebuild the
active D3D12 pipelines from its current shader source root. A bad shader edit
leaves the previous working shaders bound and writes the compiler failure to
stderr.
Epiphany client/runtime code is split into `Aquarium.Epiphany` behind
`Aquarium.Engine.Contracts`. The host loads that client DLL through a collectible

View file

@ -17,8 +17,10 @@ interpretation, camera intent, cursor semantics, agent visual state, diegetic
layout rules, and the render graph configuration that turns Epiphany state into
world pixels.
`Aquarium.Sample.Minimal` exists to keep the split honest. If a feature cannot
be explained without Epiphany, it is not engine API yet.
`Aquarium.Sample.Minimal` exists as the tiny smoke test. `Aquarium.Zyphos`
exists as the first real non-Epiphany demo: a planetary client with its own
runtime, controls, scene state, and SDF shaders. If a feature cannot be
explained without Epiphany or Zyphos, it is not engine API yet.
## Hard Rules

View file

@ -3,6 +3,7 @@ param(
[switch]$NoStop,
[switch]$BuildOnly,
[switch]$Reopen,
[string]$ClientProject = "src\Aquarium.Epiphany\Aquarium.Epiphany.csproj",
[int]$RetainSlots = 12,
[int]$StartupTimeoutSeconds = 5,
[int]$HeadlessTimeoutSeconds = 60
@ -13,7 +14,9 @@ Set-StrictMode -Version Latest
$repoRoot = Resolve-Path (Join-Path $PSScriptRoot "..")
$projectPath = Join-Path $repoRoot "src\Aquarium.Engine\Aquarium.Engine.csproj"
$liveProjectPath = Join-Path $repoRoot "src\Aquarium.Epiphany\Aquarium.Epiphany.csproj"
$liveProjectPath = if ([System.IO.Path]::IsPathRooted($ClientProject)) { $ClientProject } else { Join-Path $repoRoot $ClientProject }
$liveProjectPath = (Resolve-Path $liveProjectPath).Path
$liveAssemblyName = [System.IO.Path]::GetFileNameWithoutExtension($liveProjectPath)
$devRoot = Join-Path $repoRoot "artifacts\dev-reload"
$slotRoot = Join-Path $devRoot "slots"
$visibleStatePath = Join-Path $devRoot "state.clixml"
@ -233,7 +236,7 @@ function Reopen-VisibleProcess {
}
$slotPath = [string]$state.slot
$liveAssemblyPath = Join-Path $slotPath "Aquarium.Epiphany.dll"
$liveAssemblyPath = Join-Path $slotPath "$liveAssemblyName.dll"
if ($state.PSObject.Properties.Name -contains "liveAssembly" -and $state.liveAssembly) {
$liveAssemblyPath = [string]$state.liveAssembly
}
@ -300,7 +303,7 @@ if ($BuildOnly) {
Stop-PreviousOwnedProcess
$exePath = Join-Path $slotPath "Aquarium.Engine.exe"
$liveAssemblyPath = Join-Path $slotPath "Aquarium.Epiphany.dll"
$liveAssemblyPath = Join-Path $slotPath "$liveAssemblyName.dll"
if (-not (Test-Path $exePath)) {
throw "Expected apphost was not produced: $exePath"
}

View file

@ -3,6 +3,7 @@ param(
[switch]$NoInitialLaunch,
[switch]$ReopenWhenClosed,
[switch]$Once,
[string]$ClientProject = "src\Aquarium.Epiphany\Aquarium.Epiphany.csproj",
[int]$IntervalMilliseconds = 1000,
[int]$DebounceMilliseconds = 350,
[int]$RetainSlots = 12,
@ -14,13 +15,16 @@ Set-StrictMode -Version Latest
$repoRoot = Resolve-Path (Join-Path $PSScriptRoot "..")
$reloadScript = Join-Path $PSScriptRoot "dev-reload.ps1"
$liveProjectPath = Join-Path $repoRoot "src\Aquarium.Epiphany\Aquarium.Epiphany.csproj"
$liveProjectPath = if ([System.IO.Path]::IsPathRooted($ClientProject)) { $ClientProject } else { Join-Path $repoRoot $ClientProject }
$liveProjectPath = (Resolve-Path $liveProjectPath).Path
$liveAssemblyName = [System.IO.Path]::GetFileNameWithoutExtension($liveProjectPath)
$clientSourceRoot = Split-Path $liveProjectPath
$watchLogPath = Join-Path $repoRoot "artifacts\dev-reload\watch.log"
$liveSlotRoot = Join-Path $repoRoot "artifacts\dev-reload\live-slots"
$liveReloadPointerPath = Join-Path $repoRoot "artifacts\dev-reload\live-current.txt"
$shaderPath = Join-Path $repoRoot "src\Aquarium.Engine\Render\Shaders\Aquarium.hlsl"
$engineShaderRoot = Join-Path $repoRoot "src\Aquarium.Engine\Render\Shaders"
$clientShaderRoot = Join-Path $repoRoot "src\Aquarium.Epiphany\Shaders"
$clientShaderRoot = Join-Path $clientSourceRoot "Shaders"
$visibleStatePath = Join-Path $repoRoot "artifacts\dev-reload\state.clixml"
$headlessStatePath = Join-Path $repoRoot "artifacts\dev-reload\headless-state.clixml"
$ownedProcessStatePath = if ($Headless) { $headlessStatePath } else { $visibleStatePath }
@ -83,13 +87,13 @@ function Get-ShaderFiles {
function Get-LiveFiles {
Get-SourceFiles | Where-Object {
$_.FullName -like (Join-Path $repoRoot "src\Aquarium.Epiphany\*")
$_.FullName -like (Join-Path $clientSourceRoot "*")
}
}
function Get-RestartFiles {
Get-SourceFiles | Where-Object {
$_.FullName -notlike (Join-Path $repoRoot "src\Aquarium.Epiphany\*")
$_.FullName -notlike (Join-Path $clientSourceRoot "*")
}
}
@ -205,6 +209,7 @@ function Invoke-Reload {
"-NoProfile",
"-ExecutionPolicy", "Bypass",
"-File", $reloadScript,
"-ClientProject", $liveProjectPath,
"-RetainSlots", "$RetainSlots"
)
@ -284,6 +289,7 @@ function Invoke-Reopen {
"-ExecutionPolicy", "Bypass",
"-File", $reloadScript,
"-Reopen",
"-ClientProject", $liveProjectPath,
"-RetainSlots", "$RetainSlots"
)
@ -312,7 +318,7 @@ function Invoke-LiveReload {
throw "client runtime build failed with exit code $LASTEXITCODE."
}
$liveAssemblyPath = Join-Path $liveSlot "Aquarium.Epiphany.dll"
$liveAssemblyPath = Join-Path $liveSlot "$liveAssemblyName.dll"
if (-not (Test-Path $liveAssemblyPath)) {
throw "Expected client runtime assembly was not produced: $liveAssemblyPath"
}

View file

@ -0,0 +1,21 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<AssemblyName>Aquarium.Zyphos</AssemblyName>
<RootNamespace>Aquarium.Zyphos</RootNamespace>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="..\Aquarium.Engine.Contracts\Aquarium.Engine.Contracts.csproj" />
</ItemGroup>
<ItemGroup>
<Content Include="Shaders\**\*.hlsl" CopyToOutputDirectory="PreserveNewest" TargetPath="Render\Shaders\%(RecursiveDir)%(Filename)%(Extension)" />
<Content Include="Shaders\**\*.hlsli" CopyToOutputDirectory="PreserveNewest" TargetPath="Render\Shaders\%(RecursiveDir)%(Filename)%(Extension)" />
</ItemGroup>
</Project>

View file

@ -0,0 +1,48 @@
static const int SDF_INDEX = 1;
#include "D3D12SdfCommon.hlsli"
#include "D3D12SdfMath.hlsli"
float zyMoonRelief(float3 dir)
{
float ridges =
sin(dir.x * 15.0 + dir.y * 4.0) * 0.018 +
sin(dir.y * 21.0 - dir.z * 7.0) * 0.012 +
sin((dir.x + dir.y + dir.z) * 34.0) * 0.006;
float craterA = 1.0 - smoothstep(0.055, 0.115, abs(length(dir.xy - float2(0.22, -0.18)) - 0.32));
float craterB = 1.0 - smoothstep(0.040, 0.090, abs(length(dir.yz - float2(0.30, 0.24)) - 0.22));
return ridges - (craterA * 0.035 + craterB * 0.026);
}
float sdfDistance(float3 p, int sdfIndex)
{
SdfObject sdfObject = sdfObjects[sdfIndex];
float radius = max(sdfObject.state.x, 0.001);
float3 local = p - sdfObject.centerRadius.xyz;
float3 dir = normalize(local);
return length(local) - (radius + zyMoonRelief(dir));
}
SdfSurface sdfSurface(float3 p, int sdfIndex)
{
SdfObject sdfObject = sdfObjects[sdfIndex];
float3 dir = normalize(p - sdfObject.centerRadius.xyz);
float relief = zyMoonRelief(dir);
float dust = sin(dir.x * 31.0 + dir.y * 17.0 - dir.z * 11.0) * 0.5 + 0.5;
SdfSurface surface;
surface.baseColor = lerp(float3(0.31, 0.30, 0.28), float3(0.66, 0.62, 0.54), dust);
surface.baseColor = lerp(surface.baseColor, float3(0.20, 0.20, 0.19), saturate(-relief * 18.0));
surface.metallic = 0.0;
surface.roughness = 0.92;
surface.emission = 0.0;
return surface;
}
float3 shadeSdf(float2 uv, float travel, float3 p, float3 normal, int sdfIndex, SdfSurface surface)
{
float3 sunDirection = normalize(float3(-0.46, -0.72, 0.52));
float daylight = saturate(dot(normal, sunDirection) * 0.82 + 0.24);
return shadeSdfPbr(p, normal, surface) * daylight;
}
#include "D3D12SdfProxy.hlsli"

View file

@ -0,0 +1,96 @@
static const int SDF_INDEX = 0;
#include "D3D12SdfCommon.hlsli"
#include "D3D12SdfMath.hlsli"
float3 zyRotateZ(float3 p, float angle)
{
float s = sin(angle);
float c = cos(angle);
return float3(c * p.x - s * p.y, s * p.x + c * p.y, p.z);
}
float3 zyPlanetDir(float3 local, SdfObject sdfObject)
{
return normalize(zyRotateZ(local, -sdfObject.state.y));
}
float zySphericalField(float3 dir)
{
float latitude = asin(saturate(abs(dir.z)) * 2.0 - 1.0);
float longitude = atan2(dir.y, dir.x);
float plates =
sin(longitude * 2.0 + dir.z * 4.5) * 0.28 +
sin(longitude * 3.0 - dir.z * 7.0 + 1.7) * 0.22 +
sin((dir.x + dir.y * 0.7 + dir.z * 0.4) * 8.0) * 0.16 +
sin((dir.x * 1.3 - dir.y + dir.z * 1.9) * 13.0) * 0.08;
float equatorialWarmth = cos(latitude) * 0.18;
return 0.50 + plates + equatorialWarmth;
}
float zyTerrainOffset(float3 dir, SdfObject sdfObject)
{
float field = zySphericalField(dir);
float seaLevel = sdfObject.state.z;
float land = smoothstep(seaLevel - 0.04, seaLevel + 0.08, field);
float mountain = pow(saturate(field - seaLevel), 1.65);
float polarCap = pow(abs(dir.z), 8.0) * 0.035;
return (field - seaLevel) * 0.10 + mountain * 0.13 + polarCap * land;
}
float sdfDistance(float3 p, int sdfIndex)
{
SdfObject sdfObject = sdfObjects[sdfIndex];
float planetRadius = max(sdfObject.state.x, 0.001);
float3 local = p - sdfObject.centerRadius.xyz;
float3 dir = zyPlanetDir(local, sdfObject);
return length(local) - (planetRadius + zyTerrainOffset(dir, sdfObject));
}
SdfSurface sdfSurface(float3 p, int sdfIndex)
{
SdfObject sdfObject = sdfObjects[sdfIndex];
float3 local = p - sdfObject.centerRadius.xyz;
float3 dir = zyPlanetDir(local, sdfObject);
float field = zySphericalField(dir);
float seaLevel = sdfObject.state.z;
float land = smoothstep(seaLevel - 0.03, seaLevel + 0.06, field);
float mountain = smoothstep(seaLevel + 0.12, seaLevel + 0.28, field);
float polar = smoothstep(0.72, 0.92, abs(dir.z));
float cloud = smoothstep(0.73, 0.91, sin(dir.x * 18.0 + dir.y * 13.0 + dir.z * 9.0 + timeSeconds * 0.19) * 0.5 + 0.5);
float3 ocean = lerp(float3(0.004, 0.070, 0.130), float3(0.010, 0.220, 0.330), saturate(field));
float3 lowland = float3(0.070, 0.300, 0.185);
float3 highland = float3(0.540, 0.405, 0.220);
float3 snow = float3(0.800, 0.865, 0.830);
float3 landColor = lerp(lowland, highland, mountain);
landColor = lerp(landColor, snow, saturate(polar + mountain * 0.38));
SdfSurface surface;
surface.baseColor = lerp(ocean, landColor, land);
surface.baseColor = lerp(surface.baseColor, float3(0.78, 0.84, 0.80), cloud * 0.16);
surface.metallic = 0.0;
surface.roughness = lerp(0.34, 0.84, land);
surface.emission = 0.0;
return surface;
}
float3 shadeSdf(float2 uv, float travel, float3 p, float3 normal, int sdfIndex, SdfSurface surface)
{
SdfObject sdfObject = sdfObjects[sdfIndex];
float3 dir = zyPlanetDir(p - sdfObject.centerRadius.xyz, sdfObject);
float3 viewDirection = normalize(cameraPosition - p);
float3 sunDirection = normalize(float3(-0.46, -0.72, 0.52));
float daylight = saturate(dot(normal, sunDirection) * 0.74 + 0.34);
float night = saturate(-dot(normal, sunDirection) * 1.7 - 0.20);
float citySeed = sin(dir.x * 43.0 + sin(dir.y * 19.0) * 4.0 + dir.z * 31.0);
float cityWeb = smoothstep(0.82, 0.96, citySeed * 0.5 + 0.5);
float coast = 1.0 - smoothstep(0.020, 0.070, abs(zySphericalField(dir) - sdfObject.state.z));
float fresnel = pow(1.0 - saturate(dot(normal, viewDirection)), 3.2);
float3 city = float3(1.0, 0.54, 0.14) * cityWeb * coast * night * 1.25;
float3 atmosphere = float3(0.07, 0.38, 0.78) * (fresnel * 1.35 + pow(fresnel, 6.0) * 2.6);
return shadeSdfPbr(p, normal, surface) * daylight + city + atmosphere;
}
#include "D3D12SdfProxy.hlsli"

View file

@ -0,0 +1,34 @@
using Aquarium.Engine.Render;
namespace Aquarium.Zyphos;
public static class ZyphosRenderPlan
{
public const int PlanetIndex = 0;
public const int MoonIndex = 1;
public const int SdfObjectCount = 2;
public static AquariumRenderPlan Create()
{
var app = new AquariumApp();
app.Shaders
.Core("D3D12HeightField.hlsl", "D3D12Scene.hlsl", "D3D12Post.hlsl")
.SdfShader("D3D12ZyphosPlanet.hlsl")
.SdfShader("D3D12ZyphosMoon.hlsl");
var heightField = app.RenderTargets.Create("height-field")
.FixedSize(128, 128)
.Format(RenderFormat.R16Float)
.Register();
var scene = app.RenderTargets.Hdr("scene");
app.Cameras.Orbit("main");
app.Graph.Pass("height-field").Fullscreen();
app.Graph.Pass("scene").Fullscreen();
app.Graph.Pass("sdf-proxies").Proxy();
app.Features.Bloom(scene.Color);
app.Features.Presentation(scene.Color);
app.Features.DirectWriteOverlay();
app.Debug.View("Height Field", heightField).View("Scene", scene.Color);
return app.Plan;
}
}

View file

@ -0,0 +1,133 @@
using System.Numerics;
using Aquarium.Engine;
using Aquarium.Engine.Audio;
using Aquarium.Engine.Input;
using Aquarium.Engine.Render;
using Aquarium.Engine.Ui;
namespace Aquarium.Zyphos;
public sealed class ZyphosRuntime : IAquariumRuntime
{
private float timeSeconds;
private float previousTimeSeconds;
private float orbitYaw = -0.28f;
private float orbitPitch = 0.34f;
private float orbitDistance = 15.6f;
private float timeScale = 1.0f;
private bool autoOrbit = true;
public AquariumRuntimeOptions Options { get; private set; }
public GraphicsSettings GraphicsSettings { get; set; } = new(0, 1.08f, 0.32f, 0.05f);
public AquariumRenderPlan RenderPlan { get; } = ZyphosRenderPlan.Create();
public AquariumUiDocument Ui { get; }
public AquariumSynthDocument Synth { get; } = AquariumSynthDocument.Empty;
public AquariumFrame Frame => new(
new ViewFrame(Vector2.Zero, 32.0f),
CameraPosition(),
timeSeconds,
Vector2.Zero,
ZyphosSceneBuilder.Build(timeSeconds, previousTimeSeconds));
public ZyphosRuntime()
{
Ui = new AquariumUiDocument()
.Panel("Zyphos", 18.0f, 82.0f, 340.0f, panel =>
{
panel.Section("Planetary Demo");
panel.Toggle("Auto Orbit", () => autoOrbit, value => autoOrbit = value);
panel.Slider("Time Scale", () => timeScale, value => timeScale = value, 0.0f, 4.0f, "0.00");
panel.Slider("Orbit Distance", () => orbitDistance, value => orbitDistance = value, 9.0f, 24.0f, "0.0");
panel.Readout("Runtime", () => $"{timeSeconds:0.0}s");
panel.Readout("Camera", () => $"{orbitDistance:0.0} wu / yaw {orbitYaw:0.00}");
panel.Readout("Objects", () => "spherical terrain, atmosphere, moon");
})
.Command("zyphos", _ => "Zyphos: planetary-scale client demo loaded.", "Report Zyphos demo status.");
}
public AquariumFrame ComposeFrame(AquariumFrame frame, AquariumFrameInput input)
{
return frame;
}
public void Start()
{
Console.WriteLine("Zyphos planetary demo booted.");
}
public void Update(float deltaSeconds, InputState input)
{
previousTimeSeconds = timeSeconds;
var safeDelta = Math.Max(deltaSeconds, 0.0f);
timeSeconds += safeDelta * MathF.Max(timeScale, 0.0f);
if (autoOrbit)
{
orbitYaw += safeDelta * 0.055f;
}
if (input.IsKeyDown(KeyCode.A))
{
orbitYaw -= safeDelta * 0.85f;
}
if (input.IsKeyDown(KeyCode.D))
{
orbitYaw += safeDelta * 0.85f;
}
if (input.IsKeyDown(KeyCode.W))
{
orbitPitch += safeDelta * 0.45f;
}
if (input.IsKeyDown(KeyCode.S))
{
orbitPitch -= safeDelta * 0.45f;
}
if (MathF.Abs(input.WheelDelta) > 0.0f)
{
orbitDistance = Math.Clamp(orbitDistance - input.WheelDelta * 0.8f, 8.0f, 26.0f);
}
orbitPitch = Math.Clamp(orbitPitch, 0.12f, 0.86f);
}
public void FlushState()
{
}
public void Dispose()
{
}
internal void SetOptions(AquariumRuntimeOptions options)
{
Options = options;
}
private Vector3 CameraPosition()
{
var horizontal = MathF.Cos(orbitPitch) * orbitDistance;
return new Vector3(
MathF.Sin(orbitYaw) * horizontal,
-MathF.Cos(orbitYaw) * horizontal,
MathF.Sin(orbitPitch) * orbitDistance + 3.1f);
}
}
public sealed class ZyphosRuntimeFactory : IAquariumRuntimeFactory
{
public IAquariumRuntime Create(AquariumRuntimeOptions options)
{
var runtime = new ZyphosRuntime();
runtime.SetOptions(options);
return runtime;
}
}

View file

@ -0,0 +1,87 @@
using System.Numerics;
using Aquarium.Engine.Render;
namespace Aquarium.Zyphos;
public static class ZyphosSceneBuilder
{
private const float PlanetSurfaceRadius = 3.8f;
private const float PlanetBoundRadius = 4.52f;
private const float MoonSurfaceRadius = 0.54f;
private const float MoonBoundRadius = 0.70f;
public static AquariumSceneState Build(float timeSeconds, float previousTimeSeconds)
{
return new AquariumSceneState
{
HeightFieldBrushes = BuildHeightFieldBrushes(),
SdfObjects = BuildSdfObjects(timeSeconds, previousTimeSeconds),
SdfLights = BuildSdfLights(timeSeconds),
};
}
private static AquariumHeightFieldBrush[] BuildHeightFieldBrushes()
{
return
[
new AquariumHeightFieldBrush(
Vector2.Zero,
30.0f,
2.6f,
-0.18f,
0.03f,
1.9f,
0.22f,
1.1f)
];
}
private static AquariumSdfObject[] BuildSdfObjects(float timeSeconds, float previousTimeSeconds)
{
var planetCenter = new Vector3(0.0f, 0.0f, PlanetSurfaceRadius + 0.48f);
var rotation = timeSeconds * 0.032f;
var previousRotation = previousTimeSeconds * 0.032f;
var moonCenter = MoonCenter(timeSeconds);
var previousMoonCenter = MoonCenter(previousTimeSeconds);
var objects = new AquariumSdfObject[ZyphosRenderPlan.SdfObjectCount];
objects[ZyphosRenderPlan.PlanetIndex] = new AquariumSdfObject(
new Vector4(planetCenter, PlanetBoundRadius),
new Vector4(planetCenter, 0.0f),
new Vector4(PlanetSurfaceRadius, rotation, 0.56f, previousRotation));
objects[ZyphosRenderPlan.MoonIndex] = new AquariumSdfObject(
new Vector4(moonCenter, MoonBoundRadius),
new Vector4(previousMoonCenter, 0.0f),
new Vector4(MoonSurfaceRadius, timeSeconds * 0.11f, PlanetSurfaceRadius, 0.0f));
return objects;
}
private static AquariumSdfLight[] BuildSdfLights(float timeSeconds)
{
var sunPhase = timeSeconds * 0.015f;
var sunCenter = new Vector3(
-12.0f + MathF.Sin(sunPhase) * 2.4f,
-18.0f,
11.0f + MathF.Cos(sunPhase * 0.7f) * 1.3f);
return
[
new AquariumSdfLight(
new Vector4(sunCenter, 5.5f),
new Vector4(8.6f, 7.9f, 6.7f, -100.0f)),
new AquariumSdfLight(
new Vector4(0.0f, 0.0f, PlanetSurfaceRadius + 0.48f, 4.0f),
new Vector4(0.10f, 0.18f, 0.28f, -101.0f))
];
}
private static Vector3 MoonCenter(float timeSeconds)
{
var orbit = timeSeconds * 0.075f + 1.3f;
var radius = 6.35f;
return new Vector3(
MathF.Cos(orbit) * radius,
MathF.Sin(orbit) * radius * 0.62f,
PlanetSurfaceRadius + 0.62f + MathF.Sin(orbit * 0.73f) * 1.2f);
}
}

View file

@ -108,4 +108,6 @@
{"timestamp":"2026-05-14T15:32:00+01:00","topic":"life-balanced-whorl-domain","lesson":"Life needs both sides of the nautilus grammar: a log-spiral whorl solve must physically shape the shell, but it cannot be the only body authority or the form collapses into a hollow C-shell. Union the whorl with a smaller same-domain backing mass, then derive aperture lip, chamber gold, ember reveal, raised ribs, and pearl beads from the shared spiral/aperture fields.","files":["src/Aquarium.Epiphany/Shaders/D3D12LifeAgent.hlsl","state/life-agent-sdf-notes.md","state/evidence.jsonl"],"source":"user rejected the egg lineage and required repeated restart until the spiral shell manifests as geometry"}
{"timestamp":"2026-05-14T16:31:00+01:00","topic":"life-curve-first-build","lesson":"When rebuilding Life, do not start by tuning the full organ. First make the log-spiral domain read as a naked curve: ember at the core, roughly two revolutions, and the wide mouth-side lip termination. Only after that curve reads should shell inflation, aperture carving, ember reveal, ribs, and pearl beads be layered back on the same solved domain.","files":["src/Aquarium.Epiphany/Shaders/D3D12LifeAgent.hlsl","state/life-agent-sdf-notes.md","state/evidence.jsonl"],"source":"user corrected the iteration process: build the log spiral one step at a time instead of doing everything at once"}
{"lesson":"Shader hot reload edits must update the running process slot Render/Shaders files so D3D12Renderer can rebuild pipelines from its existing shader source root. Client assembly live reload does not change renderer shaderSourceRoot, so treating .hlsl/.hlsli edits as assembly reloads leaves the renderer watching stale slot files.","timestamp":"2026-05-15T17:48:35.6220956+01:00","files":["scripts/dev-watch.ps1","src/Aquarium.Engine/Render/D3D12Renderer.cs"],"topic":"shader-hot-reload-slot-transport"}
{"timestamp":"2026-05-17T23:28:00+01:00","topic":"non-epiphany-demo-client","lesson":"A reusable Aquarium engine boundary needs a real non-Epiphany client, not only a minimal smoke sample. Zyphos exercises the same host, reload transport, UI, bloom, and SDF proxy path with its own planetary scene and shader domain, while dev-reload/dev-watch accept -ClientProject so client selection stays tooling-owned instead of hardcoded Epiphany lore.","files":["src/Aquarium.Zyphos/Aquarium.Zyphos.csproj","src/Aquarium.Zyphos/ZyphosRuntime.cs","scripts/dev-reload.ps1","scripts/dev-watch.ps1","README.md"],"source":"user asked for a real planetary-scale demo named Zyphos to support the Aquarium/Epiphany split"}
{"timestamp":"2026-05-17T23:32:49+01:00","topic":"cube-sphere-fractal-brush-research","lesson":"Planetary terrain should use a cube-sphere/QSC-family six-face quadtree domain instead of lat-long; projection candidates should be measured rather than assumed, with tangent, fifth-order odd polynomial, and COBE/QSC-style bivariate warps as the first comparison set. Multiscale terrain and agent/body detail should converge on bounded IFS brush grammars with compact-support anisotropic shaped Gaussian-style envelopes, borrowing covariance/binning/LOD discipline from EWA and 3D Gaussian splatting without importing unbounded Gaussian cost or radiance-field machinery by default.","files":["research/rendering/cube-sphere-fractal-brushes.md","state/map.yaml","state/memory.json","state/scratch.md"],"sources":["https://proj.org/en/stable/operations/projections/qsc.html","https://ntrs.nasa.gov/citations/19810002572","https://jcgt.org/published/0007/02/01/paper.pdf","https://arxiv.org/abs/2308.04079","https://experts.illinois.edu/en/publications/sphere-tracing-a-geometric-method-for-the-antialiased-ray-tracing/","https://vcg.seas.harvard.edu/publications/20011001-ewa-volume-splatting"]}

View file

@ -41,6 +41,14 @@ current_model:
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:
@ -59,6 +67,7 @@ current_model:
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.
@ -90,6 +99,9 @@ renderer_state:
- 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:
@ -98,6 +110,8 @@ renderer_state:
- 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.
@ -109,6 +123,7 @@ next_actions:
- 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.