An interactive, deterministic natural-selection sandbox. Creatures forage, remember resources and danger, hunt, flee, return home, reproduce, and mutate while live charts show selection taking shape across generations. The live What happened panel keeps the latest salient event prominent, with a bounded earlier-moment trail for context.
Each fixed simulation step is resolved in phases: perceive, decide, move and metabolize, settle food contacts, settle attacks, then regrow resources. Creatures have directional vision, reaction intervals, distance-dependent detection, and obstacle occlusion. The selected creature shows its field of view, current target, remembered locations, and compact perception counts.
In addition to speed, size, and sensing, creatures inherit aggression, caution, and exploration. Decisions use short-term food and threat memories, target commitment, travel safety, energy, expected hunting payoff, and correlated wandering. Attacks are contests shaped by relative size, speed, energy, aggression, and caution; attempts cost energy and impose a handling cooldown.
Founders begin with conservative standing variation by default (4% physical and 6% behavioral variation). This makes selection visible before the first birth without overwhelming the configured starting means. Clonal, low-diversity, and high-diversity controls are available; zero variation produces exactly equal founders. Version-2 experiments migrate to zero founder variation so their prior deterministic starting populations remain reproducible. Version-3 setups migrate to classic lifecycle, perfect-perception, and threshold-predation modes. Version-4 experiments migrate with reproductive maturity age 0. Version-5 experiments retain their maturity setting and migrate with neutral patch quality, preserving their prior trajectories. Fresh version-6 setups use ecological modes, maturity age 1, and contrasting patch quality; all mechanisms remain switchable.
Biological individual and lineage identifiers are separate from transient render objects. A surviving adult keeps its individual identifier across generations; offspring receive a new identifier linked to their parent and lineage. The generation ledger reconciles each starting individual as survived, hunted, energy-depleted, unfed, late, or aged. Ecological survivors retain configurable energy, reproduction deducts a cost, offspring receive a configured reserve, and capacity-limited births use a seeded fair ranking. The ledger records production, consumption, attack outcomes, birth capacity, and selection moments. Autoplay also keeps a bounded newest-first list of salient actor-level moments—such as food collection, attacks, home arrivals, energy loss, regrowth, interventions, and generation settlement—with generation/day provenance and a short model-context line. Movement-only ticks are omitted, so this is not a long per-tick trace or replay. The latest retained event stays above expandable history at every screen size. Clicking a creature opens its bounded inspection telemetry, which compares its current destination with the captured choice and explains the timing of decision and perception samples. An expandable perception table separates food and creature counts, showing detections and the first reason each missed item was filtered out. Perfect-perception mode explains its different sensing rules.
An expandable How to read the arena guide sits above the field. Illustrated examples explain creatures, food, rocks, patch richness (1.0× is normal), and stock rings, with separate explanations for classic mode. It also explains outline colors, inspection highlights, and playback controls. The guide starts closed; live population/food counts and the Highlight filter remain below the playback controls. Selecting a living actor in an event record pauses playback and inspects its current state. Event annotations appear only after an explicit review, keeping ordinary playback free of event callouts. “Happened here” marks where the selected event occurred; highlighted creatures show their current positions. The What happened panel shows one short update, with detailed history inside a closed disclosure that opens only when requested.
Arena view controls zoom from 1× to 4×. Drag with a mouse or touch to pan while zoomed. Focus the arena or view controls to use arrow keys, plus/minus, or Home to reset. Inspections bring the selected subject or reviewed event site into view. Zooming and panning do not advance the simulation.
The individual inspector's Individual history follows its stable biological identity across generations. A separate shared archive retains up to 480 actor events, oldest first, with generation and event context. Older archived records remain readable after leaving the short arena review trail; recent records can be reviewed in the arena. This bounded archive excludes relatives and ordinary movement ticks and does not promise a complete biography.
Save & resume run provides one manual save slot in the current browser. Save run captures the current simulation moment, configuration, random state, environment, individuals, and retained history. It survives closing and reopening the browser. Resume saved run asks before replacing the current run and staged settings, then restores the saved moment paused. Save again to replace the slot; clearing browser data removes it. Configuration links still share only a setup. Download run JSON creates a portable backup of the current moment. Import run JSON validates a backup file up to 4 MB and asks before replacing the current run and staged settings, then restores paused. Downloading or importing does not replace the browser save slot. Setup-only experiment files use the settings import.
Steering wraps accumulated headings before choosing the shortest turn, so equivalent orientations produce the same pursuit, obstacle detours, and energy use. Hunting and energy rules remain model assumptions, with regression tests for costs, cooldowns, simultaneous attacks, and generation settlement.
Review event in arena pins a retained record, including earlier generations, instead of highlighting an unrelated newer event. Actor inspection also reviews its associated record when a stable event identity is available. Review explains when no site or living actor position exists. Earlier, Later, and the record slider browse retained events in order without advancing simulation time; this is a review of recorded moments, not a replay. Return to latest event ends review without resuming playback; Play, Next action, Finish generation, live shocks, and restart also leave review mode.
The seeded environment persists across generations. Food patches have visible stock, bounded capacity, and deterministic within-generation regrowth. Each patch also receives a persistent seeded quality: richer patches replenish faster and produce higher-energy food, while creatures weigh that value against travel distance. Patch multipliers are centered around the configured baseline, so their continuous item-regrowth rates sum to the same baseline before capacity and discrete rounding. Total nutritional supply can still rise with contrast because richer patches also produce higher-energy items. Remaining food carries across generation boundaries in ecological mode. Obstacles persist, and seasons, trend, and response rate change the resource target. Classic mode retains the original generation-pulse food rules.
During a run, Resource bloom, Drought, and Founder migration apply immediately without restarting. They obey the food and population safety caps and are deterministic for a seed when replayed at the same simulation ticks. A bounded event timeline records each shock. The Evolution story summarizes living lineages, inverse-Simpson effective diversity, leading lineage shares, and the latest survivor/reproducer trait shifts. Selecting a creature also highlights its living lineage relatives in the arena.
The Experiment lab compares a control with a treatment across matched random seeds. Choose a preset pressure, intervention generation, outcome, replicate count, and fixed horizon; the chart reports both medians and middle-50% intervals on one shared scale, plus the paired treatment-minus-control effect. Patch quality contrast is available as a generation-boundary treatment pressure; the same persistent patch ordering becomes more or less unequal in both arms. Runs use a separate worker when available and can be cancelled without changing the live ecosystem. Results export as validated versioned JSON or tidy, spreadsheet-safe CSV. A result seed can be staged in the live parameters for an explicit replay on the next Apply & restart.
npm install
npm run devThen open the local URL printed by Vite. No accounts, services, or external runtime assets are required.
npm test
npm run build
npm run check
npm run previewThe public engine facade is src/simulation/engine.ts; deterministic random,
environment, behavior, and motion logic live in focused neighboring modules.
The same reset configuration reproduces the same run.
This is an educational toy model, not a biological prediction. Creatures are asexual, traits are scalar, offspring mutation is simplified, and the square arena omits genetics, disease, social behavior, and real ecosystem complexity. Do not use its outcomes to infer the behavior of real species or populations.
Locomotion pressure is proportional to size³ × actual velocity²; sensing adds
a separate linear energy cost. In ecological mode, positive-energy creatures
must return home before the generation ends and retain part of their reserve.
Their retained energy must be strictly greater than the configured
reproduction cost, and their age must be at least maturityAge, before they can
reproduce. Founders and newborns start at age 0; every survivor gains one age
unit at each settlement. Fresh v6 runs therefore keep age-0 founders and
newborns out of the next reproduction pool, while v4 imports use maturity age 0
for replay compatibility. Advanced patch multiplier is
1 + patchQualityVariation × qualityBias; the seeded biases are bounded,
centered around zero, and persist for the run. The multiplier scales both
within-generation regrowth and the energy of newly produced food. Version-5 and
older imports set patchQualityVariation to zero for replay compatibility.
In classic mode, the original rule is unchanged: one food brought home survives
and two also produce one offspring; classic mode does not apply the ecological
maturity gate. These equations are calibrated for legible dynamics rather than
fitted to empirical data.
Applied experiments are encoded as versioned configuration data. “Copy experiment link” stores the full sanitized setup in the URL; export and import use the same versioned JSON envelope. URL configuration takes precedence over local storage, which takes precedence over defaults. Simulation seeds and stable fixed-step updates reproduce the same run.
Parameter edits are staged until Apply parameters & restart. Discard staged changes restores the running experiment's settings without restarting or changing playback. Experiment links and exports use the running settings.
Everything runs in the browser. There are no accounts, analytics, server calls, or uploads. Experiment links place configuration—not simulation history—in the URL. Exported files remain on the user's device.
Current stable Chrome, Edge, Firefox, and Safari are supported. A module worker owns playback where available; a bounded, visibly identified main-thread mode is used when workers are unavailable. Reduced-motion preferences start playback paused. Population is capped at 120 and seasonal food at 180 to protect the quadratic interaction model. Up to 240 generation summaries are retained; the charts show the latest 40. The high-load test uses a generous five-second threshold intended only to catch catastrophic regressions; timings vary by machine and CI load.
The project is currently intended to run locally. Nothing in the app publishes,
uploads, or hosts a simulation. Use Node 20.19 or newer and npm ci when an exact
dependency install is needed; npm run preview only serves the production build
on the local machine for verification.
Ecological shelter is rest, not free survival: resting creatures pay the same baseline metabolism as active creatures (0.08 + senseEnergyFactor × sense × 8 per time unit), without movement cost, and can die when energy runs out. Below the starting energy reserve they leave to forage if enough time remains for a quarter-day foraging trip plus the return safety allowance. Separate departure and return thresholds prevent repeated turnarounds. Ecological travel uses a base speed of 0.055 so central resources are reachable within the default day, with movement energy normalized to that speed. Classic mode retains its original 0.038 travel speed and shelter rules. Existing ecological saves still load, but these rule corrections change their future trajectories.
The arena now leads the page with a live description based on living creatures' current actions and actual food counts. Click a creature for its action, purpose, and energy; survival forecasts and captured decision telemetry start collapsed. Completed generations summarize survival, births, population change, and death causes. Environment tools, event history, statistics, journals, lineages, and charts remain available in expandable sections; review links open their destination before moving focus.
In the ecological model, survivors retain their homes and offspring begin at the parent's chosen home. Founders and new migrants receive random starting homes. At a round boundary, a survivor may move up to 0.06 arena units along its existing edge, using only average locations of food it collected and attackers it encountered that round. Staying wins unless the estimated benefit exceeds the movement cost and at least a quarter of the starting energy reserve remains. Relocation is paid from energy remaining after survival and reproduction costs; it cannot rescue a creature that failed settlement. Per-round experience resets, while the last move's reason and cost remain visible in the inspector and recorded moves appear in event history. Classic mode retains its historical random placement. Old saves load without relocation experience, and begin collecting it from the restored moment.