01Overview
An interactive agent-based simulation of a small ecosystem, originally built as part of the SURE (Sheffield Undergraduate Research Experience) scheme at the University of Sheffield.
Live demo: enable GitHub Pages for this repo (Settings → Pages → deploy from main, root) and open the published URL.
It also runs locally: open index.html in a browser (the bundled-sample batch button needs a local server, e.g. python3 -m http.server).
02Why predator–prey?
Predator–prey systems are a classic example in complex-systems research. They can be modelled with equations (e.g. Lotka–Volterra) or, as here, with an agent-based model where every individual makes its own decisions and the population-level dynamics emerge from those local interactions.
03The model
Four kinds of agents move around a bounded 2D arena:
| Species | Eats | Flees from | Notes |
|---|---|---|---|
| Food (green) | – | – | Static. Spawns randomly over time. Dead predators/humans often leave food behind. |
| Prey (blue) | food | predators, humans | Reproduces every time it eats. Slow but numerous. |
| Predators (red) | prey | other predators | Fast. Stops to attack; each bite succeeds 20% of the time; 20% of kills produce offspring. |
| Humans (purple) | food, prey | predators | Omnivores, slower than predators; same attack/reproduction odds. |
Every tick (60 per simulated second) each agent:
- looks at everything within its perception radius;
- accelerates towards what it wants to eat and away from what it fears (weighted by chase/avoid priority), or wanders randomly if nothing relevant is visible;
- loses 1 unit of nutrition and dies at 0;
- eats anything edible it is touching, regaining nutrition.
Population counts are recorded every tick, which gives the time series plotted under the arena.
Species parameters (speed, perception, nutrition, …) are in js/sim.js under SPECIES.
04Using the web page
- Set the starting populations and run settings (duration, food spawn rate, random seed, population cap).
- Press Run. Use the speed slider to fast-forward, Pause to inspect.
- Press Download CSV to save the run (
tick, time_s, food, prey, pred, human, total). Nothing downloads automatically.
The same seed and settings always produce the same run.
Batch mode (Latin hypercube sampling)
Under Batch run, upload a CSV with columns food,prey,pred,human (one row per run; header optional) or run the bundled
sample data/lhs_input.csv. Each row is simulated headlessly using the other settings from the form, and
all runs are combined into a single downloadable CSV with a run column and the initial populations. This is how the original project
explored the parameter space of starting populations.
05Project layout
index.html page + controls
style.css styling
js/sim.js simulation engine (no DOM; also usable from Node: require('./js/sim.js'))
js/app.js UI, canvas rendering, live chart, CSV export, batch runner
data/ sample Latin hypercube design
06Changes from the original (Processing/p5.js) version
- Removed the p5.js dependency; the simulation is now plain JavaScript and can run headless (a 30 s run takes about 0.2 s in Node).
- No automatic CSV downloads; the simulation starts only when asked and is fully parameterisable.
- Fixed bugs: predator/prey counts were swapped in the batch presets, food/human histories were recorded from the wrong arrays, history was never reset between runs, and predator corpses spawned food with probability 1/3 instead of the intended 2/3.
- Added seeded randomness, a population cap, a live chart, and a combined batch output.