Pets

A breed is a named class of moving agents. Declare it inside pets: using just its name. The explicit pet breed-name: form is also accepted when the declaration benefits from being spelled out.

A breed declaration is followed by an indented body of typed field declarations. Each individual pet of that breed carries those fields. A breed can also nest an actions: block of reusable mutating behavior (see the actions section below).

The breed name is itself a usable agentset. Anywhere an agentset is expected — counts, queries, updates — you can refer to ants or flockers by name.

Every pet carries four runtime fields the engine maintains: id (an integer index assigned at creation), x and y (continuous, real-valued position), and heading (degrees in [0, 360)). A boolean hidden field can be set to omit the pet from the rendered world without removing it from queries.

These names do not overlap with patch coordinates px and py; reading the wrong one inside a patch or pet update is a compile-time error.

patch is the canonical way to talk about the patch under the current pet.

Read with patch.field. Write a single field with patch.field := value, or write several with the block form patch := :followed by an indented field map. Topology is applied to the pet's continuous coordinates before the patch is resolved.

patchis a context-bound view, not a first-class value: you can't pass it to a function or store it in a let, only read its fields or assign to them. No breed, zone, or memory declaration may use the name patch.

create breed-name count makes new pets in setup or in a step. The new pets get consecutive integer ids and default field values. Their position is (0, 0) and their heading is 0 until you set them.

Position assignment happens in a follow-up breed update. set-random-position drops the pet on a random patch. set-position(x, y) places it at an explicit coordinate. The earlier set-random-position() paren form still parses; the no-paren form is the canonical shape, since actions have always used the bare-name form.

scatter spread drops the pet uniformly inside a square of side spread centered on its current position. scatter spread from agent centers the square on another agent, and scatter spread from x, y on a point — handy for spawning a colony around its home.

A breed update runs the indented body once per pet of that breed. Use breed-name: for every pet, or breed-name where (...): to filter. Inside the block, bare field names refer to the current pet; patch.field refers to the patch under it.

Nested where branches and match arms work the way they do in patch updates — they branch per current pet.

match is especially useful for state-machine pets. The inline form breed-name match expr: elides the wrapping update block when the body is only match arms — see the termites example.

forward(distance) moves the current pet forward along its heading. turn(degrees) rotates relative to the current heading — positive values turn left, negative right.

face(target) points the pet at a patch or another pet. face(target, percent) turns only partway, where percent is in [0, 100]. turn-towards(target, max) and turn-away(target, max) each limit the turn to max degrees, making smooth steering simple.

set-position(x, y) and move-to(target) are the teleport forms. Topology applies to every motion command: on a torus world a forward step crosses the seam cleanly; on a box world the position clamps to the edge.

A pet can read the patch grid relative to its own heading. patch-ahead(distance) gives the patch distance in front; patch-left-and-ahead(angle, distance) and patch-right-and-ahead(angle, distance) offset the look by angle degrees.

can-move(distance) is the boolean predicate: would a forward(distance)stay inside the world? On wrapped axes it's always true; on hard axes it's false near the edge.

follow-patch-gradient(field) samples a numeric patch field at three positions — ahead, ahead-left, ahead-right — turns toward the strongest uphill side, and wiggles when no side is stronger. It is the canonical primitive for chemotaxis, scent-following, and any "walk uphill" behavior.

Optional min and max bounds gate the current patch value before following: follow-patch-gradient(chemical, 0.05, 2) only follows when chemical is in [0.05, 2], and otherwise wiggles. This keeps ants from chasing infinitesimal traces or saturating on the strongest source.

breed-name in-radius r is the standard nearby-pet query. Inside a pet update, it returns the pets of that breed within r of the current pet — excluding the current pet itself.

nearest agentset picks the closest single agent. It accepts a where filter for conditional searches. pet-at(breed, x, y).field looks up one breed member by the patch at an explicit coordinate.

The same count, any, sum, mean, min, and maxaggregates from the patches chapter apply to breeds. Use them in monitors, in stop conditions, or to ask "how many of my breed are near me right now?".

one-of agentset picks a single random member, deterministic for the current seed and call site. Combine with other breed-name to exclude self: one-of other peopleis "a random other person".

distance-to(target) and towards(target) compute the topology-aware distance and heading to a patch or pet. The pair average-heading(query) and average-heading-towards(query) summarize a crowd: the first is the mean of their own headings, the second is the mean direction from self toward each of them.

any sheep here and count sheep here are the same-patch population checks — here filters a breed to the current patch and composes with the whole query surface. It is the natural primitive for predator/prey contact rules.

Actions are class-level mutating behavior — reusable blocks of commands and assignments. Two scopes: actions declared under pets: actions:are callable from every breed's update, while actions declared inside a breed block are only callable from that breed.

An action body looks exactly like an agent update body. It expands inline at the call site under the current pet, mutating its fields, its patch, and calling movement commands.

Actions may declare typed parameters (wiggle(spread: number):); arguments evaluate once in the caller's context. They have no return value — for pure value-producing calculations, use a def instead (see the Essentials chapter). The rule of thumb: defs produce values for expressions; actions execute behavior for the current pet.

hatch(breed)creates a child pet of the named breed at the current pet's position, copying fields where they match. die removes the current pet from the world (no parens — zero-argument commands are bare names, matching the action calling convention).

kill(ref) removes the referenced pet. Predation composes from the query surface: pick a victim with one-of sheep here, guard on the reference (killing nobody is a runtime error), then kill it. Wolf-Sheep Predation uses exactly this shape.

Four catalog models cover the breed surface, from pure motion to full lifecycle commands.