docs: cellular revamp build plan and ADR-0179
Foundation / checks (checks) (push) Successful in 5s
Foundation / checks (client) (push) Successful in 5s
Foundation / checks (network) (push) Successful in 4s
Foundation / checks (ecs) (push) Successful in 4s
Foundation / checks (postgres) (push) Successful in 5s
Foundation / checks (tsan) (push) Successful in 5s
Foundation / checks (deploy) (push) Successful in 4m34s
Foundation / postgres-tools (push) Successful in 5s
Foundation / server-image (push) Successful in 5s
Foundation / image (push) Successful in 5s

ADR-0179 records the maintainer's cellular gameplay revamp (rules 13) and the
two locked-requirement questions it raises: whole-organism mutations versus
"structural changes are expressed in offspring", and what Emerge does before
the 3D world exists. The build plan stages the work in six phases (genome and
body, feeding and predation, mutation offers, reproduction, multicellular and
emergence, wildlife and the playtest), each pushed with CI green and deployed
once at the end. Refreshes the DEV session window.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-22 17:59:35 -04:00
co-authored by Claude Opus 5.5
parent 628721dff4
commit 0a5cf3e6bd
5 changed files with 235 additions and 2 deletions
+150
View File
@@ -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. |
+2 -1
View File
@@ -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.
@@ -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.
+80
View File
@@ -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.
+2
View File
@@ -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.