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

24 KiB

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 or 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, 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.

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. 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. 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. 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. 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.