Simcraft Docs
Open the app

OSDL Simulation Event

Wire format for one event on the typed simulation event stream. A stream is a sequence of these objects (newline-delimited JSON over a socket, or structured messages in-process). Transports vary; the envelope does not. Core event types are validated below; libraries and models may emit additional namespaced types.

Generated from spec/schemas/osdl.events.schema.json · https://osdl.dev/schemas/0.1/osdl.events.schema.json

Document root#

FieldTypeDescription
vrequired "0.1" Event stream format version.
seqrequired integer Monotonically increasing sequence number within a run. Total order of emission; ties in simulation time are broken by seq. min 0
timerequired number Simulation time of the event, in model time units. min 0
wallTime integer Optional wall-clock timestamp, milliseconds since the Unix epoch.
typerequired string pattern ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
sourcerequired string The emitting component id, or kernel for engine lifecycle events. pattern ^[A-Za-z_][A-Za-z0-9_-]*(\.[A-Za-z_][A-Za-z0-9_-]*)*$
run object
payload object

Definitions#

simStarted#

FieldTypeDescription
modelrequired string
duration number
seed integer

simProgress#

FieldTypeDescription
progressrequired number Fraction of the configured duration elapsed. min 0 · max 1

simCompleted#

FieldTypeDescription
reasonrequired "endTime" | "condition" | "requested" | "quiescent" Why the run completed normally.

simError#

FieldTypeDescription
coderequired "component.failure" | "kernel.runtime" | "expression.error" Stable diagnostic code.
messagerequired string
source string Component id path at fault, if known.
operation "start" | "handle" | "receive" | "finish" The component runtime operation, if known.
time number Simulation time of the failure.

simAborted#

FieldTypeDescription
reasonrequired "budgetExceeded" | "cancelled" Host or implementation-policy abort reason.

entityCreated#

FieldTypeDescription
entityIdrequired string
entityType string
atrequired string Component id path where the entity was created.

entityMoved#

FieldTypeDescription
entityIdrequired string
from string Component id path the entity left.
torequired string Component id path the entity entered.
position array<number> Optional spatial coordinates for renderers, [x, y] or [x, y, z]. min items 2

entityDisposed#

FieldTypeDescription
entityIdrequired string
atrequired string

stateChanged#

FieldTypeDescription
pathrequired string State path, e.g. waiting.length.
valuerequired stateValue

paramChanged#

FieldTypeDescription
namerequired string pattern ^[A-Za-z_][A-Za-z0-9_-]*$
valuerequired stateValue

metricUpdated#

FieldTypeDescription
namerequired string Output path or alias as configured in the experiment.
valuerequired recordedValue

agentTransitioned#

FieldTypeDescription
agentIdrequired string
fromrequired string
torequired string

messageSent#

One of:
object

ABM agent-to-agent message.

FieldTypeDescription
topicrequired string
fromAgent string
toAgent string
payload object
object

Message-port delivery between components.

FieldTypeDescription
from string Sending component id.
torequired string Receiving component id.
portrequired string Receiving message input port.
payload object

valueChanged#

FieldTypeDescription
portrequired string The value output port that published.
valuerequired stateValue

stateValue#

A value that matches a library observable state type. JSON numbers represent both number and integer state.

number | boolean | string

recordedValue#

A recorder telemetry value, or null when no value is available.

number | boolean | string | null