Flow: register the flow keywords, one zone-time value for Zone.Flow and the scroll, presenter phases from zone time, folded scroll, tighter parity

- VolumeSampling registers FLOW_GLOBAL / FLOW_SLOPE with GlobalKeyword.Create (the constructor only looks up).
- FlowField.Scroll folds each Tri3D octave's phase modulo 1 in double (float2, [0,1)); Zone.Flow evaluates at Zone.FlowScroll.
- FlowField.Cycle: the nebula's flow cycle and Stardust's particle lifetime phase come from zone time (_FlowCycle, phase uniform), not _Time.y / Time.time.
- FlowFieldParityVerify reaches the keyword-gated flow(), fails on logged errors, tolerance 3e-4; mutants updated.

Not built or run when committed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-10-13 21:43:41 +02:00
commit 0a3180d386
10 changed files with 178 additions and 55 deletions

View file

@ -11,15 +11,30 @@ using float3 = CultMath.float3;
/// </summary>
public static class FlowField
{
// The scroll offset of the noise field, in field units: speed times zone time and nothing else.
public static float Scroll(FlowSettings settings, double zoneTime) => (float) (settings.GlobalScrollSpeed * zoneTime);
// The second octave of the noise samples at position * Golden (Volumetric.cginc Tri3D).
const float Golden = 1.61803398875f;
// The scroll of the noise field, in field units: speed times zone time, for each of the two octaves, as a phase.
// Every term of Tri3D reaches the scrolled axis through frac, so a phase is only meaningful modulo 1: the fold
// happens here in double, where zone time is exact, and the float that reaches the shaders is in [0, 1) however
// old the zone is. x is the first octave's phase, y the second's (the second octave's axis is scaled by Golden).
public static float2 Scroll(FlowSettings settings, double zoneTime)
{
var scroll = (double) settings.GlobalScrollSpeed * zoneTime;
return float2((float) frac(scroll), (float) frac(scroll * Golden));
}
// The phase of a cycle of `period` seconds at zone time, in [0, 1). The nebula's flow-advected noise cycles and
// Stardust's particle lifetimes take their phase from here, so drift follows sim time and stops with the sim.
public static float Cycle(double zoneTime, float period) => period == 0f ? 0f : (float) frac(zoneTime / period);
// The procedural term (Volumetric.cginc globalFlow): a Tri3D field of position / scale, scrolled along y.
// Skipped when its amplitude is zero, as the shader's FLOW_GLOBAL keyword skips it.
public static float3 Global(FlowSettings settings, float3 position, float scroll)
public static float3 Global(FlowSettings settings, float3 position, float2 scroll)
{
if (settings.GlobalAmplitude == 0f) return float3.zero;
var sample = Tri3D(position / settings.GlobalScale - float3(0f, scroll, 0f)) * settings.GlobalAmplitude;
var field = position / settings.GlobalScale;
var sample = Tri3D(field - float3(0f, scroll.x, 0f), field * Golden - float3(0f, scroll.y, 0f)) * settings.GlobalAmplitude;
sample.y *= .5f;
return sample;
}
@ -37,8 +52,8 @@ public static class FlowField
+ float3(direction.x, 0f, direction.y) * settings.SlopeAmplitude;
}
public static float3 At(FlowSettings settings, float3 position, double zoneTime, float2 downhill) =>
Global(settings, position, Scroll(settings, zoneTime)) + Slope(settings, downhill);
public static float3 At(FlowSettings settings, float3 position, float2 scroll, float2 downhill) =>
Global(settings, position, scroll) + Slope(settings, downhill);
// Volumetric.cginc tri / tri3 / Tri3D, term for term.
static float Tri(float x) => abs(frac(x) - .5f);
@ -46,10 +61,11 @@ public static class FlowField
static float3 Tri3(float3 p) =>
float3(Tri(p.z + Tri(p.y)), Tri(p.z + Tri(p.x)), Tri(p.y + Tri(p.x)));
static float3 Tri3D(float3 p)
// The two octaves' positions are given already scrolled (see Scroll).
static float3 Tri3D(float3 p, float3 pGolden)
{
var t1 = normalize(Tri3(p));
var t2 = normalize(Tri3(p * 1.61803398875f));
var t2 = normalize(Tri3(pGolden));
return cross(t1, t2);
}
}

View file

@ -110,7 +110,7 @@ public class Zone
}
// Zone time at full precision, for the index's orbital keys, which must agree with ChunkPose's own.
internal double ExactTime => _time;
public double ExactTime => _time;
public ZonePack Pack { get; }
public GalaxyZone GalaxyZone { get; }
public Galaxy Galaxy { get; }
@ -696,11 +696,14 @@ public class Zone
public float3 Flow(float3 position)
{
var normal = GetNormal(position.xz);
return FlowField.At(Settings.Flow, position, _time, new float2(normal.x, normal.z));
return FlowField.At(Settings.Flow, position, FlowScroll, new float2(normal.x, normal.z));
}
// The flow's noise scroll at zone time; lowered to the shaders' _FlowScroll.
public float FlowScroll => FlowField.Scroll(Settings.Flow, _time);
// The flow's noise scroll at zone time (Zone.Flow evaluates at exactly this); lowered to the shaders' _FlowScroll.
public float2 FlowScroll => FlowField.Scroll(Settings.Flow, _time);
// The phase of a cycle of `period` seconds at zone time, for presenters that animate on the flow.
public float CyclePhase(float period) => FlowField.Cycle(_time, period);
public static float PowerPulse(float x, float exponent)
{