npm package: @hla4ts/spacekit
Description: SEE-first starter kit and default application layer for hla4typescript federates
Latest version: 0.1.1

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

```bash
bun add @hla4ts/spacekit
```

## Recommended Entry Point

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

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

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

```bash
cd packages/spacekit
bun test
```