Flow field: FlowField owns the global flow, Zone.Flow evaluates it at zone time, VolumeSampling.LowerFlow lowers it

FlowField (ServerShared) is the flow law; Zone.Flow/FlowScroll read PlanetSettings.Flow at zone
time. The Flow block moves from DefaultEnvironment to PlanetSettings (ZoneEnvironment key 1 is
retired), VolumeSampling's frame-clock scroll accumulator and the Stardust leftover field are
deleted, and slopeFlow returns 0 for a zero gradient. Unity parity probe follows in the next
commit; this commit has not been built in Unity.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-10-13 20:06:35 +02:00
commit e8ec8e903c
9 changed files with 248 additions and 18 deletions

View file

@ -9,7 +9,7 @@ using float2 = CultMath.float2;
public class ZoneEnvironment
{
[JsonProperty("nebula"), Key(0)] public NebulaSettings Nebula;
[JsonProperty("flow"), Key(1)] public FlowSettings Flow;
// Key 1 is retired (it held the flow, now PlanetSettings.Flow); never reuse it.
[JsonProperty("noise"), Key(2)] public NoiseSettings Noise;
[JsonProperty("lighting"), Key(3)] public AmbientLightingSettings Lighting;
[JsonProperty("grid"), Key(4)] public GridSettings Grid;

View file

@ -0,0 +1,53 @@
using CultMath;
using static CultMath.math;
/// <summary>
/// The global flow law: the one definition of the drift that stardust and nebula follow and that the sim knows.
/// A pure function of the zone's FlowSettings, a position, a scroll and a downhill gradient; nothing here keeps
/// a clock. Zone.Flow evaluates it at zone time. Assets/Shaders/Volumetric.cginc (globalFlow, slopeFlow) is its
/// HLSL lowering, driven by VolumeSampling.LowerFlow and pinned to it by Aetheria.EditorTools.FlowFieldParityVerify.
/// </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 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)
{
if (settings.GlobalAmplitude == 0f) return float3.zero;
var sample = Tri3D(position / settings.GlobalScale - float3(0f, scroll, 0f)) * settings.GlobalAmplitude;
sample.y *= .5f;
return sample;
}
// The slope term (Volumetric.cginc slopeFlow): swirl around and slide along the gravity gradient.
// `downhill` is the DOWNHILL gradient, -grad(height) in world xz. The shader's texel gradient is that same
// vector (getUV negates the world x and z axes), and Zone.GetNormal's xz is proportional to it.
// Skipped when both amplitudes are zero (the FLOW_SLOPE keyword), and zero for a zero gradient.
public static float3 Slope(FlowSettings settings, float2 downhill)
{
if (settings.SlopeAmplitude == 0f && settings.SwirlAmplitude == 0f) return float3.zero;
if (dot(downhill, downhill) == 0f) return float3.zero;
var direction = normalize(downhill);
return float3(direction.y, 0f, -direction.x) * settings.SwirlAmplitude
+ 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);
// Volumetric.cginc tri / tri3 / Tri3D, term for term.
static float Tri(float x) => abs(frac(x) - .5f);
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)
{
var t1 = normalize(Tri3(p));
var t2 = normalize(Tri3(p * 1.61803398875f));
return cross(t1, t2);
}
}

View file

@ -32,6 +32,9 @@ public class PlanetSettings
public float SecureAreaRadiusMultiplier = .45f;
public ExponentialCurve OrbitPeriod;
// The global flow stardust and nebula follow and the sim knows (FlowField). Zero flow by default.
public FlowSettings Flow = new FlowSettings();
}
[Serializable, MessagePackObject(keyAsPropertyName:true), JsonObject]

View file

@ -691,6 +691,17 @@ public class Zone
return GravityAcceleration(new float2(normal.x, normal.z), Settings.GravityStrength);
}
// The global flow velocity at `position` in zone time, in u/s (FlowField is the law). The slope term reads the
// downhill gradient, which GetNormal's xz is proportional to.
public float3 Flow(float3 position)
{
var normal = GetNormal(position.xz);
return FlowField.At(Settings.Flow, position, _time, 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);
public static float PowerPulse(float x, float exponent)
{
x *= 2;