Package-level declarations
Types
The minimal contract a Statechart needs from its owner. Both AgentModel.Agent and AgentResource implement this interface, so a statechart can govern either kind of actor without the statechart runtime having to know which it is.
Base type for messages exchanged between agents.
Container for an agent-based modeling layer that runs alongside KSL's process view. Following the precedent of ksl.modeling.entity.TaskProcessingSystem, an AgentModel ships two kinds of agent — transient and permanent — plus the supporting machinery (a shared message bus, inner-class Statechart and AgentMailbox) that lets both kinds work uniformly.
A resource that is also an agent. Behaves like an ordinary ResourceWithQ from the seizing entity's perspective — entities pass it to seize / release from inside a process — and on top of that exposes the agent capabilities the user might want for a forklift, repair worker, or nurse:
A broadcast trigger that statecharts can listen for. Unlike AgentMessage (point-to-point) and onCondition (a predicate tested in the C-phase), a signal is an explicit notification fired by user code — typically at the end of a transition, a phase change, or an externally-driven schedule event.
A discrete cell in a GridProjection addressed by integer column / row coordinates.
A 3D Euclidean projection — the volumetric analog of ContinuousProjection. Each agent in the context has an optional Point3D position; positions are set explicitly via placeAt / moveTo from user code.
Result of a successful Contract-Net negotiation. Contains the agent that won the contract and the proposal they submitted, so the caller can read the bid details (e.g., quoted completion time, price).
Continuous-time dynamics primitive for agents on a ContinuousProjection. Owns the per-agent velocity state and the list of Forces contributing to motion; the step method performs the Euler integration step (sum forces → integrate velocity → compute candidate position) without applying it. Applying the new state — including boundary handling — is the caller's responsibility, because boundary policy varies between models (toroidal wrap for boids, walled rejection for pedestrians).
3D analog of Dynamics. Continuous-time dynamics primitive for agents on a ContinuousVolume; owns the per-agent 3D velocity state and the list of Force3Ds contributing to motion. The step method performs the Euler integration step (sum forces → integrate velocity → compute candidate position) without applying it; the caller decides what to do with the candidate (wrap onto a 3D torus, reject if it enters a no-fly zone, clamp altitude to ground/ceiling, accept as-is).
A directed edge in a NetworkProjection, with an optional weight. For undirected networks each "logical" edge is stored as a single Edge instance with the canonical ordering chosen by the user (the projection emits each undirected edge exactly once from NetworkProjection.edges).
A precomputed distance-from-sources field over a VoxelGraph, exposed at point-level granularity for continuous-space 3D agents (drones, UAVs, AUVs). The 3D analog of FlowField.
A 2D-lattice graph: cells are first-class nodes, edges represent allowed movement between adjacent cells, and cells carry movement costs and blocked / passable status. Separate from GridProjection, which places agents on a lattice but doesn't model the lattice's navigation structure.
Pre-built heuristic functions for A* pathfinding on a GridGraph. All are admissible on uniform-cost grids (cell costs all ≥ 1.0) under the appropriate movement rule:
Choice of distance metric for GridProjection neighborhood and spatial-query operations.
Occupancy rule for a GridProjection; see that class for details.
A 2D lattice projection: each agent in the context occupies an integer-coordinate Cell. The grid has fixed columns and rows; cells are addressed by (col, row) with col ∈ [0, columns) and row ∈ [0, rows).
An AgentResource whose position is tracked in a ContinuousProjection. Composes the agent-resource semantics (seizable, queueable, on-shift / off-shift, statechart, mailbox, optional AgentPerformance stats) with continuous-space position tracking. Spatial queries on the projection (space.within(p, r), space.neighborsOf(...)) automatically see this resource at its current position.
Movement rule for a GridGraph. Selects the allowed neighbors of each cell:
A graph-based projection: agents are nodes, edges are typed relationships between pairs of agents. The third projection type in the agent layer's spatial abstraction (alongside ContinuousProjection and GridProjection).
A composable view over a group of agents.
A relational or positional structure layered over an AgentModel.Context. Borrowed from Repast Simphony's terminology: a context owns membership (who is in this collection), while projections add structure (where each member is, who's related to whom). A single context can have multiple projections layered on top — an agent can simultaneously have a 2D position and membership in a network without those abstractions interfering.
Adapter that exposes an agent-layer ContinuousProjection as a spatial-layer SpatialModel. This is the bridge that lets entity-layer code requiring a LocationIfc (notably MovableResource and the KSLProcess.move() family) operate in the same coordinate space as agent-layer code.
Runtime context passed to every statechart action block. Exposes the owning agent so handlers can read or mutate agent state, and provides transitionTo to schedule a transition to another state.
Builder for an individual StatechartState. Triggers and lifecycle hooks are configured by calling onEntry, onExit, onMessage, onTimeout, onCondition, or onSignal inside the state { } block. Composite states declare substates by nesting more state(...) { ... } calls inside the block and naming one via initial.
Top-level builder for AgentModel.Statechart. Constructed via the statechart { } method on an AgentLike owner; users do not instantiate this class directly.
Marker for DSL scope safety on the statechart builders. Prevents an inner state { } block from accidentally calling builder methods of an enclosing statechart builder.
A configured state within a statechart. Created by the StatechartBuilder DSL; users do not instantiate this class directly. The actual statechart runtime that consumes these is AgentModel.Statechart.
Namespace holding mutable, globally-overridable defaults for the agent-layer travel primitives (travelTo, travelThrough).
Mutable handle representing an in-progress interruptible travel in 2D. Returned by startTravel; consumed by awaitTravel. The integration loop inside awaitTravel reads this handle on every step, so external entities (dispatchers, statecharts, other agents) can interrupt or redirect by calling cancel / redirect from their own coroutine context.
Mutable handle representing an in-progress interruptible 3D travel. The 3D analog of TravelHandle. Same semantics: returned by startTravel3D; consumed by awaitTravel3D; cancellable / redirectable from any coroutine with a reference to the handle.
Outcome of a travelTo call. Exposed so callers can inspect what just happened — duration, distance, and the start/arrival times — without computing them externally.
A discrete 3D cell in a VoxelProjection / VoxelGraph, addressed by integer column / row / layer coordinates. The 3D analog of Cell.
A 3D-lattice graph: voxels are first-class nodes, edges represent allowed movement between adjacent voxels, and voxels carry movement costs and blocked / passable status. The 3D analog of GridGraph. Separate from VoxelProjection, which places agents on a lattice but doesn't model the lattice's navigation structure.
Pre-built heuristic functions for A* pathfinding on a VoxelGraph. All are admissible on uniform-cost grids (voxel costs all ≥ 1.0) under the appropriate movement rule:
Choice of distance metric for VoxelProjection neighborhood and volumetric-query operations. The 3D analog of GridMetric.
Movement rule for a VoxelGraph. Selects the allowed neighbors of each voxel:
Occupancy rule for a VoxelProjection; see that class for details.
A 3D lattice projection: each agent in the context occupies an integer-coordinate Voxel. The grid has fixed columns, rows, and layers; voxels are addressed by (col, row, layer) with col ∈ [0, columns), row ∈ [0, rows), layer ∈ [0, layers). The 3D analog of GridProjection.
Result of a weighted shortest-path query on a NetworkProjection. nodes lists the path including both endpoints (single-element list for a self-path); totalWeight is the sum of edge weights along the path.
Functions
Construct a ProjectionSpatialModel over this projection. Each call creates a new spatial model; locations created by one spatial model are not valid in another. Store the result and reuse it across all MovableResource / move / transport calls that need to share coordinates with this projection.
Drive the integration loop for handle to completion (or cancellation). Suspends. Returns the final TravelResult.
Drive the 3D integration loop for handle to completion or cancellation. Suspends. Returns the final TravelResult.
Reynolds-rule cohesion: steer toward the average position of neighbors within radius. Computed as the average of torus- aware deltas (via ContinuousProjection.delta) so it works correctly across wrap boundaries — averaging absolute positions would break for a peer just over the wrap.
Reynolds-rule cohesion in 3D: steer toward the average position of neighbors within radius. Computed as the average of torus-aware deltas via ContinuousVolume.delta so it works correctly across 3D wrap boundaries.
Run a Contract-Net Protocol negotiation from inside the calling agent's process. The calling agent (the initiator) sends a AgentMessage.Request with payload callForProposals to every agent in bidders, waits for deadline simulated time units, then collects the AgentMessage.Propose messages that arrived with the matching conversation id. The selectBest function picks the winning proposal (default: first received).
Helbing-style desired-velocity relaxation force in 3D: F = mass * (v_desired - v_current) / tau. Pulls the agent's velocity toward direction * speed over a timescale of tau.
Strict lower bound: value must be >minimum.
Closed range: value must be in range.
Generate a process-global, JVM-unique conversation id. Exposed for callers that want to construct messages with a pre-allocated id (rare). Note: contractNet does not use this — it draws from a per-model counter reset each replication, so its ids are reproducible run-to-run and isolated between models. If you mix manual ids with contractNet on the same mailboxes, pass a distinct prefix here to avoid any overlap with the default "cnp" namespace.
Non-negativity: value must be >= 0.0.
Non-negativity: value must be >= 0.
Peer-peer repulsion. For each neighbor inside radius (excluding self), apply a force along the direction away from the neighbor with magnitude given by falloff of the inter-agent distance. Distances are clamped at minDistance to keep falloff finite at contact.
3D peer-peer repulsion. For each neighbor inside radius (excluding self), apply a force along the direction away from the neighbor with magnitude given by falloff of the inter- agent distance. Distances are clamped at minDistance to keep falloff finite at contact. Uses ContinuousVolume.delta for the inter-agent direction so torus-wrapped 3D worlds compute the correct shortest-way vector.
Strict positivity: value must be > 0.0. Throws on construction or assignment otherwise. Pass name to have construction-time errors (where the property name is not yet known) name the field.
Strict positivity: value must be > 0. Throws on construction or assignment otherwise.
Probability: value must be in 0.0, 1.0.
Drive a whole population under dynamics from a single controller process using a Jacobi (synchronous, order-independent) update — the batched, 3D analog of runDynamics3D. Each tick computes every agent's step from the shared current state via Dynamics3D.stepAll, applies them all, then delays dt.
Drive a whole population under dynamics from a single controller process using a Jacobi (synchronous, order-independent) update. Each tick computes every agent's step from the shared current state via Dynamics.stepAll, then applies them all, then delays dt. This is the batched analog of runDynamics and avoids the order-of-update bias you get when each agent runs its own runDynamics loop.
Reynolds-rule separation: peer-peer repulsion with inverse- distance falloff over radius. Convenience wrapper around peerRepulsion; equivalent to peerRepulsion(radius, minDistance) { d -> 1.0 / d }.
Reynolds-rule separation in 3D: peer-peer repulsion with inverse-distance falloff over radius. Convenience wrapper around peerRepulsion3D.
Start an interruptible 2D travel. Returns the TravelHandle immediately without suspending — the caller must then either call awaitTravel to drive the integration to completion, or hand the handle to another entity (statechart, dispatcher, controller) that will manage the integration.
Start an interruptible 3D travel. Returns the TravelHandle3D immediately without suspending. Caller drives the integration via awaitTravel3D.
Extract 2D Cartesian coordinates from any LocationIfc that has them. Returns null for locations whose underlying spatial model does not have a 2D Cartesian representation (DistancesModel.Location — just a name; GreatCircleBasedSpatialModel.GPSCoordinate — spherical geometry, not directly Cartesian).
Travel a sequence of waypoints in 3D order. Equivalent to a chain of travelTo3D calls, returning the cumulative result. The agent starts from its current position and visits each waypoint in order; the last waypoint is the final destination.
Move agent from its current position in space to destination at constant velocity. The traversal takes distance / velocity simulated time units; the projection is updated to interpolated intermediate positions every stepSize coordinate-units of travel so concurrent spatial queries (space.within(...), space.neighborsOf(...)) reflect the moving agent's current position at step granularity.
Move agent from its current 3D position in space to destination at constant velocity. The 3D analog of travelTo.
Exponential repulsion from blocked cells (walls) in a GridGraph. Walls are treated as solid cell-sized bounding boxes: the force per cell uses the closest point on that cell's box to the agent's position. Scans a square of cells of radius ceil(scanRadius/cellSize) around the agent's current cell; cells outside that scan don't contribute.
Exponential repulsion from blocked voxels (walls / obstacles / no-fly zones) in a VoxelGraph. Voxels are treated as solid 3D bounding boxes: the force per voxel uses the closest point on that voxel's box to the agent's 3D position. Scans a cube of voxels of half-side ceil(scanRadius/cellSize) around the agent's current voxel.