← Natura·Docs
Contents · Home

Natura -- a pocket-universe framework of composable natural systems

A framework for simulating any force of the natural world, at any scale, composed together or run alone -- "from the branching of rime on a leaf in a storm to the battle of two moose in a forest to the slow cooling of a sun over billions of years" (operator, 2026-08-02). The dynamic-simulation sibling to the static world(seed) spine; the Terrain Engine's composable-pipeline ethos generalized to all of nature across all scales.

The docs (read in this order)

The code (built + tested: 45 system modules, 60 test and probe files, 951 assertions -- the scale ladder from rime to a dying sun, up through mind + society + the human/made world, and the cryosphere's ice ages; this list highlights the core stack, see SYSTEMS.md for the full catalog incl. economy/technology/city/soil/epidemic/speculation/artifact/cryosphere)

The world model (zones in a hierarchy)

The map is one ZONE of a larger world -- zone < region < continent < world < universe. A zone is an OPEN window: life migrates out across the edges (emigrate) and in from the neighbouring zones (immHerb/ immPred), so the visible population is a metapopulation window, not a sealed island -- it is buffered by space + migration, adapts to the terrain, and may locally die out. (A self-contained small world can instead use torus wrap.) Oceans are the water cycle's moisture source, so a zone keeps its sea.

Quickstart (the functional API)

const { World, defineSystem, UNITS } = require('./natura.js');
const { makeWeather } = require('./weather.js');

// a world is a chosen STACK of systems; run one or many
const w = World({
  seed: 7,
  t0: 0,                                   // start time (seconds)
  systems: [ makeWeather({ N: 64, elevation: (x,y) => myTerrain.heightAt(x,y) }) ]
});
for (let i = 0; i < 100; i++) w.step(UNITS.HOUR);   // advance the clock + step every system
const rain = w.fields().weather.rain;               // read a system's exposed field
w.clock.season();                                    // 'autumn' -- one clock, every cadence

Defining a new system (the interface every system implements):

const mySystem = {
  name: 'vegetation', domain: 'life', scale: 'ecological',
  params: { /* preset defaults */ },
  init(rng, params, clock) { return { /* state */ }; },
  step(state, ctx, dt) { /* ctx.clock, ctx.fields.weather.moisture, ctx.rng */ return state; },
  fields(state) { return { biomass: state.biomass }; },   // exposed for coupling
  events(state) { return [ /* {kind,...} */ ]; }
};

Conventions (functional details, pinned here so they don't drift)

Status (1.0.0, 2026-09-27)

Released at https://neap.systems/natura/ under the BSD licence: the page (with a quickstart for a person and for an AI building a game), these docs as web pages with a generated module reference, every source file readable online and served raw at /natura/raw/<path>, and the source zip (publish/make_all.py builds all of it; the curated public list, and why each excluded file is excluded, are in publish/manifest.py). 45 modules build systems; 60 test and probe files run in node, 951 assertions, all passing (publish/run_tests.py). The scene pages built on Natura (the living-world art pieces) live in the gallery at garden.neap.art, not in the release. Open threads: wiring the deep-time systems into a multi-timescale view; deeper MIND and SOCIETY rungs (memory, culture, factions); weather's long-run cloud field.

On this site

About the names in code style. The docs name files as they are in the source. A name that is a link opens that file here: every module, test and bench page in the release can be read online, and all of them are in the source zip, natura-src-1.0.0.zip, on the Natura page. A name that is not a link is not part of this release: the scene pages the docs mention (weather-world.html and the others) and the working notes stay in the author's own copy. The design docs are the author's working docs, kept as they were written; their status notes carry their own dates, and the module reference below is generated from the code as released.

Start here

Design

Creatures

About