Aetheria/docs/aetheria-fauna-target.md

Aetheria spaceborne fauna: target

Campaign aetheria-fauna, target content r4 (r1 was admitted from the r0 draft at f9705d32, r2 by Self; r3 and r4 are admitted by Imagination). Repo GameCult/Aetheria, working branch master, cut branches eureka/aetheria-fauna-<cut>; the DAG's node primitives land in GameCult/CultLib (CultMath). Written by Imagination (agents imagination-aeth-fauna, imagination-aeth-fauna-r2, imagination-aeth-fauna-r3 and imagination-aeth-trophic-dag, sessions self-2026-10-13-ag2 and self-2026-10-14-ag); r4 is against origin/master 7633408f and CultLib 6c902fd4. Trophic DAG prior art: docs/research/2026-10-14-trophic-dag-filaments-prior-art.md (TD:<line>); its probe: docs/research/2026-10-14-trophic-dag-probe/. Body facts and probes are in docs/aetheria-fauna-map.md (cited below as B<n>); prior art is docs/research/2026-10-13-fauna-prior-art.md (PA:<line>; [M] items are from memory and unverified), docs/research/2026-10-13-fauna-placement-prior-art.md (placement by simulation) and docs/research/2026-10-14-fauna-placement-closed-form.md (CF:<line>; its tags: [V] read, [S] search summary only, [M] memory or derivation, unverified). This is the target and the model page. Open forks are questions in the mind under aetheria-fauna.

r4 applies habitat-trophic-dag (2026-10-14), after the r3 density drivers missed the look:

I'm not getting the filament feeling. I think we need a few layers of ecological abstraction, all deterministic, to author the various species with. The trophic levels should form a DAG which we can evaluate in either shader passes or in C#

with voronoi-primitive (a weighted Voronoi node, her reference shader a sketch of the look) and her correction, relayed by Self: "Parity between shader and C# is CultMath's whole raison d'etre". Placement becomes a layered, donor-controlled trophic DAG whose filament layer is the lore's Skein, whose nodes are CultMath functions with HLSL twins, and which Aetheria composes ("Placement law" below; map section r4). The krill carriage of habitat-no-pop-ruled stands and is extended to every fast term (map B34).

r3 applies fauna-placement-ruled (2026-10-13), against the recommendation to run a Physarum pass at generation:

Nothing we generate ahead of time would suffice, because the level is constantly changing. I'd imagine we can come up with something deterministic based on the gravity slope and flow that makes nice patterns.

Placement is therefore a pure function evaluated when it is asked, never a generated and saved product. The invariant fauna-placement-seeded ("the saved zone pack is the authority") is replaced by the placement invariants below. r3 also carries the rulings admitted after r2: drift by advected cycles (fauna-flow-coupling-ruled), loose matter drifts with the flow and ships do not (flow-moves-what-ruled), the slope terms are turned on (flow-slope-terms-ruled), and presenters take their phase from zone time (presenter-phase-from-zone-time).

r2 applies the operator's rulings of 2026-10-13: fauna attack ships in various ways (fauna-interaction-ruled), are harvestable and prominent in Elysium (fauna-harvest-ruled), are placed to tell an ecological story shaped by gravity (fauna-habitat-ruled), are native pseudospace life absent from Sol (fauna-origin-pseudospace, sol-flatspace-bubble), and drift with the global flow, whose authority moves into the sim (sim-knows-the-flow). The standing directions aetheria-release:ruling:kitchen-sink-content, catalog-breadth-now and setting-permits-necrotech make the ecology broad: more classes, more modes of harm, more goods, more uses, and no trimming for genre consistency.

Purpose, in the operator's words

I'm gonna need the spaceborne microfauna cut mapped too. I wanna see swarms of space minnows and clouds of space krill, space sharks and space whales. EW is a prop hunt game and we need more props.

(2026-10-13, this session)

You can't really camp in Aetheria because everything is constantly moving. We can provide a helper to sync the player to an orbit but we can't do that for matching the behavior of a whale if that's what you're currently disguised at. It becomes a game of adversarial observation

(ruling aetheria-ew:ruling:disguise-held-by-flying, 2026-10-13)

Earlier, on the targeting index (docs/scenarios-cut.md:872): "we'll want a bunch of subsystems feeding targeting data. Think the spacebound microfauna from the slime mold experiment". The index is general for this reason (docs/aetheria-release-map.md:3712).

What fauna are for

Fauna are an ecology a pilot reads, hunts in, hides in, harvests and is hunted by. The first use is the oldest: they are props, things in the sensor picture that are not ships, that a ship can be mistaken for, and that a pilot must imitate by flying. They give the EW campaign (docs/aetheria-ew-target.md) a populated background. A hunter reading a crowded picture has to ask of each return whether it moves like what it seems to be. That is the prior art's oldest lesson: radar "angels" were birds and insects (PA:7). Insects drift with the wind and birds fly relative to it, so the motion tells them apart (PA:9). Sonar's false floor was a layer of animals that rose and fell with daylight (PA:14). Clutter that is alive is told apart by how it moves, not by how bright it is.

The other uses follow from the rulings. Fauna are a renewable harvest, big in Elysium, with goods for many trades (the lore draft names krill paste for Bloom concrete, photophores, shark heat-organs and whale bone carrying strange matter). Fauna are a hazard: classes attack ships, each in its own way. Fauna are material for every genre the factions carry: cultivators harvest them, necrotech binds them, mecha pilots ride them. Fauna are a map: where they gather shows the shape of the wells and the currents, and where they are missing says something happened.

Design truths (ends, not means)

1. Anything a sensor can perceive or a shot can hit is simulated; nothing below detection decides anything. Sensing, the targeting index and fire control are all in ServerShared, so a fauna that is only drawn cannot be a contact, a target or a prop. The slime-mold experiment (Slime.cs, a GPU Physarum swarm of 131,072 agents in the ARPG scene, B8) stays what it is: ambient presentation that no sensor reads.
2. Fauna never lie. Their returns are truth. Only ships lie, through aetheria-ew's claims. A fauna class is the standard a disguised ship must fly to (disguise-held-by-flying).
3. Each class has one motion law, legible and learnable. An observer who watches a return for long enough can test it against the class's law. The laws are written to be told apart:
   • krill drift with the global flow: each member advects along the flow at its seed point for one cycle, fades and re-seeds (fauna-flow-coupling-ruled). This is the drifting-insect tell (PA:9);
   • minnow schools ride the flow and mill fast inside their school, so their jitter is quick;
   • sharks cut across the flow, patrol and sprint, and accelerate harder than anything else in the class list;
   • whales are slow, huge and hot, and swing in long arcs. An orbit-sync helper that matches a ship to the local flow is a separate, generic flying aid. It makes "krill" the cheapest disguise, and nothing makes a ship move like a shark or a whale except its pilot.
4. Per-tick cost is per swarm, not per member. Members are evaluated only when a query, a presenter or a sensor asks, as belt rocks are (Zone.ChunkPose, B3). Probe B10 measured it: 128 ships take about 4.9 ms per sim tick, and 100,000 stepped bodies that read the zone force take 16 ms. Neither form scales to fauna counts.
5. One detection rule. Fauna are seen through Sensor.Gain by way of Entity.PassiveInfo, as chunks are (Entity.ChunkInfo, B5). There is no second sensor model and no fauna-specific threshold.
6. Deterministic. A fauna's state is a function of the zone's seed, its world laws, its bodies' orbits, zone time and sim events on fixed steps (SimClock, B9). Nothing about where fauna are is saved. It uses no UnityEngine.Random, no wall clock and no frame time. Any dice come from SimulationDice on a stream of their own.
7. The zone owns fauna; presenters read them. No Unity callback writes fauna state. The renderer draws them as it draws belts, from a pose evaluated at zone time (ZoneRenderer.cs:543-569, B7).
8. The targeting index carries fauna as providers. No consumer scans a swarm (TargetingIndex.cs, B4).
9. The flow is a world fact with one owner in the sim. The global flow that stardust and nebula follow (Volumetric.cginc flow(), B15) is evaluated by one ServerShared function of position and zone time from the zone's flow settings. Fauna drift with it. The shader lowers the same function from the same settings and time, and a parity check pins the two. No presenter accumulates its own flow time (B16).
10. Placement tells an ecological story, and the level writes it as it moves. Where fauna are is a closed form of the gravity slope and the flow, evaluated at zone time whenever a query, presenter or sensor asks (fauna-placement-ruled). Wells orbit, gas giants and suns ripple their wells (B24), and the flow scrolls, so the pattern moves with the level: a placement generated ahead would go stale. Life follows the Skein, the slime-mould web strung from well to well, and the energy the wells give off; predators follow their prey, and ambushers wait in the slack between wells. Nothing gathers in the cores, and open flat space away from the Skein is nearly empty. The law is in "Placement law" below.
11. No fauna in Sol. Sol is a single flatspace zone with no fauna inside it; the strangeness begins at its edge.
12. Harm and harvest go through existing owners. A fauna attack is damage through the path a weapon's hit takes; a harvest yields items through the economy's yield path; neither gets a fauna-only damage or loot rule.

Placement law

Where fauna of a species are is decided by a trophic DAG: layers of fields, each a deterministic function of the layers below it and of world facts, evaluated at a point at zone time when a query, presenter or sensor asks (habitat-trophic-dag). Pointwise fields of slope and flow alone draw bands and blobs (B25); filaments need an input that is not local, and the DAG takes it from the zone's bodies, which every point can read (map r4).

Layer	Fields (the first web, from the lore's Open Water; the bestiary stays open)	Reads
0 Environment	Slope and the operator's Deposition(slope) band, the steep-core mask (Zone.GetNormal); the flow (Zone.Flow); the zone's bodies: positions from the per-tick orbit cache, gravity radius, kind; energy kernels round them: starlight inside a sun's light radius, heat-light on warm well floors. Later sources join here: gravity-wave rings (whales), mind-light round crews and stations (moths), wormhole mouths (upwelling), wrecks (succession).	World facts only
1 Structure	The Skein: strands between neighbouring bodies (a site graph with a soft gate, each edge a Gaussian strand, bent by a Zel'dovich warp of the flow, TD:39 [V]) and a weighted lattice Voronoi web hanging off them (voronoi-primitive). Slack: the borders of the bodies' weighted Voronoi, where pulls cancel. Which construction is the Skein is the question skein-filament-construction.	Layer 0
2 Producers	Glim: energy times the Skein's feeding.	0, 1
3 Grazers	Krill: the Skein times a saturating response to glim (Holling II, TD:55 [S]). Minnows: krill over a hunting ring.	0-2
4 Predators and ambushers	Sharks: minnows over a wider ring, on the band. Lanterns and void spiders: slack times krill over a ring.	0-3

1. Operators. A sim-visible layer uses only: pointwise arithmetic, remap curves, smoothstep, min, max and smooth min, saturating responses; CultMath nodes (integer hash, weighted lattice cellular, weighted diagram over explicit sites, segment kernel, soft site-graph gate); a stencil (the mean of a lower layer at the point and a fixed ring of taps, at most two levels deep, 9x the cost per level, B36); and kernel widening where the prey is a sum of Gaussian kernels (the exact blur, TD:78 [M]). Grid operators (blur of arbitrary fields, distance transforms, eikonal paths, jump flooding, TD:19, TD:78), iteration and stored fields are presentation-only.
2. Donor control. A layer never reads itself or a layer above it: predators follow prey and never thin it in the law (TD:56 [M]). Thinning is a sim event (harvest, attack wear), not a placement term.
3. Candidates with fixed thresholds (r3, kept). Each species has a lattice of candidate seed points, one per cell, jittered by a hash of the zone seed and the cell, each with its own fixed threshold from the same hash; a candidate hosts a member when its species' density there is above its threshold (Horizon Zero Dawn's shape, CF:33 [V]; nesting pinned as an invariant, CF:40 [M]). The member's identity is the cell, a ChunkId with no stored state. Candidate spacing is per species (16 u krill, 48 u minnows, 128 u sharks in the probe).
4. No pop. Terms that move fast are read at the member's own cycle start (habitat-no-pop-ruled for the flow, extended to the flow warp and the lattice web's drift, measured in B34); terms that move slowly and continuously (the slope band, the soft site graph, B33) are read now and carried by the fade. A member never appears or vanishes at full presence.
5. Nodes in CultMath, compositions in Aetheria. Every node primitive is a CultMath function with an HLSL twin, pinned by CultMath's mirror test (map B29); what CultMath lacks is a gap filled in CultLib (map r4, gaps 1-5), never a helper in Aetheria. Each species' composition is C# in ServerShared (Habitat) calling those functions, with its parameters in a per-species settings record; the sim evaluates only C#. A presenter that draws a composed layer (the Skein's glow, glim haze) uses the composition's HLSL twin under a CultMath-owned composition check. Whether compositions later become data on CultMath's parked tape is the question trophic-graph-tape.

The law costs nothing per tick: it runs per candidate when asked, as Zone.ChunkPose does for rocks; the site graph is per zone per tick over a handful of bodies.

Scale classes

Class	Shape in the sim	Light	Motion law (tell)	Prop role
Krill	Thousands of members at hosted candidates on the well shoulders; each advects along the flow for one cycle, fades and re-seeds	Faint reflection per member; a patch is bright in aggregate	Drifts with the global flow (advected cycles)	Hide in a cloud; later, a dense cloud thins sight lines as a vapour cloud does (Zone.Obscuration)
Minnow	Schools of hundreds that ride the flow	Faint reflection, a bright school	Flow plus fast milling inside the school	Clutter of small returns; a ship moving through a school is noticed (later: scatter)
Shark	One to three members, each about the size of a ship	Reflection and moderate thermal	Crosses the flow; patrols with sprints	A ship-sized return a hunter must think about; the best disguise target for a fighter
Whale	One member, many times a ship's size	Strong thermal; heard song (later)	Slow long arcs	A bright anchor; a ship near it is hard to separate (later: shadowing)

More classes are wanted, not fewer (kitchen-sink-content). The lore draft's room for more becomes classes in the cut sequence: void spiders that string nets across trojan points and snare what drifts in, gas giant drifters that live in the upper cloud deck, and edge giants, the larger things past the charts, found only far from Sol. Each class gets its own motion law, its own mode of harm and its own goods. Attack modes are designed per class in later cuts; the ones the lore implies are sharks that strike, minnow schools that scour sensors and hulls, whale song that is noise in the shared signal space, spider nets that snare and tether, and drifters that discharge.

The krill and minnow rows need nothing the Body lacks except a bounded per-kind motion term on field members and the flow (B3, B4, B15). Sharks and whales need an anchor that does not ride the flow, which comes later.

Model page: identity, lifecycle, authority

The rows follow the rulings fauna-in-sim-ruled, fauna-identity-ruled and fauna-motion-model-ruled.

Kind	Identity (what names it)	Lifecycle	Authority (who decides; forbidden writers)
Field kind (existing, extended)	FieldKindData catalog record (ZoneData.cs:122), by key. A fauna kind is a field kind with a non-zero member sway and zero belt GenerationWeight, so a rock belt never draws it (FieldKinds.Assign, "Zero never picks it").	Authored in AetherDb, append-only MessagePack keys.	The catalog. Forbidden: runtime writes.
Fauna field (one per fauna kind a zone hosts)	The fauna kind's catalog key within the zone: a zone hosts every fauna kind its world laws admit, so the field is derived, not generated.	Derived when the zone is built, from its world laws and the catalog; never saved. Only its members' wear is saved (ZonePack.ChunkWear).	Zone. Forbidden: ZoneGenerator writing fauna into the pack; presenters; entities.
Member (a chunk of a fauna field)	ChunkId(field, index) (Zone.cs:825; the type was named Field so other field kinds could join, per its own comment); the index is a lattice cell.	Present while its candidate is hosted (placement law) and it is not broken (Zone.ChunkExists). Wear and respawn are lazy comparisons against zone time (Zone.Wear), as for rocks. Its pose is a pure function of zone time: its seed point advected along the flow for its cycle.	The habitat law decides hosting; the class law alone computes the pose; Zone.Wear is the only writer of damage. Forbidden: any stored pose or hosting bit, any per-tick member loop.
Fauna provider (existing, widened)	BeltTargets, one per field (Zone.cs:175).	Built with the zone, never saved.	Its region bounds must hold for every member. Sway widens the slack by the kind's amplitude. Forbidden: a second index or a fauna scan.
Fauna detection (derived)	(observer, member), never stored.	Derived per query: ChunkInfo → PassiveInfo → Sensor.Gain.	Entity. Forbidden: any fauna-specific threshold or gain.
Swarm anchor (later, sharks and whales)	Per field: a law that moves the field's frame across the flow.	Pure function of zone time plus sparse event records (fork fauna-motion-model).	Zone. Forbidden: per-member stepping.
Disturbance (later)	(member, time, push), sparse, as ChunkWear is.	Written when a hull passes through or a shot lands, then decays lazily against zone time.	Zone. It is read only by Pose.
Flow field (new owner)	One law: FlowField, evaluated per zone by Zone.Flow(position) from the zone's world-law settings (PlanetSettings.Flow).	Settings authored in Settings.asset; time is zone time. Never stored per position.	Zone. Derived: every shader flow uniform (_FlowScroll and the rest). Forbidden: VolumeSampling._flowScroll, ZoneEnvironment.Flow, any frame-time accumulator.
Habitat (new owner, a law: the trophic DAG)	Habitat in ServerShared: one composition per species over CultMath nodes, a species' settings record, a candidate's hashed seed point and threshold.	Never stored: evaluated at zone time per candidate when asked.	Habitat decides density and hosting; Zone supplies world facts (GetNormal, Flow, body positions from the per-tick orbit cache); CultMath owns every node and its HLSL twin. Forbidden: a generation pass, a saved or cached habitat map, a per-tick sweep, a math twin in Aetheria, a grid operator in a sim-visible layer.
Skein site graph (derived)	Per zone: the soft gate of each pair of bodies (map r4).	Recomputed per tick from orbit positions; never saved.	Habitat, through a CultMath gate function. Forbidden: a hard (0/1) gate; a cached graph across ticks.
Attack (later, per class)	(member or swarm, ship, time), an event.	Raised by a class law when its trigger holds; applied through the ordinary damage path.	Zone. Forbidden: a fauna-only damage rule.
Harvest yield (later)	Item kinds in the catalog, per fauna kind.	A member broken or netted by harvesting gear yields items through the economy's yield table; the field refills by respawn.	The catalog and the yield table. Forbidden: fauna-only loot code.
Fauna background kind (aetheria-ew)	Entries of aetheria-ew's BackgroundKind for fauna classes (that target's row says "more by ruling").	Static data.	GameplaySettings, per aetheria-ew. Its envelope gains a motion term per class (fork fauna-disguise-path).

Invariants

• fauna-sim-owned: no fauna state is written outside Zone, ZoneGenerator and the catalog. A test spies the renderer's inputs, and a grep finds no Unity writer.
• fauna-pose-pure: a member's pose at time t does not depend on the steps taken to reach t. Stepping a zone to t by 1/60 and by 1/7 gives equal poses.
• fauna-cost-per-swarm: zone update cost does not grow with member count. This is pinned with the index's Examined counter and by Zone.Update touching no member, not by timing.
• fauna-one-gain: a fauna member is visible exactly when ChunkVisible says so.
• fauna-bounds-hold: every member of a swaying or drifting field lies inside the regions its provider offers.
• fauna-tell-holds: each class's members move by that class's law; a krill member advects with the global flow from its seed point for its cycle. Each class gets its own tell test.
• fauna-never-lie: no claim, suppression or belief is written for a fauna.
• flow-one-owner: the global flow has one owner, FlowField in ServerShared, evaluated at zone time from the zone's flow settings. Every shader flow uniform is derived from it; no presenter keeps its own flow clock.
• flow-shader-parity: the HLSL globalFlow and slopeFlow in Volumetric.cginc give the C# owner's values for the same position, time, settings and gradient, within a stated tolerance; a parity check that evaluates both pins it and fails when either side changes alone.
• flow-step-free: the flow at a position and zone time does not depend on step size or frame rate.
• fauna-none-in-sol: Sol's zone hosts no fauna kind, so no candidate there is ever hosted.
• fauna-placement-closed-form: whether a candidate hosts a member at zone time t is a pure function of the zone seed, the species' settings, the world facts at t (slope, flow at the member's cycle start, the bodies' positions) and the lower layers evaluated at bounded points. Nothing about placement is generated ahead, saved, cached across ticks or stepped.
• fauna-placement-story: density is zero in well cores; along a Skein strand between two bodies it exceeds the density at a point of equal slope off the strand; ambushers' density peaks on the slack borders; a predator's density rises with its prey's within its hunting ring.
• fauna-placement-nested: each candidate's threshold is fixed, so raising the density at a candidate never un-hosts it and lowering it never hosts it.
• fauna-placement-no-pop: a member never appears or vanishes at full presence; every change of hosting is carried through a fade. Within a member's cycle its presence moves by at most a stated bound per 1/60 s step as the bodies orbit (the probe's worst was .066, map B34).
• trophic-dag-acyclic: each layer reads only world facts and the layers below it; no layer reads itself or a layer above it.
• trophic-dag-pointwise: every sim-visible layer is evaluated at a point from world facts, the per-tick site graph and a bounded number of evaluations of lower layers (stencils at most two levels deep); no grid, no iteration, no stored field.
• trophic-nodes-in-cultmath: every node primitive a layer calls is a CultMath function with an HLSL twin pinned by CultMath's parity checks; Aetheria holds compositions only.
• skein-gate-continuous: the Skein's site-graph gates are continuous in the bodies' positions, so no strand appears or vanishes as the bodies orbit.

Not in scope

• Ambient presentation-only life (the slime trails) beyond leaving it untouched; the habitat law reuses its Deposition(slope) curve, but the presenter stays presentation.
• Population dynamics: no layer is stepped or regulated by the layer above it; harvest and attack wear thin members as sim events through Zone.Wear, not as placement terms.
• Phantom positions (aetheria-ew ew-where-lies-ruled).
• Ships drifting with the flow (flow-moves-what-ruled: ships do not; floating items, mines and vented clouds do, in a later cut).
• Per-zone flow and nebula environments; Sol's cloudless bubble is a later cut, and until it lands every zone shares one flow.

Attacks and harvest are in scope as later cuts, designed per class (fauna-interaction-ruled, fauna-harvest-ruled); the first cuts build the ground they stand on: the flow, the habitat law and the krill field.

Cut sequence

The map's r4 cut sequence (with the r3 lines it keeps) has one line per cut; each is mapped when it is about to run.