Interface control document

1. Identification

2. Scope

HCP MACE observes a running MACE mission and publishes entity state and events to HEAT Capture. It starts, pauses, resumes and stops a HEAT Capture session in step with the MACE mission state.

It does not control MACE entities and does not consume or override aircraft control inputs: MACE (and ARMOR as its visual/output attachment) remain the sole control path. Capture is observational only.

3. Interface inventory

4. IF-HCPMACE-01 Session control

4.1 Transport and addressing

HTTP or HTTPS, matching the scheme of CaptureBaseUrl (default http://localhost:5005, HEAT Capture’s own shipped default). Endpoint paths are fixed in the plugin, not configurable.

4.2 Connection lifecycle

The transport supervisor gets or starts a session, then validates the returned identity, on a continuous loop: session start retries with exponential backoff (RetryInitialDelayMs/RetryMaxDelayMs, default 500 ms / 15 s) on any failure, including a 409 session-conflict response, which is treated as recoverable if a session is actually active. Session pause/resume calls follow the MACE mission’s own Paused/Running transitions. Session stop does not retry - see Section 4.7.

4.3 Authentication

None presented by the plugin. HEAT Capture requires a signed-in user for session control to succeed; the plugin waits for a valid, non-empty user id in the session response before it will capture or publish anything (see IF-HCPMACE-02, Section 5.6).

4.4 Messages

4.5 Data elements

The session response’s user id and session id are read to validate and identify the session. UserId is re-published on IF-HCPMACE-02 as HeatUserComponent.user_name for locally controlled entities. SessionId is retained for session handling and is not included in the published frame.

4.6 Timing

Continuous: the supervisor loop re-checks session state on every pass (HealthyPollDelayMs, default 250 ms, while connected), not only once at startup.

4.7 Error behaviour

5. IF-HCPMACE-02 Frame and event publish

5.1 Transport and addressing

WebSocket, wss:// if CaptureBaseUrl is https:// and ws:// otherwise, at CaptureBaseUrl + /ws/publish.

5.2 Connection lifecycle

Connected as part of the same supervisor loop as session control (Section 4.2): the loop ensures a valid session, then a connected socket, before flushing any buffered frames; on any failure (socket error, send failure) it closes the socket and retries the whole sequence after an exponential backoff delay. Unlike some other plugins in this catalogue, reconnection is automatic and unconditional - there is no scenario in which this plugin gives up permanently.

5.3 Authentication

None presented by the plugin. HEAT Capture requires a signed-in user for the WebSocket handshake to succeed.

5.4 Messages

One binary WebSocket frame per SimulationFrame, Any-wrapped. HEAT Capture closes the connection on any frame larger than 10 MiB and ignores text frames.

5.5 Data elements

See Data produced for the entity component and event catalogue, and ProtoLib’s message reference for field-level detail.

5.6 Timing

Entity-state frames: gated by CaptureIntervalMs (default 33 ms, about 30 Hz) at the outer level, then further throttled per entity category and per slow-changing component group - see Configure. A tick with nothing due publishes no frame at all, so simulationTimeSeconds is not a guaranteed continuous per-tick sequence from a consumer’s perspective. Discrete events publish on the next tick after the underlying MACE callback fires; they are never throttled by any interval setting.

Capture and publish are both gated on a valid session identity. While unavailable, events queue (bounded by MaxBufferedEvents, default 20000, oldest-first) for up to SessionIdentityBufferTimeoutSeconds (default 120 s); beyond that, queued data is discarded and capture effectively resumes from empty once identity returns.

5.7 Error behaviour

6. Data model reference

Entities carry SimulationFrame → EntityState → component messages: HeatUser, WorldPosition, Dynamics, Health, Air/FWA/RotaryWing data, Cloud, Emission, SensorContacts, ReceiverCharacteristics/ReceiverEnvironment, Signature, CombatState, IFF, DataLink, TargetData, Radio, UnitType, ResourceStores, aircraft/ground Lighting, and LinkedEntity. Events carry TrackingEvent (the authoritative verb) paired with a typed EntityDataEvent (FiredEvent/DetonationEvent/HitEvent/CollisionEvent/ LasedEvent/EmissionEvent/EsmContactEvent/JammingEvent/StateChangedEvent). See Data produced for which fields are never populated in this version (WeaponLoadoutComponent, link_type, IFF mode 4/5 codes, a jamming-stopped verb) and ProtoLib’s message reference for the schema itself.

7. Units, frames and conventions

8. Configuration affecting the interface

See Configure for the full settings reference.

9. Compatibility and versioning

Documented against hcp_mace commit 2e8b00d and HEAT.ProtoLib.CSharp 0.37.0. There is no version negotiation on either interface. A SimulationFrame carrying components a given HEAT Capture build does not recognise is expected to be tolerated as unknown protobuf fields, consistent with how HEAT ProtoLib messages evolve elsewhere in this catalogue.

10. Security considerations

Both interfaces can run over TLS (https:///wss://) if CaptureBaseUrl uses https://; otherwise both are plain HTTP/WS. Both rely entirely on HEAT Capture’s own signed-in-user requirement; the plugin presents no credential of its own. Treat network isolation between the MACE workstation and the HEAT Capture workstation as the security boundary, consistent with HEAT Capture’s own security guidance - see HEAT Capture’s web API.

11. Conformance

1. Deploy the plugin per Install and confirm it is listed under System Settings → Third Party Plugins.
2. Sign in to HEAT Capture, then start a MACE mission. Confirm a session appears active on the HEAT Capture side within SessionIdentityBufferTimeoutSeconds.
3. Confirm at least one entity appears in HEAT Capture within one CaptureIntervalMs period (default 33 ms) of the mission running.
4. Fire a weapon. Confirm a FIRED event, and later a HIT/DETONATION pair on impact, are observable on the HEAT Capture side.
5. Pause the mission. Confirm the HEAT Capture session pauses and no further periodic frames arrive until resumed.
6. Stop the mission. Confirm the HEAT Capture session closes.

12. Revision history

HEAT Capture team. Last updated 2 October 2026.