diff --git a/Cellular_Revamp_Build_Plan.md b/Cellular_Revamp_Build_Plan.md new file mode 100644 index 0000000..4704dc9 --- /dev/null +++ b/Cellular_Revamp_Build_Plan.md @@ -0,0 +1,150 @@ +# Cellular revamp build plan + +Status: approved for implementation, 2026-10-22. Builds the +[cellular gameplay plan](Cellular_gameplay_plan.md) and its system plans: +[mutation](Cellular_mutation_plan.md), [reproduction](Cellular_reproduction_plan.md), +[feeding and energy](Cellular_feeding_energy_plan.md), +[predation and defense](Cellular_predation_defense_plan.md) and +[body and maintenance](Cellular_body_maintenance_plan.md). Decision record: +[ADR-0179](docs/adr/0179-cellular-gameplay-revamp.md). Continues from phases 1-2 of +the [region and movement plan](Cellular_Region_Movement_Plan.md), which shipped as +rules 12. + +## Approach + +- **Build every phase, then playtest once.** Each phase is committed and pushed with + CI green (AGENTS.md), but nothing is deployed until the last phase. The playtest + runs on a fresh DEV region opened with the new rules. +- **New versions, disposable DEV worlds.** Rules 13, genome schema 7, development 7, + founder 6, a new owner format, bundle and schema, and a fresh `cellular-v10` + opening. No upgrade from existing rules-12 regions (ADR-0177). +- **One tuning file.** Every new tunable goes in + `deploy/kubernetes/region/dev/tuning/cellular.tuning`, validated at startup. +- **Client and server together** in every phase. +- **Shared biology.** Derivations stay in the headless library, so the client + predictor and the server agree. + +## Phases + +### Phase 1: genome and body (rules 13 foundation) + +Server: +- Genome schema 7: every heritable value the plans name, in points (founder 100) + unless stated: + - size, density, membrane, body recipe (per thousand, C/N/P/O), upkeep + efficiency, growth speed; + - collection per channel (E/C/N/P/O), shared intake, burn efficiency per matter + channel, energy kept per bubble (`energy_conversion`), light capture; + - engulf capacity, kill absorption; + - bud share, litter (founder 0), Adhesion flag; + - the existing movement arrangement. +- Development 7 and founder 6: size, density and recipe set mass, footprint and + surface; upkeep = essential floor + adjustable part / efficiency; membrane mass + from points; no legacy photosynthesis speed penalty. +- Rules 13 owner skeleton (new owner format) and tuning keys for every body value. + +Client: hover and HUD show the new body values. + +Verify: founder 6 derives the same body as founder 5 where the plans say "today's +value"; the essential floor holds; encode/decode and bound checks for schema 7. + +### Phase 2: feeding, energy and predation + +Server: +- Collection per channel with the shared intake limit; the membrane collection penalty. +- Energy kept per bubble; the rest to heat. +- Matter as energy: burn the largest non-excluded channel, upkeep overrides + exclusions, death only when nothing can pay. +- Region spent pool with a seeded drip back as bubbles; waits at the deposit limit. +- Reserve matter in mass for handling and movement energy, not upkeep. +- Engulf check with engulf capacity and `engulf_reserve_mass_percent`; kill + absorption; the kill remainder split between bubbles and the spent pool. +- Session v14 for the new perception fields and the exclusion control. + +Client: energy display including what matter can stand in for; channel exclusion +toggles; spent-pool drips drawn like infall. + +Verify: conservation per channel and energy across burning, the pool, kills and +drips; no burn of excluded matter except for upkeep; replay determinism. + +### Phase 3: mutation offers + +Server: +- Catalog of the 49 mutations as data: effect, eligibility, triggers, base weight, + steps, cost and `enabled`, all from the tuning file. +- Per-cell affinity scores, inherited at birth; activity counters for every trigger. +- Chance allocation (`clamp(k x weight, floor, cap)`, summing to the option count) + and a seeded systematic draw; the draw and chances are recorded so a retry never + rerolls. +- Offer cadence from the tuning file; one pending offer. +- Cost paid from the reserve (matter may stand in for energy) and reclaimed as seeded + random bubbles, merging into the farthest bubble at the deposit limit. + +Client: offer screen with name, pro, con, chance, cost and shortfall. + +Verify: chances sum to the option count and respect floor and cap; the draw's +marginal frequencies match the chances over a seed ensemble; triggers fire as +specified; costs conserve. + +### Phase 4: reproduction + +Server: +- On-demand bud with the control choice (stay or become the bud), the tunable fee and + bud share; one-way control transfer (ADR-0163). +- Mutation split: write the mutation into both plans, split body and reserve by + `split_share`, the offspring expresses it, the player chooses the cell; refusals + leave the offer pending. +- Litter: guaranteed and chance extra offspring sharing one investment, limited by + free spots and the region cap. +- Wildlife buds from its own plan with litter; wildlife never mutates. + +Client: Bud with Stay / Become; offer options with Stay as founder / Become offspring; +refusal reasons. + +Verify: control transfer is one way and exactly once across retries and restarts; +splits and litters conserve; a refused split spends nothing. + +### Phase 5: multicellular organisms and emergence + +Blocked on the maintainer's confirmation of the locked-requirement question in +ADR-0179 (whole-organism mutations). + +Server: +- Adhesion forms the organism at once. The organism is one life with a member count, + one genome, one reserve and a body that is the sum of its members. +- Internal buds add members; mutations are expressed by the whole organism; whole- + organism engulfment by total mass; mass-scaled handling. +- Emergence threshold (members, mass, reserve energy) and the Emerge action; the + wildlife member limit as a safeguard. + +Client: organism drawn as its member cells; Emerge button at the threshold. + +Verify: one reserve and one genome across members; whole engulfment conserves; the +Emerge action only at the threshold. + +### Phase 6: wildlife, instrumentation and the playtest + +- Wildlife controller: matter-as-energy aware, budding with litter, engulfing with the + new eligibility. +- Play summary: first-birth time, time to Adhesion, deaths by cause, energy share paid + by matter, offers seen and chosen, mutations held per lineage. +- Opening `cellular-v10` in a new DEV region; promote the images; full Argo sync. +- Playtest. + +## Open items + +| Item | Phase | +| --- | --- | +| Whole-organism mutations versus the locked "structural changes are expressed in offspring" requirement | 5 | +| What Emerge does before the 3D world exists | 5 | +| Retuning bubble energy or founder `energy_conversion` (keep 40% vs today's 100%) | 2 | + +## Risks + +| Risk | Mitigation | +| --- | --- | +| Many new genome fields exceed the 256-byte genome bound | Measure in phase 1; widen the bound in schema 7 if needed. | +| Matter-as-energy makes cells nearly unkillable by starvation | Burn rates and drip rate are tunable; instrument the matter share of energy paid. | +| 49 triggers add per-tick work | Counters are integer and per cell; measure tick time in phase 6. | +| Control transfer across retries duplicates or loses control | Durable action receipts, as for existing births. | +| One deploy at the end hides integration problems | Every phase ships its client half and runs end to end in local tests. | diff --git a/Cellular_gameplay_plan.md b/Cellular_gameplay_plan.md index d160e1b..9bf016a 100644 --- a/Cellular_gameplay_plan.md +++ b/Cellular_gameplay_plan.md @@ -99,7 +99,8 @@ into plans rather than merged. 1. Done: system plans for movement, reproduction, feeding and energy, predation and defense, body and maintenance; the mutation catalog for this pass. -2. Build the plans in phases (build plan, to be written), then playtest at the end. +2. Build the plans in phases ([build plan](Cellular_Revamp_Build_Plan.md), + [ADR-0179](docs/adr/0179-cellular-gameplay-revamp.md)), then playtest at the end. 3. Later: temperature, damage and repair, armor, live capture, sensing, multicellular mutations, draft groups 071-150. 4. After the cellular game: each mutation's effect on the 3D organism. diff --git a/deploy/kubernetes/region/dev-session-route/listener.yaml b/deploy/kubernetes/region/dev-session-route/listener.yaml index ee2a7c3..319635d 100644 --- a/deploy/kubernetes/region/dev-session-route/listener.yaml +++ b/deploy/kubernetes/region/dev-session-route/listener.yaml @@ -12,7 +12,7 @@ spec: env: - {name: REGION_SESSION, value: "dev"} - {name: REGION_SESSION_LISTEN, value: "0.0.0.0:7400"} - - {name: REGION_SESSION_WINDOW, value: "dev-20261022T143710-858ce998:1792694230"} + - {name: REGION_SESSION_WINDOW, value: "dev-20261022T215205-42ad8184:1792720325"} - {name: REGION_M10_MAX_GRANT_LIFETIME, value: "14400"} ports: # QUIC (ADR-0090): UDP only; nothing listens on TCP 7400. diff --git a/docs/adr/0179-cellular-gameplay-revamp.md b/docs/adr/0179-cellular-gameplay-revamp.md new file mode 100644 index 0000000..9cb4d1f --- /dev/null +++ b/docs/adr/0179-cellular-gameplay-revamp.md @@ -0,0 +1,80 @@ +# ADR-0179: Cellular gameplay revamp + +## Status and scope + +Accepted product direction, 2026-10-22, from the maintainer's decisions in chat. +Implementation pending; see the [build plan](../../Cellular_Revamp_Build_Plan.md). +New rules (13) only: historical rules, checkpoints, tests and running worlds keep their +meanings. Every number is a trial value in the Git tuning file. DEV-only; no World0 +operation. + +## Context + +Playtests of rules 11-12 showed that reproduction had no purpose for the player and +that mutations were uniform draws over 32 generic operators unrelated to play. The +maintainer reviewed the cellular drafts (movement, feeding, energy and photosynthesis, +defense, the 150-entry mutation catalog) and settled each gameplay system in turn. + +## Decision + +The system plans are the decision. In summary: + +- **Mutations** ([plan](../../Cellular_mutation_plan.md)): a named catalog of 49 with a + pro and a con each. Per-cell affinity scores, raised and lowered by behaviour + triggers, inherited and never drifting, set each mutation's chance of appearing in + an offer between a 0.001% floor and a 70% cap. Three distinct options per offer by a + seeded draw that honors those chances. Per-mutation tunable cost, reclaimed by the + region as random bubbles. +- **Reproduction** ([plan](../../Cellular_reproduction_plan.md)): on-demand buds with a + stay-or-become choice; accepting a mutation splits the cell, both halves carry the + mutation in their heritable plan, only the offspring expresses it, and the player + chooses which cell to continue as. Litter gives up to 10 offspring per bud. Adhesion + forms a multicellular organism (one genome, one reserve) whose goal is emergence. +- **Feeding and energy** ([plan](../../Cellular_feeding_energy_plan.md)): per-channel + collection rates; reserve matter stands in for energy at a worse rate; burned matter + goes to a region spent pool that drips back as bubbles; reserve matter counts toward + mass for movement. +- **Predation and defense** ([plan](../../Cellular_predation_defense_plan.md)): instant + engulfment for everyone, with engulf capacity and membrane points; a kill's remainder + is split between bubbles and the spent pool. Armor and live capture are postponed. +- **Body and maintenance** ([plan](../../Cellular_body_maintenance_plan.md)): size, + density, a heritable body recipe, upkeep efficiency above an essential floor, growth + speed and bud share. +- **Postponed:** temperature, sensing, multicellular mutations, damage, draft groups + 071-150. + +## Conflicts with locked requirements + +The project vision is the product authority. Two decisions need the maintainer's +explicit confirmation before the affected code (build plan phase 5) is written: + +1. **Whole-organism mutations.** The vision locks "structural mutations are expressed + in offspring rather than rebuilding the parent's existing body". The reproduction + plan has a multicellular organism express an accepted mutation directly. Proposed + resolution: amend the vision so that the rule applies to single cells, and a + multicellular organism, being one body grown from many cells, re-expresses its plan + as a whole. Alternative: an organism's mutation is expressed only by members added + after it. +2. **Emergence before the 3D world.** ADR-0177's emergence needs the 3D world, which + does not exist. Proposed for the playtest: Emerge records the organism's matter as an + export from the region and ends the cellular life with an "emerged" outcome; the + player then starts a fresh life. + +## Alternatives + +- Keep the generic operator catalog and add weights (ADR-0135's rules-7 proposal): + rejected; operators carried no pro or con and no behaviour link. +- Burning matter into energy through bound chemical potential (feeding draft): + rejected as a new hidden resource; matter instead stands in for energy, so no energy + is created. +- Colonies of separate cells (ADR-0135 rules 8-9): replaced by one organism with one + genome and one reserve. + +## Consequences + +- Benefits: reproduction drives evolution; mutations follow play; more variation + between lives; a defined path toward emergence. +- Costs: genome schema 7 with many new fields, a new owner format, session protocol + and client screens; 49 triggers' counters per cell. +- Risks: matter-as-energy may make starvation rare; the energy-kept rule cuts founder + income to 40% unless bubble energy is retuned; one deploy at the end of the build. diff --git a/docs/adr/README.md b/docs/adr/README.md index f3bbe51..44233ba 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -1,5 +1,7 @@ # Architecture decision records +- [ADR-0179: Cellular gameplay revamp](0179-cellular-gameplay-revamp.md) - maintainer-accepted direction for rules 13: a 49-mutation catalog with behaviour-weighted offers, mutation splits and stay-or-become reproduction, multicellular organisms and emergence, matter as energy with a region spent pool, per-channel collection, membrane points and heritable body traits; two locked-requirement questions open; implementation pending. + - [ADR-0178: Durable liquid regions and session v13](0178-durable-liquid-region.md) - rules 12 on owner format 10 (currents, moving food, liquid motion), raw bundle 14 and schema 58 with a 13 -> 14 upgrade from the Git tuning file, the `cellular-v9` opening and session v13 (motion, currents, brake). - [ADR-0177: Cellular regions, world linkage and emergence](0177-cellular-regions-world-linkage.md) - maintainer-accepted direction: regions map to a world area rather than a voxel, currents and the thermal map are conditions not stock, capped regions refuse births, scaled emergence export, protected anchored logout; implementation pending.