npm package: @hla4ts/proto
Description: HLA 4 Federate Protocol Protobuf definitions and generated TypeScript types
Latest version: 0.1.1

# @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

```mermaid
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

```bash
bun add @hla4ts/proto
```

## Usage

### Importing Types

```typescript
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

```typescript
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`:

```typescript
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:

```typescript
// 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:

```typescript
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

```typescript
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:

```bash
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) - Transport layer (TLS/TCP, message framing)
- [`@hla4ts/session`](../session) - Session management
- [`@hla4ts/hla-api`](../hla-api) - High-level HLA API facade

## License

MIT