magicciv/.project/objectives/p2-58-ambient-encounter-rolls.md

id	title	priority	status	scope	owner	updated_at	evidence	blocked_by
p2-58	Ambient encounter rolls per tile moved — fauna_density × ecology_tier	p2	done	game1	unassigned	2026-05-07	p2-58b done cycle 39: GUT test + api-gdext ambient_encounter_count surface + EventBus.ambient_encounter_fired signal Prior cycles: mc-ecology roll_ambient_encounter, encounter_rates.json, mc-turn Step 1b hook, TurnEvent::AmbientEncounterFired in mc-replay, mc-core encounter 7/7, mc-turn 1/1

Context

public/games/age-of-dwarves/docs/ecology-gameplay.md Layer 1 specifies that any unit moving through wilderness rolls a per-tile encounter chance keyed on fauna_density × ecology_tier, with unit-type roll-rate scaling (e.g., scouts trip fewer encounters, large armies trip more). Today combat encounters fire only on lair-adjacency or scripted spawn events — ambient wilderness traversal is risk-free, contradicting the design.

Acceptance

• ✓ mc-ecology exposes roll_ambient_encounter(tile_meta, unit_kind, rng) -> Option<EncounterSpec> keyed on tile_meta.fauna_density * tile_meta.ecology_tier — src/simulator/crates/mc-ecology/src/encounter.rs:175 (re-exported at src/simulator/crates/mc-ecology/src/lib.rs:51).
• ✓ Unit-kind roll-rate multipliers (scout: 0.5, infantry: 0.8, civilian/pioneer: 2.0, …) authored under public/resources/ecology/encounter_rates.json:19-31.
• ✓ Per-tile-moved hook: p2-58a added fauna_density: f32 and fauna_index: Vec<SpeciesId> to TileState (path A). mc-turn Step 1b in process_fauna_encounters_inner builds AmbientTileCtx from these fields and calls mc_core::encounter::roll_ambient_encounter, pushing TurnEvent::AmbientEncounterFired to result.events_emitted. (p2-58 + p2-58b, cycles prior + cycle 39)
• ✓ Encounter selection draws from fauna_index (candidate species list) — src/simulator/crates/mc-ecology/src/encounter.rs:204-205. Trophic + domain gates run upstream during fauna selection (mc-ecology::fauna_select::pick_fauna_for_tile); the encounter draw consumes the already-filtered list.
• ✓ Determinism: encounter rolls use seed::derive_step(map_seed, SeedDomain::Encounter, &[turn, unit_id, step_idx]) — src/simulator/crates/mc-core/src/seed.rs:73 (the Encounter = 6 variant + derive_step shipped with the typed wrappers); replay determinism asserted by test_encounter_seeded_determinism (src/simulator/crates/mc-ecology/src/encounter.rs:344).
• ✓ Cargo test in mc-ecology: 100-step deterministic walk yields the expected encounter count within plausible bounds — test_encounter_probability_scales_with_density (src/simulator/crates/mc-ecology/src/encounter.rs:289); also test_civilians_higher_roll_rate (src/simulator/crates/mc-ecology/src/encounter.rs:325). 8/8 mc-ecology encounter tests pass on apricot.
• ✓ GUT integration test: test_p2_58b_ambient_encounter.gd — headless, drives GdTurnProcessor::step with fauna_density=0.8 tile via GdGridState::set_tile_dict (dict_to_tile extended for fauna fields). Asserts ambient_encounter_count ≥ 1 within 50 steps. Also asserts barren tile yields zero. EventBus.ambient_encounter_fired signal declared. turn_result_to_dict extended with ambient_encounter_count + ambient_encounters[]. (cycle 39)

Source-of-truth rails

• Rust crate: mc-ecology owns the roll. mc-turn::movement is the single caller (no GDScript shadow roll).
• JSON path: public/resources/ecology/encounter_rates.json owns unit-kind multipliers and base roll rate. No data/ overrides.
• mc-core typed wrapper: EncounterSpec { species_id: SpeciesId, group_size: u8, posture: EncounterPosture }.

Out of scope

• Pioneer escort rules (covered by p2-59).
• Lair siege/assault/raid combat modes (covered by p3-10).
• Encounter narrative text / event cards — separate UI objective.

References

• public/games/age-of-dwarves/docs/ecology-gameplay.md (Layer 1)
• public/games/age-of-dwarves/docs/ECOLOGY_BINDING.md
• public/games/age-of-dwarves/docs/terrain/WORLDGEN_RNG.md