feat(examples): add gn-sim-fountain

[TMHSDigital]

Summary

Adds examples/gn-sim-fountain/ — the first flagship example from the ROADMAP candidate pool. A two-tier stone fountain whose 20 jets are integrated by a Geometry Nodes Simulation Zone using the exact constant-gravity update (p += v·dt − ½g·dt²ẑ; v −= g·dt·ẑ), so every stepped frame must land on the closed-form arc p₀ + v₀t − ½gt².

Selection rationale: flagship tier is the top priority in the pool; the last ten PRs were showcase pieces, so an uncovered API contract added more value. No open PRs or feat/examples-* branches collided.

API contract witnessed

A Simulation Zone only advances when the scene steps one frame at a time. Two silent traps, identical on 4.5.11, 5.1.2 and 5.2.1 (the 4.x-vs-5.x divergence the roadmap entry anticipated does not exist; documented in the README):

• frame_set(start) → frame_set(N) with no cache runs one step (dt = 1/fps): frame 25 shows the frame-2 state, 1.68–2.42 m off the true arc.
• simulation_nodes_cache_calculate_to_frame(selected=True) fails its poll headless, logs Invalid operator call, returns {'PASS_THROUGH'} without raising, and frames between cached endpoints read as linear interpolation.
• simulation_nodes_cache_bake(selected=True) under temp_override bakes PACKED in memory; random-access reads are then exact.

Falsifiers — live-run-proven on all three binaries

Flag	Breaks	Target check	Exit	Measured
--unpair	Simulation Input never paired	one point per jet	3	0 points
--euler	drops −½g·dt² term	stepped frames on closed-form arc	4	0.2044 m (= g·dt·t/2 at t=1 s)
--prebake-trap	bakes before the jump	unbaked jump runs one step	5	one-step err 2.42 m, gap 0.000 m
--calc-to-frame	cache via calculate_to_frame	baked random access	6	PASS_THROUGH, 2.4155 m / 9.4013 m/s

Exit-code matrix — live-run-proven

Binaries: .scratch/blender-4.5.11-windows-x64/blender.exe (reports 4.5.11 LTS), .scratch/blender-5.1.2-windows-x64/blender.exe (5.1.2), .scratch/blender-5.2.1-windows-x64/blender.exe (5.2.1 LTS).

Run	4.5.11	5.1.2	5.2.1
default	0	0	0
--unpair	3	3	3
--euler	4	4	4
--prebake-trap	5	5	5
--calc-to-frame	6	6	6
tests/smoke/run_example.py	PASS	PASS	PASS
--output render (framing gate)	0	—	0

Measured on every version: stepped worst 6.57e-7 m / 1.43e-6 m/s; baked random access worst 5.62e-7 m (TOL 1e-4, stated and justified in README).

Visual

• Contact sheet: docs/gallery/contact-sheets/gn-sim-fountain-contact-sheet.webp (vs armature-bend, damped-track-aim, bmesh-gear).
  • Stage darkness: 0.191 vs 0.145–0.213 — pass
  • Mean luminance: 0.267 vs 0.151–0.279 — pass
  • Subject fill: framing gate x=0.575 y=0.839, margins ≥0.044 — pass
  • Saturation: 0.215 vs 0.144–0.250 — pass
  • Wedge warmth: +0.117 vs +0.277/+0.303 (armature-bend −0.428) — lower, because the lower half is dominated by cyan droplets and teal water; the warm pool sits upper-right on the wall as in bmesh-gear. Judged not the odd one out.
  • Thumbnail legibility: fountain arcs read instantly — pass
• Render is proof: every droplet bead is a recorded stepped position; the thin line each string is threaded on is the closed-form arc drawn from launch data. The --euler 0.20 m drift is computed (that flag exits before render), not a rendered still.
• Renders inspected by eye on 5.2.1 and 4.5.11 (identical). Issues fixed during iteration: rim light mis-aimed at the back wall, water mirroring the rim as a pale sheet, floor/wall seam behind the arcs (now in shadow).
• Asset sheet: not applicable — a simulation contract example, not a game-prop/kit asset (inspection-only judgment).

Validation — live-run-proven locally

Counts (60 examples), plugin manifest, exit-code README tables, engine-id, falsifier targets, harness unit tests, structure/frontmatter, gallery image sizes. Gallery regenerated with scripts/build_gallery.py; generated alt and witness callout read in docs/gallery/index.html and docs/gallery/gn-sim-fountain/index.html. CI-proven pending: gallery-no-drift step, smoke 5.2/4.5 (+5.1 via needs-5.1).

🤖 Generated with Claude Code