ecology

name

ecology

description

Use for ANY change to the Cosmic Shore cell ecosystem — flora, fauna, cells, crystals, spawn profiles (SpawnProfileSO / CellConfigDataSO), phase/volume (Cell.LiveVolume, CellPhaseThresholds), lifeform powerups (LifeFormCrystal / ElementalCrystal*), wither/starvation, predator-prey, reproduction, evolution, or biome/intensity tuning. Loads the locked invariants + the collider-budget gate + the change protocol so changes start from the correct design and stay performant. Trigger when editing Assets/_Scripts/Controller/Environment/** (Cell, RandomLifeSpawner, Flora*, Fauna, LightFauna), the ecology SOs, or Docs/ECOSYSTEM*.md.

Ecology Change Protocol

You are changing the Cosmic Shore cell ecosystem — a platform fundamental on the path to credible artificial life. The system's design intent has caused repeated rework when guessed at; this protocol exists to prevent that. Follow it exactly.

1. Read the canon first

• CLAUDE.md ▸ Ecosystem Design Principles (LOCKED) — the invariants (authoritative).
• Docs/ECOSYSTEM_MASTERPLAN.md — north star, the artificial-life scorecard (§3), the collider contract (§4), the platform-wiring plan (§5), the phased roadmap (§6), the orchestration (§7).
• Docs/ECOSYSTEM.md — the mechanics log (how the current system actually works).

2. Restate before you edit (this kills the #1 source of rework)

In one or two lines, state which invariants the change touches and confirm it violates none: continuity of existence (nothing pops in/out — everything grows/fades/suctions/withers; PLATFORM-WIDE) · no imposed death/decay/lifespan · no domain asymmetry (controlling-color spawn only) · wither-to-crystal + mass conservation · volume is the spine (not count) · the lifeform→elemental- crystal invariant · territorial permanence (don't cull the dominant canopy) · endogenous selection only (survival = fitness, never a scripted fitness function) · the collider budget. If a change might violate one, STOP and ask (AskUserQuestion). Do not guess the design.

3. Implement (emergence first, surgically)

• Favor emergence: never hard-code an outcome that should emerge from the fundamentals (Domain · Mass/prisms · Cells · Elementals · Flora & Fauna · Vessels) interacting. A scripted outcome is the same bug as a scripted fitness function — it breaks the gameplay and the artificial-life claim. Order of preference: use a fundamental → tune it → extend it → (with sign-off) propose a new one → bespoke only as last resort.
• Config-driven: tunables in ScriptableObjects; cross-system comms via SOAP events/variables; no singletons/static events. Variety = biome × intensity × heritable traits, not bespoke code.
• Surgical: match surrounding style; three similar lines beat a premature abstraction.

4. Respect the collider budget (HARD GATE — perf is collider-bound)

• State the change's impact on active colliders per cell.
• Prefer the Burst BlockDensityGrid / PrismSpatialIndex (QuerySphere / IsAnyPrismWithin / TryReserve — see Docs/SPATIAL_INDEX.md) for spatial queries over Physics.OverlapSphere and over adding colliders. Fauna senses already ride the index.
• Honor collider-LOD-by-phase (prism colliders disabled at Frozen) and the per-cell budget.
• If a change adds colliders or queries, say explicitly how the budget stays met.

5. Hand back verification — you cannot run Unity; the human is the gate

• State the exact in-editor steps to verify, the scene to test, and the precise SO knobs to tune.
• Use the collider/volume telemetry overlay when it exists to make the budget observable.
• Never claim something works that you have not seen work. Report honestly (failures, skips, caveats).

6. Commit

One coherent step per commit; conventional-commit message; develop on the feature branch (never bleeding-edge); open a PR only when asked. After lifeform-prefab changes, note to run Tools ▸ Cosmic Shore ▸ Validate Lifeform Crystals.