magicciv/.project/objectives/p2-54-resource-visibility-three-axis.md

id	title	priority	status	scope	owner	updated_at	canonical_doc	coordinates_with
p2-54	Resource visibility — three-axis (visibility/yield_gate/improvement_gate) refactor	p2	done	game1	terraformer	2026-05-02	public/games/age-of-dwarves/docs/RESOURCES.md	p1-05 p1-39 p2-52

Summary

Replace the binary revealed_by_tech field on resources with three orthogonal axes (visibility / yield_gate / improvement_gate) plus forward-compatible schema extensions for environmental indicator decorations and a per-player observation cache.

Multi-cycle objective. This cycle (p2-54) delivers the schema + data + Rust struct. Follow-on cycles handle rendering, AI, and the observation cache.

---

Acceptance Criteria

• ✓ Canonical design doc authored at public/games/age-of-dwarves/docs/RESOURCES.md with §1–§8 covering the three-axis model, flora/fauna policy, per-resource classification table (all 15 luxuries + 9 bonus + 7 strategic), migration notes, AI consumption pattern, renderer pattern, observation model design, and indicator decorations design.

• ✓ public/resources/resources.json migrated in-place:

  • revealed_by_tech deleted from all 31 entries
  • visibility, yield_gate, improvement_gate, indicator_decorations added
  • All 15 luxuries mapped per the user-confirmed classification table
  • All 9 bonus resources: visibility: "always", yield_gate: null
  • All 7 strategic resources: visibility: "tech_gated" (except flint: "always")
  • Migration script at tools/migrate-resources-visibility.py ran without errors
  • Validator confirms zero revealed_by_tech remaining, all new fields present

• ✓ Rust struct mc_core::resources::Resource added:

  • Fields: id, category, visibility, yield_gate, improvement_gate, indicator_decorations
  • Visibility enum with Always / Scout / TechGated
  • Helper: is_tile_visible_for_player(&Resource, &HashSet<String>, bool) -> bool
  • Helper: is_yield_active(&Resource, &HashSet<String>) -> bool
  • Helper: is_improvement_unlocked(&Resource, &HashSet<String>) -> bool
  • ResourceBundle struct with luxury, bonus, strategic arrays + all() iterator
  • 13 unit tests covering all visibility branches, yield-gate logic, serde round-trip

• ✓ cargo test -p mc-core: 112 passed, 0 failed

• ✓ cargo test -p mc-mapgen --test cross_build_determinism: 4 passed, 0 failed

• ✓ cargo check -p mc-core -p mc-economy -p mc-mapgen: clean (0 errors)

• ✓ TypeScript Resource interface in src/packages/guide/src/types/game-data.ts updated:

  • visibility?, yield_gate?, improvement_gate? fields added
  • revealed_by_tech marked @deprecated with | null type widening
  • npx tsc --noEmit: clean

• ✓ ResourcesPage.tsx updated:

  • getCategory() switched from revealed_by_tech heuristic to category field
  • Tech tag render reads yield_gate ?? revealed_by_tech

• ✓ EconomyResourcesPage.tsx updated:

  • DepositRecord interface updated with three-axis fields
  • Tech badge render reads yield_gate ?? revealed_by_tech

• ✓ GDScript consumers updated (4 sites):

  • tile.gd:342: reads yield_gate first, falls back to revealed_by_tech
  • tile_info_panel.gd:109: reads yield_gate first, falls back
  • turn_processor_helpers.gd:407: reads yield_gate first, falls back

• ✓ e2e baseline: 55 passed / 6 skipped (unchanged)

• ◻ Migrate public/resources/deposits/*.json (30 files) to three-axis schema — blocking precondition for GDScript and guide-web to read the new fields. Until this is done, all consumer code falls back to revealed_by_tech (the fallback paths are in place; nothing breaks, but the new field path is inert). Tracked as p2-54a.

• ◻ Per-player tile observation cache (flora/fauna last-observed state) — mc-save struct authoring + GDExtension bridge. Tracked as p2-54b.

• ◻ Indicator decorations rendered on tech-gated resource tiles — godot-renderer work. Tracked as p2-54c.

• ◻ AI reads indicator_decorations as tech-priority hints + reads observations not ground truth. Tracked as p2-54d.

---

K/N Completion

K = 8 / N = 12 (4 follow-on items deferred: p2-54a deposits migration, p2-54b observation cache, p2-54c renderer, p2-54d AI)

---

Handoff to Next Cycle

Domain	Work	Objective
game-data	Migrate deposits/*.json (30 files) to three-axis schema — unblocks all downstream	p2-54a
godot-renderer	Dim yield_gate-gated icons; render indicator_decorations sprites	p2-54c
game-ai (mc-ai)	Tech-priority bias for visible-but-gated luxuries; read indicator_decorations	p2-54d
guide-web	Encyclopedia tooltips for new axes	p2-54c
simulator-infra	mc-save::PlayerObservations struct + GDExtension bridge	p2-54b

Important: Until p2-54a (deposits migration) is done, GDScript and guide-web always fall back to revealed_by_tech. The new field path in both systems is forward-compatible but inert. The resources.json aggregate and mc-core::resources Rust struct are correct — they are the schema source of truth and will become authoritative once deposits are migrated.

---

Files Modified (this cycle)

• public/games/age-of-dwarves/docs/RESOURCES.md — new, canonical doc
• public/resources/resources.json — migrated in-place
• tools/migrate-resources-visibility.py — new, migration + validation script
• src/simulator/crates/mc-core/src/resources.rs — new, Rust struct + helpers
• src/simulator/crates/mc-core/src/lib.rs — added pub mod resources
• src/packages/guide/src/types/game-data.ts — Resource interface updated
• public/games/age-of-dwarves/guide/src/pages/ResourcesPage.tsx — updated
• public/games/age-of-dwarves/guide/src/pages/EconomyResourcesPage.tsx — updated
• src/game/engine/src/map/tile.gd — yield_gate-first read
• src/game/engine/scenes/world_map/tile_info_panel.gd — yield_gate-first read
• src/game/engine/src/modules/management/turn_processor_helpers.gd — yield_gate-first read