Stigmery / Docs / Core concepts

Core concepts

A Stigmery model has four moving parts.

World

A grid of square cells called patches. You choose the width, height, and how big each patch renders. Edges can either wrap (a torus) or act as hard walls.

Patches

The cells underneath everything. They can hold properties - for example grass (a number) or burning (a boolean) - and can run their own rules each tick. Most simple models barely touch patches; ecological and spatial models lean on them heavily.

Agents

The mobile entities walking around on top of the patches. Every agent belongs to an agent type (e.g. sheep, wolf, boid) and carries:

• a position (x, y) on the world,
• a heading (degrees, 0 = east),
• a unique id,
• whatever properties you declare on its type - energy, age,

whatever you need.

Appearance

Every agent type has an appearance:

shape:  'circle' | 'triangle' | 'square' | 'arrow'
color:  a CSS color or an expression that returns one
size:   a number or an expression

color and size are evaluated per agent, per frame, so you can make appearance react to state. Wolves-and-Sheep uses literal strings (in quotes) so the DSL doesn't treat them as identifiers:

color: "'red'"
color: "energy > 5 ? 'green' : 'pink'"
size:  "1 + energy / 50"

Patches have an appearance.color expression too - the wolves-and- sheep model paints empty patches brown and grass-covered patches green with a single rule:

color: "grass > 0 ? 'green' : 'brown'"

Rules

The verbs of the model. A rule has a name, a when condition, and a do action. Rules live in one of four scopes:

• setup_rules - run once when the user clicks Setup. This is where

you create initial agents.

• go_rules - run once per tick, with no specific agent context. Useful

for global bookkeeping.

• agent_type.rules - run for every agent of that type, every tick.

This is where most behaviour lives.

• patches.rules - run for every patch, every tick.

Each tick is just: evaluate go_rules, then every patches.rules for every patch, then every agent_type.rules for every agent. Order within a scope is the order you wrote them in.