magicciv/.project/objectives/g2-08-fauna-population-dynamics.md

id	title	priority	status	scope	updated_at	evidence	blocked_by
g2-08	Fauna population dynamics — confirm the existing LV engine ticks in the playable turn	p2	partial	game1	2026-06-08	src/simulator/crates/mc-ecology/src/dynamics.rs::trophic_cascade_predator_lags_prey_collapse — isolated trophic-cascade demonstration (bullet 3): predator collapse tick strictly lags prey collapse tick after habitat crash src/simulator/crates/mc-ecology/src/dynamics.rs::population_dynamics_golden_vector — population golden vector (bullet 5): fixed (seed,habitat,start) reproduces exact 10-tick rabbit+wolf series, re-run byte-identical public/games/age-of-dwarves/docs/ECOLOGY_BINDING.md §11b Population dynamics — playable-turn integration (bullet 7) mc-ecology 346 tests green on apricot (332 lib + 8 + 6). Outstanding/handoff: in-game HUD fauna overlay (bullet 6) is a godot-renderer handoff (population overlay already exists per p2-80 render hook)	p2-80 g2-07

Progress (2026-06-06, worldsim increments 2–3b): the LV engine now ticks in the playable turn and persists. tick_populations (→ process_step) runs every played turn via turn_manager.gd::next_player → EcologyState.tick; tile_populations round-trips through the save (EcologyContinuationState / worldsim_state). Determinism + save-transparency proven (mc-worldsim tests; GUT test_worldsim_playable_path 5/5). mc-ecology 324/324. Visual: population spread 3→31 tiles over 12 played turns (worldsim_ecology_proof screenshot). Outstanding (status stays partial): isolated trophic-cascade demonstration (bullet 3), population golden vector (bullet 5), in-game HUD overlay (bullet 6), and ECOLOGY_BINDING.md doc update (bullet 7).

Summary

Lotka-Volterra fauna population dynamics (habitat thresholds, carrying capacity, prey-driven growth/collapse, trophic cascade) already exist and are tested — the work is integration, persistence, determinism, and presentation.

• Engine: mc-ecology/src/dynamics.rs:273 tick_populations (CPU; GPU path via gpu_bridge::gpu_tick_populations).
• Already wired into the ecology step: EcologySim::process_step calls dynamics::tick_populations every tick, with substeps, plus emergence / dispersal / fish-stock feedback (mc-ecology/src/engine.rs:276). WorldSim::step already calls process_step (mc-worldsim/src/lib.rs:161).

Species data is authored: every fauna carries habitat_min / carrying_capacity, and 373/589 carry prey[] (e.g. grey_wolf.json: habitat_min 0.2, carrying_capacity 0.15, prey [moose, red_deer, musk_ox, european_rabbit, wild_boar]).

The gap is that this engine runs only at worldgen / in benches today; it does not tick in the playable game turn. This objective lands once mc-worldsim (p2-80) drives the step: confirm fauna populations respond per played turn, persist, and are deterministic + visible.

Acceptance

• ◻ Fauna tick_populations runs each played turn via WorldSim::step (p2-80) — populations grow toward carrying_capacity / collapse with prey, over played turns.
• ◻ The engine's tile_populations side-structure persists through mc-save (round-trip test); #[serde(default)].
• ◻ Trophic cascade observable in a played game: prey collapse → predator decline (lagged); reintroduction re-seeds from neighbour tiles (the Yellowstone path already modelled in the engine).
• ◻ Existing cargo test -p mc-ecology LV invariants hold.
• ◻ Determinism: same (seed, save) → identical population trajectories across played turns (PCG64 + SeedDomain::WorldsimDynamics); golden vector.
• ◻ Render: population state surfaced to the renderer / fauna overlay.
• ◻ ECOLOGY_BINDING.md "Population dynamics" section documents the playable-turn integration.
• ◻ cargo test green, headless GUT green, proof-scene screenshot of a played-turn population trajectory reviewed.

Non-goals

• Building the LV engine — it exists (mc-ecology).
• Migration paths (g2-10, apply_migrations — a sibling engine fn not yet in the per-turn step).
• Disease / parasitism (not in schema).

Risks

• Save-format growth: tile_populations becomes persisted live state; #[serde(default)], round-trip tested. (Shared with p2-80.)
• Determinism: the GPU vs CPU tick paths must agree, and the stream must stay stable across the api-gdext bridge.

Dependencies

• Blocked-by: p2-80 (mc-worldsim drives the step), g2-07 (flora lifecycle → habitat quality the LV engine reads).
• Couples with: g2-10 (migration moves the populations this engine tracks).