An agent's position in a projection changed. Emitted from the projection's placeAt/moveTo chokepoint, so it uniformly captures travel, steering dynamics, and manual moves (decision D6, Phase 3A.1).

AgentPositionSampled

@Serializable

@SerialName(value = "AgentPositionSampled")

data class AgentPositionSampled(val simTime: Double, val agentName: String, val projectionName: String, val x: Double, val y: Double, val z: Double = 0.0) : AnimationEvent

An agent's position as read by a timed sampler (the non-invasive position option, decision D6 option b, Phase 2A.4).

AgentRegistered

@Serializable

@SerialName(value = "AgentRegistered")

data class AgentRegistered(val simTime: Double, val agentName: String, val agentType: String) : AnimationEvent

An agent joined the model registry.

AgentRemoved

@Serializable

@SerialName(value = "AgentRemoved")

data class AgentRemoved(val simTime: Double, val agentName: String) : AnimationEvent

An agent left the model registry.

AgentStateEntered

@Serializable

@SerialName(value = "AgentStateEntered")

data class AgentStateEntered(val simTime: Double, val agentName: String, val stateName: String) : AnimationEvent

An agent's statechart entered a state.

AgentStateExited

@Serializable

@SerialName(value = "AgentStateExited")

data class AgentStateExited(val simTime: Double, val agentName: String, val stateName: String) : AnimationEvent

An agent's statechart exited a state.

AgentTransition

@Serializable

@SerialName(value = "AgentTransition")

data class AgentTransition(val simTime: Double, val agentName: String, val fromState: String, val toState: String) : AnimationEvent

An agent's statechart transitioned between two states.

AgentVectorSampled

@Serializable

@SerialName(value = "AgentVectorSampled")

data class AgentVectorSampled(val simTime: Double, val agentName: String, val projectionName: String, val vx: Double = Double.NaN, val vy: Double = Double.NaN, val fx: Double = Double.NaN, val fy: Double = Double.NaN) : AnimationEvent

A sampled per-agent velocity (vx,vy) and/or net steering force (fx,fy) for the vector overlay (G10). Rate-limited by the sampler's interval (default 5/sec), decoupled from the model's integration step. A NaN component means it wasn't captured. Opt-in (off by default) — the volume-sensitive overlay.

BatchFormed

@Serializable

@SerialName(value = "BatchFormed")

data class BatchFormed(val simTime: Double, val batchEntityId: Long, val batchName: String, val size: Int) : AnimationEvent

A batch of entities was formed into a single batch entity of size members.

Companion

object Companion

ConveyorAccessRequested

@Serializable

@SerialName(value = "ConveyorAccessRequested")

data class ConveyorAccessRequested(val simTime: Double, val entityId: Long, val conveyorName: String, val entryLocation: String) : AnimationEvent

An entity requested access to a conveyor at an entry location.

ConveyorDefined

@Serializable

@SerialName(value = "ConveyorDefined")

data class ConveyorDefined(val simTime: Double, val conveyorName: String, val anchorLocations: List<String>, val anchorCells: List<Int>) : AnimationEvent

The static cell structure of a conveyor (emitted once per replication, at the conveyor's initialize). anchorLocations and anchorCells are parallel lists giving each named entry/ exit location and its cell index along the belt, so a renderer can map any cell index to a world position by interpolating between the (layout-positioned) named anchors (8G.6).

ConveyorDestinationReached

@Serializable

@SerialName(value = "ConveyorDestinationReached")

data class ConveyorDestinationReached(val simTime: Double, val entityId: Long, val conveyorName: String, val location: String) : AnimationEvent

An entity reached its conveyor destination.

ConveyorEntryBlocked

@Serializable

@SerialName(value = "ConveyorEntryBlocked")

data class ConveyorEntryBlocked(val simTime: Double, val entityId: Long, val conveyorName: String, val entryLocation: String) : AnimationEvent

An entity's conveyor entry was blocked (could not board yet).

ConveyorExited

@Serializable

@SerialName(value = "ConveyorExited")

data class ConveyorExited(val simTime: Double, val entityId: Long, val conveyorName: String, val location: String) : AnimationEvent

An entity exited (fully off) a conveyor.

ConveyorItemMoved

@Serializable

@SerialName(value = "ConveyorItemMoved")

data class ConveyorItemMoved(val simTime: Double, val entityId: Long, val conveyorName: String, val cellIndex: Int) : AnimationEvent

A conveyed item advanced to cell cellIndex of its conveyor (the single ConveyorRequest.moveForwardOneCell chokepoint). The renderer maps the cell index to a world position via the conveyor's ConveyorDefined anchors and interpolates between consecutive samples — the conveyor analog of the agent position stream (8G.5). Captures accumulation and blocking for free: when an item cannot advance, no event fires and it holds on the belt.

ConveyorRideStarted

@Serializable

@SerialName(value = "ConveyorRideStarted")

data class ConveyorRideStarted(val simTime: Double, val entityId: Long, val conveyorName: String, val fromLocation: String, val toLocation: String) : AnimationEvent

An entity began riding a conveyor from one location toward another.

DelayEnded

@Serializable

@SerialName(value = "DelayEnded")

data class DelayEnded(val simTime: Double, val entityId: Long, val suspensionName: String? = null) : AnimationEvent

An entity's delay has ended.

DelayStarted

@Serializable

@SerialName(value = "DelayStarted")

data class DelayStarted(val simTime: Double, val entityId: Long, val duration: Double, val arrivalTime: Double, val suspensionName: String? = null) : AnimationEvent

An entity has started a timed delay. arrivalTime is the simulated time at which the delay will end (simTime + duration); carrying it lets the renderer drive a progress indicator without re-deriving it.

EnteredNetwork

@Serializable

@SerialName(value = "EnteredNetwork")

data class EnteredNetwork(val simTime: Double, val entityId: Long, val networkName: String, val ingressName: String, val qObjectType: Int = 1, val qObjectTypeName: String? = null) : AnimationEvent

An entity entered a station network through an ingress. qObjectType is the QObject's integer type id (1 by default; a QObjectClass.typeId in multi-class networks) and qObjectTypeName is the resolved class name when one is registered (else null), so a renderer can style station entities by class (8G.1).

EntityCreated

@Serializable

@SerialName(value = "EntityCreated")

data class EntityCreated(val simTime: Double, val entityId: Long, val entityType: String) : AnimationEvent

A new entity has been created. entityType is the entity's class/type label.

EntityDisposed

@Serializable

@SerialName(value = "EntityDisposed")

data class EntityDisposed(val simTime: Double, val entityId: Long) : AnimationEvent

An entity has been disposed normally (it finished its process).

EntityTerminated

@Serializable

@SerialName(value = "EntityTerminated")

data class EntityTerminated(val simTime: Double, val entityId: Long) : AnimationEvent

An entity's process ended abnormally (terminated/failed).

ExitedNetwork

@Serializable

@SerialName(value = "ExitedNetwork")

data class ExitedNetwork(val simTime: Double, val entityId: Long, val networkName: String, val egressName: String) : AnimationEvent

An entity left a station network through an egress (disposed).

ExperimentEnded

@Serializable

@SerialName(value = "ExperimentEnded")

data class ExperimentEnded(val simTime: Double, val experimentName: String) : AnimationEvent

The experiment has ended; no further events follow for this run.

ExperimentStarted

@Serializable

@SerialName(value = "ExperimentStarted")

data class ExperimentStarted(val simTime: Double, val experimentName: String, val numberOfReplications: Int) : AnimationEvent

The experiment (a set of replications) has begun.

FlowFieldDefined

@Serializable

@SerialName(value = "FlowFieldDefined")

data class FlowFieldDefined(val simTime: Double, val spaceName: String, val cols: Int, val rows: Int, val cellSize: Double, val originX: Double, val originY: Double, val cells: List<FlowCell> = emptyList(), val maxDistance: Double = 0.0) : AnimationEvent

A flow-field distance gradient over the grid space spaceName (G11): a one-time per-replication snapshot (the field is computed once at initialize()). cells gives reachable cells with their distance-to-goal; maxDistance anchors the heatmap color ramp; cellSize/originX/originY place the grid in world coordinates. Opt-in (off by default) — an "agent debugging / teaching" overlay.

HoldEntered

@Serializable

@SerialName(value = "HoldEntered")

data class HoldEntered(val simTime: Double, val entityId: Long, val holdName: String) : AnimationEvent

An entity entered a hold queue.

HoldReleased

@Serializable

@SerialName(value = "HoldReleased")

data class HoldReleased(val simTime: Double, val entityId: Long, val holdName: String) : AnimationEvent

An entity was released from a hold queue.

MarkerPulsed

@Serializable

@SerialName(value = "MarkerPulsed")

data class MarkerPulsed(val simTime: Double, val x: Double, val y: Double, val z: Double = 0.0, val holdTime: Double = 1.0, val label: String? = null, val colorHex: String? = null) : AnimationEvent

A transient highlight ("pulse") the model reports at a world location when something noteworthy happens there — e.g. a delivery completes at a drop-off point (G-animated). Reported by the model via reportMarkerPulse; opt-in (off by default), so a normal run pays zero cost. The renderer draws an expanding, fading ring centered on (x,y) over the window [simTime, simTime + holdTime] (model time); label and colorHex (e.g. "#1f77b4") are optional styling. A teaching/demo overlay — it visualizes a domain event, not agent internals, but rides the same capture/display gates as G10–G12.

MoveCompleted

@Serializable

@SerialName(value = "MoveCompleted")

data class MoveCompleted(val simTime: Double, val entityId: Long, val toX: Double, val toY: Double, val toZ: Double = 0.0) : AnimationEvent

An entity completed a move and is at rest at (toX, toY, toZ).

MoveStarted

@Serializable

@SerialName(value = "MoveStarted")

data class MoveStarted(val simTime: Double, val entityId: Long, val fromX: Double, val fromY: Double, val toX: Double, val toY: Double, val velocity: Double, val duration: Double, val arrivalTime: Double, val fromZ: Double = 0.0, val toZ: Double = 0.0, val fromLocationName: String? = null, val toLocationName: String? = null) : AnimationEvent

An entity began a point-to-point move at constant velocity. The renderer reconstructs the entity's position at any replay time by linearly interpolating from (fromX, fromY, fromZ) to (toX, toY, toZ) between simTime and arrivalTime. This same contract covers the agent-layer travel primitives, whose legs are also straight-line constant-velocity.

NetworkDefined

@Serializable

@SerialName(value = "NetworkDefined")

data class NetworkDefined(val simTime: Double, val name: String, val nodes: List<NetworkNodeDef> = emptyList(), val edges: List<NetworkEdgeDef> = emptyList()) : AnimationEvent

Defines a network (graph) backdrop with auto-laid-out nodes and weighted edges (G7). Emitted once per replication after the model wires the graph (e.g. in initialize()), since a ksl.modeling.agent.NetworkProjection is non-spatial — node positions are assigned by a layout at snapshot time. Agents are emitted at the same node positions (AgentPositionChanged) so their state colors render on top of the edges.

PlannedPath

@Serializable

@SerialName(value = "PlannedPath")

data class PlannedPath(val simTime: Double, val agentName: String, val points: List<PathPoint> = emptyList()) : AnimationEvent

A route the model planned for an agent (G12): the polyline points in world coordinates, reported by the model right after it computes a path (e.g. A-star / network shortest path). Opt-in (off by default), emitted only when the model calls reportPlannedPath — a teaching/debugging overlay showing intended vs actual.

ProcessActivated

@Serializable

@SerialName(value = "ProcessActivated")

data class ProcessActivated(val simTime: Double, val entityId: Long, val processName: String) : AnimationEvent

A process coroutine has been activated for an entity.

ProcessCompleted

@Serializable

@SerialName(value = "ProcessCompleted")

data class ProcessCompleted(val simTime: Double, val entityId: Long, val processName: String) : AnimationEvent

A process coroutine has run to completion for an entity.

QObjectDequeued

@Serializable

@SerialName(value = "QObjectDequeued")

data class QObjectDequeued(val simTime: Double, val entityId: Long, val queueName: String) : AnimationEvent

A specific QObject/entity left a queue (8C.2).

QObjectEnqueued

@Serializable

@SerialName(value = "QObjectEnqueued")

data class QObjectEnqueued(val simTime: Double, val entityId: Long, val queueName: String) : AnimationEvent

A specific QObject/entity entered a queue. Lets a renderer show the identified members of any queue (and style them by type), not just a count (8C.2). Covers every queue type.

QueueLengthChanged

@Serializable

@SerialName(value = "QueueLengthChanged")

data class QueueLengthChanged(val simTime: Double, val queueName: String, val length: Int) : AnimationEvent

A queue's length changed. Covers every queue type (one shared event).

Released

@Serializable

@SerialName(value = "Released")

data class Released(val simTime: Double, val entityId: Long, val resourceName: String, val amountReleased: Int) : AnimationEvent

An entity has released units of a resource.

ReplicationEnded

@Serializable

@SerialName(value = "ReplicationEnded")

data class ReplicationEnded(val simTime: Double, val replicationNumber: Int) : AnimationEvent

A replication has ended.

ReplicationStarted

@Serializable

@SerialName(value = "ReplicationStarted")

data class ReplicationStarted(val simTime: Double, val replicationNumber: Int) : AnimationEvent

A replication has begun. Delimits a replication block in the trace stream.

ResourceStateChanged

@Serializable

@SerialName(value = "ResourceStateChanged")

data class ResourceStateChanged(val simTime: Double, val resourceName: String, val state: String, val busyUnits: Int, val capacity: Int) : AnimationEvent

A resource changed state. Covers both the process-view Resource and the station-package SResource. state is a String tag (e.g. "Busy", "Idle", "Failed", "Inactive") so the renderer needs no enum dependency.

ResponseObserved

@Serializable

@SerialName(value = "ResponseObserved")

data class ResponseObserved(val simTime: Double, val responseName: String, val value: Double, val count: Double = Double.NaN, val average: Double = Double.NaN, val min: Double = Double.NaN, val max: Double = Double.NaN) : AnimationEvent

A statistical quantity was observed. Drives live bar charts and time-series plots. Covers Response, TWResponse, and Counter (the renderer does not need to distinguish which). For responses, the current within-replication statistics (count/average/min/max) are carried so a renderer can show a live summary without recomputing (decision D11); they are NaN for counters and any source without within-replication statistics.

SeizeAllocated

@Serializable

@SerialName(value = "SeizeAllocated")

data class SeizeAllocated(val simTime: Double, val entityId: Long, val resourceName: String, val amountAllocated: Int) : AnimationEvent

Units of a resource have been allocated to an entity.

SeizeQueued

@Serializable

@SerialName(value = "SeizeQueued")

data class SeizeQueued(val simTime: Double, val entityId: Long, val resourceName: String, val queueName: String, val amountRequested: Int) : AnimationEvent

An entity's seize request was enqueued waiting for a resource.

SeizeWaiting

@Serializable

@SerialName(value = "SeizeWaiting")

data class SeizeWaiting(val simTime: Double, val entityId: Long, val resourceName: String) : AnimationEvent

An entity is suspended waiting for units of a resource to become available.

SignalReceived

@Serializable

@SerialName(value = "SignalReceived")

data class SignalReceived(val simTime: Double, val entityId: Long, val signalName: String) : AnimationEvent

An entity received the signal it was waiting for.

SpaceDefined

@Serializable

@SerialName(value = "SpaceDefined")

data class SpaceDefined(val simTime: Double, val name: String, val kind: String, val cols: Int = 0, val rows: Int = 0, val cellSize: Double = 1.0, val xMin: Double = 0.0, val xMax: Double = 0.0, val yMin: Double = 0.0, val yMax: Double = 0.0, val torus: Boolean = false) : AnimationEvent

Records an agent projection's spatial dimensions (8K.6a), so the renderer can draw the space backdrop from the trace when the layout omits a gridSpace/continuousSpace. kind is "Grid" (uses cols/rows/cellSize) or "Continuous" (uses xMin/xMax/yMin/yMax).

SpatialElementMoveCompleted

@Serializable

@SerialName(value = "SpatialElementMoveCompleted")

data class SpatialElementMoveCompleted(val simTime: Double, val name: String, val toX: Double, val toY: Double, val toZ: Double = 0.0) : AnimationEvent

A named spatial element finished moving (8K.5).

SpatialElementMoved

@Serializable

@SerialName(value = "SpatialElementMoved")

data class SpatialElementMoved(val simTime: Double, val name: String, val fromX: Double, val fromY: Double, val fromZ: Double = 0.0, val toX: Double, val toY: Double, val toZ: Double = 0.0, val velocity: Double, val duration: Double, val arrivalTime: Double, val fromLocationName: String? = null, val toLocationName: String? = null, val mode: MoverMode = MoverMode.EMPTY, val carriedEntityId: Long? = null, val carriedEntityType: String? = null) : AnimationEvent

A named spatial element (e.g. a movable/transport resource) started moving (8K.5). Mirrors MoveStarted but is keyed by name (the spatial element's name) rather than an entity id, so the renderer can animate the resource itself — including empty repositioning that carries no entity. Carries location names so coordinate-free spaces (DistancesModel) resolve by name (8H.3).

StationEntered

@Serializable

@SerialName(value = "StationEntered")

data class StationEntered(val simTime: Double, val entityId: Long, val stationName: String) : AnimationEvent

An entity entered a station.

StationExited

@Serializable

@SerialName(value = "StationExited")

data class StationExited(val simTime: Double, val entityId: Long, val stationName: String) : AnimationEvent

An entity exited a station.

Transferred

@Serializable

@SerialName(value = "Transferred")

data class Transferred(val simTime: Double, val entityId: Long, val networkName: String, val egressName: String) : AnimationEvent

An entity was transferred (handed off) out of a network at an egress.

WaitForProcessCompleted

@Serializable

@SerialName(value = "WaitForProcessCompleted")

data class WaitForProcessCompleted(val simTime: Double, val entityId: Long, val childProcessName: String) : AnimationEvent

A child process an entity was waiting on has completed.

WaitingForProcess

@Serializable

@SerialName(value = "WaitingForProcess")

data class WaitingForProcess(val simTime: Double, val entityId: Long, val childProcessName: String) : AnimationEvent

An entity is waiting for a child process to complete.

WaitingForSignal

@Serializable

@SerialName(value = "WaitingForSignal")

data class WaitingForSignal(val simTime: Double, val entityId: Long, val signalName: String) : AnimationEvent

An entity is waiting for a signal.

Properties

simTime

abstract val simTime: Double