Data produced by HCP VBS
Every 0.1 seconds (10 Hz, hardcoded - see Configure), HCP VBS builds
one SimulationFrame containing every tracked entity’s current state, and sends it. Events
(weapon fire, damage, mount/dismount, and others below) are sent independently, as they happen,
not on this cadence.
Entities and components
Each tracked VBS object becomes one entity. Components are added only when the underlying VBS
data is available; an entity with no orientation, for example, gets no rotation on its
TransformComponent.
| Component | Populated when | Notes |
|---|---|---|
WorldPositionComponent | Entity has a position | Latitude, longitude, altitude; UTM eastings/northings when available (truncated to whole metres); heading is -180 - yaw in VBS’s own convention |
TransformComponent | Entity has a map position, or is a linked/turret entity with a local transform | Position plus a body-to-ENU orientation quaternion in the local tangent plane at the entity - see Interface control document for the exact convention |
DynamicsComponent | Entity has velocity | Linear velocity and its magnitude; angular velocity (converted from VBS degrees/second to the schema’s radians/second) and linear acceleration when available |
GroundVehicleControlComponent | Entity is a VBS car | Presence marker only - VBS exposes no driver control-input data |
ResourceStoresComponent | Entity has fuel or magazines | One fuel_main entry (litres if capacity is known, otherwise percent of a normalized 0-1 VBS value) plus one entry per magazine, in rounds |
WeaponLoadoutComponent | Entity has weapon stations | One entry per weapon, with the VBS weapon index as hardpoint_index and which one is selected |
AircraftEngineComponent | Entity is a helicopter or airplane and has powertrain data | Engine running state, reused as ignition - VBS exposes only one engine boolean |
GroundVehiclePowertrainComponent | Entity has powertrain data and is not air | Engine on/off, RPM and gear index when available |
CombatStateComponent | Any of affiliation, weapons posture, or engagement posture is set | Sourced from a periodic SQF sample, not from the VBS weapon-posture callback - see below |
IffComponent | Any IFF mode 1/2/3A code is non-empty | Modes 4 and 5 are flags-only in the schema and are never populated by this module |
LinkedEntityComponent | Entity is ammunition, or has a parent | Turrets are always linked with LINK_TYPE_ARTICULATED_MOUNT; an entity with no parent reports the schema’s “no parent” sentinel |
HealthComponent | Damage data has been set | current_health is 100 - damage; VBS damage is on a 0-100 scale |
HeatUserComponent | Entity is the player’s currently-controlled unit | Player name and role only; updates on OnPlayerSwitchedUnits |
RotaryWingDataComponent | Entity is a helicopter | Presence marker only - VBS exposes no rotor torque or trim data |
FwaDataComponent | Entity is a fixed-wing aircraft | Presence marker only - VBS exposes no flight-instrument data |
GenericAircraftComponent | Entity is an aircraft with a position | True altitude (MSL) only |
AirDataComponent | Entity is an aircraft with sampled ambient air data | Temperature, pressure, wind speed, and wind direction as an ENU unit vector |
UnitTypeComponent | Always | DIS kind/domain/country/category/subcategory/specific/extra, from the mapping described in Configure |
A turret entity is a special case: it carries only LinkedEntityComponent (linking it to its
platform) and a parent-relative TransformComponent. Everything else - weapons, ammo, damage - is
attributed to the platform entity, not the turret.
VBS reassigns object ids across a mission load or reset. An object that existed before the
reload can be replaced by a fresh id without VBS ever firing a deletion callback, leaving a
stale, dead entry behind. HCP VBS detects this each tick by validating every tracked handle, and
reports any that have gone invalid as TRACKING_EVENT_TYPE_DESTROYED before dropping them - so a
DESTROYED event with no preceding damage or hit is expected right after a mission reload, not a
sign that something was actually destroyed.
Tracking events
Events use HEAT ProtoLib’s TrackingEventType enum. Several events this module emits use a
generic type with a JSON payload rather than a dedicated enum value that exists for that purpose
- noted below.
| VBS trigger | Tracking event type | Notes |
|---|---|---|
| Object created | TRACKING_EVENT_TYPE_CREATED | |
| Object deleted, or found invalid on a tick (see above) | TRACKING_EVENT_TYPE_DESTROYED | |
| Weapon discharge (platform or turret) | TRACKING_EVENT_TYPE_FIRED | Carries a FiredEvent |
| Laser designation | TRACKING_EVENT_TYPE_LASED | |
| Projectile impact | TRACKING_EVENT_TYPE_AMMO_HIT | Only when the projectile’s own shot_exploded flag is true - see below |
| Impact that exploded | TRACKING_EVENT_TYPE_DETONATION | Emitted alongside AMMO_HIT for the same impact |
| Damage state change | TRACKING_EVENT_TYPE_DAMAGED | |
| Physical collision | TRACKING_EVENT_TYPE_COLLISION | |
| Mounted / dismounted | TRACKING_EVENT_TYPE_MOUNTED / TRACKING_EVENT_TYPE_DISMOUNTED | |
| Entered / exited vehicle | TRACKING_EVENT_TYPE_ENTERED_VEHICLE / TRACKING_EVENT_TYPE_EXITED_VEHICLE | |
| Crew position changed | TRACKING_EVENT_TYPE_CREW_POSITION_CHANGED | |
| Gesture, animation, URN, description, or light-system state changed | TRACKING_EVENT_TYPE_STATE_CHANGED | JSON payload distinguishes which field changed, for example gesture=.... The schema’s dedicated TRACKING_EVENT_TYPE_ACTION_PERFORMED (documented for gesture/animation) is not used |
| Magazine added, removed, or switched | TRACKING_EVENT_TYPE_UNSPECIFIED | JSON payload carries the detail. No dedicated magazine-change type is used |
| AAR bookmark reached (recording or replay) | TRACKING_EVENT_TYPE_UNSPECIFIED | Carries a typed BookmarkEvent (id, name, message, mode, recording file) on the environment sentinel entity - no dedicated bookmark verb exists in the schema |
Non-exploding hits are not reported. AMMO_HIT and DETONATION only fire when the VBS hit
event’s own shot_exploded flag is true. A kinetic hit that does not explode - most small-arms
and cannon fire - produces no tracking event at all; only the resulting DAMAGED event (if any
damage was actually applied) shows up.
Mission start and end are not reported as tracking events. HCP VBS calls HEAT Capture’s session-start and session-stop endpoints at those points (see Interface control document), but sends no corresponding entity event.
Combat state sourcing
CombatStateComponent’s weapons posture, truth affiliation and engagement posture come from a
periodic SQF script sample (about once per second), not from VBS’s own weapon-posture change
callback. That callback exists and is wired up in the plugin, but its handler is a documented
no-op: the comment in source states the VBS physical weapon-carry state (stowed or deployed) is
not the same thing as the ROE-style posture the schema wants, so the callback is ignored in
favour of the SQF sample.
Environment data and AAR bookmarks
Fog density and sky coverage (converted to a percentage) are sampled from VBS’s weather-change
callbacks and carried on CloudDataComponent, attached to a synthetic, always-present
"environment" entity separate from any VBS object - it is never validated or pruned the way
real entities are. AAR bookmarks (see the events table above) are published as they occur,
attributed to the same environment entity, and are not part of the per-tick frame.