Files
aevolution/Cellular_mutation_plan.md
T
dingoandClaude Opus 5.5 628721dff4 docs: cellular gameplay revamp plans
Plans for the cellular revamp, from the maintainer's decisions of 2026-10-22:
an overview of every gameplay system, the mutation offer system with a
49-mutation catalog, reproduction (on-demand buds, mutation splits,
multicellular organisms, emergence), feeding and energy (per-channel
collection, matter as energy, the spent pool), predation and defense, and
body and maintenance. Nothing is implemented by this commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-22 17:49:38 -04:00

400 lines
24 KiB
Markdown

# Cellular mutation plan
Status: planning draft, 2026-10-22. Records the maintainer's decisions on what a
mutation is, how offers work, and the full catalog for this pass (49 mutations). Where this document
conflicts with [Cellular_mutation_draft.md](Cellular_mutation_draft.md) or
[Cellular_movement_draft.md](Cellular_movement_draft.md), this document wins. No code,
runtime rule or live region is changed by it.
For a single cell, accepting a mutation divides it: the offspring expresses the
mutation and both cells carry it in their heritable plan. A multicellular organism
expresses an accepted mutation directly, without dividing. See
[Cellular_reproduction_plan.md](Cellular_reproduction_plan.md), sections 4 and 6.
## 1. What a mutation is
A mutation is an opportunity to steer the evolution of your organism. Each one is a
catalog entry describing one change to the genome. Very few mutations are pure
upgrades: most carry a pro and a con, and both are shown to the player when choosing.
| Field | Meaning |
| --- | --- |
| Name / description | What the player sees. |
| Effect | The exact genome change, e.g. `output +5, efficiency -2`. |
| Pro / Con | Shown in the offer. Derived from the effect where possible, not a flat penalty. |
| Available | Prerequisites (anatomy, region features) and limits (never past an axis bound). |
| Increase trigger | Behaviour that raises the mutation's affinity score. |
| Decrease trigger | Behaviour that lowers it. |
| Cost | Tunable price in energy and matter, per channel (section 4). |
## 2. Offer cadence
Offers arrive periodically while the player is actively playing. One offer is pending
at a time; it stays available while the player moves and is not dismissed by a timer.
Tunable: `mutation.offer_interval_ms` (trial 25,000) and the definition of active play.
Both need playtesting.
## 3. Weights and the draw
### Affinity scores
- Every cell holds an integer **affinity score per mutation**, starting at 0.
- When a mutation's increase trigger completes, its score rises by that mutation's
`increase_points`; a decrease trigger lowers it by `decrease_points`. The trigger's
timer then restarts, so a held behaviour fires repeatedly.
- Scores are bounded to `[score_min, score_max]`.
- **No drift:** scores change only through triggers, never with time.
- **Inheritance:** offspring start with their parent's scores.
### From score to chance
1. **Eligible pool:** every mutation whose prerequisites are met and whose effect stays
within its limits. Ineligible mutations have no chance at all.
2. **Weight:** `weight = base_weight x multiplier(score)`. The multiplier is 1 at score 0
and rises or falls linearly to `max_multiplier` at `score_max` and `min_multiplier`
at `score_min`.
3. **Chance of appearing in the offer:** `p = clamp(k x weight, floor, cap)`, with `k`
solved so that the chances of the eligible pool sum to the number of options
(300% for three). `floor` = **0.001%** (anomalies always happen); `cap` = **70%**.
4. **Draw:** systematic sampling over the pool. One random number picks the options,
they are always distinct, and each mutation's real chance of appearing equals its
`p`. The draw is seeded per cell and offer, so a retry or reconnect never rerolls.
The pool always holds well over five eligible mutations, so the 70% cap is always
satisfiable.
### Tunable draw settings
| Setting | Scope | Trial |
| --- | --- | --- |
| `offer_options` | global | 3 |
| `cap`, `floor` | global | 70%, 0.001% |
| `score_min`, `score_max` | global | -1000, +1000 |
| `max_multiplier`, `min_multiplier` | global | 10x, 0x (the floor still applies) |
| `base_weight` | per mutation | 100 |
| `increase_points`, `decrease_points` | per mutation | 100 |
| Trigger thresholds (seconds, counts, angles) | per mutation | listed with each mutation |
| Step sizes: primary, paired, spread | per mutation | 5, 2, 1 points |
## 4. Choosing and cost
The player picks one of the options or declines. Declining is free; the next offer
draws again.
Each mutation has its own tunable **cost**: an amount per channel (energy E in
picojoules; carbon C, nitrogen N, phosphorus P and other matter O in femtograms), plus
one **scale** from 0% to 100% for fine tuning. The charged amount per channel is
`amount x scale`.
```text
mutation.strong_propulsion.cost_e_pj = 0
mutation.strong_propulsion.cost_c_fg = 0
mutation.strong_propulsion.cost_n_fg = 0
mutation.strong_propulsion.cost_p_fg = 0
mutation.strong_propulsion.cost_o_fg = 0
mutation.strong_propulsion.cost_scale_percent = 0
```
Every mutation starts with all amounts and the scale at 0. Playtesting decides whether
a mutation needs a cost at all, and further playtesting tunes it, one mutation at a
time.
The cost is paid from the reserve when the mutation is applied; reserve matter can
stand in for its energy part (feeding and energy plan, section 3). An unaffordable
option is still offered; it shows the shortfall and cannot be selected until the
reserve covers it.
**Where the cost goes:** the environment reclaims it. Each non-empty channel of the
paid cost becomes a new resource bubble of that amount at a random point in the
region, chosen by the region's seeded draw so a replay places it identically. Nothing
is destroyed; the region's totals are unchanged.
If the region is already at its deposit limit, the reclaimed amount merges into the
existing bubble **farthest** from the paying cell, so the cost cannot easily be
collected straight back.
This replaces the earlier draft policy of no separate fee for selecting a mutation.
### Testing the pool
For testing, every mutation can be switched on or off in the tuning file
(`mutation.<name>.enabled = 1`). A disabled mutation is not in the pool at all, even
at the floor. Together with `base_weight`, this lets a playtest narrow the pool to
the mutations under test or bias the draw toward them.
## 5. Movement mutations
Movement edits the genome's movement arrangement, in reference points where the founder
is 100. Steps add or remove fixed points; they never compound (100 -> 105 -> 110).
Global defaults: primary step `mutation.step_points` = 5, paired step
`mutation.paired_points` = 2; each mutation can override them (section 3).
Percentages below are at matched conditions against the arrangement before the edit,
from the current handling model (top speed ~ thrust / drag; thrust energy ~ output /
efficiency).
### Core mutations (available from birth)
#### Strong Propulsion
- **Effect:** output +5, efficiency -2.
- **Pro:** top speed and acceleration +5%.
- **Con:** energy per second at full thrust +7%; energy per distance +2%.
- **Increase:** thrust for 10 s in total.
- **Decrease:** no thrust for 30 min.
#### Economical Propulsion
- **Effect:** coasting +5 (lower drag, forward and sideways).
- **Pro:** drifts about 5% further after letting go; top speed +5%; cheaper travel when
thrust is pulsed.
- **Con:** stops more slowly, so precise stops need braking, which costs energy; slides
more in turns.
- **Increase:** thrust at least every 15 s for a minute, or move steadily for a minute.
- **Decrease:** no movement for 2 min.
#### Efficient Propulsion
- **Effect:** efficiency +5, output -2.
- **Pro:** energy per distance -5%; energy per second at full thrust -7%.
- **Con:** top speed and acceleration -2%.
- **Increase:** movement is over half the energy spent in a minute.
- **Decrease:** no thrust for 5 min.
#### Agile Steering
- **Effect:** steering +5, output -2.
- **Pro:** turns 5% faster.
- **Con:** top speed and acceleration -2%.
- **Increase:** 5 sharp turns (over 90 degrees) within 20 s.
- **Decrease:** hold one heading (within 20 degrees) for 60 s of thrust.
#### Streamlined Body
- **Effect:** streamlining +5, steering -2 (lower forward drag only).
- **Pro:** top speed +5% and longer forward glide.
- **Con:** turns 2% slower.
- **Increase:** thrust in a straight line (within 20 degrees) for 20 s.
- **Decrease:** 5 sharp turns within 20 s.
Distinct from Economical Propulsion: Streamlined lowers forward drag only and pays in
turning; Economical lowers drag in every direction and pays in stopping and sliding.
#### Strong Brakes
- **Effect:** braking +5, output -2.
- **Pro:** stops and reverses 5% faster.
- **Con:** top speed -2%; each brake draws 5% more energy.
- **Increase:** brake 5 times within a minute.
- **Decrease:** no braking for 10 min.
### Mirror mutations (kept for now)
Each core mutation has a mirror that moves the same axes the other way, so lowering a
trait is a real choice with its own benefit. A mirror's triggers are its core
mutation's triggers swapped.
| Mirror | Effect | Pro | Con | Increase | Decrease |
| --- | --- | --- | --- | --- | --- |
| Light Propulsion | output -5, efficiency +2 | Energy per second -7%, per distance -2% | Top speed -5% | No thrust for 30 min | Thrust for 10 s |
| Damped Body | coasting -5 | Stops sooner, slides less | Top speed -5%; energy per distance +5% | No movement for 2 min | Pulsed or steady movement for a minute |
| Overdriven Propulsion | efficiency -5, output +2 | Top speed +2% | Energy per second +7%, per distance +5% | No thrust for 5 min | Movement over half of energy spent |
| Forward Drive | steering -5, output +2 | Top speed +2% | Turns 5% slower | One heading for 60 s of thrust | 5 sharp turns in 20 s |
| Rounded Body | streamlining -5, steering +2 | Turns 2% faster | Top speed -5% | 5 sharp turns in 20 s | Straight thrust for 20 s |
| Light Brakes | braking -5, output +2 | Top speed +2% | Stops 5% slower | No braking for 10 min | Brake 5 times in a minute |
### Limits
Each axis has tunable bounds (trial: 25 to 1,000 points; the genome already caps at
1,000). A mutation that would cross a bound is not eligible. Efficiency divides thrust
cost, so it can never reach 0.
### Postponed
Burst, Anchor, Shed propulsion and Colony propulsion are postponed. They are not in the
pool, not even at the 0.001% floor, until their mechanics exist.
## 6. Feeding and energy mutations
Systems and terms are defined in the
[feeding and energy plan](Cellular_feeding_energy_plan.md). All indices are points with
the founder at 100. All available from birth unless stated.
**Spread pattern:** a channel mutation raises one matter channel by the primary step
(5) and lowers each of the other three matter channels by the spread step (1). The
steps are tunable per mutation.
### Feeding
| Name | Effect | Pro | Con | Increase | Decrease |
| --- | --- | --- | --- | --- | --- |
| Carbon Gatherer | C collection +5, N/P/O collection -1 each | Collects carbon 5% faster | Collects N, P, O 1% slower each | Carbon is at least half the matter collected in the last minute | No carbon collected for 5 min |
| Nitrogen Gatherer | N collection +5, C/P/O -1 each | Collects nitrogen 5% faster | Collects C, P, O 1% slower each | Same, for nitrogen | Same, for nitrogen |
| Phosphorus Gatherer | P collection +5, C/N/O -1 each | Collects phosphorus 5% faster | Collects C, N, O 1% slower each | Same, for phosphorus | Same, for phosphorus |
| Other Matter Gatherer | O collection +5, C/N/P -1 each | Collects other matter 5% faster | Collects C, N, P 1% slower each | Same, for other matter | Same, for other matter |
| Big Appetite | Shared intake limit +5, upkeep efficiency -2 | Takes in 5% more per second at rich food | More upkeep | Feeding at the intake limit for 10 s total | No feeding for 5 min |
| Small Appetite (mirror) | Shared intake limit -5, upkeep efficiency +2 | Less upkeep | Takes in 5% less at rich food | No feeding for 5 min | Feeding at the intake limit for 10 s total |
### Energy
| Name | Effect | Pro | Con | Increase | Decrease |
| --- | --- | --- | --- | --- | --- |
| Thorough Extraction | Energy kept per bubble +5, energy collection -2 | More energy from each energy bubble | Drains energy bubbles 2% slower | Burning matter for energy for 30 s total | No matter burned for 10 min |
| Rapid Extraction | Energy collection +5, energy kept per bubble -2 | Drains energy bubbles 5% faster | Keeps slightly less of each | Energy collection at its limit for 10 s total | No energy collected for 5 min |
| Carbon Metabolism | C burn efficiency +5, N/P/O -1 each | Carbon covers 5% more energy when burned | N, P, O cover 1% less each | Burning carbon for 30 s total | No carbon burned for 10 min |
| Nitrogen Metabolism | N burn efficiency +5, C/P/O -1 each | Nitrogen covers 5% more energy | C, P, O cover 1% less each | Burning nitrogen for 30 s total | No nitrogen burned for 10 min |
| Phosphorus Metabolism | P burn efficiency +5, C/N/O -1 each | Phosphorus covers 5% more energy | C, N, O cover 1% less each | Burning phosphorus for 30 s total | No phosphorus burned for 10 min |
| Other Matter Metabolism | O burn efficiency +5, C/N/P -1 each | Other matter covers 5% more energy | C, N, P cover 1% less each | Burning other matter for 30 s total | No other matter burned for 10 min |
Thorough and Rapid Extraction mirror each other. Energy kept per bubble can never
exceed 100% of the bubble's energy.
### Photosynthesis
Light capture is in points, with acquisition at 100.
| Name | Effect | Pro | Con | Available | Increase | Decrease |
| --- | --- | --- | --- | --- | --- | --- |
| Acquire Photosynthesis | Gain producer tissue at 100, energy collection -2 | Steady energy from light | Tissue adds mass (slower, more upkeep); drains energy bubbles slower | After burning a tunable amount of carbon; not a producer | Burning carbon for 30 s total | Burning other channels for 30 s total |
| Expand Photosynthesis | Light capture +5, energy collection -2 | 5% more energy from light | More tissue mass and upkeep; drains energy bubbles slower | Is a producer | Drifting without thrust for 60 s total | Thrust for 2 min total |
| Reduce Photosynthesis (mirror) | Light capture -5, energy collection +2 | Less tissue, lighter; drains energy bubbles faster | Less energy from light | Is a producer, above the minimum | Thrust for 2 min total | Drifting without thrust for 60 s total |
| Shed Photosynthesis | Remove producer tissue | No producer mass or upkeep | No light energy | Is a producer | Thrust for 5 min total | Drifting without thrust for 60 s total |
Shed Photosynthesis has `base_weight` 25 (others 100), so shedding is rarer than
trimming. A cell that sheds it can be offered Acquire again; the carbon it has already
burned still counts.
## 7. Predation and defense mutations
Systems and terms are defined in the
[predation and defense plan](Cellular_predation_defense_plan.md). All indices are points
with the founder at 100. All available from birth.
| Name | Effect | Pro | Con | Increase | Decrease |
| --- | --- | --- | --- | --- | --- |
| Reinforced Membrane | Membrane +5 | Predators need 5% more mass to engulf you | More membrane mass and upkeep, slower collection, heavier | In contact with a cell over 1.5x your mass for 5 s total | No contact with a larger cell for 10 min |
| Thin Membrane (mirror) | Membrane -5 | Faster collection, less mass and upkeep | Easier to engulf | No contact with a larger cell for 10 min | In contact with a cell over 1.5x your mass for 5 s total |
| Expanding Chamber | Engulf capacity +5, membrane -2 | Can engulf prey 5% bigger | Stretched wall: slightly easier to engulf yourself | 3 failed engulfs because the prey was too large or its membrane too thick | No engulf attempts for 10 min |
| Small Mouth (mirror) | Engulf capacity -5, membrane +2 | Tougher wall | Only smaller prey | No engulf attempts for 10 min | 3 failed engulfs because the prey was too large |
| Rapid Digestion | Kill absorption +5, shared intake -2 | Takes 5% more from a kill straight away, so less is left behind | Slower everyday feeding | A successful engulf | No successful engulf for 15 min |
| Grazer's Gut (mirror) | Kill absorption -5, shared intake +2 | Faster everyday feeding | Takes less from kills | No successful engulf for 15 min | A successful engulf |
Expanding Chamber links offense and defense: a better hunter is slightly easier prey.
Failed-engulf reasons (prey too large, membrane too thick) are already reported by the
server; contact with a larger cell is a new counter.
## 8. Body and maintenance mutations
Systems and terms are defined in the
[body and maintenance plan](Cellular_body_maintenance_plan.md). Indices are points with
the founder at 100; the body recipe is in per thousand. All available from birth.
**Recipe spread:** a thrifty body lowers one channel's share by the recipe step (20 per
thousand) and spreads the same amount evenly across the other three. Tunable per
mutation.
| Name | Effect | Pro | Con | Increase | Decrease |
| --- | --- | --- | --- | --- | --- |
| Larger Body | Size +5 | Harder to engulf, can engulf bigger prey, larger footprint touches more food | More upkeep, costlier buds and regrowth, heavier and slower | Reserve holds more matter than the body for 60 s total | Burning matter for energy for 30 s total |
| Smaller Body (mirror) | Size -5 | Less upkeep, cheaper buds and regrowth, quicker | Easier to engulf, smaller prey only | Burning matter for energy for 30 s total | Reserve holds more matter than the body for 60 s total |
| Carbon-Thrifty Body | Carbon share -20, N/P/O share +20 in total | Building, regrowth and buds need less carbon | Need more N, P and O | Growth or a bud blocked by lack of carbon for 10 s total | Carbon is at least half the matter collected in the last minute |
| Nitrogen-Thrifty Body | Nitrogen share -20, C/P/O share +20 in total | Need less nitrogen | Need more C, P and O | Same, for nitrogen | Same, for nitrogen |
| Phosphorus-Thrifty Body | Phosphorus share -20, C/N/O share +20 in total | Need less phosphorus | Need more C, N and O | Same, for phosphorus | Same, for phosphorus |
| Other-Thrifty Body | Other-matter share -20, C/N/P share +20 in total | Need less other matter | Need more C, N and P | Same, for other matter | Same, for other matter |
| Efficient Upkeep | Upkeep efficiency +5, growth speed -2 | Lower upkeep, never below the essential floor | Regrows 2% slower | Upkeep is over half the energy spent in the last 5 min | Regrowing for 60 s total |
| Rapid Growth | Growth speed +5, upkeep efficiency -2 | Regrows 5% faster after splits | More upkeep | Regrowing for 60 s total | Fully grown for 10 min |
| Dense Tissue | Density +5 | Smaller footprint for the same mass, lighter membrane, less upkeep | Less surface: slower collection, touches less food | In contact with a cell over 1.5x your mass for 5 s total | Feeding by contact for 60 s total |
| Light Tissue (mirror) | Density -5 | Larger surface: faster collection, touches more food | More membrane mass and upkeep, bigger target | Feeding by contact for 60 s total | In contact with a cell over 1.5x your mass for 5 s total |
Thrifty bodies have no performance effect; their value is fitting the region's supply,
and they pair with the Gatherer mutations. Efficient Upkeep and Rapid Growth mirror
each other. Dense Tissue and Reinforced Membrane share an increase trigger: both answer
the same threat.
## 9. Reproduction mutations
Systems and terms are defined in the
[reproduction plan](Cellular_reproduction_plan.md). Bud share is in points with the
founder at 100 (half the parent's body). Only on-demand buds count as reproductions;
mutation splits do not.
### Bud size
| Name | Effect | Pro | Con | Increase | Decrease |
| --- | --- | --- | --- | --- | --- |
| Bigger Buds | Bud share +5 | Buds start 5% larger: harder to engulf, more likely to survive | Each bud costs 5% more from the reserve | One of your buds is engulfed within 2 min of birth | A bud refused for lack of resources |
| Smaller Buds (mirror) | Bud share -5 | Each bud is cheaper | Buds start smaller and more vulnerable | A bud refused for lack of resources | One of your buds is engulfed within 2 min of birth |
### Multiple offspring
**Litter** is a heritable value, founder 0, giving extra offspring per bud:
- Each full 100 litter points is one guaranteed extra offspring; the remainder is the
percentage chance of one more. Litter 150 means one extra, plus a 50% chance of a
second.
- Every offspring of one bud shares the same investment, so more offspring means each
is smaller. The bud costs the same.
- The maximum offspring per bud is tunable (trial 10, so litter up to 900).
- Each extra offspring needs a free spot touching the parent and room under the region
cap. If fewer can be placed, fewer are born and the investment is shared among them.
- This replaces the current 25% twin chance: new founders start at litter 0.
| Name | Effect | Pro | Con | Increase | Decrease |
| --- | --- | --- | --- | --- | --- |
| Twinning | Litter +25 | More offspring per bud | Each offspring starts smaller and more vulnerable | Bud while the reserve covers at least twice the bud's cost | One of your buds is engulfed within 2 min of birth |
| Single Bud (mirror) | Litter -25 | Each offspring starts larger | Fewer offspring per bud | One of your buds is engulfed within 2 min of birth | Bud while the reserve covers at least twice the bud's cost |
Single Bud is not eligible at litter 0. Twinning is not eligible at the maximum.
### Becoming multicellular
| Name | Effect | Pro | Con | Available | Increase | Decrease |
| --- | --- | --- | --- | --- | --- | --- |
| Adhesion | Gain Adhesion | Become a multicellular organism: the path to emerging into the world | Permanent: no more splits, one shared reserve, the whole organism can be engulfed at once, heavier | After a tunable number of on-demand buds (trial 5) | Each on-demand bud | No bud for 15 min |
Adhesion has `base_weight` 50. Accepting it is a split whose offspring expresses
Adhesion and attaches, so the organism forms at once whichever cell the player keeps;
its offer shows Accept and Decline only.
Emerging into the world is a **button**, not a mutation: it appears once the organism
reaches the emergence threshold (reproduction plan, section 7).
## 10. Balance notes
- Economical Propulsion and Streamlined Body raise top speed without raising energy per
second. Their cost and weights must keep them from dominating.
- Big Appetite only matters where a channel's own limit is above the share of the
shared limit it gets; the shared limit and channel limits must be tuned together.
- Thresholds above are first guesses. "Thrust for 10 s" is cumulative and fires each
time 10 s of thrust accrues; "no thrust for 30 min" is continuous.
## 11. Implementation map
| Piece | State today |
| --- | --- |
| Movement arrangement in the genome | Exists (schema 6); not edited by any mutation yet. |
| Handling from the arrangement | Exists: output, efficiency, steering, streamlining, braking, coasting. |
| Step/paired points, interval, option count | Keys exist in `cellular.tuning`; unused by code. |
| Named catalog with pro/con, triggers and cost | New: replaces the 32 generic adjust/acquire/shed operators for new rules. |
| Per-cell affinity scores | New persisted state, inherited at birth (lives format bump). |
| Trigger tracking | New server-side activity counters from per-tick thrust, brake, heading and velocity. |
| Chance allocation and systematic draw | New: replaces the current uniform draw of 3. |
| Per-mutation cost and scale | New tuning keys and funding path; defaults all 0. |
| Reclaimed cost | New: paid channels become seeded random bubbles in the region. |
| Per-mutation `enabled` switch | New tuning key, for narrowing the pool in tests. |
| Per-mutation step sizes | New tuning keys (primary, paired, spread). |
| Feeding and energy genome fields | New: collection index per channel, shared intake, burn efficiency per channel; energy kept per bubble reuses `energy_conversion`. |
| Feeding and energy triggers | New counters: diet share per channel, time at intake limit, matter burned per channel, drifting time. |
| Predation genome fields | New: membrane in points, engulf capacity, kill absorption. |
| Predation triggers | Failed-engulf reasons exist; contact time with larger cells and kill timers are new. |
| Body genome fields | New: size in points, body recipe, upkeep efficiency, density, growth speed. |
| Body triggers | New: growth or bud blocked by a named channel, regrowth time, time fully grown, reserve-to-body ratio. |
| Reproduction genome fields | Bud share exists (reproduction capability, in points is new); litter and Adhesion are new. |
| Multiple offspring per bud | Twin budding exists (shared investment, room check); litter in place of the fixed 25% chance is new. |
| Reproduction triggers | New: on-demand bud count, bud refusals, early deaths of own buds, reserve-to-bud-cost ratio. |
| Offer UI | Shows name, pro, con, cost, shortfall and chance. |
Every new behaviour goes in a new rules version; regions on earlier rules keep their
meaning.