Schemas

The schema is the single source of truth: every language’s builders are generated from the same .proto files, so a field exists in one language if and only if it exists in all of them. This page describes the layout of that schema. For the messages themselves, field by field, see Message reference.

Obtaining the schema

Most consumers do not need the raw .proto files: the language packages in Consume the packages already carry compiled bindings. Obtain the schema directly only when generating bindings for a language HEAT ProtoLib does not publish, or when integrating with schema tooling such as buf .

• HEAT-ProtoLib-Protos-<version>.zip, built by the project’s CMake protos target and produced alongside the language packages, contains only the .proto tree under HEAT/.
• Cloning the repository gives the same tree at protos/HEAT/.

All imports inside the schema are written relative to the protos/ root, for example import "HEAT/Proto/Common/Float3.proto";, so either distribution is a drop-in --proto_path for protoc or an import root for buf.

Directory layout

protos/HEAT/Proto/
  Common/               Domain-agnostic value types: Float2, Float3, Quaternion,
                         LLAPosition, ECEFPosition, DateTime types, KeyValuePair
  Capture/               DataPacket, DataPacketBundle: transport envelopes
  Data/                  PDU, FolderUploadData: opaque payload wrappers
  Simulation/
    Entity.proto          Entity
    Component.proto       Component (the 53-way oneof)
    SimulationData.proto  SimulationFrame, EntityState, EntityEvent
    EntityDataEvent.proto EntityDataEvent (the 22-way event oneof)
    TrackingEvent.proto   TrackingEvent, TrackingEventType
    Components/           53 component messages, in subdirectories by domain
                           (GroundVehicle/, AircraftData/, AircraftData/UAS/,
                           AircraftData/RotaryWingAircraft/,
                           AircraftData/FixedWingAircraft/, EW/, Sonar/)
    Events/                22 event payload messages

Four proto packages map onto that tree: HEAT.Proto (Common), HEAT.Proto.Simulation (everything under Simulation/, including its Components/ and Events/ subdirectories), HEAT.Proto.Capture and HEAT.Proto.Data. A proto package is a namespace, not a directory constraint: every message under Simulation/, however deep its subdirectory, declares package HEAT.Proto.Simulation;.

Conventions the schema follows

These are conventions, not enforced constraints; they explain why the schema reads the way it does and what to expect when a new message is added.

A handful of older enums predate the _UNSPECIFIED = 0 convention and are called out individually in Message reference where that changes how an absent field decodes.

Field numbering follows a loose priority range, visible across most components: 1 to 9 for core fields, 10 to 99 for common extensions, 100 and above for domain-specific fields. It is a convention the schema authors follow when adding fields, not a rule protoc enforces.

Retired fields are reserved, never reused. When a field or an entire component is removed, its number is marked reserved rather than freed for reassignment, so an old capture (or a peer running an older schema version) can never have its bytes misinterpreted as a different field. Component itself carries this scar: field numbers 6 to 12 are reserved for a retired LightsComponent, ControlComponent and EngineComponent, superseded by the ground-vehicle and aircraft component families documented in Message reference. See Versioning and compatibility for what this means for a consumer.

Linting

The schema is linted with buf , configured in protos/buf.yaml with the standard rule set and five naming rules disabled (PACKAGE_LOWER_SNAKE_CASE, FILE_LOWER_SNAKE_CASE, DIRECTORY_SAME_PACKAGE, PACKAGE_DIRECTORY_MATCH, PACKAGE_VERSION_SUFFIX) to accommodate the PascalCase file and package naming above, which predates adopting buf.

HEAT Capture team. Last updated 2 October 2026.