Records the maintainer's region decisions: regions linked to a world area rather than a voxel, currents and a world-derived thermal map as conditions rather than stock, capped regions, fresh-life region choice, scaled emergence and a protected logout anchor. ADR-0098, 0172 and 0173 note the amendments. Adds the movement draft decisions (fixed-point motion state, player-dropped 007 anchor) and the phased implementation plan with a Git tuning file and bubble merging. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
269 lines
15 KiB
Markdown
269 lines
15 KiB
Markdown
# Cellular region and movement implementation plan
|
|
|
|
Status: approved for implementation, 2026-10-21. Implements
|
|
[Cellular region changes](Cellular_Region_Changes.md),
|
|
[Cellular movement draft](Cellular_movement_draft.md) and
|
|
[ADR-0177](docs/adr/0177-cellular-regions-world-linkage.md). Movement mutation
|
|
weights and timing start from the values chosen here and are tuned through the
|
|
tuning file; the separate [mutation review](Cellular_mutation_draft.md) can
|
|
replace them later.
|
|
|
|
## Approach
|
|
|
|
- **Test on the live DEV system.** Every phase ends in a deployable image and a new
|
|
DEV region opened with the new rules, then a playtest. No local-simulation gate.
|
|
- **Fast pushes (Phase 0, done).** A push to `main` gates only on the deploy policy
|
|
suite, then builds and publishes images. The full check matrix runs nightly, on
|
|
pull requests and on manual dispatch.
|
|
- **Disposable DEV worlds (ADR-0177).** New rules get new versions and a fresh
|
|
opening. No upgrade paths from existing bundles, checkpoints or envelopes.
|
|
- **One tuning file in Git.** Every tunable value lives in one file; see
|
|
[Tuning file](#tuning-file). Retuning is a Git change and a full Argo sync; no
|
|
image build.
|
|
- **Client and server together.** Each phase ships its client half, so every DEV
|
|
deploy is playable.
|
|
- **One shared motion step.** The same integer code runs on the server and in the
|
|
client predictor.
|
|
|
|
## Current code this plan changes
|
|
|
|
| Area | Today | File(s) |
|
|
| --- | --- | --- |
|
|
| Motion | Stateless per-tick proposal: position from intent x speed, cost proportional to distance, instant stop. | `include/evo/biology/cellular_motion.hpp`, `src/biology/cellular_motion.cpp` |
|
|
| Life step | Maintenance, then movement, then intake (ADR-0104). | `src/biology/cellular_step.cpp` |
|
|
| Region step | Lives in life-id order, shared deposit contention, engulfment, corpses become bubbles. | `src/biology/cellular_region_step.cpp` |
|
|
| Food | Habitat format 2: up to 4,096 static deposits, ordered and updated by address. | `include/evo/biology/cellular_habitat.hpp`, `src/biology/cellular_habitat.cpp` |
|
|
| Environment | Joint owner `AEVOCEN1`: one ambient temperature, infall, heat export. | `src/server/lifecycle/cellular_environment.cpp` |
|
|
| Lives and population | Owners 7/8, rules up to 11, bundle 13, schema 57. | `src/server/lifecycle/cellular_lives.cpp`, `cellular_population*.cpp` |
|
|
| Wildlife | Shared controller choosing intents. | `src/server/lifecycle/wildlife_controller.cpp` |
|
|
| Sessions | Session v12 perception lists in-range deposits by id (max 512, 26 bytes each). | `src/network/protocol/session_protocol.cpp`, `src/server/session/region_sessions.cpp` |
|
|
| Client | Probe-style own-marker predictor and interpolation. | `src/client/prediction/*.cpp`, `src/client/views/*.cpp` |
|
|
| Opening | `cellular-v8`: 30 x 30 mm, 9 pools, 1,800 bubbles, 20 C ambient. | `apps/evo-world-clone/main.cpp`, `deploy/kubernetes/region/dev/region-values.yaml` |
|
|
|
|
The world has no thermal map yet: each cellular region has one ambient temperature.
|
|
Phase 3 adds a seeded world thermal field for regions to sample.
|
|
|
|
## Tuning file
|
|
|
|
- **Location:** `deploy/kubernetes/region/dev/tuning/cellular.tuning`, mounted into
|
|
the region pod by a kustomize `configMapGenerator`, so a change restarts the
|
|
region through a normal Argo sync.
|
|
- **Format:** plain `key = value` lines with `#` comments; units in key names
|
|
(for example `founder.thrust_um_per_s2 = 400`). Integer values only, matching the
|
|
simulation. No new dependency.
|
|
- **Validation:** unknown keys, missing keys, duplicates and out-of-range values
|
|
are refused at startup, so a typo fails the sync visibly instead of running with
|
|
a default. The file carries a `tuning.version` key.
|
|
- **Determinism:** the region persists the tuning values with its checkpoint. When
|
|
a restarted region finds different values, it records a tuning change at the
|
|
next tick boundary and uses the new values from that tick. Replay of earlier
|
|
intervals uses the values in force at the time.
|
|
- **Scope:** every value in [v0 trial values](#v0-trial-values) plus movement
|
|
mutation weights, offer timing and future tunables as they are added. Values
|
|
that only shape a new region (size, current routes, seed) apply when a region
|
|
opens; the rest apply on restart.
|
|
|
|
## v0 trial values
|
|
|
|
Starting values for the tuning file, none locked.
|
|
|
|
| Quantity | v0 value | Reasoning |
|
|
| --- | --- | --- |
|
|
| Region size | 60 x 60 mm | Founder crosses in about 5 min; room for 2-4 routes and quiet pockets. Within the existing 1,000,000 um axis limit. |
|
|
| Perception radius | 5 mm (unchanged) | About 25 s of founder travel. |
|
|
| Founder top speed | 200 um/s (unchanged) | Top speed = thrust / drag. |
|
|
| Founder drag | k = 2 /s (95,163 ppm per tick) | 0.5 s time constant: responsive, coasts about 100 um from top speed. |
|
|
| Founder thrust | 400 um/s^2 | Gives the 200 um/s top speed at k = 2. Reverse thrust equal. |
|
|
| Founder turn rate | 1 turn/s | Responsive founder handling. |
|
|
| Currents | 2-4 per region, 3-6 mm wide, 60-300 um/s | 0.3x-1.5x founder speed (accepted). |
|
|
| Flow grid pitch | 250 um | Smooth at cell scale, 240 x 240 grid. |
|
|
| Ambient range | 5-40 C across the region | Gradual gradients; extremes optional. |
|
|
| Founder preferred | 20 C, comfort band +/- 5 C | Matches today's 20 C ambient. |
|
|
| Body response | tau = 20 s | Readable lag; gives warning before lethal. |
|
|
| Lethal (body temperature) | <= 0 C or >= 45 C | Applied to body, not ambient. |
|
|
| Thermal multiplier | `min(8, exp(0.08 * off_pref_C + 0.04 * transition_C))` | Two costs from the region draft, capped. |
|
|
| Region organism cap | 2,000 | Above today's population; tune from census. |
|
|
| Deposit limit | 8,192 | Larger region; raises the 4,096 limit. |
|
|
| Merged bubble cap | 8x a scattered bubble's stock | Bounds clumping; see moving food. |
|
|
| Visible moving bubbles | 256 per update, nearest first | Fits the snapshot budget with velocities. |
|
|
| Logout delay | 10 s | Same as the existing linger. |
|
|
| Movement mutation step | +/- 5 reference points, paired -/+ 2 | From the movement draft. |
|
|
| Recovery weight | `max(0.10, (index/100)^2)` below 100 | From the movement draft. |
|
|
| Offer cadence | 25 s of productive active play, 3 options per offer | Midpoint of the draft's 20-30 s. |
|
|
|
|
## Moving food
|
|
|
|
- **Merging.** When two bubbles touch, they become one bubble holding both
|
|
inventories. Its radius follows its total stock, and it keeps the lower id.
|
|
Bubbles at the merged-size cap stop merging, so currents cannot collapse all food
|
|
into a few huge bubbles. Merging is conserved by construction (one inventory sum)
|
|
and resolved in id order for determinism.
|
|
- **Multi-channel bubbles.** A merged bubble can hold several channels; contact
|
|
feeding already drains per channel. The client draws a merged bubble with its
|
|
channel colors.
|
|
- **Update limit.** Each update carries at most the configured number of moving
|
|
bubbles, nearest first. Farther ones are dropped from that update; the client
|
|
keeps advancing them with the shared flow field until a later update corrects
|
|
them. Bubbles overlapping on screen are indistinguishable, so this is not visible.
|
|
|
|
## Phases
|
|
|
|
Each phase lists server and client deliverables, then what is verified on DEV.
|
|
|
|
### Phase 0: pipeline (done)
|
|
|
|
- `.gitea/workflows/build.yaml`: on push only the deploy suite runs before the image
|
|
jobs; the full matrix runs nightly (09:00 UTC), on pull requests and on dispatch.
|
|
Nightly runs have their own concurrency group so pushes do not cancel them.
|
|
|
|
### Phase 1: motion core and tuning file
|
|
|
|
Server:
|
|
- `CellularMotionState`: Q10 velocity, 16-bit heading, sub-micrometre accumulator.
|
|
- Checked-in integer sine/cosine table with golden tests.
|
|
- Per-tick step from the movement draft's numeric representation: turn, funded
|
|
thrust, drag toward exactly zero, add flow, displacement with carried remainder.
|
|
- Cost proportional to thrust used, divided by efficiency, not to distance.
|
|
Unfundable thrust is not applied; the cell coasts. Maintenance failure still
|
|
kills (existing behavior).
|
|
- Swept contact against deposits and cells, subdividing so no step exceeds half
|
|
the smallest contact radius, with a fixed work bound per tick.
|
|
- `CellularMovementProfile` derived from the genome: thrust, efficiency, burst
|
|
capacity and reserve, turn rate, forward and lateral drag, reverse thrust, anchor
|
|
capacity, colony drive. Ten fields for 001-010.
|
|
- Genome schema 6 with movement records at reference 100 for the founder; founder
|
|
version 5; development version 6.
|
|
- Tuning file parser and validation, shared by the server and `evo-world-clone`.
|
|
|
|
Client:
|
|
- Shared motion step linked into the client; the cell predictor uses it.
|
|
- Brake and reverse controls (rebindable, ADR-0085); movement-state indicator.
|
|
|
|
Verify: golden trajectories, decay to zero, no tunneling at 2x the top current
|
|
speed, equal results across restore points, thrust-cost properties, tuning file
|
|
refusals.
|
|
|
|
### Phase 2: currents, moving food and persistence
|
|
|
|
Server:
|
|
- Habitat format 3: deposits keyed and updated by stable id (not address), each
|
|
with Q10 velocity for induced drift; a fixed-pitch spatial bucket index for
|
|
contact; deposit limit from tuning.
|
|
- Seeded current generator: 2-n looping routes with width, direction and speed,
|
|
rasterized to the Q10 flow grid. Intersections add as vectors and are clamped to
|
|
the larger route speed.
|
|
- Bubbles move with the flow each tick in id order, merge on contact (see moving
|
|
food), and deflect along solid edges so nothing piles up.
|
|
- Induced drift from passing cells: radius, falloff, decay and maximum speed from
|
|
tuning; contributions combine in life-id order.
|
|
- Region step tick order: maintenance, turn and thrust, motion and swept contact,
|
|
deposit advection, induced drift and merging, contact feeding, engulfment,
|
|
deaths, births.
|
|
- Persistence: rules 12, owner format 10, population envelope 4 and joint envelope
|
|
format 2 carry motion state, deposit velocities and current configuration;
|
|
durable bundle 14 and schema 58, entered only by a fresh `cellular-v9` opening.
|
|
Joint batch 2 re-derives currents from configuration.
|
|
- Opening `cellular-v9` in a new DEV region (`evo-world-clone`).
|
|
|
|
Client:
|
|
- Session v13: own-life motion state; deposits with velocity under the update limit;
|
|
current configuration sent once at admission so the client builds the same grid.
|
|
- Bubbles advanced with the flow field between updates; merged bubbles drawn with
|
|
their channel colors.
|
|
- Flow cues: trails and drifting specks that are clearly not food.
|
|
|
|
Verify on DEV: food circulates and merges without loss or piles; founder handling
|
|
in and across currents; restart resumes identical trajectories; tick time against
|
|
the load governor (ADR-0097).
|
|
|
|
### Phase 3: thermal map and thermal biology
|
|
|
|
Server:
|
|
- World thermal field: seeded and coarse per world, sampled over the region's world
|
|
area and scaled down to the habitat (ADR-0177). The region configuration stores
|
|
the world-area reference and scale.
|
|
- Per-cell thermal state: body temperature (mK) and acclimation offset.
|
|
- Genome thermal fields: preferred temperature, comfort band, tau, lethal cold and
|
|
heat limits; the parameters thermal mutations (091-095, 097) edit.
|
|
- Integer exp table (Q16) for the capped multiplier on survival E. A body-temperature
|
|
lethal check feeds the existing corpse-to-bubbles path with a new death cause.
|
|
|
|
Client:
|
|
- Heat-map terrain; compass; temperature gauge showing ambient, body and preferred
|
|
band; contours or patterns for stressful and lethal areas, not color alone.
|
|
- Thermal death shown as its own cause on the end-of-life screen.
|
|
|
|
Verify on DEV: costs rise and settle as expected crossing gradients; lethal areas
|
|
are reached only by choice; first-birth time stays near 3 minutes.
|
|
|
|
### Phase 4: movement mutations 001-010
|
|
|
|
Server:
|
|
- Operators for all ten as fixed-reference percentage edits on the Phase 1 fields,
|
|
including acquisition and shedding for 003, 007, 009 and 010.
|
|
- 007 anchor: a player-triggered drop that fixes the cell at the point it hits
|
|
until released; holding capacity against flow load.
|
|
- 009 and 010 are offered only where colony attachment makes them meaningful.
|
|
- Offer weights, recovery factor and cadence from the tuning file.
|
|
|
|
Client:
|
|
- Offer screen previews: before and after movement profile at matched conditions.
|
|
- Anchor drop/release control and anchored state.
|
|
- Visual body changes from the movement draft's tentative indicators (001-006),
|
|
shared by NPCs and players.
|
|
|
|
Verify on DEV: each option changes handling in the expected direction.
|
|
|
|
### Phase 5: wildlife
|
|
|
|
- The wildlife controller plans with inertia (brakes before targets), uses currents
|
|
(rides toward food), avoids lethal temperatures, seeks its preferred range and
|
|
drops its anchor when it has one. Same rules as players.
|
|
- Verify on DEV: wildlife survives and reproduces in the new regions without
|
|
collapsing into one site.
|
|
|
|
### Phase 6: logout, capacity and region choice
|
|
|
|
Server:
|
|
- Logout: a delay with the cell vulnerable, then anchored, protected, and with
|
|
metabolism and thermal response frozen; resume restores frozen motion state.
|
|
Replaces the ADR-0098 linger for rules 12.
|
|
- Region cap: births refused at the cap with a recorded reason; the wildlife
|
|
controller stops attempting them.
|
|
- Admin culling: an operator endpoint on the existing ops HTTP server
|
|
(`src/server/ops_http.cpp`) that records each cull as an operator action.
|
|
- Fresh-life region choice: list a world's regions with open capacity at admission,
|
|
and route the new life through the existing redirect and handoff path (ADR-0096).
|
|
|
|
Client:
|
|
- Region choice screen for a fresh life; logout countdown; a notice when a birth is
|
|
refused because the region is full.
|
|
|
|
Verify on DEV: cannot escape a closing predator by logging out; a capped region
|
|
refuses births and reopens after deaths; two accounts choose the same region.
|
|
|
|
### Later: emergence
|
|
|
|
Emergence (scaled export, candidate selection, bulk queue) needs multicellularity
|
|
and the 3D world. This plan keeps it possible: the region's world-area link and the
|
|
thermal field from Phase 3 are what emergence targeting will use.
|
|
|
|
## Instrumentation for every playtest
|
|
|
|
Extend `src/server/lifecycle/cellular_play_summary.cpp` with first-birth time,
|
|
solitary-stage length, deaths by cause (starved, engulfed, thermal), time spent in
|
|
currents versus quiet water versus anchored, propulsion E share of total E, bubble
|
|
merges, and per-tick region work. These answer whether the 3-minute and
|
|
30-60-minute targets hold.
|
|
|
|
## Risks
|
|
|
|
| Risk | Mitigation |
|
|
| --- | --- |
|
|
| Moving deposits raise tick cost | Spatial bucket index and merging reduce work; measure against the load governor in Phase 2. |
|
|
| Merging collapses food into few large bubbles | Merged-size cap from tuning; watch merge counts. |
|
|
| Prediction feels rubbery | Shared motion code in the client; measure prediction error on DEV. |
|
|
| Ten movement parameters interact badly | Instrumentation plus removal of options that do not fit, as decided. |
|
|
| Determinism drift between server and client | One library, golden trajectory tests in both builds. |
|
|
| Less CI on pushes lets regressions reach DEV | Nightly full matrix; fix red nightly runs before the next phase. |
|