A step-by-step series for the Taos Engine agents module — GPU agent-based modeling (NetLogo / AgentScript-style turtles + patches + links) built on top of the particle system. Each tutorial is short, runnable, and builds on the one before it.
These tutorials are written for someone who already knows AgentScript (or
NetLogo): each one maps the concept you know onto the Taos Engine way of doing it. The
big shift is that Taos Engine is declarative and GPU-parallel — you don't write an
imperative turtles.ask(t => …) callback that runs on the CPU each tick; you
declare a per-agent step program once and it compiles to a compute shader that
runs for the whole population in parallel. That trades arbitrary-JS-per-turtle
flexibility for ~1000× the agent count at interactive frame rates.
These tutorials are the guided path; the Agents module guide
is the reference. Read the Quick-Start Guide first if you've
never touched the engine — everything here assumes you know Engine, GameObject,
and Camera from "Hello, Cube".
Runnable code. Every tutorial below has a working, build-verified entry in the standalone project
standalone/agent_tutorials/— one page per tutorial, plus a ▶ live launcher.cd standalone/agent_tutorials && npm install && npm run dev, then open the launcher. Each tutorial is a single self-contained file: it runs its model throughrunAgentModel— the engine's one-call agent harness (taos/agents/agent_app.js, which wires the engine, camera, render stack, and frame loop) — so the file spends its lines on the model. Each tutorial page also has a "▶ Live demo" link at the top.
The path#
| # | Tutorial | You'll learn | AgentScript analog |
|---|---|---|---|
| 1 | Hello, Agents | A complete app: turtles wandering on a torus, rendered as arrows. | the "hello world" snippet |
| 2 | Turtle Verbs & the Step Program | forward/turn/face/towards/distance, edge topologies, and how the GPU step replaces ask. | Turtle methods + Snippets |
| 3 | Patches & Stigmergy | The diffusing/evaporating grid: sense, deposit, diffuse, importDataSet — the slime-mold model. | Patches + Diffuse / SlimeMold |
| 4 | Neighbors & Flocking | The spatial hash + in-radius queries; a flock hand-written from neighborCenter + neighborSeparation. | inRadius / Flocking |
| 5 | State & Breeds | Per-agent state in color.a, and N named breeds with their own behavior. | breeds |
| 6 | Births & Deaths | GPU reproduction (hatch/die) via a free-list — a Lotka-Volterra cycle. | hatch / die / Wolf-Sheep |
| 7 | Links | A force-directed graph: spring links untangle a community network. | links / Network |
| 8 | Measurement & Plots | Read agent / patch state back to the CPU; a live population plot. | model plots / exportDataSet |
| 9 | Defining Your Own Model | The AgentModelConfig spec end-to-end — build NetLogo "Termites" from scratch. | writing a new model |
Reference#
These aren't steps in the linear path — read them when relevant.
| # | Tutorial | You'll learn |
|---|---|---|
| 10 | Agents on the Globe | The AgentScript Leaflet/MapLibre equivalent — a herd walking real streamed terrain (keyless). |
| 11 | Runoff on Real Terrain | 3D agents governed by the terrain — gradient flow + a born→flow→die lifecycle: rain runs down a real watershed (keyless). |
Conventions in these tutorials#
- Imports use the
taos/<subdir>/index.jsform an external consumer writes (see the import conventions). Inside this repo, the same modules are relative paths (../src/agents/index.js); the in-repo samples undersamples/use the relative form. - The whole authoring surface is one import.
agent,buildAgentConfig,expr,action, and the config types all come fromtaos/agents/index.js. - Most things are keyless. Tutorials 1–9 are pure compute — no data, no account. Tutorials 11–12 stream keyless AWS Terrarium terrain + Esri imagery.
- Every tutorial cites the in-repo sample it's distilled from. When in doubt,
the sample under
samples/is the ground truth.