This guide covers setting up a development environment and contributing to Evo.
Evo is being rebuilt as a pnpm workspace around a headless simulation engine (see ADR 0001 and ADR 0002). The original app is archived in legacy/prototype.
- Node.js v22 or later
- pnpm, via corepack:
corepack enable(the version is pinned inpackage.json)
Run from the repository root:
| Command | Description |
|---|---|
pnpm install |
Install all workspace dependencies |
pnpm check |
Typecheck, lint (including dependency rules), and test |
pnpm build |
Compile-check every package and build the web app |
pnpm typecheck |
TypeScript checks for every package |
pnpm lint |
Dependency-rule check plus ESLint |
pnpm test |
Tool tests plus every package's Vitest suite |
pnpm format |
Format with Prettier (pnpm format:check verifies without writing) |
pnpm lint:deps |
Only the workspace dependency-rule check |
pnpm test:determinism |
The slow suite: 100,000-tick runs and pinned state hashes (CI runs it in shards) |
pnpm --filter @evo/simulation probe |
A measurement, not a test: runs presets over many seeds and writes a table (see below) |
pnpm --filter @evo/web dev |
The web app with hot reload (preview serves a build) |
pnpm --filter @evo/web dev starts the application; pnpm --filter @evo/web build produces apps/web/dist, which is what GitHub Pages serves (see the web application). Open it with ?debug in the address to expose window.__evo (the host and renderer) for experiments; real-browser checks are run with Playwright against vite preview.
Packages live in packages/* (contracts, config, simulation, renderer, ui) and apps/* (web, desktop, simulator-cli). Allowed dependencies are documented in the dependency diagram and enforced in CI. The simulation package must stay headless and deterministic: no React, DOM, Electron, Math.random(), or wall-clock time.
The commands below apply to the archived prototype. Run them from legacy/prototype.
- Node.js v18 or later (Download)
- npm (comes with Node.js)
- Git (Download)
- VS Code (recommended) with extensions:
- ESLint
- Prettier
- TypeScript and JavaScript Language Features
-
Fork the repository on GitHub
-
Clone your fork
git clone https://github.com/YOUR_USERNAME/Evo.git cd Evo -
Install dependencies
npm install
-
Start development server
Web version (recommended for development):
npm run dev:web
Desktop version:
npm run dev
| Script | Description |
|---|---|
npm run dev:web |
Start web development server |
npm run dev |
Start Electron development app |
npm run build:web |
Build web version for production |
npm run build |
Build Electron app |
npm run build:win |
Build for Windows |
npm run build:mac |
Build for macOS |
npm run build:linux |
Build for Linux |
npm run lint |
Run ESLint |
npm run format |
Format code with Prettier |
npm run typecheck |
Run TypeScript type checking |
src/
├── main/ # Electron main process
├── preload/ # Electron preload scripts
└── renderer/ # React application
├── App.tsx # Root component
├── components/ # UI components
│ ├── SimulationCanvasNew.tsx # Main canvas
│ ├── Sidebar.tsx # Control sidebar
│ ├── DNAPanel.tsx # Agent info panel
│ └── ...
├── core/ # Simulation logic
│ ├── Agent.ts # Agent class
│ ├── NeuralNetwork.ts # Neural network
│ ├── EvolutionManager.ts # Evolution logic
│ └── utilities/ # Helpers
├── hooks/ # Custom React hooks
├── types/ # TypeScript types
└── assets/ # CSS and static assets
- Use strict TypeScript with proper typing
- Avoid
anytypes when possible - Use interfaces for object shapes
- Use functional components with hooks
- Keep components small and focused
- Use
useCallbackanduseMemoappropriately
- 2 spaces for indentation
- Single quotes for strings
- Semicolons required
- Run
npm run formatbefore committing
- ESLint is configured for the project
- Run
npm run lintto check for issues - All lint errors must be resolved before merging
-
Create a feature branch
git checkout -b feature/your-feature-name
-
Make your changes
- Write clean, well-documented code
- Follow existing patterns in the codebase
-
Test your changes
- Run the development server
- Test in both web and Electron modes if applicable
- Check for console errors
-
Lint and format
npm run lint npm run format npm run typecheck
-
Commit your changes
git add . git commit -m "feat: add your feature description"
-
Push and create PR
git push origin feature/your-feature-name
Then open a Pull Request on GitHub.
Follow conventional commits:
feat:New featurefix:Bug fixdocs:Documentation changesstyle:Code style changes (formatting)refactor:Code refactoringperf:Performance improvementstest:Adding testschore:Maintenance tasks
- Component-based architecture for UI
- Rich ecosystem and tooling
- TypeScript support
- High performance for many moving objects
- Direct control over rendering
- Efficient for 2D simulations
- Cross-platform desktop support
- Native OS integration
- File system access for saves
- Create file in
src/renderer/components/ - Export from component file
- Import and use in parent component
Example:
// src/renderer/components/MyComponent.tsx
import React from 'react'
interface MyComponentProps {
value: string;
}
export const MyComponent: React.FC<MyComponentProps> = ({ value }) => {
return <div>{value}</div>
}- Update type in
src/renderer/types/simulation.ts - Add default value in
src/renderer/core/utilities/AgentConfig.json - Add UI control in sidebar
- Use value in simulation logic
- Edit
src/renderer/core/Agent.ts - Update neural network inputs/outputs if needed
- Test extensively - small changes can have big effects!
- Edit
src/renderer/core/EvolutionManager.ts - Update types if adding new config options
- Add UI controls if user-configurable
- Use React DevTools for component inspection
- Console logs appear in browser console
- Network tab for any API calls
- DevTools automatically open in development
- Main process logs appear in terminal
- Use
console.logfor debugging
TypeScript errors:
- Run
npm run typecheckfor details - Check import statements
- Verify type definitions
Simulation bugs:
- Add console.log in update loop
- Reduce speed to observe behavior
- Check for NaN values in calculations
pnpm --filter @evo/web build
node tools/check-pages-artifact.mjs apps/web/dist
# Output in apps/web/dist; pushed to main, it is deployed by .github/workflows/deploy-web.ymlThe desktop installers are still built from the archived prototype. Run these from legacy/prototype:
# All platforms
npm run build
# Specific platform
npm run build:win
npm run build:mac
npm run build:linux
# Output in ./release/The Quality workflow (.github/workflows/quality.yml) starts with a Changed paths job that reads the files a pull request touches (tools/ci-scope.mjs, with its own tests) and decides what the slow jobs need:
| Change touches | Runs |
|---|---|
only docs/ or Markdown |
format, lint, typecheck, the package tests and the build; not the simulation suites |
the interface (packages/ui, packages/renderer, apps/web) |
the above plus the Pages artifact; not the simulation suites |
packages/simulation, config or contracts, the lockfile, tools/, root config or the workflows |
everything: the simulation unit tests in three shards and the determinism suite in three shards on Ubuntu and Windows |
anything it cannot read (a push to main, a failed diff) |
everything |
A skipped job is a passing check. The Unit and integration tests check is an aggregate of the test jobs, so it keeps the name it always had and fails if anything that had to run failed.
The determinism suite is cut into files of at most about two minutes each (a file runs its tests one after another, so a long file is what limits a shard) and the workflow names the files of each shard. tools/determinism-shards.test.mjs fails if a test file is in no shard or in two, so a new file has to be added to the workflow. Tests that would build an identical world share it, and "one tick at a time" runs are compared with a run() world at the same tick over a shorter stretch than the full run; every assertion is kept. Locally pnpm test:determinism still runs every file, in parallel across your cores.
Tuning food, births and deaths is done from measurements. packages/simulation/tests/probe/presets.probe.ts runs each preset over several seeds and writes a table and a JSON file with, per preset: worlds that went extinct, population mean and range, the share of deaths that were starvation (against age and damage), the food stock against its cap, the share of food energy wasted (eaten beyond an organism's capacity), and, in cluster worlds, how many clusters ended empty.
# one preset per process uses several cores; settings are environment variables
PROBE_PRESETS=balanced,lush PROBE_SEEDS=8 PROBE_TICKS=20000 PROBE_OUT=/tmp/probe \
pnpm --filter @evo/simulation probe
cat /tmp/probe.mdThe probe steps tick by tick and also reports how creatures die: deaths by cause and life stage (juvenile is younger than organisms.maturityAge), the median age at death, births per mature creature per second (compare with 1 / cooldown, the most one can do), and the evolved cooldown, minEnergy, offspringInvestment and maxAge among the living, sampled every 2,500 ticks, so a tuning that evolution would undo shows up as drift. It also reports ticks per second.
Use at least 20,000 ticks: a creature's lifespan is 6,000 ticks, so shorter runs report almost every death as starvation. The probe is never part of pnpm test, the determinism suite or CI.
Three smaller probes in packages/simulation/tests/probe/ answer one question each and are run directly (pnpm exec vitest run --config vitest.probe.config.ts tests/probe/<file> from packages/simulation; the probe script ignores a file argument and runs them all): step-profile.probe.ts (where a tick's time goes, per system), species.probe.ts (how many species a world ends with under a set of distance weights and thresholds), and parts.probe.ts (which of the 16 part types living bodies carry, with and without open type mutation). Each writes its report to <tmpdir>/evo-probe/.
- Questions: Open a GitHub Discussion
- Bugs: Open a GitHub Issue
- Features: Open a GitHub Issue with proposal
All contributions are subject to the MIT License. See LICENSE for details.
packages/simulation/tests/probe/food.probe.ts measures a food setup (ADR 0021): worlds that died out, population (mean and lowest), the starved share of deaths, births per creature-minute, food and plants on the field, how clumped the food is (coefficient of variation per 50 x 50 cell), the idle-spin and lost-spin shares (creatures that barely moved but turned a lot over 20 ticks, and the same with nothing to eat within sensing range), how many part types and part lists the living carried, and ticks per second. Name a preset with FOOD_PRESET=balanced, or pass JSON overrides in FOOD_CONFIG with a label in FOOD_NAME; FOOD_SEEDS (default 1 to 8) and FOOD_TICKS (default 30,000) set the size. One line is written to <tmpdir>/evo-probe/food-<name>.txt. Run it directly, since the package probe script ignores a file filter: pnpm exec vitest run --config vitest.probe.config.ts tests/probe/food.probe.ts from packages/simulation. starts.probe.ts does the same for the starting bodies of ADR 0020. predation.probe.ts (ADR 0023) reports, over seeds, whether carnivory arises (jaw bodies alive, seeds where a jaw ever lived), bites on creatures, kills, the predation share of deaths, carcasses left and eaten and the usual population and part columns; it also reports whether a jaw lineage is alive at the end (worlds and mean count) and writes one line per seed (base body, jaws at the end, population, bites, kills, species) to <tmpdir>/evo-probe/predation-seeds-<name>.txt. PRED_OFF=1 is the control, PRED_HUNTERS=1 starts every world as hunters (the mechanism, not the evolution), PRED_GROUPS takes the founder groups as JSON ([] for none; the default hunter group otherwise), PRED_CONFIG takes JSON overrides, PRED_SEEDS and PRED_TICKS set the size. evolution.probe.ts (ADR 0024) tabulates the observatory's indicators over seeds for one setup, first half of the run against the second (EVO_NAME, EVO_PRESET, EVO_CONFIG JSON, EVO_SEEDS, EVO_TICKS); evo-sim --observatory --seed N --ticks N --preset NAME prints one world's series as CSV. longrun.probe.ts (ADR 0023 step three) is the long view that a 30,000-tick probe cannot give: per seed, every 10,000 ticks, the population, the mouth forms alive, predation against starvation deaths in the window and where the energy came from (LONG_SEEDS, default the owner's seed then 1 to 7; LONG_TICKS, default 100,000; LONG_CONFIG JSON). obstacles.probe.ts (ADR 0022) has the same columns plus the number of obstacle circles, the share of the field they cover and the pinned share (creatures held within a body-length of a rock's edge for a whole 20-tick window while barely moving); it takes OBS_NAME, OBS_CONFIG, OBS_PRESET, OBS_SEEDS and OBS_TICKS like the food probe, and OBS_OFF=1 switches obstacles off for the control run.