NLTurtle API reference

Manual contents | Programming turtles | Project settings | Neighborhood reference | Supporting types | Alphabetical index

Source: nlturtle.js. Inheritance: NLTurtle extends NLRoot extends APIRoot. The module exports NLTurtle and re-exports Shape and NLRoot.

This page inventories declared instance members and the static goDiscrete helper. Examples assume lifecycle: "aligned". For complete models use Walkers, Grazers, or the obstacle example. Internal/legacy entries are identified, not presented as supported shortcuts. Unless stated otherwise, mutating methods return undefined.

1. Subclass and lifecycle

import {NLTurtle} from "@nwk/api/nlturtle.js";

class StraightTurtle extends NLTurtle {
  setup() {
    this.currentSpeed = this.main.getParam("SPD");
  }

  turtleStep() {
    this.nextSpeed = this.main.getParam("SPD");
    super.turtleStep();
  }
}

export default StraightTurtle;

Use an aligned agent Project with an SPD input, trajectory movement, continuous motion, explicit boundaries, and a Main that creates patches and turtles. This turtle reads current speed at setup/reset and each tick. With no heading updater it keeps its supplied heading.

World Reset recreates turtles rather than calling reset on each old turtle. Custom local-reset policies and disposal of listeners on longer-lived owners are separate responsibilities.

2. State properties

For these built-ins, the plain property reads committed state and assignment initializes current/next and replaces its local reset baseline:

The corresponding pending properties are read/write: nextLocation, nextColor, nextSize, nextShape, nextSpeed, nextTheta. They propose for commitment without changing current values/baselines. There is no public nextRealLocation property.

The immediate-edit properties are setter only: currentLocation, currentColor, currentSize, currentShape, currentSpeed, currentTheta. They set current/next immediately but retain the baseline. Reading one does not read the committed state. Location-only assignments do not also update realLocation. Prefer initLocation for deliberate position initialization.

Broken legacy properties: nextX_val and nextY_val reference absent _x_val/_y_val Stores, not the allocated velocity Stores. Reading or assigning them throws unless a subclass separately defines those fields. They are not aliases for pending velocity; use setNextVelocity instead.

Context and geometry

getRadius(), getCenterX(), and getCenterY() are method equivalents of radius/center accessors. inBounds() tests the square-style range 0 <= x < cols, 0 <= y < rows. Duplicate source definitions are equivalent; this is not a hex-aware footprint or collision test. clipped() instead tests y >= rows - 1 (as well as other outside bounds), so it is not the negation of inBounds. rowClip(y) and colClip(x) clamp to [0, rows - 1] / [0, cols - 1], without flooring or hex conversion.

3. Movement and commitment

go's wrap uses (value + period) % period, not full modulo normalization for arbitrarily large negative offsets. Non-wrap clamps to min and max minus 0.000001; it does not itself implement reflection. Bounce/collision machinery is separate. These helpers do not validate arbitrary finite inputs. Do not use nonfinite headings in goDiscrete.

Movement occurs before the base step's thetaUpdater evaluation. Proposing nextTheta before the base call affects this move; doing it afterward affects the next move. Move proposals replace rather than accumulate: two fdNext calls start from the same committed location. Do not combine trajectory movement with another move unless intentionally replacing its proposal.

Legacy movement helpers

4. Heading and velocity

Typical turning:

this.nextTheta = this.right(90);

This is a method-body fragment, not a complete Turtle rule. Assigning speed or heading separately does not recalculate velocity components; use the joint helpers only when your model actually relies on those components. The base local-reset list excludes x_vel/y_vel even though they are synchronized. If individual reset needs them restored, define that policy explicitly.

5. Appearance, updaters, and visibility

Read/write thetaUpdater, colorUpdater, sizeUpdater, and shapeUpdater store zero-argument functions returning proposals. Assign once in init. Aligned super.turtleStep evaluates them after movement in that order. Set undefined to disable. Use arrows to retain Turtle this: ordinary callbacks are called as Store methods, not bound to the Turtle. Exceptions propagate.

setNextSize(val), setNextSpeed(val), setNextTheta(val), and setNextShape(val) are pending-property method aliases. setNextColor(val) is not always an alias: while hidden it only updates cacheColor, whereas nextColor assignment bypasses the hidden-color check.

Hiding does not remove a turtle from population, indexing, stepping, sensing, or resource use. It is not death. Direct nextColor writes or colorUpdater can replace sentinel and reveal it. Local reset does not separately reset cacheColor; do not treat visibility/cache as a synchronized ecological state. See appearance guidance.

6. Location and environmental sensing

patch_ahead is a destination-point sample, not a whole-path or turtle-radius collision check. Its preliminary wrap adjustment is single-period and square dimension based; do not infer general hex/path-normalization support. Use small checked square-world sensing steps as in the obstacle example. The final Main lookup can normalize farther square Wrap offsets, but does not repair the helper's hex geometry.

Directions and distances

These are not shortest wrapped direction/distance helpers. Main.turtlesInRadius accepts a coordinate point for a wrapped-distance query; filter out self explicitly when using it from a Turtle.

7. Local turtle queries

Require indexed committed occupancy and initialized populations. Results hide zombies/newbies and exclude this Turtle, independently of drawing visibility.

Duplicate patches/coordinates do not duplicate results or predicate calls. Include the current patch with block(1) if co-residents should be considered; blockX/ring excludes it. Optional predicates receive actual other Turtle objects, not distances or patches. Callback exceptions propagate.

Example method-body fragment:

const region = this.myPatch().block(1);
const others = this.nhoodPatches(region);
const count = this.nhoodCount(region);

See full local-query contracts.

8. Population and index operations

Birth operations live on Main. Constructor/defaults/init occur before customization; setup follows insertion. Membership, local-query visibility, and opportunity to step begin at different boundaries. Retain the base turtleShift for newborn visibility.

9. Notifications

Each initialization setter replaces a single callback f(value). Each change method appends f(store, oldValue, newValue), without deduplication or a Turtle removal method:

Initialization callbacks run on initialize/reinitialize, not ordinary immediate set/shift. Assign undefined to disable one. Change listeners run for those operations too, even equal-value shifts. Initialization reports a falsy old value as null under Store's existing fallback. Register once, not every setup. Exceptions can interrupt an operation after the value is already changed. Location already has the runtime's indexing listener; these append, rather than replace it.

The similarly named setXValInitListener(f), addXValChangeListener(f), setYValInitListener(f), and addYValChangeListener(f) are broken legacy methods referencing absent _x_val/_y_val, not the velocity Stores. Do not use.

10. Serialization and internals

Serialization reads committed state, does not commit/consume output, and does not include updater/listener/custom Store state.

Trails and legacy field sampling

willBounce can be supplied by collision machinery; it is not initialized here. Trails are not guaranteed continuous shortest seam paths. Do not repair these limitations by manually shifting private Stores. The checked obstacle and Grazers examples use explicit public queries instead.

11. Inherited utilities and verification

NLRoot supplies newCoords/path, collection operations and selection helpers; APIRoot supplies static random/math functions. See NLRoot reference and tools and utilities. Call static helpers on their class, not this.random(). Not every legacy inherited helper/collection shape is certified.

The guide tests inventory every NLTurtle prototype member plus static goDiscrete, execute this page's StraightTurtle and query/turn fragments, and check motion proposals, aliases, velocity/reset distinctions, visibility, serialization, and known defective entry points. Existing guide tests cover movement/updater ordering, indexed birth/death visibility, live inputs, wrapping, and repeated world reset. These are headless contract checks, not certification of every collision, hex movement, trail, or legacy sampler behavior.