@hla4ts/proto

HLA 4 Federate Protocol TypeScript Types

This package contains TypeScript type definitions generated from the official IEEE 1516.1-2025 HLA 4 Federate Protocol .proto files. It provides type-safe interfaces for all protocol messages, enabling TypeScript federates to communicate with HLA 4 RTIs.

Overview

The HLA 4 standard (IEEE 1516-2025) introduces the Federate Protocol, a language-neutral wire protocol that allows federates to communicate with RTIs without requiring vendor-specific native libraries. This package provides the TypeScript bindings for that protocol.

Sequence Diagram

sequenceDiagram
  participant App as Federate Code
  participant Types as @hla4ts/proto
  participant PB as protobufjs
  App->>Types: Create CallRequest / CallbackRequest
  Types->>PB: encode(...)
  PB-->>App: Uint8Array payload
  App->>Types: decode(bytes)
  Types-->>App: Typed response/callback

What's Included

| File | Description | |------|-------------| | datatypes.ts | Core HLA types: handles, enums, FOM modules, credentials | | RTIambassador.ts | 178 request/response message types for RTI service calls | | FederateAmbassador.ts | 62 callback message types from RTI to federate |

Installation

bun add @hla4ts/proto

Usage

Importing Types

import {
  // Enums
  ResignAction,
  OrderType,
  CallbackModel,
  
  // Handle types
  type FederateHandle,
  type ObjectClassHandle,
  type AttributeHandle,
  type ObjectInstanceHandle,
  
  // Request/Response types
  type JoinFederationExecutionRequest,
  type JoinFederationExecutionResponse,
  type CallRequest,
  type CallResponse,
  
  // Callback types
  type CallbackRequest,
  type DiscoverObjectInstance,
  type ReflectAttributeValues,
  type TimeAdvanceGrant,
} from '@hla4ts/proto';

Creating Messages

import { 
  type JoinFederationExecutionWithNameRequest,
  ResignAction,
} from '@hla4ts/proto';

// Create a join request
const joinRequest: JoinFederationExecutionWithNameRequest = {
  federateName: 'MyFederate',
  federateType: 'SimulationType',
  federationName: 'TestFederation',
};

// Use enums
const resignAction = ResignAction.DELETE_OBJECTS_THEN_DIVEST;

Encoding/Decoding Messages

The generated types include encode/decode methods using protobufjs:

import { 
  CallRequest,
  JoinFederationExecutionRequest,
} from '@hla4ts/proto/rti';

// Encode a message to bytes
const request: JoinFederationExecutionRequest = {
  federateType: 'MyType',
  federationName: 'MyFederation',
};

const encoded: Uint8Array = JoinFederationExecutionRequest.encode(request).finish();

// Decode bytes to a message
const decoded = JoinFederationExecutionRequest.decode(encoded);

Message Categories

RTI Ambassador Messages (Federate → RTI)

These are service calls from the federate to the RTI:

| Category | Examples | |----------|----------| | Federation Management | CreateFederationExecution, JoinFederationExecution, ResignFederationExecution | | Declaration Management | PublishObjectClassAttributes, SubscribeObjectClassAttributes, PublishInteractionClass | | Object Management | RegisterObjectInstance, UpdateAttributeValues, SendInteraction, DeleteObjectInstance | | Time Management | EnableTimeRegulation, EnableTimeConstrained, TimeAdvanceRequest | | Ownership Management | AttributeOwnershipAcquisition, NegotiatedAttributeOwnershipDivestiture | | Support Services | GetObjectClassHandle, GetAttributeHandle, GetInteractionClassHandle |

Federate Ambassador Callbacks (RTI → Federate)

These are callbacks from the RTI to the federate:

| Category | Examples | |----------|----------| | Object Discovery | DiscoverObjectInstance, RemoveObjectInstance | | Attribute Updates | ReflectAttributeValues, ProvideAttributeValueUpdate | | Interactions | ReceiveInteraction, ReceiveDirectedInteraction | | Time Grants | TimeAdvanceGrant, TimeRegulationEnabled, TimeConstrainedEnabled | | Ownership | RequestAttributeOwnershipAssumption, AttributeOwnershipAcquisitionNotification | | Synchronization | AnnounceSynchronizationPoint, FederationSynchronized |

Envelope Types

All messages are wrapped in envelope types for the wire protocol:

// RTI calls use CallRequest/CallResponse
type CallRequest = {
  callRequest: 
    | { connectRequest: ConnectRequest }
    | { joinFederationExecutionRequest: JoinFederationExecutionRequest }
    | { updateAttributeValuesRequest: UpdateAttributeValuesRequest }
    // ... 175 more variants
};

// Callbacks use CallbackRequest/CallbackResponse
type CallbackRequest = {
  callbackRequest:
    | { discoverObjectInstance: DiscoverObjectInstance }
    | { reflectAttributeValues: ReflectAttributeValues }
    | { timeAdvanceGrant: TimeAdvanceGrant }
    // ... 59 more variants
};

Key Types

Handles

HLA uses opaque handles to reference objects. These are represented as byte arrays:

interface FederateHandle { data: Uint8Array }
interface ObjectClassHandle { data: Uint8Array }
interface AttributeHandle { data: Uint8Array }
interface InteractionClassHandle { data: Uint8Array }
interface ParameterHandle { data: Uint8Array }
interface ObjectInstanceHandle { data: Uint8Array }
interface LogicalTime { data: Uint8Array }

Enums

enum ResignAction {
  UNCONDITIONALLY_DIVEST_ATTRIBUTES = "UNCONDITIONALLY_DIVEST_ATTRIBUTES",
  DELETE_OBJECTS = "DELETE_OBJECTS",
  CANCEL_PENDING_OWNERSHIP_ACQUISITIONS = "CANCEL_PENDING_OWNERSHIP_ACQUISITIONS",
  DELETE_OBJECTS_THEN_DIVEST = "DELETE_OBJECTS_THEN_DIVEST",
  CANCEL_THEN_DELETE_THEN_DIVEST = "CANCEL_THEN_DELETE_THEN_DIVEST",
  NO_ACTION = "NO_ACTION",
}

enum OrderType {
  RECEIVE = "RECEIVE",
  TIMESTAMP = "TIMESTAMP",
}

enum CallbackModel {
  EVOKED = "EVOKED",
  IMMEDIATE = "IMMEDIATE",
}

Regenerating Types

If you need to regenerate the TypeScript types from updated .proto files:

1. Place .proto files in proto/ directory
2. Ensure protoc is installed
3. Run:

bun run generate

Prerequisites

• protoc (Protocol Buffer Compiler)
  • Windows: choco install protoc or scoop install protobuf
  • macOS: brew install protobuf
  • Linux: apt install protobuf-compiler

Source

The .proto files are from the IEEE 1516.1-2025 standard:

Reprinted with permission from IEEE 1516.1(TM)-2025

Related Packages

• @hla4ts/transport - Transport layer (TLS/TCP, message framing)
• @hla4ts/session - Session management
• @hla4ts/hla-api - High-level HLA API facade

License

MIT