@hla4ts/spacekit

SEE-first application layer for HLA federates.

@hla4ts/spacekit is now the default entry point for new users, especially for SEE and SpaceFOM federates. It sits on top of @hla4ts/hla-api and bundles the runtime pieces most users actually need:

• SpacekitApp: opinionated SEE/SpaceFOM app runtime
• canonical SpaceFOM entity and interaction classes
• late-joiner bootstrap and typed bootstrap state
• run loop, tick(), and logical-time send-time helpers
• declarative object/interaction schemas and decorator-based registration
• entity sync, environment parsing, and console logging helpers

@hla4ts/spacefom is now the thinner helper layer underneath it. Use that package directly only when you need raw SpaceFOM assets such as bundled XML modules or low-level coders.

Install

bun add @hla4ts/spacekit

Recommended Entry Point

import { PhysicalEntity, SpacekitApp } from "@hla4ts/spacekit";

const app = new SpacekitApp({
  federationName: "SpaceFederation",
  federateName: "LunarRover-1",
  federateType: "LunarRover",
});

const rover = new PhysicalEntity("LunarRover-1", {
  parent_reference_frame: "AitkenBasinLocalFixed",
});

await app.start();
await app.registerEntity(rover);

await app.run({
  entities: [rover],
  onTick: ({ timeSeconds }) => {
    rover.state = {
      translation: {
        position: [0.5 * timeSeconds, 0, 0],
        velocity: [0.5, 0, 0],
      },
      rotation: {
        attitude: { scalar: 1, vector: [0, 0, 0] },
        angularVelocity: [0, 0, 0],
      },
      time: timeSeconds,
    };
  },
});

What SpacekitApp Adds

• SEE-oriented environment defaults
• built-in SpaceFomLateJoinerBootstrap
• automatic reference-frame waiting for PhysicalEntity registration
• tick() and run() for paced logical-time loops
• getSendTimeMicros() for timestamped updates/interactions
• spacefomState for typed bootstrap state access
• configurable missing-reference-frame behavior via missingReferenceFrameMode
• graceful shutdown wiring by default

If you want an app to keep running when a configured parent reference frame is not yet available, set missingReferenceFrameMode: "continue" on SpacekitApp. The app will warn and proceed instead of throwing during entity registration.

Canonical SpaceFOM Types

The canonical decorated SpaceFOM classes now live in @hla4ts/spacekit:

• ExecutionConfiguration
• ReferenceFrame
• PhysicalEntity
• DynamicalEntity
• ModeTransitionRequest

These classes are the single source of truth for the runtime adapters, bootstrap subscriptions, and extension-FOM generation.

Lower-Level Escape Hatches

If you need to drop below the SEE-first app layer, @hla4ts/spacekit still exports the generic framework primitives:

• BaseSpacekitApp
• SpacekitFederate
• DeclarativeFom
• DeclarativeRuntime
• SpacekitEntity
• decorators such as FomObjectClass and FomInteractionClass

SpaceFOM Assets and Coders

@hla4ts/spacekit re-exports the common SpaceFOM helpers so most SEE users do not need a second package import:

import {
  HLAunicodeStringCoder,
  SpaceFomExecutionMode,
  encodeSpaceTimeCoordinateState,
  loadSpaceFomModules,
} from "@hla4ts/spacekit";

E2E Validation

The repo includes an opt-in real-stack validation path built around the lunar-rover and lunar-rover-tracker examples.

Prerequisites:

• target RTI already running
• SpaceMaster already running
• Root Reference Frame Publisher already running

Command:

RTI_HOST=localhost bun run e2e:spacekit-see

The command fails on timeout or missing success markers and validates:

• join/bootstrap completion
• reference-frame discovery
• rover state publication
• tracker receipt of rover updates
• interaction round-trip plus ACK
• multiple logical ticks for both federates

Package Split

• @hla4ts/spacekit: default SEE/SpaceFOM app layer
• @hla4ts/spacefom: bundled SpaceFOM XML modules, coders, constants, and optional dashboard loader
• @hla4ts/hla-api: direct HLA API surface when you do not want the framework

Test

cd packages/spacekit
bun test