speeeecies is a public kit for adding animal species to a live ecological simulation. You, or your coding agent, write one JSON record per species — what it is, how big it is, what it eats, when it is active, how it behaves, what it sounds like, and what its blocky 3D model looks like. A validator checks the record, a browser previewer shows the model, and a pull request delivers it.
Watch the simulation live: https://www.youtube.com/@jt55401/live Site (schema docs, behaviour guide, previewer, gallery): https://eeeearth.github.io/speeeecies/
Read AGENTS.md. It has the full step-by-step: pick an issue,
claim it, write the record, fetch activity data, validate, preview, open a
PR. To add a whole place (a locale: a public city or district and at least
8 of its species), see "Contribute a locale" in the same file.
Humans: read CONTRIBUTING.md instead — same flow,
shorter.
The open animal requests are the tasks contributors can claim after checking for an active ETA. We aim to keep 1,000 open requests at the start of the 10,000-species effort. The queue and replenishment rule explains when later batches are released. The reserve holds 9,000 unpublished discovery leads; each lead still needs screening before it becomes an issue.
To browse by animal group, search the issue bodies for birds, mammals, reptiles or amphibians.
The live simulation rotates
through places: a London garden now, and any city or district you add. A
locale is locales/<id>/locale.json: a public centroid (never an
address), its climate, a generic plot and at least 8 species (aim for 12
or more), plus locales/<id>/flora-catalog.json, the plants its garden
shows. See docs/locale-richness.md for why both matter. Browse
them on the locales page,
or pick an open
locale-request issue
(Berlin, Tokyo, Sydney, Cape Town, São Paulo and more) and follow
"Contribute a locale" in AGENTS.md.
United States, state by state. The rotation is working through every
US state in rural, coastal, suburban and urban settings, ordered so that
each new place adds an ecoregion or setting the stream has not shown.
The open US locale-request issues are the slots anyone can take, and
more are posted as those are claimed. The whole queue is in
docs/us-queue.md.
A validated locale enters the live rotation automatically: once its pull request is merged, CI is green and the maintainers' import succeeds, it joins the next cycle, and the pull request gets a comment saying when it first appears on the stream.
schema/v0.1/species.schema.json the species record (JSON Schema 2020-12)
schema/v0.1/behavior-program.schema.json behaviour programs (state machines and trees)
schema/v0.1/body-plans.json generated mesh parts and defaults per body plan
schema/v0.1/licenses.json licence tiers, scores, rejections
behaviors/<program-id>.json shared behaviour programs any species can use
species/<slug>/species.json one species record
species/<slug>/behavior.json optional: a program only this species uses
species/<slug>/ATTRIBUTION.md generated by tools/validate.py --write-attribution
schema/v0.1/locale.schema.json a locale manifest: a public place and its species
schema/v0.1/flora-catalog.schema.json a locale's flora catalog: the plants its garden shows
schema/v0.1/flora-taxa.json the plants the simulation can draw, for flora-catalog.json's taxon field
locales/<id>/locale.json one locale for the live simulation's rotation
locales/<id>/flora-catalog.json that locale's plant list (optional; the validator warns without it)
docs/locale-richness.md why sparse locales look empty, and targets for animals and plants
tools/ validator, activity fetcher, visual check, site builder (uv scripts)
tools/issues/ generator for the locale-request issues, and their bodies (out/)
site/ landing page, schema docs, gallery, previewer
| Tool | What it does |
|---|---|
uv run tools/validate.py [PATH ...] |
Checks species records and behaviour programs against the schema and licence policy. --report prints a Markdown report for a PR; --write-attribution writes species/<slug>/ATTRIBUTION.md; --strict turns warnings into errors. |
uv run tools/validate.py --locale <id> |
Checks a locale manifest and every species it lists (activity for the locale's region, behaviour, poses, licences, public-safety lint). --self-check scans the whole repo for addresses, home paths, hostnames and SSH remotes. |
uv run tools/fetch_activity.py <slug> --region <ISO> --write |
Builds a 12-month activity curve for a species in a region from iNaturalist and GBIF observations. |
uv run tools/visual_check.py <slug> --write |
Advisory: renders the model headless and scores it against its name with BioCLIP, on CPU. |
python3 tools/build_site.py |
Assembles the GitHub Pages site into _site/ (schema docs, gallery, previewer, combined attribution). |
Code (tools/, site/) is MIT. Species and behaviour data
(species/, behaviors/) is CC BY-SA 4.0, except data
drawn from non-commercial sources, which is marked and keeps its source
licence.
Format 0.1. Species records are animals only — plant species need a
data-driven preset format first and are tracked as a later milestone (see
ROADMAP.md). Issues labelled phase-2 are for plant species records
and are not open for work yet. A locale's flora-catalog.json is not a
plant species record; it can be contributed today (see "Locales" above).