experiment: LivingPlane - GPU wave-equation height field reacting to a moving sphere (L162)

Standalone EGL/OpenGL 4.3 compute runner (runtime GLSL, no shader compiler needed), ping-pong height/velocity field,
damped wave + foundation spring + Gaussian sphere push + optional breathing, vertex-displaced render to PNG.
Independent of generation. Intel ADL GT2: ~0.08 ms/step at 512^2, ~0.29 ms/step at 1024^2 (wall-time difference).
.gitignore now allows Experiments/.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016dhxM43dnWvUu2B5Ph1iG1

.gitignore

@@ -15,6 +15,10 @@
 /Standalone/Build/
 /Standalone/bin/
 
+# Research and prototype experiments.
+!/Experiments/
+!/Experiments/**
+
 # The guarded single-entry test harness is source, not generated output.
 !/Tools/
 !/Tools/**

Experiments/LivingPlane/REPORT.md

@@ -0,0 +1,62 @@
+# L162 — Living Plane
+
+The EGL/OpenGL 4.3 runner builds and passes its llvmpipe correctness and frame checks. The sandbox has no accessible DRM render node, so it did not run or report Intel GPU performance. The runner refuses `--device=gpu` here instead of falling back to software.
+
+## Implementation
+
+`LivingPlane.cpp` runs a ping-pong `RG32F` height/velocity field through a runtime-compiled GLSL compute shader. The damped wave update includes a weak foundation spring, a Gaussian sphere push, and an optional slow breathing force. The spring is needed because a persistent local push otherwise accelerates the zero-frequency height mode and sinks the whole plane. The sphere moves across the plane, stops, and bobs. A vertex-displaced mesh and lit sphere render to an EGL pbuffer-backed framebuffer and save as PNGs.
+
+The timestep is selected from the largest 2D grid eigenfrequency:
+
+`dt = 1.30 / sqrt(8*c*c/(dx*dx) + foundationStiffness)`
+
+The resulting spectral step ratio is 1.30, below the explicit update's 2.0 stability limit. The runner warms the compute kernel for eight unmeasured dispatches, then records one `GL_TIME_ELAPSED` query per requested simulation step in `timing.json`.
+
+The first-step equation audit also caught a GL state error during bring-up: frame rendering left the graphics program active before the next compute dispatch. `Dispatch` now binds the compute program before every step, so the audit fails if a frame silently stops simulation.
+
+Device selection enumerates EGL devices and uses `EGL_EXT_platform_device` for an accessible Intel render node first. On this host, the known integrated device is Intel on `renderD128`. Automatic mode falls back to a surfaceless Mesa context with `LIBGL_ALWAYS_SOFTWARE=1`; explicit GPU mode fails when no accessible hardware node is present. EGL does not expose Vulkan's integrated/discrete enum, so Intel vendor/render-node identity is the selection heuristic.
+
+The Unreal handoff is in [UNREAL-MAPPING.md](UNREAL-MAPPING.md). It keeps the prototype render-only and describes the density mapping if the surface later needs to affect voxel queries. No Unreal `Source/` files changed.
+
+## Measurements and checks
+
+- Built with `Experiments/LivingPlane/build.sh` using the installed EGL, desktop GL, and libpng development files; no shader compiler or package install was needed.
+- Final llvmpipe run: 128² field, 360 steps, `dt=9.56814 ms`, spectral ratio 1.30. The first-step equation audit and finite-field/dynamics audit passed. Final field range was −0.139533 m to +0.0366704 m. It wrote 16 128×128 PNGs and a JSON file containing 360 per-step query samples. The frames were inspected; the moving sphere and wake are visible.
+- Auto-selection smoke check: 32², 12 steps; selected llvmpipe and passed both audits. Breathing smoke check: 64², 180 steps with `--breathing=on`; passed both audits.
+- Negative device-selection control: `--device=gpu` returned an error because the sandbox has no accessible EGL DRM render node.
+- Existing fast verification tier passed: 278.9 seconds, ending in `SUMMARY PASS`. Its build and logs are under `Saved/Linux/l162/verify/` and `Saved/Linux/l162/`.
+- The llvmpipe `GL_TIME_ELAPSED` samples are preserved in JSON but are software-driver query values, not GPU timings. The requested hardware timing pass remains to be run outside the sandbox.
+- No Unreal build was run; no Unreal `Source/` files changed.
+
+## Intel GPU pass
+
+Run these from the plugin root as `jahni`. The frame run writes 512×512 PNGs to `Saved/Linux/l162/gpu-frames-512/`; the two timing runs write `timing.json` with one GPU query per step and skip PNG capture. They still read the field for the first-step and final-state correctness audits.
+Before the timing runs, check `uptime` and run them on a quiet machine (load below about 1.5, with no other build active).
+
+```sh
+uptime
+taskset -c 0-11 prlimit --as=6442450944 -- timeout 1740s ./Saved/Linux/l162/living-plane --device=gpu --size=512 --steps=1800 --capture-every=12 --out=Saved/Linux/l162/gpu-frames-512
+taskset -c 0-11 prlimit --as=6442450944 -- timeout 1740s ./Saved/Linux/l162/living-plane --device=gpu --size=512 --steps=1800 --capture-every=0 --out=Saved/Linux/l162/gpu-timing-512
+taskset -c 0-11 prlimit --as=6442450944 -- timeout 1740s ./Saved/Linux/l162/living-plane --device=gpu --size=1024 --steps=1800 --capture-every=0 --out=Saved/Linux/l162/gpu-timing-1024
+```
+
+Encode the captured sequence as MP4 with:
+
+```sh
+ffmpeg -y -framerate 30 -i Saved/Linux/l162/gpu-frames-512/frame_%06d.png -c:v libx264 -pix_fmt yuv420p Saved/Linux/l162/living-plane-512.mp4
+```
+
+## Files and remaining risk
+
+The only changed file outside `Experiments/LivingPlane/` is `.gitignore`, which now allows `Experiments/` and its contents. GPU timings and Intel render-node selection remain unverified until the commands above run on the host outside this sandbox.
+
+## Intel GPU pass (run by the orchestrator outside the sandbox, 2026-11-02)
+
+- The device was selected correctly: `Mesa Intel(R) Graphics (ADL GT2)`, OpenGL 4.6, `/dev/dri/renderD128`. 512²,
+  1,800 steps, 151 frames; the equation audit passes. MP4: `Saved/Linux/l162/living-plane-512.mp4` (local).
+- **The `GL_TIME_ELAPSED` per-dispatch values (~0.0001 ms) are not credible** for 262k cells, so they aren't
+  reported as timings.
+- Wall-time difference between 1,800 and 200 steps, divided by the 1,600 steps (start-up cancels out; this includes
+  submission, so it's an upper bound): **0.080 ms/step at 512²** and **0.292 ms/step at 1024²**.
+- Visual read: the effect is very subtle in the current render (a slight dip under the sphere, faint rings). It needs
+  a larger push amplitude, grazing light or height colouring, and a closer camera to read.

Experiments/LivingPlane/UNREAL-MAPPING.md

@@ -0,0 +1,23 @@
+# Unreal mapping note
+
+The prototype stores a two-channel height and vertical-velocity field in a pair of
+`RG32F` textures. A world-owned Unreal component could keep equivalent transient
+render graph textures and advance them with a compute pass. It should own simulation
+time and clear or restore its buffers when the world is recreated.
+
+The sphere path becomes a world-space interaction event: position, contact radius,
+and impulse strength are supplied to the compute pass. For multiplayer or deterministic
+replay, replicate the compact events and simulation tick, or record the resulting field;
+do not assume that independent GPU floating-point runs will produce byte-identical
+textures.
+
+The rendered top surface can remain a render-only displaced mesh. If it must participate
+in voxel collision or queries, its height must also reach the density evaluator. For a
+height `h(x,y)`, the plugin's density convention is negative inside solid and positive
+in air, so the plane's signed density is `z - h(x,y)`. Keep this calculation in metres
+until the existing voxel/Core boundary converts with the active voxel size (25 cm by
+default); do not mix metre distances and voxel counts in the wave solver.
+
+The current sample is an isolated visual field. Wiring this into `AVoxelWorld` would
+need an explicit owner for simulation lifetime, collision/update cadence, save/load,
+and the replication policy before it could affect shipped terrain.

Experiments/LivingPlane/build.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+PLUGIN_ROOT="$(cd -- "${SCRIPT_DIR}/../.." && pwd)"
+OUTPUT_DIR="${PLUGIN_ROOT}/Saved/Linux/l162"
+CXX="${CXX:-g++}"
+
+command -v "${CXX}" >/dev/null || { echo "C++ compiler not found: ${CXX}" >&2; exit 2; }
+pkg-config --exists egl gl libpng || {
+    echo "EGL, desktop OpenGL, and libpng development files are required" >&2
+    exit 2
+}
+mkdir -p "${OUTPUT_DIR}"
+read -r -a GRAPHICS_FLAGS <<<"$(pkg-config --cflags --libs egl gl libpng)"
+
+taskset -c 0-11 prlimit --as=6442450944 -- \
+    "${CXX}" -std=c++20 -O2 -g -Wall -Wextra -Wpedantic \
+    "${SCRIPT_DIR}/LivingPlane.cpp" -o "${OUTPUT_DIR}/living-plane" \
+    "${GRAPHICS_FLAGS[@]}"
+
+echo "built ${OUTPUT_DIR}/living-plane"