Documentation
MathPets language
MathPets is a small language for agent-based models. A model file declares what the world contains and what each agent stores, then gives the rules that run at setup and on every tick.
A MathPets file is a set of declarations followed by a setup section, one or more step sections, and an optional stop condition. The compiler turns it into JavaScript that runs in the browser or headless. You edit and share the source file, never the generated code.
Read Essentials first. Patches, Pets, and Graph each cover one kind of agent and can be read in any order, though Graph assumes you know how pets work.
world: x: -25..25 y: -18..18 topology: box params: density: number = slider(62, 0..100) patches: state: empty | tree | burning | burned = empty setup: patches: state := if (random-float(100) < density) then tree else empty where (tree and px = min-x): state := burning step staged: patches: where burning: state := burned where (tree and any neighbors4 where burning): state := burning stop when (count patches where burning = 0)Orientation
Core, advanced, and host-specific
The grammar covers more than most models need. The core, the first group below, is enough for the whole course and most of the model library. The advanced group handles cases the core can't express. The host-specific group exists for products that embed the engine outside the Studio, and the Studio doesn't expose it.
core world · params · monitors · patches · pets · links setup · step · step staged · stop when — everything the course and most library models use advanced zones · brush · teams · walls multi-step pipelines · defs-heavy models — reach for these when a model outgrows the core host-specific rounds · players · external decide — kept in the language for embedding hosts; not surfaced in StudioIf you are learning, you can skip the Zones and Walls sections of the Patches chapter on a first pass. Among library models, only Hierarchical Cellular Automaton uses zones; Maze and Ant Transport use walls, and they and Slime define a brush.
Optional capabilities
Import a library
List libraries under imports:, then call their commands with the library prefix. The six libraries (sound, mechanics, genome, gp, physics, and x) are documented in the Libraries section.
imports: sound setup: sound.load(clap) step: sound.playDelayed(100 ms)Task index
Common modeling tasks
Each entry names a modeling task, the chapter section that covers it, and library models that use it.
Diffusion and evaporation — taught in Patches · Diffusion; worked examples: Ants and Slime.
Spread on a network (contagion and diffusion) — taught in Graph · From a pet; worked examples: Virus on a Network and Diffusion on a Directed Network.
Flocking and local steering — taught in Pets · Movement; worked example: Flocking.
Energy, birth, and death — taught in Pets · Lifecycle commands; worked examples: Wolf Sheep Predation and Sugarscape (metabolism and death, no births).
Staged cellular automata — taught in Essentials · Staged vs serial steps; worked examples: Life and Fire.
Params and monitors — taught in Essentials · Params and controls and Memory and monitors; Fire is the smallest model that uses both.
Chapter 1
Essentials
How a model file is laid out: declaration sections, types, expressions, control flow, defs, and the lifecycle. Read this first; the other chapters assume it.
Open chapter →Chapter 2
Patches
The grid agents: world bounds, edge topology, patch fields, neighborhood reporters, diffusion, walls, and zones.
Open chapter →Chapter 3
Pets
Moving agents grouped by breed: continuous coordinates, the patch under the pet, movement and sensing, breed queries, actions, birth and death.
Open chapter →Chapter 4
Graph
Links between pets, which are agents with fields of their own: directed and undirected breeds, random graph construction, weighted force layout, and queries from either end.
Open chapter →Sources of truth
The language is defined by its spec, docs/pets-language-spec.md in the public core repository. These chapters are derived from it; where they disagree, the spec wins. Design history (why a feature looks the way it does, and which alternatives were rejected) is in the decision records next to the spec.