From 34f544942f40446c7846628a4d68d42eabb01679 Mon Sep 17 00:00:00 2001 From: dingo Date: Wed, 21 Oct 2026 16:13:20 -0400 Subject: [PATCH] docs: cellular region and movement redesign with ADR-0177 and implementation plan 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 --- Cellular_Region_Changes.md | 660 ++++++++++++++++ Cellular_Region_Movement_Plan.md | 268 +++++++ Cellular_movement_draft.md | 718 ++++++++++++++++++ .../0098-m11-first-cellular-loop-decisions.md | 6 + .../0172-cellular-environment-ownership.md | 7 + docs/adr/0173-cellular-environment-batch.md | 5 + .../0177-cellular-regions-world-linkage.md | 110 +++ docs/adr/README.md | 2 + 8 files changed, 1776 insertions(+) create mode 100644 Cellular_Region_Changes.md create mode 100644 Cellular_Region_Movement_Plan.md create mode 100644 Cellular_movement_draft.md create mode 100644 docs/adr/0177-cellular-regions-world-linkage.md diff --git a/Cellular_Region_Changes.md b/Cellular_Region_Changes.md new file mode 100644 index 0000000..44d2366 --- /dev/null +++ b/Cellular_Region_Changes.md @@ -0,0 +1,660 @@ +# Cellular region changes + +Status: discussion draft, 2026-10-21. Companion to +[Cellular_mutation_draft.md](Cellular_mutation_draft.md) and +[Cellular_movement_draft.md](Cellular_movement_draft.md). This document proposes +region changes needed for liquid movement, circulating food, and meaningful +thermal adaptations. It changes no runtime rules, public APIs, schema versions, +live worlds, or milestone status. No commit, push, or deployment is authorized +while the maintainer reviews these drafts. + +## Purpose and scope + +Make the early cellular habitat a readable, interactive liquid environment. +Regions should support useful travel, feeding routes, reproduction, and early +colonies rather than rewarding long periods of waiting on a pool. + +The discussion establishes the following design direction: + +- Cells propel themselves through liquid; food and cells also respond to flow. +- Quiet areas and stronger currents coexist. Main currents can circulate around + a region instead of carrying everything into one boundary. +- Generate each region procedurally with 2-n currents, each with its own direction + and speed. Currents can intersect; the maximum count and speed ranges need trials. +- Movement needs acceleration, passive deceleration, active braking, and turning. +- Generate a regional thermal map. The cell has its own temperature, and the UI + provides a compass, temperature gauge, and heat-map-style environmental colors. +- Thermal mismatch increases survival E use exponentially; cells can acclimate or + evolve cold, heat, and overall thermal adaptations. Extreme freezing/boiling + exposure can cause immediate death. Current cell temperature, preferred cell + temperature, and environmental temperature all contribute; the equation and + numeric thresholds remain open for balancing. +- Passing cells disturb nearby food bubbles in their direction of travel, with + distance falloff and decay of the induced drift. +- Ordinary active founders should be able to fund their first birth in about + three minutes. The intended solitary-cell stage is roughly 30-60 minutes, + without making a multicellular transition mandatory for every strategy. + +Specific field layouts, temperatures, response curves, costs, representations, +phase ordering, and implementation stages below remain **proposals**. This is a +gameplay model to tune for useful choices, not a requirement for full fluid or +biochemical simulation. Presentation can be expressive without expanding the +authoritative simulation beyond what gameplay needs. + +The scope is cellular 2D habitat behavior and its environmental ownership. No +macroscopic renderer, shared 2D/3D collision model, automatic World0 upgrade, +prebuilt wildlife, or new third-party dependency is introduced. + +### Maintainer responses to the original ten questions + +Recorded from the region review on 2026-10-21. These establish draft gameplay +direction, not runtime admission or a replacement for existing architecture. + +| Original question | Recorded direction | Remaining scope | +| --- | --- | --- | +| 1. Motion/current values | Trial and error; include currents of different speeds. | Tune founder handling and current ranges in playtests. | +| 2. Current generation | Procedural regions with 2-n currents; determine direction per current; intersections allowed. | Bounded count, generation, intersection composition, and representation. | +| 3. Boundaries/contact | N/A for this gameplay discussion. | Retain technical ownership/contact constraints; do not reopen as a required player-facing feature. | +| 4. Thermal model/UI | Procedural thermal map; compass and temperature gauge; cells have an actual temperature and a preferred temperature. | Field accounting/response and readable presentation of all three temperatures. | +| 5. Thermal effects | Current cell, preferred cell, and environmental temperatures all matter. Drastic changes require more E; mismatch from preference keeps costs elevated after adjustment. Mutations modify cold, heat, or overall handling; extreme exposure can kill immediately. | Balance the combined exponential response, acclimation rates, protection costs, and death thresholds. | +| 6. Flow and speed | With the flow is faster; against it is slower; outside flow is baseline. | Relative-vector behavior, braking/reversing controls, and numeric tuning. | +| 7. Visible cues | Cellular mechanics have visual cues; terrain resembles a thermal heat map. | Readable palette, compass/gauge details, and local perception integration. | +| 8. Offline/lifecycle | Logout takes effect after a delay, then the cell is anchored, protected from engulfment, and frozen. See the follow-up decisions below. | Delay duration and resume behavior. | +| 9. Colony roles | Requires playtesting. | Viable support roles and whether distinct propulsion adaptations add value. | +| 10. Unattended feeding | Lower priority; expected to be slower and risky because other cells can engulf the player. | Verify in playtests; no separate anti-AFK layer proposed. | + +### Maintainer follow-up decisions + +Recorded 2026-10-21 and documented as accepted direction in +[ADR-0177](docs/adr/0177-cellular-regions-world-linkage.md), which amends +ADR-0172 and ADR-0173 for new cellular rules. + +| Topic | Decision | Still open | +| --- | --- | --- | +| Current energy | Currents are a fixed environmental condition. No mechanical energy accounting; drifting never credits usable E. | None for playtests. | +| Thermal backing | A static maintained thermal map, not owned thermal energy. | Owned thermal energy only if gameplay later needs changing temperatures. | +| Versions and worlds | New rules start in new, disposable DEV worlds; no migration of existing DEV worlds. | None. | +| Habitat size and world link | A region is linked to an area of its world, not to one voxel. Its thermal map is that area's world thermal map scaled down. | Mapping scale and region dimensions. | +| Region capacity | Regions do not grow. Each has a hard organism cap; the world adds regions. Births are refused at the cap. Engulfment and death reopen slots. Operators can cull wildlife through an admin interface when a capped region has had no players for extended days. | Cap value; equation for adding a region to the world versus attaching it to a new world. | +| Region choice | A fresh cell is offered a choice of region when it begins. | Selection presentation. | +| Emergence exchange | Matter that emerges is lost to the cellular region (a recorded export). The organism enters the world scaled to world values. | Conversion scale, after regions per world and matter per region are known. | +| Emergence target | Rank several candidates in the region's mapped world area closest to the preferred temperature with needed nutrients; choose one at random. Finite resources self-penalize crowding. | Candidate count and ranking weights. | +| Group emergence | The emerging organism chooses individual or bulk. Bulk joins a selection queue; organisms emerging together with the same or close biology share one target pick. | Queue timing and similarity threshold. | +| Logout | A logout delay keeps the cell in play and vulnerable; logging out while about to be engulfed does not save it. Afterwards the cell is anchored, cannot be engulfed, is not moved by flow, and its metabolism and thermal response stop. | Delay duration. | + +## Existing architecture and the changes needed + +Read this proposal against: + +- [Project vision](docs/PROJECT_VISION.md). +- [World architecture](docs/architecture/WORLD_ARCHITECTURE.md). +- [Environmental units and compartments](docs/world/ENVIRONMENTAL_UNITS.md). +- [Existing optional environmental fields](docs/world/ENVIRONMENTAL_FIELDS.md). +- [Energy and matter accounting](docs/biology/ENERGY_MODEL.md). +- [Bounded cellular motion trial](docs/adr/0102-cellular-spatial-trial.md). +- [Open energy, food bubbles, and pools proposal](docs/adr/0136-open-energy-and-scattered-nutrients.md). +- [Cellular environmental ownership](docs/adr/0172-cellular-environment-ownership.md). +- [Joint environmental batch](docs/adr/0173-cellular-environment-batch.md). +- [Local environmental scheduling](docs/architecture/ENVIRONMENTAL_SCHEDULING.md). +- [Photosynthesis producers](docs/adr/0175-photosynthesis-producers.md). + +| Existing boundary | Required extension or decision | +| --- | --- | +| The spatial trial resolves phenotype-limited movement intentions and contact. | Add explicit velocity/response semantics for propulsion, turning, slowing, currents, and anchoring. Do not reinterpret old movement records. | +| The cellular environment owns tagged water, dissolved nutrients, and nested organic inventories. | Add currents and the thermal map as seeded environmental conditions under the same spatial authority. They are not stock and not a second resource store. | +| Waste heat and radiative export have accounting meanings. | Keep them unchanged. The thermal map is a maintained condition derived from the world, not accumulated waste heat. Specify the biological response. | +| The habitat sits inside one environmental voxel (ADR-0172). | Link the region to a world area instead, with a hard organism cap (ADR-0177). | +| Optional M6 fields and processes are scoped experiments. | Their existence does not automatically provide live cellular flow, temperature, feeding conversions, or damage. | +| Existing environmental intervals have explicit tick and replay boundaries. | Any new coupled process needs its own documented ordering, bounds, persistence, and restored continuation. | +| Presentation consumes immutable environmental/biological views. | Publish readable flow and temperature information without moving simulation authority into the client. | + +These are design gaps to resolve before implementation, not permission to silently +extend an accepted ADR. New motion, thermal, and durability behavior need scoped +decisions and explicit versions. New rules start in new DEV worlds; existing DEV +worlds are disposable and are not migrated. + +## Region layout and geometry + +Keep the distinction between a logical region, its cellular habitat, environmental +field resolution, and any underlying world voxel/chunk. A current does not need +to follow server partitions, and a visual river-like path is not a new ownership +boundary or a solid corridor. + +The habitat remains a bounded 2D area with a declared effective depth. Changing its +area, depth, or sampling resolution does not create water, nutrients, energy, or +extra organisms. Under ADR-0177 the habitat is no longer tied to one world voxel: +it is linked to an area of its world and can be as large as currents, quiet +pockets, and eddies need. Its size grows only by design, not with population; a +hard organism cap bounds each region and the world adds regions instead. + +Proposed features within one habitat: + +| Feature | Gameplay purpose | Design constraint | +| --- | --- | --- | +| Quiet pockets | Learn steering, collect initial food, and reproduce. | Still provide useful exits and resources; do not become the universally best AFK location. | +| Main circulating route | Carry food and provide a recognizable travel route. | Allow crossing/exiting; avoid a forced one-way ride. | +| Rejoining branches | Offer shortcuts, interception routes, and different risks. | Communicate where routes lead within perception limits. | +| Local eddies | Create recurring encounters and food gathering areas. | Do not trap all food permanently or manufacture replenishment. | +| Anchoring | Support anchored and stationary colony strategies. | The 007 anchor is player-triggered and holds where it hits; no prepared surface is needed. | +| Thermal gradients | Make habitat choice and thermal specialization useful. | Readable transitions and reachable alternatives; no hidden lethal line at a field boundary. | + +Do not make every quiet area cold, every fast current hot, or every rich food site +hazardous. Independent combinations allow several viable strategies. Reproduction +needs enough physical space for resulting organisms, including when the parent +and offspring are being carried by a current. + +## Flows + +### Local velocity and circulation + +Define local flow as a velocity vector sampled at an authoritative position and +tick, in the same spatial frame and compatible units as cell movement. Distinguish: + +`world velocity = local liquid velocity + swimming velocity relative to liquid` + +This decomposition does not mean adding current repeatedly as unlimited swimming +acceleration. Coupling to changing flow, response time, sampling, interpolation, +rounding, and motion limits need a defined model. Ordinary cells and loose bubbles +already drift; a mutation must add something beyond that baseline to be useful. + +Generate 2-n current routes/areas per region from explicit procedural configuration +and seed, with an individually determined direction and speed for each. Evaluate +several speeds through trial and error rather than selecting one universal current +speed. The maximum n, route width, speed distribution, and quiet-area coverage remain +tunable and bounded before implementation. Seeded generation does not grant infinite +water, nutrients, or energy. + +Currents may intersect. Cells and food must experience one consistent resulting +local flow at an intersection, not whichever current happens to be processed last. +Vector composition with bounded magnitudes is a candidate, not a selected rule; +opposing cancellation, crossing deflection, and limit handling need trials. +Use the same field/sample semantics for affected objects, subject to their explicit +response and attachment rules. + +A bounded seeded velocity field is a possible representation; full computational +fluid dynamics is not required. Keep transitions readable and compatible with +boundaries. A static field means unchanging flow directions/strengths, not stationary +water. Whether currents later vary over time remains open and must preserve replay. + +Main routes can loop inside the habitat, with slow pockets and rejoining branches. +This is a proposed initial layout, not a requirement that every future region be +hydrologically closed. There is no edge wrap or teleport returning a bubble to +the opposite side. Avoid outward flow that is merely clamped at a wall, producing +an artificial pile of every cell and food item. + +At solid boundaries, the chosen flow/motion representation needs consistent +nonpenetration and no unintended stock loss. Future open boundaries need actual +handoff of organisms and material, not despawn-at-source/spawn-at-destination. +Cross-region flow belongs to a later explicitly qualified ownership contract. + +### Propulsion and slowing + +At the same supported propulsion output and body state, travelling with the current +increases progress through the region; travelling against it reduces progress. +Outside a current, ambient flow is zero and ordinary swimming is at the cell's +baseline for those conditions. Acceleration/braking transients still apply. Cross-flow +deflects world movement according to the eventual vector model; this is not a +universal scalar speed bonus. A sufficiently strong opposing current can prevent +upstream progress without reducing the cell's swimming capacity relative to water. + +Do not separately add a matching speed buff/debuff after applying flow. Equal +output may have the same propulsion E/time while the time and E needed to reach a +fixed world destination differ. Station keeping still requires funded opposing work. + +| Action/state | Required behavior | Cost meaning | +| --- | --- | --- | +| Propelling | Accelerate relative to liquid within available output and steering limits. | Fund applied output; do not charge maximum propulsion at every nonzero speed. | +| Releasing propulsion | Lose relative swimming speed through passive resistance while continuing to drift. | No active propulsion expenditure; dissipation is not usable cellular energy. | +| Active braking/reversing | Use opposing propulsion to slow or reverse faster. | Pay for actual opposing output. | +| Station keeping | Swim against flow to hold a position in the region. | Continuous funded work, not the default meaning of no input. | +| Anchored (007) | The player drops the anchor; the cell holds at the point it hits. | Construction, drop/release, load, and holding-capacity rules must be explicit. | +| Attached colony | Combine useful propulsion with total arrangement load/resistance. | No automatic speed multiplier from member count; no duplicate charge for shared work. | + +Use the [movement draft's](Cellular_movement_draft.md) calculated profile: +propulsion and steering machinery, body shape, mass, and resistance produce speed, acceleration, passive +slowing, active braking, turning, and operating cost. Founder reference displays +can read 100% under fixed reference conditions; actual values still need tuning. +Zero/absent capabilities are not 100%, and account age confers no movement bonus. + +Exact control behavior remains open: automatic versus deliberate braking, +reverse-thrust controls, how heading changes at different speeds, and how an +energy-starved cell passively drifts. Start with responsive founder handling; +extended uncontrollable coasting should not be required to learn the game. + +### Environmental driving and energy + +Decided: currents are a fixed environmental condition, like incident light. They +are not stock and carry no mechanical energy accounting; no driving source, +entitlement, or work/dissipation ledger is needed. Forces against an anchor or +attached body are likewise mechanical rules, not energy transfers. + +Drifting never credits a cell's usable E reserve, and no process harvests flow +energy. Propulsion expenditure still transfers reserve E to heat as today. + +## Food and material transport + +| Material/object | Proposed behavior | Accounting requirement | +| --- | --- | --- | +| Loose nutrient/energy bubbles | Move with local flow under a stated response model; retain identity and finite stock. | Movement changes position, not amount or channel. | +| Finite resource pools | Can remain fixed where explicitly declared. | No replenishment from an animation or passing current; any resupply needs a source debit/import. | +| Living cells | Drift plus their funded relative swimming, subject to contact/attachment. | Existing bodies/reserves remain the same owned inventory while moving. | +| Corpses/detritus | Use explicit mobility/attachment rules, or the supported corpse-to-bubble process. | Conversion occurs once; no spendable corpse and duplicate bubbles. | +| Dissolved compartments | Only move/convert through defined conservative processes. | Bubble advection does not automatically implement dissolved transport or make dissolved stocks edible. | +| Visual particles/trails | Illustrate flow without being collectible resource objects. | Must not appear as edible stock or create a second food system. | + +### Drift caused by passing cells + +In addition to ambient currents, a passing cell disturbs nearby food bubbles so +they drift somewhat in the direction the cell was travelling. This is part of +the recorded gameplay direction, not just a client animation. The influence +decreases with distance from the passing cell, and the extra bubble drift speed +falls off over time, returning toward ordinary local-current drift. + +Separate base flow from the temporary induced motion: + +`bubble world velocity = ambient flow response + temporary cell-induced drift` + +This is a conceptual decomposition, not a selected numerical solver. Influence +radius, near/far falloff, decay time, maximum induced speed, and dependence on cell +speed, size, or propulsion output need playtesting. Specify whether the disturbance +uses world travel or swimming relative to water; do not silently settle that choice. +Use a bounded deterministic combination when several cells pass the same bubble, +without dependence on connection or iteration order. + +The disturbance changes position/motion, not nutrient identity or amount. It can +occur outside a main current too. It must not pull distant food through other cells, +grant unlimited extra collection range, or stack permanent velocity on every pass. +Like currents, it has no energy accounting and is never a source of usable cellular +E. Persist or deterministically reconstruct +any temporary bubble motion needed for identical restored continuation. + +Equal drift does not make a cell catch a nearby bubble. Players still need useful +relative motion or contact. Active play can involve intercepting a cluster, +matching its drift while feeding, then exiting toward a quiet reproduction site. +Collecting a bubble should not automatically impose a generic speed penalty. + +High flow or propulsion must not skip contact with food or pass through cells. +Choose swept contact or bounded motion subdivisions with explicit work limits; +do not change the biological tick duration or skip feeding costs to hide tunneling. +Contention and transfer order must remain stable and independent of connection +order. Collisions, sticking, pushing, and engulfment need their own supported +rules rather than one generic "speed through other cells" percentage. + +Decided 2026-10-21: bubbles that touch merge into one bubble holding both +inventories, keeping the lower id, with radius from total stock. A tunable size cap +stops further merging. Merges resolve in id order. Each update carries a tunable +number of moving bubbles, nearest first; the client advances the rest with the +shared flow field. See the [implementation plan](Cellular_Region_Movement_Plan.md). + +## Thermal conditions + +### What temperature means + +The selected draft direction is a **procedurally generated thermal map**, plus an +actual temperature state for each cell. Use explicit seed/configuration and +continuous/readable spatial differences. The map describes local environmental +temperature; it is not the cell's own temperature and is not a new edible resource. +The UI must expose a compass and temperature gauge for navigation and make thermal +differences visible in the habitat rather than rendering flat-color terrain. + +Temperature is an environmental condition, not usable E or an amount of food. +The existing heat sink does not by itself define local temperature: we need an +explicit thermal reference, heat capacity, spatial ownership, and exchange model. +Stored units should follow the repository's dimensional conventions; a Celsius +display can be derived for readability. No gameplay temperature values are selected +by this draft, and missing thermal state is not zero kelvin or a safe default. + +Decided backing: the region's thermal map is the thermal map of its linked world +area, scaled down to the habitat (ADR-0177). It is a static maintained condition, +not owned thermal energy, and needs no energy exchange accounting. Owned thermal +energy with heat capacity is deferred until gameplay needs temperatures that +change, for example colonies warming their surroundings. Waste heat is never +recovered into usable cell E. + +### Layout, sources, and transport + +Use broad, readable differences rather than a random checkerboard of lethal cells. +A founder-accessible comfortable area can border cooler/warmer opportunities with +gradual transitions. Extreme areas should initially be optional routes, not the +only source of a nutrient every founder needs to reproduce. + +Because the map is maintained, currents do not carry heat and gradients stay +fixed. A warm vent illustration is presentation, not an energy source. Existing +radiative exports must not also be counted as heating local liquid. + +Thermal map resolution may differ from flow or food resolution. Sampling, +organism footprint overlap, and boundary continuity need explicit semantics. + +### Effects on organisms + +The maintainer clarified that **all three temperatures contribute**, rather than +choosing a single reference: + +| Temperature | Meaning | Role in the response | +| --- | --- | --- | +| Environmental temperature | The local liquid temperature experienced by the cell. | Determines current exposure and the conditions the body is adjusting to. | +| Current cell temperature | The cell's actual present temperature. | Responds over time; its difference from the environment contributes to the difficulty of handling a transition. | +| Preferred cell temperature | The cell's favored operating temperature, distinct from its actual temperature. | Keeps off-preference living more costly even after actual temperature approaches the environment. | + +There are two connected cost behaviors to preserve when choosing an equation: + +- **Transition/handling cost:** drastic changes between the current body state and + surrounding temperature require more E to handle. Rapidly entering a very different + environment can be especially demanding. This component can diminish as the cell + adjusts, depending on its acclimation and mutations. +- **Persistent off-preference cost:** settling toward the environmental temperature + does not automatically restore baseline. If the resulting conditions remain far + from the preferred temperature, survival still costs more than living near preference. + +The overall thermal penalty should increase exponentially with relevant unsupported +mismatch, subject to balancing. Do not select an exponent, coefficient, comfort width, +or cap simply to fill this draft. Whether the terms add, multiply, share one response +curve, or use another relationship remains open. Avoid counting the same sustained +stress twice just because both body-to-preference and environment-to-preference +differences can describe it. + +Use `survival E/time = baseline survival E/time * thermal multiplier` only as a +conceptual placeholder. The multiplier depends on all three temperatures, the cell's +acclimation state, and relevant mutations. It approaches 1 when conditions are well +handled and near preference; a supported adaptation can reduce or remove extra +thermal cost over its useful range. Ordinary movement, construction, and other +activity costs remain separate; do not indiscriminately multiply every resource +cost by a thermal factor. + +Cells can **acclimate** over time or acquire **mutations** that change how well +they handle temperature. Actual temperature adjustment must not automatically +overwrite preferred temperature to equal the surroundings. Acclimation is +physiological adjustment, distinct from selecting structural offspring adaptations +or automatically rewriting the inherited genome. Its range/rate, whether it can +shift a preferred operating range within limits, and inheritance behavior need +balancing and explicit rules. Neither adjustment nor acclimation instantly erases +all extremes. + +Example behavior, without choosing temperatures or coefficients: a cell leaves +its preferred environment for a much hotter area. It initially pays a high handling +cost. Its actual temperature then rises and its handling cost can decrease, but +remaining in that hot area still has an off-preference cost. A heat-adapted descendant +can reduce that burden; a cold specialist need not receive the same benefit. + +| State relative to the organism's supported range | Proposed gameplay response | Decision still needed | +| --- | --- | --- | +| Current body and environment near preference | Survival E use approaches ordinary baseline. | Comfort band, baseline calibration, and the combined equation. | +| Abrupt transition away from current body temperature | Increased handling E demand while the cell responds. | Response rate, acclimation limits, mutation effects, and how abruptness enters the equation. | +| Body adjusted but environment/body still off preference | Extra survival cost persists despite a smaller body/environment difference. | Sustained stress curve and specialist/generalist tolerance. | +| Extreme freezing/boiling exposure | Can cause immediate permanent death, including rapid entry into an extreme area. | Organism-specific lethal thresholds and whether ambient or actual cell temperature triggers the event. | + +This explicitly revises the earlier suggestion that thermal boundary crossings +should never kill instantly. Extreme areas may be immediately lethal; do not +silently grant a universal exposure grace period. Communicate danger before entry +through visible thermal cues, the gauge, and navigation. Ordinary gradients and +founder routes should remain usable without requiring entry into those extremes. +No universal 0/100-degree thresholds are adopted; temperature values and environmental +conditions must be explicitly chosen. Body-temperature change, acclimation, exposure, +and lethal thresholds are related but distinct. Partial footprint exposure still +needs defined treatment. + +Thermal protection must occupy actual tissue or require actual operating resources +if shedding it is to save anything. A specialist can give up breadth for better +local performance only through a specified response/recipe. The current tolerance +parameter must not silently acquire new low/high/optimum meanings under old schemas. + +Provide cold-specific, heat-specific, and overall thermal adaptation options. +Heat and cold handling may differ in the same cell. A broader adaptation may handle +both well enough to leave no extra thermal penalty across the supported practical +range. That does not silently grant immunity to every lethal threshold or eliminate +the actual construction/upkeep cost of the adaptation. Specify any such protection +explicitly; useful traits still need the catalog's meaningful tradeoffs. +The exact effects on handling cost, persistent cost, acclimation, preferred range, +and lethal limits need later review against the balanced equation. Do not revise +the 150 mutation entries incidentally while the maintainer reviews other groups. + +Do not apply new temperature effects to food spoilage, nutrient conversion, +reproduction, mutation rates, or photosynthesis merely because a field now exists. +Each coupling needs a defined benefit, drawback, accounting treatment, and version. + +## Mutation opportunities supported by the region + +The mutation catalog remains the source for individual tradeoffs; this document +lists what the environment must provide for those offers to mean anything. + +| Draft IDs | Environmental requirement | Offer/context treatment | +| --- | --- | --- | +| 001-005 propulsion/steering | Useful routes, readable resistance, acceleration/braking, and actual output costs. | Productive travel/interception/crossing can raise weights; inputs alone do not farm offers. | +| 006 active braking propulsion, proposed replacement | Funded opposing propulsion with useful capacity beyond ordinary founder braking. | Stop/reverse demands weight the option; old Current sail stays archived pending a distinct benefit. | +| 007, 099 anchoring | Currents that make holding position useful; paid anchor construction, drop, and release. | Costly station keeping/dislodging is relevant context; no need to suffer injury first. | +| 008 coasting-biased body, proposed replacement | Stored relative velocity and a body-resistance change distinct from 005 streamlining. | Useful open coasting can favor it; overshooting/precise-stop demands can reduce weight. Former food sensing is reclassified for later review. | +| 104 flow sensing | A useful information benefit beyond the visible current cues promised to all cells. | Sensing is information, not swimming speed; do not require it to see basic flow. | +| 009 shed propulsion | Real ongoing stationary supply or supported carried role. | Photosynthesis/pool proximity alone is insufficient; nutrient access must work. | +| 010 specialized colony propulsion | Attached movement/load and machinery beyond ordinary member propulsion. | Does not require 009; ordinary attached movement is not gated on 010. | +| 024-025, 100 light adaptation/sensing | Meaningful, perceivable spatial light differences. | Light is separate from temperature; shade is not automatically cold. | +| 091-095 thermal specialization | Real temperature-dependent benefits and disadvantages, plus reachable habitat choices. | Observed useful thermal conditions/transitions weight offers; dangerous exposure is not a prerequisite. | +| 097 shed thermal protection | Existing costly protection and functional thermal gameplay. | Stable safe conditions can favor shedding; no offer when there is no actual saved cost. | +| 098 protective rest | Supported hazards, funded protection, finite survival, and reactivation. | Optional specialization, not an enforced inactive opening. | + +A region with thermal effects disabled offers no thermal adaptations. A thermal +map with only decorative color is still disabled for this purpose. Hard availability +comes before behavior/context weights; merely discovering an area does not create +the missing environmental mechanics. + +## Readability and controls + +- Flow cues should communicate direction and strength before the cell is committed. + Use trails, suspended specks, and actual food motion without making every visual + speck look collectible. +- Render terrain/habitat colors as a thermal heat map with readable cold-to-hot + differences instead of a flat background. Basic cellular conditions and interactions + have visible indicators/cues; their readability does not require a sensory mutation. +- Provide a compass and temperature gauge for navigating the cell. Distinguish local + ambient temperature, actual cell temperature, and preferred temperature/range. + Final gauge layout remains open, but it should explain why E demand stays high + after a cell's actual temperature has adjusted to an off-preference location. +- Distinguish comfortable, stressful, and dangerous conditions for the controlled + organism using contours/patterns and labels as well as color. Food channel colors + must remain distinguishable; visible heat must not hide current direction. +- Show whether the cell is swimming, drifting, actively braking, holding position, + or anchored. A world-space speed readout alone can conceal propulsion expenditure. +- Explain a changing budget: for example, station keeping uses E while passive + drift does not use propulsion E; basal maintenance remains separate. +- Respect perception/interest limits. A readable local current/thermal view does + not grant an exact global map or reveal out-of-range food. +- Any later sensory adaptation needs a benefit beyond these baseline visual cues; + it cannot merely restore information already promised to every cellular player. +- Show biological state under shared presentation rules for NPCs and players; + do not add account/owner labels to make flow or thermal behavior understandable. + +The renderer consumes immutable views with frame, tick, revision, and field presence. +It can interpolate presentation, but client animation cannot move authoritative +food/cells, determine temperature injury, or alter collection outcomes. + +## Ownership, lifecycle, and persistence + +Keep one authoritative owner per patch of space, including cells and their local +environment. Several regions scale the world; one global fluid owner is not implied. +Environmental fields, organic stock, corpses, independent descendants, and transfer +escrow must remain disjoint resource representations. + +Before a coupled implementation, specify and persist or deterministically derive: + +- Field definitions, units, frame/mapping, immutable seed/configuration, and rules. +- The linked world area and scaling used for the thermal map, so it reconstructs + exactly; currents and the map have no time-dependent stock or entitlement. +- Actual movement state needed for acceleration, braking, and restored continuation. +- Attachment state, loads, member identities, and valid release/breakage outcomes. +- Temperature/exposure state needed by the chosen organism response model. +- Atomic flow/thermal/resource/movement outcomes and their recorded replay inputs. + +Choose one explicit tick order for environmental exchange, motion/contact, feeding, +metabolism, thermal response, reproduction, and terminal transfers. The list here +does not select that order. Restore, recorded replay, and differently partitioned +batches must produce the same authoritative outcomes under the chosen rules. +No database write per simulation tick is required by this proposal. + +Cross-region transport needs paired conservation and durable authority handoff. +It must include the relevant organism motion/thermal state and any in-transit stock; +an adjacent field's read-only view cannot authorize spending its inventory. The +initial closed circulation experiment can defer open transport without declaring +future regional boundaries impermeable world walls. + +Offline controlled organisms still cannot move, feed, reproduce, mutate, or progress +passively. Logout takes effect after a delay; during it the cell stays in play and +vulnerable, so logging out while about to be engulfed does not prevent it. After +the delay the cell is anchored in place, cannot be engulfed, is not moved by +currents, and its metabolism and thermal response are frozen. There is no offline +catch-up on return. Independent NPC relatives continue under ordinary active-world +rules. Resume restores the cell's frozen velocity and temperature state; its +surroundings may have changed. + +## Region capacity and world linkage + +Each region maps to an area of its world and takes its thermal map from that area. +Regions do not grow with population. A hard organism cap bounds each region: + +- At the cap, births are refused. Engulfment and death return matter to the region + and reopen slots for players and wildlife alike. +- If a capped region has had no players for extended days, an operator can cull + wildlife through an admin interface. Culling is a recorded operator action, not + automatic despawning presented as selection. +- The world adds regions as demand requires. A later equation decides whether a + new region joins the same world or a region attaches to a new world. +- A fresh cell is offered a choice of region when it begins, so friends can share one. + +A new region starts without life under player-origin biology; its founders shape it. + +## Emergence into the world + +When an organism evolves out of the 2D stage, it leaves its cellular region: + +- Its matter is a recorded export and is lost to the cellular scale. The organism + enters the world scaled to world values. The conversion scale is selected once + the number of regions per world and the matter per region are known. +- Target selection uses the region's mapped world area. Rank several candidates + closest to the organism's preferred temperature with the nutrients it needs and + choose one at random. Finite world resources penalize crowded sites; no separate + spreading rule is added. +- The emerging organism chooses individual or bulk emergence. Bulk joins a + selection queue; organisms emerging together with the same or close biology share + one target pick. Because players and wildlife look alike by design, this does not + depend on knowing who is a player. + +Thermal adaptation in the cellular stage therefore shapes where an organism starts +in the world. + +## Pacing and ecological checks + +All fresh primitive lives receive equivalent starting biology. Starting locations +need useful reachable food, a tolerable thermal setting, and sufficient control +to follow more than one viable route. This does not require permanent protected +zones or invulnerable founders. + +Evaluate net E and each material channel over actual routes, including propulsion, +maintenance, flow encounters, and newborn investment. Faster E collection alone +does not satisfy the three-minute first-birth target if P or another material +creates a long wait. Thermal protection must not become a required prerequisite +for every founder's ordinary reproduction route. + +The maintainer expects unattended feeding to be slower than active gathering and +risky because other organisms can engulf an unattended cell. Treat a separate +anti-AFK system as low priority; do not add input challenges, forced movement, +unattended-play timers, or new surveillance mechanics for this draft. Verify the +assumption through playtesting rather than claiming predation guarantees it in +every population. The mutation draft's proposed activity-credit rules remain a +separate review item, not a new anti-AFK feature approved by this decision. + +Compare active collection with fixed-pool camping and passive drifting in trials. +If a circuit or pool outperforms active routes, tune food, flow, intake, and costs +before adding an anti-idle layer. Viable stationary producers still need useful +interactions and births without meaningless movement/input requirements. + +Observe whether offspring establish, compete, feed, die, recycle, and form supported +groups. Flow must not sweep every newborn away before attachment is possible or +concentrate all life into one dominant trap. Finite resource depletion and deaths +remain ecological outcomes; do not conceal failures by automatically spawning food +or wildlife. Adjust documented openings/inflows and trial parameters instead. + +## Proposed implementation segments, after design review + +These are possible bounded segments for later work, not authorization to code, +commit, push, migrate, or deploy during this document review. + +| Segment | Concrete result | Qualification needed before broadening | +| --- | --- | --- | +| Design contracts | Agree motion/flow, thermal accounting/response, boundaries, and rule-version scope. | Reconcile existing ADRs, resource owners, public contracts, and lifecycle behavior. | +| Portable flow and propulsion | Deterministic fields, funded motion/braking, loose-food movement, and conservative contact. | Bounds, conservation, no tunneling, no free station keeping, replay/restore. | +| Portable thermal model | Explicit thermal sources/capacity/exchange and one readable biological response. | Energy accounting, gradients, warning time, supported adaptation tradeoffs. | +| Coupled region integration | One-owner joint outcomes, durable state, publication, recovery, and supported attachments. | Atomicity, crash/retry safety, batch equivalence, offline policy, version admission. | +| Client presentation | Readable local flow/thermal cues and movement/energy feedback. | Matches authority and perception; founder handling evaluated interactively. | +| Controlled pacing experiment | New disposable/versioned test region with ordinary founding and births. | First-birth distributions, active-vs-passive feeding, adaptation usefulness, colony opportunity timing. | + +Keep the headless simulation independent of graphics, networking, storage, Steam, +and Kubernetes. Specialized dependencies need the repository's evidence/ADR process; +none are proposed merely to supply a fluid effect. This design does not change +foundation-proof scope or authorize any World0 action. + +## Future verification checklist + +These are checks a later implementation must perform, not results claimed here: + +- Still liquid, uniform flow, circulating flow, and smooth transition cases. +- Procedural 2-n current generation, differing speeds/directions, intersections, + and identical reconstruction from saved generation configuration. +- Relative swimming versus world movement; braking does not imply free station keeping. +- Useful founder control across ordinary currents, with no high-speed contact skips. +- Finite food survives repeated circuits without gain, loss, or boundary piles. +- Passing-cell food drift has bounded distance falloff and temporal decay, combines + predictably across cells, and restores identically without changing food stock. +- Attachment, release, force/load handling, and ordinary multi-cell propulsion. +- Thermal map reconstruction from the linked world area, gradient crossings, and + scaling continuity. +- Region cap birth refusal, slot reopening, operator culling records, emergence + export and target selection, and logout delay followed by protected anchoring. +- Combined three-temperature E response: transition cost can diminish after + adjustment while off-preference cost persists; near-preference operation approaches + baseline. Check the balanced exponential curve without double-counting stress. +- Bounded acclimation, lethal extreme entry, and meaningful asymmetric cold/heat + and broad thermal-adaptation effects, including any supported zero-extra-cost range. +- Heat-map cues, compass, and gauge distinguish ambient/cell state and communicate + hazards before entry without requiring a mutation for basic visibility. +- Unsupported/missing fields rejected or explicitly disabled, never treated as safe defaults. +- Deterministic motion/thermal continuation through restore, retry, and batch partitioning. +- One-owner and cross-boundary conservation, including escrow and terminal events. +- No offline controlled-organism drift, feeding, exposure catch-up, or earned mutation credit. +- Perception limits and equivalent biological presentation for player/NPC organisms. +- Ordinary first-birth timing across seeds and novice routes, plus progression-time tails. + +## Remaining tuning and implementation details + +The original ten responses are recorded near the beginning. Do not present settled +procedural generation, visible cues, flow-speed effects, or exponential thermal +cost as unanswered gameplay questions. Remaining work is: + +- **Thermal equation:** combine current cell, preferred cell, and environment + temperatures with acclimation and mutations. Preserve extra cost for drastic + transitions and sustained off-preference conditions; the coefficients and exact + relationship require balancing, not another choice of a single reference. +- **Playtesting:** founder/current speed ranges, crossing/escape control, proposed + 006 braking and 008 coasting tradeoffs, exponential + E curve, acclimation rates/limits, lethal thresholds, colony roles, and whether + active feeding naturally outperforms risky unattended feeding. +- **Generation and composition:** maximum n, route/thermal-map generation rules, + intersecting-current composition, bounded work, and recorded configuration. +- **Food disturbance tuning:** induced-drift radius, strength, distance falloff, + decay, multiple-cell combination, and world-versus-relative driving velocity. +- **Thermal map scaling:** how the world area's thermal map is scaled to the habitat; + ambient/cell response and lethal-event semantics. +- **Controls/presentation:** exact coasting/braking/reversing/anchoring inputs in + the focused movement draft, and gauge layout, with baseline visible cues established. +- **Lifecycle:** logout delay duration and spawn placement within a chosen region. +- **Capacity and emergence:** region cap value, region-or-world creation equation, + emergence conversion scale, candidate count, and bulk-queue timing/similarity. +- **Engineering contracts:** ownership/contact, conservative boundaries, deterministic + recovery, explicit version changes, and eventual cross-region transport. The + maintainer marked original question 3 N/A for the gameplay discussion; these + existing technical constraints remain without becoming new required gameplay. + +## Document validation scope + +Check local reference targets, Markdown structure, unique headings, required design +sections, and whitespace. Preserve the separately reviewed mutation draft. These +checks establish document integrity only; no fluid behavior, thermal response, +ecological balance, implementation availability, or pacing result is qualified by +creating this file. diff --git a/Cellular_Region_Movement_Plan.md b/Cellular_Region_Movement_Plan.md new file mode 100644 index 0000000..03fc058 --- /dev/null +++ b/Cellular_Region_Movement_Plan.md @@ -0,0 +1,268 @@ +# 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. | diff --git a/Cellular_movement_draft.md b/Cellular_movement_draft.md new file mode 100644 index 0000000..1ac89ae --- /dev/null +++ b/Cellular_movement_draft.md @@ -0,0 +1,718 @@ +# Cellular movement draft + +Status: discussion draft, 2026-10-21. This is the focused movement review for +draft mutations 001-010. It documents verified source behavior separately from +planned changes and proposed replacement adaptations. No code, runtime rule, +public contract, live region, or deployment changes are made here. No commit or +push is authorized during the maintainer's draft review. + +Companions: + +- [Cellular mutation draft](Cellular_mutation_draft.md): overall selection, + expression, reproduction, and the 150-entry catalog index. +- [Cellular region changes](Cellular_Region_Changes.md): procedural currents, + thermal conditions, food disturbance, presentation, and region ownership. + +### Maintainer decisions, 2026-10-21 + +| Topic | Decision | +| --- | --- | +| Scope | 001-010 are the cellular movement mutation options. All ten stay in the first implementation; options that do not fit in play are removed afterwards. | +| Drag and top speed | Accepted: lowering passive drag (008) also raises top speed, because top speed is thrust divided by drag. | +| Precision | Fixed-point motion state, as specified in [Numeric representation](#numeric-representation). | +| Scale | Currents start at 0.3x-1.5x founder swimming speed, so the strongest cannot be swum against. Region size is chosen with founder speed and current speed together. | +| Client prediction | The client runs the same motion step and flow field as the server. | +| Energy exhaustion | Unchanged: a cell that cannot pay maintenance dies and its corpse becomes food bubbles at its death location. Thrust that cannot be funded in a tick is not applied; the cell coasts and drifts. | +| 007 anchor | Player-triggered, like a boat anchor: the anchor drops and the point it hits becomes where the cell stays. It needs no prepared surface. | +| Logout anchor | A lifecycle state ([ADR-0177](docs/adr/0177-cellular-regions-world-linkage.md)), not the 007 mechanic. | +| Offer volume | Edits are percentage-based +/- steps off the fixed base, offered three at a time from a large catalog. No per-axis cap is needed now: extreme movement investment is limited by its own energy cost. | + +## 1. How movement currently works + +This section describes the inspected repository implementation, not a claim +about which version is currently deployed or how the proposed liquid controls +already feel in play. Test descriptions below refer to inspected test source; +the tests were not executed for this documentation change. + +### Authoritative motion and input + +The motion API is in +[cellular_motion.hpp](include/evo/biology/cellular_motion.hpp), implemented in +[cellular_motion.cpp](src/biology/cellular_motion.cpp). Its historical design is +[ADR-0102](docs/adr/0102-cellular-spatial-trial.md). + +- A tick is 50 ms. The cellular motion resolver accepts per-second budgets and + converts them to that tick duration. +- A movement intention is an X/Y direction-and-magnitude vector. Each component + is between -1000 and 1000, and its squared length cannot exceed 1,000,000. + It does not authorize a client-supplied position or speed. +- Maximum per-tick travel is the current phenotype's movement speed multiplied + by the tick duration, rounded down to integer micrometres. +- Each axis displacement is the intention component times that maximum step, + divided by 1000 with integer truncation. The resulting position is clamped + to keep the square body footprint inside the declared rectangular area. +- The position identifies the lower-left footprint corner. This helper permits + areas up to 1,000,000 micrometres per axis; that bound is not a selected new + region size or a planetary layout. +- There is no stored velocity, acceleration, facing/turn-rate limit, passive + deceleration, coasting, active braking, or local-flow input in this resolver. + Releasing input immediately requests zero displacement. Reversing requests the + other direction on the next tick without an acceleration/braking transition. +- Bounds clamp position; there is no wraparound. The square-footprint contact + helper counts an exact edge touch. It is not a liquid obstacle/pushing solver. + +### Current movement energy + +The resolver derives a full-speed tick cost from the metabolic budget, rounded +up, then scales it by actual bounded travel. Conceptually: + +`movement E = ceil(full-speed tick E * conservative travelled distance / maximum tick distance)` + +Travel distance is the integer ceiling of the Euclidean distance between the +old and final clamped position. A zero-distance move costs zero movement E. +This means pressing against the region boundary with no resulting displacement +does not pay an active station-keeping cost under the current model. + +The funded helper either transfers the entire movement cost from reserve E to +heat in its detached candidate or refuses the move. It does not apply a reduced +affordable fraction of a requested move. Reserve matter channels are not consumed +by that movement transfer. Basal maintenance remains a separate charge. + +The composed step in [cellular_step.cpp](src/biology/cellular_step.cpp) charges +maintenance before movement, then handles applicable intake. Underfunded movement +leaves the cell in place while the step can continue; later food cannot retroactively +fund earlier movement. See +[ADR-0104](docs/adr/0104-cellular-single-life-tick-order.md). Later region/deposit +rules extend feeding and lifecycle behavior; this motion helper is not by itself +the complete ecology, collision, or publication contract. + +### Current founder, size, and other traits + +The inspected [founder parameters](include/evo/biology/founder.hpp) specify +**200 micrometres/second** movement for an ordinary primitive founder. With no +speed-reducing producer trait, that permits a maximum 10-micrometre step per +50 ms tick. This is an existing tunable, not acceptance of the future founder +speed or proof that the three-minute first-birth target is met. + +[Development](src/biology/development.cpp) reads the movement capability as a +speed, not as thrust or a set of acceleration/steering properties. An absent +capability yields zero speed. Ordinary growth-size changes do not independently +scale speed in the inspected derivation. The +[metabolic budget](src/biology/metabolism.cpp) makes full-speed movement demand +depend on total mass and phenotype speed, with versioned integer coefficients +and rounding. Mass and membrane changes can therefore change movement cost +without changing the basic movement-speed parameter. + +Under that approximately linear mass-and-speed budget, increasing the speed +parameter raises full-speed E/time but does not independently create a less +efficient E/distance motor, apart from integer rounding. The simple derivation +also does not build extra propulsion tissue merely because movement is acquired +or raised. Real machinery investment and independent efficiency/output properties +are planned extensions, not existing costs to describe as already implemented. + +Development version 5 adds photosynthetic organelle mass/upkeep and reduces +movement speed according to the existing producer rule: at efficiency p per +thousand, retained speed is `(1000 - p/2) / 1000`, with integer arithmetic. +See [ADR-0175](docs/adr/0175-photosynthesis-producers.md). This is a versioned +existing coupling, not the new general body-drag model. + +[Mutation implementation](src/biology/mutation.cpp) currently offers generic +adjust-up/down/acquire/shed operations over capability records. Schemas 4 and 5 +use a step of one tenth of the current parameter, at least one. These are not +the proposed compound movement adaptations below, and their runtime operator IDs +must not be confused with this document's draft IDs. + +### Source checks inspected + +| Test source | Behavior specified by the existing checks | +| --- | --- | +| [cellular_motion_tests.cpp](tests/cellular_motion_tests.cpp) | Full/partial/diagonal movement, zero input, boundary clamping, invalid vectors, low-speed quantization, funded refusal, heat transfer, and footprint contact. | +| [cellular_step_tests.cpp](tests/cellular_step_tests.cpp) | Maintenance before movement/intake and conservation of the composed candidate. | +| [development_tests.cpp](tests/development_tests.cpp) | Zero speed without capability and unchanged speed under ordinary size changes in the tested derivation. | +| [metabolism_tests.cpp](tests/metabolism_tests.cpp) | Derived movement budgets, founder values, and membrane/mass relationships. | +| [photosynthesis_tests.cpp](tests/photosynthesis_tests.cpp) | Producer tissue costs and the version-5 speed reduction. | +| [mutation_tests.cpp](tests/mutation_tests.cpp) | Versioned capability operations, prerequisites, and mutation adjustment behavior. | + +These existing checks are useful baselines; they do not validate liquid flows, +propulsion controls, thermal changes, or the proposed ten movement adaptations. + +## 2. Planned movement model + +### Liquid-relative propulsion and world travel + +Cells propel themselves through liquid while procedural currents carry both +cells and loose food. The region design specifies 2-n currents with individual +directions/speeds, possible intersections, quiet areas, and circulating routes. +The bounded maximum n, flow combinations, and speed ranges remain trial values. + +`world velocity = local liquid velocity + swimming velocity relative to liquid` + +This is a conceptual decomposition, not a finalized integrator or repeated +unbounded acceleration. At comparable propulsion output, travelling with flow +increases world progress, travelling against it decreases progress, and zero +ambient flow gives ordinary swimming for the current body/conditions. Cross-flow +deflects travel; a strong current can prevent upstream progress. + +Do not apply an additional same-direction speed bonus after adding current. +Passive drift does not consume propulsion E, but ordinary maintenance and any +thermal survival cost continue. A cell drifting beside a bubble at the same speed +still needs relative motion or useful contact to collect it. + +### Acceleration, slowing, and controls + +| Behavior | Planned response | Resource consequence | +| --- | --- | --- | +| Propel | Accelerate relative to liquid toward the requested direction within available output/steering limits. | Fund actual output; extra machinery can have construction/upkeep costs. | +| Release propulsion | Passive resistance reduces relative swimming velocity; world drift can continue. | No active propulsion expenditure; dissipation does not refill usable E. | +| Brake/reverse | Opposing propulsion changes swimming velocity faster than passive slowing alone. | Fund actual braking/reverse output. | +| Hold world position | Counter local flow rather than treating no input as a free stop. | Sustained funded output while resisting current. | +| Anchor (007) | Player drops the anchor; the cell holds at the point it hits until released. | Anchor construction, drop/release, and any supported maintenance costs. | +| Move an attached group | Useful member propulsion moves the whole arrangement against its combined resistance/load. | No free member-count speed multiplier or duplicate charging of shared work. | + +Start founders with responsive handling. Exact controls for automatic/manual +braking, reverse thrust, turning at speed, and steering assistance remain open. +Do not impose long uncontrollable coasting just to demonstrate acceleration. + +Passive deceleration has a two-sided consequence: stronger slowing improves +precise stops but sacrifices coasting; weaker slowing preserves motion but makes +overshooting more likely. Active braking can address that weakness, at its actual +machinery/output cost. Stopping relative to liquid is not stopping relative to +the region. + +### Numeric representation + +Biology stays integer-only and deterministic; server and client run the same code. + +| State | Representation | Notes | +| --- | --- | --- | +| Position | Existing integer micrometres plus a per-cell sub-micrometre accumulator. | Public position and contact keep whole micrometres. | +| Velocity relative to liquid | Signed 32-bit, 1/1024 micrometre per second (Q10). | About 1 nm/s resolution; far beyond any trial speed range. | +| Heading | Unsigned 16-bit angle, 65,536 steps per turn. | Turn rate limits heading change per tick. | +| Direction vectors | Checked-in integer sine/cosine table (Q14). | Golden-tested; no floating point or platform math. | +| Flow sample | Q10 velocity grid at a fixed pitch, bilinear integer interpolation. | Rounds toward zero; seeded and versioned. | + +Per tick: + +1. Turn: move heading toward the intent direction by at most the turn rate. +2. Thrust: add funded acceleration along heading (reverse thrust for braking). +3. Drag: `v -= trunc(v * drag_ppm_per_tick / 1,000,000)`, rounding toward zero so + speed decays to exactly zero; a speed below a small threshold snaps to zero. +4. World velocity: add the flow sample at the cell's position. +5. Displacement: `acc += v_world * tick_us`; whole micrometres are + `floor(acc / (1024 * 1,000,000))`, carried into position, with the remainder kept + in `acc`. There is no rounding drift across ticks. +6. Contact: sweep the path against food and cells, subdividing so no step exceeds + half the smallest contact radius, with a fixed per-tick work bound. + +All arithmetic is 64-bit with overflow checks. The motion state (velocity, +heading, accumulator) is persisted with the cell so restore and replay continue +exactly. + +### Derive one profile from the current organism + +Use propulsion capacity, efficiency, steering arrangement, body shape, mass, +and resistance as contributors. Derive a consistent resulting movement profile. +Do not independently assign unrelated percentage changes to every output merely +to manufacture a pro/con pair. + +| Displayed comparison | Definition | Founder reference | +| --- | --- | --- | +| Maximum swimming speed | Supported speed relative to liquid under reference conditions. | 100%. | +| Propulsion energy cost | E/distance at a stated reference speed; also show E/time at actual output when useful. | 100%; lower is cheaper. | +| Acceleration | Rate of increasing relative swimming velocity. | 100%. | +| Passive deceleration | Rate of losing swimming velocity without propulsion. | 100%; faster stopping also reduces coasting. | +| Active braking | Available opposing propulsion response. | 100% for ordinary supported founder braking, not possession of specialized 006 machinery. | +| Turning control | Ability/rate to redirect movement at a stated reference speed. | 100%. | + +Percentages compare against a fixed founder at stated body/growth/environment +conditions; they do not reset after every mutation. Store actual quantities and +derive the display. An absent burst or anchor is absent, not 100%. Every fresh +primitive life has the same baseline biology regardless of account age. + +The future founder's absolute values and mutation magnitudes require playtesting. +The numeric trial map below supplies starting steps for review, not qualified +balance. Do not automatically carry forward the existing 200-micrometre/second +speed or generic ten-percent mutation step as a selected propulsion rule. +Keep previews at matched conditions, then explain actual newborn size, reserves, +flow, and temperature separately. Thermal cost uses current cell, preferred cell, +and environment temperatures as recorded in the region draft; it is not an +automatic multiplier on every movement cost. + +### Combining one to many adaptations + +Mutation changes the current body/offspring plan. The history remains an archive, +not a stack of named buff cards applied indefinitely. + +| Combination | Useful resulting strategy | Cost or limit that remains | +| --- | --- | --- | +| 001 strong propulsion + 004 agile steering | Fast, responsive interception. | Actual machinery, operating demand, and capacity allocation. | +| 002 economical propulsion + 005 straight swimmer | Efficient sustained directional travel. | Reduced pursuit output and close turning. | +| 006 active braking + 008 coasting-biased body | Coast between targets, then brake deliberately. | Dedicated brake structure/output; overshooting if braking is delayed or unfunded. | +| 001 strong + 002 economical propulsion | Potentially a balanced power/economy design. | Valid only if output and efficiency are genuinely separate properties; opposite edits to one property are not two permanent bonuses. | +| 004 agile steering + 005 straight swimmer | Intermediate or mixed arrangement. | Recalculate one body geometry; do not keep mutually contradictory shape bonuses. | +| 009 shed propulsion + a supported propelling group | Nonpropelling specialist carried by others. | Donors supply force; group still carries its mass and needs viable material/E supply. | + +Resistance is counted once. In particular, 005 changes directional streamlining +and 008 changes passive/coasting response; if the chosen body model cannot express +them as distinct changes, merge/revise them rather than applying the same drag +reduction twice. Bound changes, reject no-op candidates, and preview the complete +combined outcome and construction requirements. + +### Frequent offers and percentage-step convention + +The maintainer wants frequent opportunities to tweak the organism while playing. +Propose a small-tuning offer approximately every **20-30 seconds of productive +active play**, including an early first offer in that range, rather than the +earlier 60-90-second interval. These timing values are trial targets, not a +wall-clock entitlement or a selected activity-credit formula. Do not gate basic +reproduction on getting any particular offer. + +Keep one pending offer rather than an accumulating queue of forced menus. Existing +earned opportunities remain available; no immediate free reroll follows a decline. +The first three minutes could therefore contain several small plan decisions +without demanding a separate division for every decision. Structural changes still +develop through funded offspring. Evolve now requires a viable division/succession; +Prepare offspring can accumulate edits to the next plan. Frequent offers do not +authorize free live reconstruction or automatic mutation of an offline cell. + +For the initial movement experiment, use **percentage points of a fixed reference** +for parameter edits, not a percentage of the current value: + +- An ordinary tuning step adds or removes 5 reference points on its primary axis. +- A paired specialization tradeoff initially moves 2 reference points on the + specified competing axis, where the proposed tissue arrangement supports it. +- 100 -> 105 -> 110 is two +5-point edits. It is not 100 -> 105 -> 110.25. +- These are changes to underlying normalized parameters, not promises that every + derived final speed/acceleration value changes by those same points. +- No amount or step may bypass a parameter's physical/recipe bounds. Reject or + clearly preview a bounded partial step; never advertise a full change then silently + truncate it. Bounds and rounding remain to be specified before implementation. +- Acquisition and complete shedding are structural cases, not a +5/-5 edit to + an absent trait. They need a real developed module/removal and explicit funding. + +The same reference remains valid across successive mutations and one-way succession. +Compare equal body/environment conditions; temporary low reserves, small newborn +size, flow, thermal stress, and damage do not redefine inherited parameter values. + +### Initial numeric map for movement adaptations + +This is a **proposed first trial matrix**. Each row names an underlying arrangement, +its primary improvement, and its competing change. Values do not create independent +RPG buffs: development must realize the arrangement with actual tissue, supported +geometry, costs, and a consistent movement model. If the proposed pair cannot be +realized meaningfully, revise it instead of inventing a flat penalty. + +| ID | Primary parameter and proposed change per tuning selection | Competing change or numeric consequence | Meaning of a positive direction | +| --- | --- | --- | --- | +| 001 | Propulsion-output capacity +5 points. | Propulsion-efficiency index -2 points for the proposed high-output arrangement; additional tissue funded where needed. | More available useful output. | +| 002 | Propulsion-efficiency index +5 points. | Propulsion-output capacity -2 points in the economical arrangement. | More useful propulsion work per E, not a higher displayed E cost. | +| 003 | Burst-output capacity +5 points after acquisition. | Sustained-output allocation -2 points at comparable investment; actual burst E is spent and replenished. | More supported short-term output. | +| 004 | Steering-authority allocation +5 points. | Forward-output allocation -2 points at comparable investment. | More useful redirection authority. | +| 005 | Axial streamlining index +5 points. | Steering-authority allocation -2 points for that directional arrangement. | Less resistance along the chosen body axis. | +| 006 | Opposing/braking-output allocation +5 points beyond ordinary supported braking. | Forward-output allocation -2 points at comparable investment; active braking still spends E. | More supported opposing output. | +| 007 | Anchor holding capacity +5 points after acquisition. | Holding-tissue investment +5% of its reference module recipe; no arbitrary whole-body speed penalty. | More supported attachment load. | +| 008 | Coasting-response time index +5 points. | Passive slowing rate changes reciprocally in the candidate response model: 100/105 of baseline at index 105, about 95.24%. No second drag debit. | Longer preservation of swimming velocity, with slower passive stops. | +| 009 | Remove independent propulsion: its available output becomes 0. | Avoid that module's future construction/upkeep, not 100% of total maintenance; lose independent swimming/braking. | Reacquisition is a separate funded positive change, not +5 to an absent motor. | +| 010 | Dedicated colony-drive capacity +5 points after acquisition. | Dedicated propulsion-tissue investment +5% of its reference module recipe; extra mass and donor operating costs are derived. | More useful group-driving capacity. | + +The paired 5/2 values are deliberately modest starting proposals for frequent +offers. Construction, upkeep, drag, total mass, final speed, and E/time are derived +from the resulting recipe; they are not also assigned all the table's percentages. +Efficiency is normalized useful work per E, with a physically valid actual range; +an index above 100 does not mean conversion efficiency above 100%. + +For a module absent in the founder, a provisional acquisition reference of 100 +means the performance of its explicit first module recipe, not that the founder +already owns it. Its initial construction and any displacement of other tissue +must be previewed; acquisition does not provide free mass. Repeated 007/010 scaling +uses that same module reference, without increasing all whole-body costs by 5%. +The initial burst recipe/capacity, anchor recipe, and colony-drive recipe still need +definition before those acquisition options can be offered. + +For 008, reciprocal slowing is one candidate lumped response: increasing a decay +time by 5% reduces the corresponding decay rate to approximately 95.24%, not 95%. +This illustrates why coasting and passive deceleration cannot be assigned unrelated +percentages. It does not select the full velocity integrator or add usable E. + +Example of composable edits: starting at output 100 and efficiency 100, one 001 +selection proposes output 105 / efficiency 98. A subsequent 002 selection would +produce output 103 / efficiency 103 before bounds and physical derivation. This +does not erase the funded machinery or any construction/upkeep its final recipe +requires. Show the complete combined result, not only the primary green number. + +### Decreasing a movement trait + +A supported lower-investment variant should also have a reason to choose it. +Use the following inverse steps as trial proposals, without creating another ten +catalog IDs. They are directional variants of the reviewed adaptations, not a +requirement to offer every inverse in every context. + +| ID | Proposed lower-primary variant | Benefit in return | Lost capacity | +| --- | --- | --- | --- | +| 001 | Output capacity -5 points. | Efficiency index +2 points in the inverse arrangement. | Maximum useful output. | +| 002 | Efficiency index -5 points. | Output capacity +2 points in the higher-throughput arrangement. | Work obtained per E. | +| 003 | Burst capacity -5 points. | Sustained-output allocation +2 points. | Short escape/interception output. | +| 004 | Steering authority -5 points. | Forward-output allocation +2 points. | Close maneuvering. | +| 005 | Axial streamlining -5 points. | Steering authority +2 points in the less directional arrangement. | Long-axis swimming economy. | +| 006 | Braking allocation -5 points. | Forward-output allocation +2 points. | Rapid stopping/reversal. | +| 007 | Anchor holding capacity -5 points, within a viable module. | Holding-tissue recipe investment -5% of reference. | Maximum supported attachment load. | +| 008 | Coasting-response time -5 points. | Faster passive stopping; at index 95 the candidate slowing rate is 100/95 of baseline, about 105.26%. | Preserved motion between propulsion intervals. | +| 009 | Full shedding is already the loss direction. | Avoid future propulsion-module investment. | All independent propulsion; restoration needs an explicit viable reacquisition recipe. | +| 010 | Dedicated group-drive capacity -5 points, within a viable module. | Dedicated propulsion-tissue investment -5% of reference. | Supported group-driving output. | + +Inverse edits affect the next developed recipe; they do not refund the unchanged +parent's existing tissue. Partial reduction cannot cross a capability's minimum +supported recipe or accidentally become complete removal. A lower-primary variant +must have the stated benefit in the physical model; otherwise exclude it rather +than offering a plain detrimental decrease. + +### Below-baseline traits and positive-offer weighting + +The maintainer's direction is that **the further into the negative a trait goes, +the less likely a positive mutation for that trait should be offered**. Interpret +this draft's negative position as a net reduction of the relevant inherited +capacity/investment index below its fixed 100 reference. "Positive" here means +increasing that option's named primary axis, not a mutation with no drawbacks. +For example, output 70 is -30 reference points; output 90 is -10. Merely falling +from output 150 to 120 is not yet below the founder baseline. + +Use the primary underlying axis rather than the color/sign of every displayed +result. Lower E/distance can be an improvement: an economical motor must not be +classified as genetically negative merely because its displayed energy cost is +80%. Coasting likewise has a useful positive axis and a stopping disadvantage. + +Propose a persistent **recovery weight factor** for a positive movement candidate: + +`recovery = max(0.10, (index / 100)^2)` when `0 <= index < 100`; otherwise `1`. + +| Inherited primary index | Offset from reference | Relative weight for its positive-direction candidate | +| --- | --- | --- | +| 100 or higher | At/above reference. | 100% of otherwise applicable weight. | +| 95 | -5 points. | 90.25%. | +| 90 | -10 points. | 81%. | +| 80 | -20 points. | 64%. | +| 70 | -30 points. | 49%. | +| 60 | -40 points. | 36%. | +| 50 | -50 points. | 25%. | +| 40 | -60 points. | 16%. | +| 30 or lower | -70 points or more. | 10% floor. | + +These are **relative sampling weights, not the probability of seeing an option +in a whole offer**. Actual appearance depends on all eligible candidates, their +weights, the number of slots, and sampling without replacement. If there are only +three eligible candidates and three slots, all three appear regardless of weights; +do not present the table as an appearance guarantee in that situation. + +Apply the factor to that candidate's primary beneficial axis after checking hard +eligibility and alongside the master draft's behavior/context/preference weights. +Do not suppress every positive movement candidate because one trait is low. +Its paired drawback is not a second multiplicative suppression. Net inherited +reductions count regardless of which adaptation produced them, not the number +of historical "negative clicks". Do not impose an extra probability reduction +merely for being above 100; any upper-bound or advanced-body rule needs separate review. + +The factor follows the inherited plan through succession and changes when the +underlying index changes; it does not expire after several offers. This differs +from transient decline preferences, which still decay. It applies to mutation +opportunities for the offspring plan, not temporary performance lost to current, +temperature, energy starvation, growth, or damage. + +Complete loss requires a distinct acquisition option. First acquisition of a +capability the founder never had is not automatically penalized as a below-baseline +defect. Reacquiring a deliberately shed propulsion module can use the proposed +10% floor, subject to a viable supported recipe; no requirement to swim first may +make a nonpropelling lineage permanently ineligible. Ordinary and alternate viable +strategies must remain available. This does not guarantee a recovery option on +the next offer, reset a body, refund its costs, or grant a free reroll. + +Both the quadratic shape and 10% floor are initial tuning proposals, not accepted +probabilities. The intended consequence is commitment that becomes harder to +reverse, without a permanent hidden class lock. Preview that consequence alongside +large reductions and removal. Frequent offers are important here: a low recovery +weight must not produce an unusable session-length wait or invalidate the overall +30-60-minute cellular pacing target. Measure the long tail, not only average draws. + +## 3. Revised movement mutations 001-010 + +These ten draft entries are **proposals for review**, not ten approved mechanics +or mandatory movement unlocks. Changes to 006 and 008 below are proposed replacements +for options that lacked a distinct movement purpose. The numeric matrix above +provides trial percentage steps; no price, final derived movement equation, or +qualified balance is selected. IDs are discussion references, not runtime operator IDs. + +| ID | Movement candidate | Review disposition | +| --- | --- | --- | +| 001 | Strong propulsion | Core candidate; increases available output with real costs. | +| 002 | Economical propulsion | Core candidate; economy versus peak output. | +| 003 | Burst propulsion | Conditional on a funded, bounded burst mechanism. | +| 004 | Agile steering | Core candidate; steering allocation versus forward output. | +| 005 | Straight swimmer | Core candidate; directional streamlining versus maneuverability. | +| 006 | Active braking propulsion | Proposed replacement for Current sail. | +| 007 | Anchor | Core candidate; player-triggered, holds the cell where the anchor hits. | +| 008 | Coasting-biased body | Proposed movement replacement for Food-gradient sensing. | +| 009 | Shed independent propulsion | Only for an actually supported stationary/carried role. | +| 010 | Specialized colony propulsion | Only if it adds machinery beyond ordinary member propulsion. | + +### Tentative visual indicators + +The maintainer proposed the following starting ideas for recognizing movement +adaptations on the cell. They are **visual concepts for review, not strong shape +definitions, accepted anatomy, or proof of a particular movement equation**. +"Limbs" here means visible cellular appendages; it does not require macroscopic +limbs or introduce a fixed species/body class. + +| ID | Initial visual idea | Intended readability | +| --- | --- | --- | +| 001 | More limbs, thicker limbs, or a combination. | A visibly stronger propulsion arrangement. | +| 002 | Longer limbs. | A distinct economical-propulsion form. | +| 003 | Shorter limbs. | A distinct burst-propulsion form. | +| 004 | Additional limbs along the cell's sides. | More lateral steering structures. | +| 005 | Small limbs at the cell's front. | A recognizable forward-oriented arrangement. | +| 006 | A hook-shaped limb at the back. | A recognizable braking/reversing structure. | + +Front, back, and sides refer to the cell's body orientation, not compass direction +or the current's flow direction. Visuals for 007-010 remain open; do not fill them +with arbitrary anatomy just to complete the table. + +Frequent percentage steps should produce readable gradual changes where practical; +each +5-point selection does not have to add a whole limb. Continuous thickness, +length, or arrangement changes and later count thresholds are possible approaches, +not selected rules. Preview the difference at useful viewing scale without promising +an exact one-to-one mapping from a numeric point to an appendage. + +When adaptations combine, render one coherent resulting body. In particular, 002's +longer-limb idea and 003's shorter-limb idea need a combined design: perhaps different +appendage roles or a resulting intermediate arrangement. Neither approach is selected +here. Opposing edits must not leave contradictory cosmetic layers or continually +accumulate disconnected limbs. + +Tie any eventual physical appendage choice to the developed body's actual capacity, +mass, and construction recipe. These concept sketches do not add a new fee or assert +that the proposed shapes already provide their intended mechanical advantages. +Structural changes appear on the offspring that develops them, including immediate +succession's new organism; an unchanged parent keeps its existing appearance. +Apply the same biological visual rules to NPCs and players, with a before/after +preview for the player considering a mutation. + +### 001: Strong propulsion + +- **Mechanism:** enlarge/support propulsion machinery to increase usable output. + Speed, acceleration, braking, body load, and E demand follow from that body. +- **Reason to choose:** cross currents, intercept food/prey, or escape faster. +- **Drawback:** additional construction/upkeep and greater E demand when high + output is used. Slow travel does not always pay maximum operating cost. +- **Available when:** enlargement changes actual capacity and its physical costs + are modeled; no fixed number of prior movement mutations is required. +- **Increases chance:** productive long routes, relevant pursuits, useful current + crossings where output is limiting. +- **Decreases chance:** reliable local feeding, little propulsion use, or construction + already being the dominant shortage. + +### 002: Economical propulsion + +- **Mechanism:** configure machinery for efficient sustained swimming at lower + maximum output; explicitly define efficiency rather than granting a flat discount. +- **Reason to choose:** reach more food per unit of propulsion E and sustain routes. +- **Drawback:** weaker pursuit, rapid escape, and upstream performance. +- **Available when:** output/efficiency tradeoff actually works. It does not require + first becoming inefficient or approaching starvation. +- **Increases chance:** propulsion consumes a large share of acquired E during useful + travel; repeated ordinary routes do not need maximum output. +- **Decreases chance:** repeated peak-output pursuits or necessary strong-current + crossings; abundant E makes economy less useful. + +### 003: Burst propulsion + +- **Mechanism:** support a short high-output interval using a defined reserve and + machinery capacity. Recovery means funded replenishment, not free timed refilling. +- **Reason to choose:** briefly escape a current/predator or intercept a moving cluster. +- **Drawback:** burst machinery occupies tissue/resources and high output drains the + available reserve rapidly; lower sustained performance than a sustained-output + arrangement at comparable construction investment. +- **Available when:** the burst capacity, cost, exhaustion, and replenishment work. +- **Increases chance:** short useful escapes/interceptions where ordinary output + falls short; observed opportunities, not deliberate repeated failed input. +- **Decreases chance:** long uninterrupted swimming or lack of E to replenish bursts. + +### 004: Agile steering + +- **Mechanism:** allocate more machinery/geometry to redirecting useful propulsion. +- **Reason to choose:** navigate current intersections, track drifting food, and + change course around supported obstacles or organisms. +- **Drawback:** at comparable investment, less machinery is available for sustained + forward propulsion. Turning is not an independent free speed multiplier. +- **Available when:** heading/force redirection has real movement consequences. +- **Increases chance:** frequent productive turns and close interceptions. +- **Decreases chance:** mainly straight travel with little need to redirect. + +### 005: Straight swimmer + +- **Mechanism:** streamline geometry/propulsion along the main travel axis. +- **Reason to choose:** reduce directional resistance on long routes. +- **Drawback:** poorer tight turning or lateral maneuvering; route commitment matters. +- **Available when:** direction-dependent geometry/resistance and turning work. +- **Increases chance:** sustained directional foraging, pursuit, or useful current routes. +- **Decreases chance:** dense turning/interception demands and frequent route reversal. +- **Combination note:** ordinary drift is already free of propulsion expenditure; + this must improve relative swimming, not duplicate a with-flow bonus. + +### 006: Active braking propulsion + +- **Mechanism:** allocate machinery to useful opposing/reverse output beyond the + founder's ordinary braking capacity. It changes relative velocity, not ambient flow. +- **Reason to choose:** stop near food, recover from overshooting, and reverse swimming + quickly without waiting for passive slowing. +- **Drawback:** additional or reallocated machinery reduces another capacity at matched + investment, and using stronger braking consumes E. The exact forward-output versus + construction tradeoff must be selected and measured before offering it. +- **Available when:** active braking works and improved capacity changes outcomes. +- **Increases chance:** productive routes with repeated stopping/reversal demands or + overshooting despite useful collection opportunities. +- **Decreases chance:** long uninterrupted travel, sufficient ordinary braking, or a + viable anchored strategy that seldom moves. +- **Restriction:** braking to zero relative speed leaves world drift; it is not free + station keeping. Current sail is archived below, not quietly treated as approved. + +### 007: Anchor + +- **Mechanism:** the player triggers the anchor, like dropping a boat anchor. The + point it hits becomes the location the cell holds until the player releases it. + No prepared surface is required. +- **Reason to choose:** stay at a productive fixed site without continuously swimming + against the current. +- **Drawback:** anchor construction investment, and the cell cannot travel while + anchored; release is needed before independent movement. Excessive loads can + exceed supported holding capacity. +- **Available when:** currents exist so that holding position has value. +- **Increases chance:** costly station keeping or repeated drifting away from useful sites. +- **Decreases chance:** frequent relocation or still liquid. +- **Distinct from logout:** the logout anchor is a lifecycle state (ADR-0177), not 007. + +### 008: Coasting-biased body + +- **Mechanism:** reduce passive slowing through a supported body-resistance arrangement. + Recalculate the whole profile; do not grant free extra momentum or a second drag bonus. +- **Reason to choose:** preserve relative travel between propulsion intervals. +- **Drawback:** slower passive stopping and more overshooting; precise stops may require + paid braking. It must differ meaningfully from 005 or the two candidates should merge. + Lower drag also raises top speed (accepted); 005 lowers forward drag only. +- **Available when:** relative velocity/passive resistance are modeled and changing + them has a demonstrable control/energy tradeoff. +- **Increases chance:** productive long, open travel with useful propulsion-release intervals. +- **Decreases chance:** frequent precise stops, short crowded routes, or repeated uncontrolled + overshooting without enough braking capacity. +- **Classification:** this is a proposed replacement movement entry; the former food + sensor remains a sensing review item, not a forgotten adaptation. + +### 009: Shed independent propulsion + +- **Mechanism:** future offspring omit independent propulsion machinery and its actual + construction/upkeep. Their bodies/reserves still exist and require maintenance. +- **Reason to choose:** devote resources to feeding, production, or another supported + role while stationary or carried by propelling colony members. +- **Drawback:** no independent swimming, propulsion braking, or escape. Passive drift + remains; being carried is not the ability to choose a new position independently. +- **Available when:** propulsion exists and a demonstrated stationary E/material supply + or supported carried role makes the resulting offspring viable. Exclude unsupported + solitary founders; photosynthesis alone does not supply C/N/P/O. +- **Increases chance:** reliable support, useful specialization, and little independent + propulsion use. +- **Decreases chance:** independent foraging, uncertain transport, depleting local food, + or temperature changes requiring relocation. +- **Restriction:** 010 is not a required partner unlock. Ordinary propelled neighbors + can provide transport where attachment mechanics support it. + +### 010: Specialized colony propulsion + +- **Mechanism:** add dedicated group-propelling machinery beyond ordinary attached + member contributions; specify what new capacity the tissue actually provides. +- **Reason to choose:** move useful attached mass that ordinary member output struggles + to carry, including supported nonpropelling specialists. +- **Drawback:** propulsion roles spend E moving other members, occupy material, and + sacrifice feeding/other functional capacity. More tissue still adds load. +- **Available when:** attached motion/load and differentiated machinery work, with a + distinct benefit. Neither shedding movement nor an arbitrary large colony is a + prerequisite; required group/body geometry must follow the actual mechanism. +- **Increases chance:** useful growing groups with a measured propulsion shortfall. +- **Decreases chance:** solitary life, adequate ordinary member output, or insufficient + feeding/transport support for a dedicated role. +- **Restriction:** ordinary colony movement is baseline attachment behavior, not gated + by 010. Coordination/polarity belongs to catalog 078 unless a clearly distinct + mechanism justifies both; do not charge twice for the same improvement. + +### Reclassified and archived concepts + +| Previous draft entry | Disposition in this review | +| --- | --- | +| 006 Current sail | On hold: ordinary cells/bubbles already drift. Reconsider only if it adds a distinct supported benefit and drawback. It is not accepted merely because currents now exist. | +| 008 Food-gradient sensing | Reclassified as sensing, retained here as an archived concept pending that category's review. No new catalog ID is assigned, and it is not a propulsion modifier. | + +Basic cellular visual cues, including the current/thermal environment, are already +promised to every player in the region draft. A future food sensor must add useful +information beyond those cues within a defined perception model. Do not reintroduce +it just to refill a movement slot. The master catalog retains 150 indexed entries; +archived concepts are not additional approved mutations or runtime IDs. + +## 4. Food, temperature, reproduction, and colony integration + +- Loose food follows flow. Passing cells also induce short-lived food drift with + spatial falloff and temporal decay, as recorded in the region draft. The driving + velocity, influence radius, multiple-cell combination, and work budget remain open. +- Food collection does not automatically slow the cell. High-speed crossing needs + conservative contact detection so neither food nor organisms are skipped. +- Existing food identities and E/C/N/P/O remain finite while moving; circulating, + disturbed, or visually clustered food does not duplicate stock. +- Temperature contributes to survival E use through the region draft's three-temperature + model. Cold/heat adaptations can affect handling/support, but do not automatically + change movement stats without a defined coupling. +- Evolve now versus Prepare offspring follows the master mutation draft. Structural + propulsion/body changes develop in offspring; current-cell experience uses funded + division and immediate one-way succession, not free parent reconstruction. +- Offspring size/reserves influence actual load, capacity, and survival. A fixed-founder + percentage preview must not promise that a newly divided small body performs exactly + like a reference adult. +- The first birth must not require a movement mutation, a colony unlock, or a specific + random draw. Useful movement and flow routes must support the three-minute target. +- NPCs and players obey the same movement/resource rules. Offline controlled organisms + do not acquire passive drift, feeding, mutations, or thermal catch-up. After the logout + delay the cell is anchored, protected, and frozen (ADR-0177); it resumes with its + frozen velocity and heading. + +## 5. Implementation boundaries and future verification + +This is documentation, not authorization to implement these systems during review. +The new profile changes the current public motion/state model. Before code changes, +define versions, units, ranges, rounding, tick order, source/work accounting, contact, +perception, replay, persistence, migration, and lifecycle semantics. Do not silently +reinterpret earlier speed-only genomes, motion traces, or founder baselines. + +Keep headless biology/world logic independent of graphics, transport, databases, +and Kubernetes. Client interpolation is presentation, not authority over motion. +No fluid dependency, placeholder service, or World0 operation is introduced here. + +Later checks must cover: + +- No-flow, with-flow, against-flow, cross-flow, intersections, and entry/exit behavior. +- Propulsion output costs, passive slowing, active braking, and funded station keeping. +- Combined body arrangements, directional drag, limits, no-op rejection, and fair previews. +- Exhausted E, zero propulsion, anchored roles, attachment release, and ordinary group load. +- Food contact at speed, passing-cell disturbance, finite stock, and stable contention. +- Deterministic continuation through restore, retry, and differently partitioned batches. +- Valid references/IDs and shared NPC/player biological presentation. +- Playtested founder handling, active feeding, first-birth time, and useful mutation tradeoffs. +- Frequent small-step offers, fixed-reference arithmetic, paired body allocation, + below-baseline recovery weights, and viable reacquisition after loss. +- Recovery-offer tail times across extreme specialization without making reversal + guaranteed or trapping ordinary active players beyond the intended stage length. + +Unselected balancing choices include the founder's future absolute quantities, +output-cost curve, braking controls, limits on mutation effects, exact recipes, +005/008 distinctness, 006's machinery tradeoff, and 010's extra group machinery. +All must be concrete before candidates become implemented offers. The trial 5/2-point +matrix, module scaling, 20-30-second cadence, and quadratic recovery factor also +require review and measured balancing; documenting them does not qualify them. + +Document checks for this segment verify source/reference targets, ten unique +movement draft IDs, consistent master-index links, unchanged 011-150 entries, +and Markdown/whitespace structure. They do not claim executed C++ tests or +qualified movement/flow behavior. diff --git a/docs/adr/0098-m11-first-cellular-loop-decisions.md b/docs/adr/0098-m11-first-cellular-loop-decisions.md index 53b778c..6da13f8 100644 --- a/docs/adr/0098-m11-first-cellular-loop-decisions.md +++ b/docs/adr/0098-m11-first-cellular-loop-decisions.md @@ -7,6 +7,12 @@ amends the target gameplay with offspring-only structural expression, birth-time one-way control succession and NPC-parent continuity. The decisions below retain their historical M11 implementation meaning until a new version is qualified. +2026-10-21: [ADR-0177](0177-cellular-regions-world-linkage.md) amends decision 4 +for new cellular rules: logout takes effect after a delay during which the cell +stays vulnerable; afterwards it is anchored in place, cannot be engulfed, is not +moved by currents, and its metabolism and thermal response are frozen. This +replaces the vulnerable linger. A fresh life is also offered a choice of region. + Accepted for M11 (2026-10-09). M11.1 records these decisions; nothing is implemented yet. The maintainer chose each one from presented options on 2026-10-09. They are game rules for the first playable loop, and changing one needs a new decision. diff --git a/docs/adr/0172-cellular-environment-ownership.md b/docs/adr/0172-cellular-environment-ownership.md index 49d54c9..f121b25 100644 --- a/docs/adr/0172-cellular-environment-ownership.md +++ b/docs/adr/0172-cellular-environment-ownership.md @@ -9,6 +9,13 @@ owner (12.5b) implements. It extends ADR-0136 step B, ADR-0144 and ADR-0157/0165 No default/live version, durable profile, SQL schema, photosynthesis, atmosphere or M6 fixture change. ADR-0136 step C remains proposed design input. +Amended by [ADR-0177](0177-cellular-regions-world-linkage.md) for new cellular +rules: habitats are linked to a world area instead of one voxel; currents and the +thermal map are environmental conditions, not stock; regions cap their organism +count; emergence is a recorded export with a scaled world credit; logged-out +controlled cells are anchored, protected and frozen. Single ownership, individual +reserves and recorded boundary crossings are unchanged. + ## Maintainer clarification - **One owner per patch of space, at any moment.** It is not one global owner. diff --git a/docs/adr/0173-cellular-environment-batch.md b/docs/adr/0173-cellular-environment-batch.md index 59e1f2f..19f2604 100644 --- a/docs/adr/0173-cellular-environment-batch.md +++ b/docs/adr/0173-cellular-environment-batch.md @@ -6,6 +6,11 @@ Accepted portable M12.5b evidence, 2026-10-19. Extends ADR-0172 and the populati batches of ADR-0142/0144/0171. No durable admission, SQL schema, checkpoint profile, automatic scheduling or live/default rule change. +Amended by [ADR-0177](0177-cellular-regions-world-linkage.md) for new cellular +rules: emergence adds a recorded export flow; currents and the thermal map are +re-derived from configuration and add no flows; refused births at the region cap +and protected anchored offline cells must be reproduced by replay. + ## Decision Joint batch 1 (`AEVOEBT1`) carries one complete, unchanged population batch (format diff --git a/docs/adr/0177-cellular-regions-world-linkage.md b/docs/adr/0177-cellular-regions-world-linkage.md new file mode 100644 index 0000000..9f2480d --- /dev/null +++ b/docs/adr/0177-cellular-regions-world-linkage.md @@ -0,0 +1,110 @@ +# ADR-0177: Cellular regions, world linkage and emergence + +## Status and authority + +Accepted product direction, 2026-10-21, from the maintainer's region review +decisions in chat. Implementation is pending. Amends ADR-0172 (habitat geometry, +environmental conditions, boundary crossings, offline treatment) and ADR-0173 +(recorded flows and unattended intervals) for new cellular rules. Companion design: +[Cellular region changes](../../Cellular_Region_Changes.md) and +[Cellular movement draft](../../Cellular_movement_draft.md). Historical rules, +envelopes, checkpoints, tests and currently running worlds retain their meanings. + +## Context + +ADR-0172 places each cellular habitat inside one environmental voxel and accounts +every environmental quantity as owned stock. The region review needs larger +habitats with procedural currents and a thermal map, a defined exit from the 2D +cellular stage into the 3D world, a bounded population per region and a simpler +logout rule. It also selects simplifications so these can be playtested on the +DEV system without full fluid or thermal energy accounting. + +## Decision + +### Cellular regions belong to a world, not to a voxel + +A cellular region is its own habitat linked to a world. It is not located in one +world voxel and its size is not limited by voxel extent. Each region maps to an +area of its world. The region's thermal map is that world area's thermal map, +scaled down to the habitat. The same mapping is used to select emergence targets. + +Regions do not grow. Each region has a hard cap on its organism count; the world +adds regions instead. Whether demand creates another region for the same world or +attaches a region to a new world is a later equation, not selected here. + +### Currents and the thermal map are environmental conditions + +Procedural currents are a fixed environmental condition, like incident light. +They are not stock, carry no mechanical energy accounting, and add no ledger +entries. Drifting never credits usable E, and no process harvests flow energy. + +The thermal map is a static maintained condition derived from the world map. It +is not owned thermal energy and is not derived from accumulated waste heat. The +existing heat compartment and radiative export keep their meanings. Owned thermal +energy with heat capacity is deferred until gameplay needs changing temperatures. + +### Births stop at the region cap + +At the hard cap, births in that region are refused. Engulfment and death return +matter to the region and reopen slots. When a region stays at the cap with no +active players for an extended period, an operator may cull wildlife through an +admin interface. Culling is an explicit, recorded operator action, never an +automatic despawn presented as selection. + +### Region choice for a fresh life + +A fresh cell is offered a choice of region when it begins, so friends can share +one. Recognition of friends stays a separate design question (ADR-0098). + +### Emergence into the world + +An organism that evolves out of the 2D stage leaves its cellular region. Its +matter is a recorded export from the region and is lost to the cellular scale. +The organism enters the world at a value scaled to world quantities. This is an +explicit scale conversion, not a one-to-one conserved transfer. The conversion +depends on the number of regions per world and the matter per region and is not +yet selected. + +Target selection uses the region's mapped world area. Several candidate locations +closest to the organism's preferred temperature with the nutrients it needs are +ranked, and one is chosen at random. Crowding is not otherwise prevented: finite +world resources penalize popular sites. + +The emerging organism chooses **individual** or **bulk** emergence. Bulk places it +in a selection queue; organisms emerging together with the same or close biology +receive one shared target choice. + +### Logout anchors and freezes the controlled cell + +Logout takes effect after a delay. During the delay the cell remains in play and +vulnerable; logging out while about to be engulfed does not prevent it. After the +delay the cell is anchored in place: it cannot be engulfed, is not moved by +currents, and its metabolism and thermal response are frozen. This replaces the +vulnerable linger of ADR-0098 for these rules. Offline fairness is unchanged: +an offline controlled organism does not move, feed, reproduce, mutate or progress. + +### Disposable DEV worlds + +New cellular rules start in new DEV worlds. Existing DEV worlds need not be +migrated; this does not authorize any World0 action. + +## Consequences + +- ADR-0172's one-voxel habitat geometry does not apply to the new rules. Its + single-owner principle, individual reserves and recorded open-boundary crossings + still apply. +- Currents and the thermal map need seeded, versioned configuration so replay and + restore reproduce them exactly, but no new joint-batch flows. +- Emergence adds a new recorded export flow to joint batches; the world-side + credit belongs to the world owner's own import record. +- The birth cap changes population outcomes and must be recorded in replay. +- Anchored offline cells are excluded from engulfment and flow in replay. +- Open: the emergence conversion scale, the region-or-world creation equation, + cap values, logout delay duration, bulk-queue timing and similarity threshold. + +## Alternatives + +Growing a single region to fit demand was rejected: capped regions scale by count. +Owned mechanical and thermal energy accounting for playtests was rejected as cost +without gameplay benefit at this stage. A vulnerable offline linger was replaced by +a logout delay followed by a protected anchor. diff --git a/docs/adr/README.md b/docs/adr/README.md index f6b83b5..3b75376 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -1,5 +1,7 @@ # Architecture decision records +- [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. + - [ADR-0176: Durable photosynthesis regions and session v12](0176-durable-photosynthesis-region.md) - schema 57 raw bundle 13 (rules 11, owner format 9) with a light-declaring 12 -> 13 upgrade, the resumable `cellular-v8` opening and session v12 (captured light, visible producers, photosynthesis offers). - [ADR-0175: Photosynthesis producers](0175-photosynthesis-producers.md) - genome schema 5 photosynthesis with trial organelle costs, founder 4/rules 11, light booked by the cell owner (format 9) from recorded intentions, light-aware wildlife; earlier bytes unchanged.