On this page
NL API User Manual
First edition: aligned patch and agent models
Build, understand, and extend NuWebKit simulations with JavaScript. This guide is written for model authors familiar with ideas such as NetLogo patches and turtles. Basic JavaScript helps; inheritance, callbacks, Stores, and runtime protocols are introduced where needed.
All teaching examples assume top-level lifecycle: "aligned" in Project.
The runtime still defaults to legacy behavior when this flag is absent.
For an existing model, read compatibility before changing
its lifecycle. This guide's publication does not migrate templates or apps.
Start here
- Fire: your first patch model. Write Project, Patch, and Main, run a small cellular automaton, and compare its results with a known case.
- Walkers: moving turtles. Add agents, live controls, movement, turning, a chart, and repeatable reset checks.
- Grazers: agents and their environment. Combine regrowing food, turtle energy, ordered resource claims, and budget checks.
Each tutorial includes complete model definitions and expected observations. Follow them in order, or consult the task-oriented chapters below.
Programming guide
| Chapter | What you will learn |
|---|---|
| Execution and lifecycle | Constructor, init, local reset, setup, visit order, commitment, and world Reset; legacy background is explicitly separated |
| Managing model state | Current/next/initial values, public built-ins, custom Stores, reset ownership, and one-time registrations |
| Programming Main | Shared decisions, population creation, patch activation, parameters, displays, logging, and stopping |
| Programming patches | Environmental rules, color, neighborhoods, occupancy, and a complete conservative Heat model |
| Programming turtles | Movement and heading timing, sensing, appearance, custom state, birth/death timing, and a checked obstacle example |
| Neighborhoods and local queries | Square/hex rings and blocks, boundary policies, unique residents, and radius queries |
| Tools and shared utilities | Named states, collections, sampling, summaries, random draws, and reproducibility limits |
| Checking and troubleshooting | Small verification routines, first-failing-stage diagnosis, reset errors, and common symptoms |
API reference
Use the alphabetical index when you know a name but not its owner. Static utilities are class calls, not methods on this.
| Reference | Contents |
|---|---|
| Project configuration | Geometry, defaults/starts, inputs, outputs, time units, and live change versus Reset/relaunch |
| NLSimMain | World operations, lifecycle hooks, scheduling, populations, custom state, and output |
| NLPatch and HexPatch | Color state, coordinates, neighborhoods, occupancy, notifications, and hex overrides |
| NLTurtle | State, motion, velocity, sensing, queries, visibility, serialization, and listeners |
| NLRoot and APIRoot utilities | Inherited context, collection adapters, extrema, sampling, statistics, geometry, and random helpers |
| Supporting types | Store, Property, coordinates, collection shapes, callback arguments, enums, and runtime choices |
Internal and defective legacy members are classified rather than endorsed. Inventory coverage is not a promise that every helper accepts arbitrary input.
Worked models and recipes
| Modeling task | Worked material |
|---|---|
| A synchronous patch cellular automaton | Fire |
| Moving agents, live speed/turn controls, and a population chart | Walkers |
| Synchronous environmental spreading and conservation | Heat |
| Regrowing resources, bounded claims, turtle energy, and multiple chart series | Grazers |
| Environmental sensing that changes motion | Obstacle example |
| Custom state and explicit reset | State examples |
| Population creation/removal and birth timing | Turtle chapter fragments and Main birth contracts |
| Output series and a text logger | Main recipes and output/log contracts |
Complete tutorials and worked models include their configuration and checks. Method-body fragments and API examples are deliberately smaller; they are not advertised as standalone applications.
Quick lookup
- Quick reference, glossary, and NetLogo bridge.
- Alphabetical method and property index.
- Compatibility, known limitations, and safer alternatives.
- Callback signature lookup.
- Live change, Reset, or relaunch?.
Scope of the first edition
The first edition covers the aligned patch-and-agent modeling path, its four principal classes, supporting types, Project settings, and inherited utilities. The three tutorials, Heat model, practical chapters, class references, lookup index, and compatibility appendix form the completed core.
A larger cookbook with standalone infection/recovery, probabilistic agent state-machine, and parent/offspring models is not part of this edition. The relevant operations are explained, but there is no claim that each has a complete independent tutorial. These are possible future additions, not missing chapters required to use this guide.
System-dynamics modeling with Stocks, flows, and integration is the subject of the separate SD API User Manual; each manual's page header links to the other. Collision internals and every internal runtime manager remain outside this manual's main scope. Remaining app migrations are deferred, not publication work. Known runtime limitations are documented in compatibility, not hidden by this edition.
Verification and maintenance
The guide tests execute actual Markdown model sources and selected fragments, check published results and reset contracts, inventory declarations, and validate index coverage and links. Related suites check lifecycle, legacy compatibility, neighborhoods, and utility edge cases. See the verification command and limits. Headless results do not certify every external model or browser launch flow.
For historical evidence and previously migrated apps, see the development and migration record. It is maintainer material, not part of the suggested reading path. For static-site build, preview, and publication instructions, see Publishing this guide.