Message reference

This page is the data dictionary: every message HEAT ProtoLib defines, every field, its type and its unit or meaning where the schema states one. It is generated from the same .proto comments and the same intermediate representation (json-ir/heat_ir.json) that HEAT ProtoLib’s own code generator reads to build the per-language builders, so it stays in step with the schema by construction.

Type names in the tables below are proto message and enum names, not any one language’s generated class name. See Consume the packages for how each language surfaces them.

The simulation frame

SimulationFrame is the root message: a complete snapshot of every entity and every event at one capture moment.

SimulationFrame

EntityState — state of a single entity at a point in time.

Entity — a simulation entity: a stable id, a name, and the components composing it.

Component — ECS-style container. oneof data: exactly one of the 53 component types below is set. Field numbers 6 to 12 are reserved (retired LightsComponent, ControlComponent and EngineComponent, superseded by the ground-vehicle and aircraft component families) and must never be reused.

EntityEvent — one event that occurred this frame: either a data-bearing event or a payload-free tracking event. oneof event: exactly one of the following.

TrackingEvent — a one-shot record that something happened to an entity, and when. This is the authoritative countable timeline: every occurrence emits a TrackingEvent, whether or not the source also emits a matching EntityDataEvent carrying the payload. Count occurrences from this path; it stays uniform across mixed-source captures.

EntityDataEvent — a data-bearing event about one entity, carrying a typed payload. oneof event_data: exactly one of the 22 event types in Events.

Emission contract: TrackingEvent is the authoritative countable record for every occurrence and is emitted by every source, whether or not it can produce payload detail. EntityDataEvent is optional enrichment: when a source has payload for an occurrence, it emits this alongside the matching TrackingEvent, with event_type set to the same verb. Count occurrences from the TrackingEvent path (SimulationFrame → events → tracking_event); do not count EntityDataEvent as a separate occurrence.

Common types

Shared value types used across many components and events.

Float2 — Generic 2D vector or point.

Float3 — Generic 3D vector or point.

Quaternion — Rotation. Convention: x, y, z are the vector part, w is the scalar part.

LLAPosition — Geodetic position (WGS84), double precision, for sub-meter accuracy that float32 lat/lon cannot carry. Preferred for any new position field.

ECEFPosition — Earth-Centered, Earth-Fixed cartesian position, meters from Earth’s center.

Timestamp — A point in time with millisecond precision. Every timestamp on the capture path is wall-clock UTC (capture-host time); simulation time is carried separately as double seconds where needed.

Date — A calendar date without time.

Time — Time of day with millisecond precision.

DateTimeDetailed — Date and time as separate human-readable components, for when a raw timestamp is not what’s wanted.

KeyValuePair — Generic key/value pair, used for extra data a component’s fixed schema does not carry.

Components

An entity’s state is composed from these 53 component types, one Component oneof per attached component. A given component type occurs at most once per entity (the oneof is entity-scoped, not repeated), except WheelComponent, which a vehicle entity attaches once per physical wheel.

Core

TransformComponent — Position, rotation, and scale in 3D space

DynamicsComponent — Physics-related dynamics for simulation entities

HealthComponent — Entity Health Data

LinkedEntityComponent — Defines parent/child relationships between entities

Identity

HeatUserComponent — The human trainee occupying/operating this entity.

UnitTypeComponent

Spatial and navigation

WorldPositionComponent

SpatialComponent — XR/VR spatial tracking for a headset user: head and controller poses, per-eye camera images, and hand tracking.

Biometrics

GazeComponent — Eye tracking and gaze data

PupillometryDataComponent — Pupillometry Component - Tracks pupilometry data from Eye Tracking.

BiometricSensorComponent — Tracks biometric data from sensors

WearableBioSensorComponent — Tracks biometric data from a sports watch and smart watch

Ground vehicles

WheelComponent — Individual wheel state and physics Note: A vehicle entity will typically have multiple wheel components (one per wheel)

GroundVehicleControlComponent — Driver control inputs for a ground vehicle. Pedal/clutch/brake values are normalized 0..1; steering is normalized -1 (full left) .. 1 (full right).

GroundVehiclePowertrainComponent — Powertrain state for a ground vehicle: engine, transmission, and fluids.

GroundVehicleLightingComponent — On/off and mode state of a ground vehicle’s lights.

GroundVehicleSuspensionComponent — Suspension Data for Ground Vehicles

Aircraft

GenericAircraftComponent — Common aircraft flight parameters: altitudes and g-loading.

AircraftEngineComponent — State of one aircraft engine: ignition, throttle, and thrust (forward and reverse). A multi-engine aircraft carries one component per engine.

AircraftLandingGearComponent — Landing gear state: wheels, brakes, and extension/lock status.

AircraftLightingComponent — On/off state of the aircraft’s exterior and interior lights.

AircraftAvionicsComponent — Autopilot / flight-director / autothrottle engagement and selected targets. active_* modes are currently flying; armed_* modes are captured but not yet active. The *_label strings carry source-specific mode text alongside the normalized enums.

AircraftDisplayStateComponent — State of the aircraft’s cockpit displays.

ATCDataComponent — Air-traffic-control identity of the aircraft as filed/displayed. String formats follow common flight-sim ATC variables (e.g. squawk as 4-digit octal).

RadarComponent — Deprecated: superseded by EmissionComponent + SensorContactsComponent. Models a single radar and one implicit target; its target_* fields carry no target entity id, so they cannot be joined for analytics. Frozen for backward compatibility; new sources fill the EW components instead and no source fills both.

FuelSystemComponent — Fuel system state: dumping, transfer, crossfeed, and refuel. Fuel quantities live in ResourceStoresComponent; this carries the flow/plumbing state.

Fixed-wing aircraft

FWADataComponent — FWADataComponent

FWAControlSurfacesComponent — Fixed-wing control surface positions and trim. Conventions across fields: *_position = commanded surface position (normalized, sign gives direction); *_deflection = physical deflection in degrees; *_deflection_percentage and *_trim_percentage = percent of available travel; *_trim_value = trim setting.

FWAInputComponent — Pilot control inputs for a fixed-wing aircraft (as commanded by the operator, before control-law processing).

Rotary-wing aircraft

RotaryInputComponent — Pilot control inputs for a rotary-wing (helicopter) aircraft.

RotaryWingDataComponent — Rotary-wing drivetrain state: rotor torques and trim.

UAS

UASControlsComponent — Operator controls and autonomy state for an unmanned aircraft (UAS).

UASMotorComponent — State of one UAS propulsion motor. A multi-rotor carries one per motor.

UASDataLinkComponent — Health of a UAS’s command-and-control links (control, video, telemetry). This is link health, distinct from DataLinkComponent (tactical datalink networks).

Electronic warfare and sensors

SignatureComponent — Detectability signatures of the entity: how it presents to radar and IR sensors. Truth values (the entity’s actual signature), distinct from what any observer perceives.

EmissionComponent — Current emission picture of the entity: every emitter and its active mode. Sampled per frame. Mode transitions (search -> acquisition -> track, a threat-escalation signal) are also emitted as EmissionEvent on change.

ReceiverCharacteristicsComponent — Design parameters for every receiver on the entity. For detailed detection-model analytics.

ReceiverEnvironmentComponent — Per-receiver local conditions for every receiver on the entity.

RfEnvironmentComponent — Background RF conditions of the battlefield. Attaches to a dedicated environment entity (following the CloudDataComponent convention), not to a combatant. Region polygons change rarely: emit on change only, never per frame.

SensorContactsComponent — All contacts currently held by the owning entity’s sensors, sampled per frame. Complements TargetDataComponent (the target’s own view of being tracked); the two are different perspectives and never share fields.

IffComponent — Identification Friend or Foe transponder/interrogator state of the entity. Mirrors the DIS IFF PDU. Per IFF mode, an enabled flag plus (for non-crypto modes) the code currently set.

Sonar

PassiveSonarDetectionComponent — Passive sonar picture: per-beam signal levels against a detection threshold. Single-sonar platforms use the top-level threshold/sonar_beams fields. Multi-sonar platforms fill sonars instead; when sonars is non-empty it carries the whole picture and the top-level fields are left empty.

SonobuoyDataComponent — State of a deployed sonobuoy (itself an entity). Lifetimes and depth plus a deployment lifecycle status.

Environment

AirDataComponent — Atmospheric conditions at the entity: temperatures, pressures, wind, and weather.

CloudDataComponent — Local visibility and cloud/fog conditions at the entity.

Combat and tactical

CombatStateComponent — Command-and-control combat posture of the entity: its affiliation, weapons and engagement stance, EMCON policy, and engagement envelope.

TargetDataComponent — This entity’s own view of being targeted: whether it is locked, spotted, or visible. Perspective is the target’s; complements SensorContactsComponent (the sensor’s view of what it tracks).

WeaponLoadoutComponent — Full weapon loadout of the entity, one entry per station.

DataLinkComponent — Every tactical datalink network the entity participates in. Distinct from UASDataLinkComponent, which carries link health (signal strength, warnings); no overlap.

RadioComponent — State of one radio/intercom asset as presented to the operator.

Logistics

CapacityDataComponent — CapacityDataComponent Tracks capacity-like data for an entity (ammo, fuel, storage, etc.)

ResourceStoresComponent

Media streaming

StreamComponent — All streams captured from the entity this frame.

Supporting types

Nested message types referenced by the tables above. These are never attached to an entity directly; they only exist inside a component or event field.

BiometricReading — A single named biometric reading, used by BiometricSensorComponent and WearableBioSensorComponent. name scopes the value’s meaning and unit.

TdlNetwork — Participation of the entity in one tactical datalink network, used by DataLinkComponent. Networks are named by string (canonical vocabulary) rather than per-network booleans, so new networks need no schema change.

FuelTransferPath — An active or configured fuel transfer between two stores, used by FuelSystemComponent. source_store_id/destination_store_id reference ResourceStoreEntry.store_id on the same entity.

AircraftDisplayStateEntry — State of one cockpit display, used by AircraftDisplayStateComponent.

WeaponStation — One weapon station (hardpoint) on the entity and what it carries, used by WeaponLoadoutComponent.

Emitter — A single active emitter mode on the owning entity (radar, jammer, datalink, beacon, etc.), sampled as steady state, used by EmissionComponent. One entity may carry several. Mirrors the DIS Electromagnetic Emission PDU emitter system + beam record.

ReceiverCharacteristics — Static design parameters of one receiver on the owning entity, used by ReceiverCharacteristicsComponent. These are properties of the hardware/mode definition and change only on mode switch; emit on change. Dynamic local conditions live in ReceiverEnvironment; the two share no fields.

ReceiverEnvironment — Dynamic local RF/terrain conditions at one receiver, sampled per frame, used by ReceiverEnvironmentComponent. Static design parameters live in ReceiverCharacteristics; pairwise link properties (masking to a specific target) live on SensorContact.

AmbientNoiseRegion — A region of background RF noise: a spectral profile applied over a geographic polygon, optionally filtered to a side/domain, used by RfEnvironmentComponent. Global environment state, not tied to any single platform.

SensorContact — One tracked contact held by a sensor on the owning entity, used by SensorContactsComponent. Sensor-side view of the tactical picture (who this entity detects/tracks/locks).

XrPosef — A pose: orientation plus position, in tracking space. Used by SpatialComponent.

RawImage — A raw image buffer with its dimensions. Used by SpatialComponent.

HandState — Hand-tracking state: the tracked joints and which hand. Used by SpatialComponent.

HandJoint — One tracked hand joint.

AudioSource — A single audio stream, one variant of StreamSource.

VideoSource — A single video stream, one variant of StreamSource.

RawSource — A single opaque data stream, for anything not audio or video. One variant of StreamSource.

StreamSource — One stream of exactly one kind, held in StreamComponent.sources. oneof source: exactly one of the following.

ResourceStoreEntry — One resource store (fuel tank, ammo bin, battery, etc.) on the entity, used by ResourceStoresComponent.

UTMPosition — UTM (Universal Transverse Mercator) alternative to the geographic position on WorldPositionComponent.

PassiveSonarBeamData — One passive sonar beam and its current signal level, used by PassiveSonarDetectionComponent and PassiveSonar.

PassiveSonar — One passive sonar on a multi-sonar platform (hull array, towed array, dipping sonar), with its own threshold and beam picture, used by PassiveSonarDetectionComponent.

CommandsPositions — A single position referenced by a command (waypoint, target point, etc.), used by CommandsEvent. oneof position: exactly one of the following.

SimulationPosition — A local-frame position, used by CommandsEvent and ReportsEvent. Predates the LLAPosition/ECEFPosition convention.

Question — A single questionnaire item with the trainee’s answer and the key, used by QuestionGroup.

QuestionGroup — A named group of questions within a questionnaire, used by QuestionnaireEvent.

JsonData — A JSON document carried as a string, used by JsonEventData.

Events

Two message families carry events. Every occurrence emits a TrackingEvent (the countable timeline; see The simulation frame). A source that has structured detail for the occurrence also emits an EntityDataEvent alongside it, carrying one of the 22 typed payloads below through its event_data oneof.

Each event’s envelope entity_id (on the enclosing EntityDataEvent) is documented per event below, since the perspective changes: for FiredEvent it is the firing entity, for HitEvent the victim, and so on.

BookmarkEvent — A user-authored marker tagging a moment in the capture, e.g. for later review or clipping. Envelope entity_id per EntityDataEvent conventions.

ButtonPressEvent — A button/control interaction. Envelope entity_id = the acting entity.

CollisionEvent — A physical collision. Envelope entity_id = the subject entity. Field 4 is declared first here; declaration order is cosmetic, only field numbers are wire-significant.

CommandsEvent — A command/order issued to or by an entity, with any associated positions. Envelope entity_id = the commanded/issuing entity.

CommsEvent — A communication transmission. Envelope entity_id = the transmitting entity.

CountermeasureEvent — Deployment of a defensive expendable (chaff, flare, decoy). Envelope entity_id = the deploying entity. Active jamming is covered by EmissionEvent/JammingEvent, not here.

DetonationEvent — A munition detonation. Pairs with the DETONATION / MISSED / HIT tracking verbs and mirrors the DIS Detonation PDU. Envelope entity_id is the munition or firing entity per source convention; munition_entity_id is the authoritative join key. Closes the shot-to-outcome loop: FiredEvent.bullet_entity_id == munition_entity_id == HitEvent.bullet_entity_id.

EmissionEvent — Emission start/stop or mode transition of an emitter. Pairs with the RADAR_EMISSION_STARTED/STOPPED and MODE_CHANGED tracking verbs. A mode transition is emitted as active = true carrying the new function/mode. Envelope entity_id = the emitting entity.

EsmContactEvent — A passive RF detection by an ESM/RWR receiver. Pairs with the ESM_CONTACT_DETECTED/LOST tracking verbs. Envelope entity_id = the detecting entity (the ESM/RWR owner).

FaultEvent — A fault/failure lifecycle event on a system. Envelope entity_id = the affected (subject) entity.

FiredEvent — A weapon launch/fire. Envelope entity_id = the firing entity.

HitEvent — A weapon impact on an entity. Envelope entity_id = the hit (victim) entity; the shooter is recovered by joining bullet_entity_id to FiredEvent.

IdentificationEvent — Pairs with TRACKING_EVENT_TYPE_IDENTIFIED. Perceived classification at the moment of declaration, not truth. Envelope entity_id = identifying entity. Comparing declared_affiliation against the target’s actual affiliation is the fratricide / ROE-compliance analysis.

JammingEvent — A jamming effect experienced by a victim receiver. Pairs with the JAMMED tracking verb. Victim-perspective: envelope entity_id = the jammed (victim) entity, which is where the analytic value is (“my radar was degraded by X at time T”). The jammer’s own on/off is covered by EmissionEvent with EMITTER_FUNCTION_JAMMING; there is no jammer-side variant of this event.

JsonEventData — An escape-hatch event carrying a named JSON payload, for source-specific data that has no typed event. Not aggregation-friendly; prefer a typed event where one exists.

LasedEvent — A laser designation. Envelope entity_id = the lasing entity.

MultiStateChangedEvent — A state transition for a multi-state control, carrying the current state and the full set of states it can take. Envelope entity_id = the subject entity.

QuestionnaireEvent — A completed training questionnaire. Envelope entity_id = the trainee entity.

ReportsEvent — A situation report: a perceived contact’s position, affiliation, and type. Perceived (what the reporter believes), not truth.

StateChangedEvent — A generic state transition. Envelope entity_id = the entity whose state changed. state is the new state label.

TargetTrackingEvent — A detection/lock/release transition against a target. Envelope entity_id = the sensing entity. Payload enrichment for the DETECTED / TARGETLOCKED / TARGETRELEASED tracking verbs: the TrackingEvent is the countable record, this carries the extra state/strength/reason (see the emission contract on EntityDataEvent).

ThresholdEvent — A monitored value crossing a threshold. Envelope entity_id = the subject entity. value and threshold_value are unitless by design: the threshold_name scopes their meaning.

Transport wrappers

Messages that carry an arbitrary payload rather than defining simulation data themselves. Other HEAT products, not ProtoLib, define the transport these travel over; see each product’s own Interface Control Document.

DataPacket — a single captured payload with its origin and capture time.

DataPacketBundle — a batch of packets sharing a bundle-level capture time.

PDU — a raw binary payload, for transports (such as DIS) that HEAT ProtoLib does not model as typed messages.

FolderUploadData — a file upload wrapper.

Enums

Every enum referenced by a component, event or supporting type above. _UNSPECIFIED = 0 is the proto3 default; a small number of older enums predate that convention and are flagged in their own description.

AircraftAutopilotLateralMode — Autopilot lateral (roll axis) guidance mode.

AircraftAutopilotVerticalMode — Autopilot vertical (pitch axis) guidance mode. VS = vertical speed.

AircraftDisplayRole — Cockpit display role. MFD = multi-function display, PFD = primary flight display, HUD_REPEATER = head-up display repeated on a panel.

AswClassification — ASW classification of a subsurface contact: the confidence ladder a sonar operator walks from first detection to confirmed submarine. Perceived, not truth. POSSUB grades 1 (lowest) to 4 (highest confidence); PROBSUB covers sources that report a single probable-submarine step instead of grades. DATUM and LOST_CONTACT describe a contact no longer held: DATUM = last known position of a lost submarine contact, kept as an analytic reference point.

BookmarkMode

ButtonState — Button interaction state. Note: PRESSED = 0 predates the _UNSPECIFIED convention, so an absent enum value decodes as PRESSED; the state field is optional to distinguish absent from an explicit PRESSED.

CommsType — Communication modality. Note: VOICE = 0 predates the _UNSPECIFIED convention, so an absent value decodes as VOICE; the comms_type field is optional to distinguish absent from an explicit VOICE.

ContactState — Steady-state sensor hold on a target. Distinct from the transitional TargetTrackingState used by TargetTrackingEvent: that enum carries transitions such as RELEASED, this one carries steady states such as TRACKING.

DetonationResult — Outcome of a munition detonation.

EmissionControl — Emission control (EMCON) policy limiting active RF emissions.

EmitterFunction — Purpose of an emitter mode. Aligned with the DIS Electromagnetic Emission PDU emitter function codes.

EngagementPosture — Overall engagement stance of the entity toward threats.

FaultState

ForceAffiliation — Allegiance of an entity or contact. Used both for truth affiliation (on an entity) and for perceived/declared affiliation (on a contact or an identification event); the field comment states which in each case. ASSUMED_FRIEND and SUSPECT are provisional identities from the STANAG 1241 ladder: they occur only as perceived affiliation, never as truth.

HeadlightMode — Headlight setting.

IffSystemMode — Overall operating state of the IFF transponder/interrogator.

LinkType

RecognitionLevel — How far a sensor/operator has discriminated a contact, on the NATO target-acquisition ladder (STANAG 3769 / Johnson criteria). Domain-agnostic: applies to air, surface, land, and subsurface contacts alike. Perceived, not truth.

ReportsMarkerType — Perceived affiliation of a reported contact. Note: Hostile = 0 predates the _UNSPECIFIED convention, so an absent value decodes as Hostile; the enclosing field is optional to distinguish absent from an explicit Hostile. Value names are unprefixed (grandfathered; renaming would break JSON/source). New messages use ForceAffiliation instead; this enum is frozen for this message.

ReportsUnitType — Perceived unit type of a reported contact. Note: Infantry = 0 has the same absent-decodes-as-value hazard as ReportsMarkerType; the field is optional. Value names grandfathered (unprefixed); frozen for this message.

ResourceType

ResourceUnit

ScanPattern — How an emitter’s antenna sweeps its beam through space.

SonobuoyStatus — Lifecycle state of a sonobuoy from deployment to end of life.

StoreLocation — Where a store is physically carried on the platform.

TargetTrackingState

TrackingEventType — Event types that can occur during simulation

TurbulenceSeverityState — Turbulence intensity band.

UnitDomain

UnitKind

WeaponsPosture — Rules-of-engagement stance governing whether weapons may be employed.

HEAT Capture team. Last updated 2 October 2026.