Beat-game API reference

Entry pointsCopy Anchor Link

The universal module does not import the Node file system. You can bundle it for a browser or worker.

Run functionsCopy Anchor Link

BeatGameRun provides events, snapshots, awaitCompletion, pause, resume, stop, and snapshot. BeatGameTeamRun applies lifecycle actions to each member and waits for all results.

Planner phasesCopy Anchor Link

Runs move through:

1. PREPARE_OVERWORLD
2. ENTER_NETHER
3. COLLECT_NETHER_RESOURCES
4. RETURN_TO_OVERWORLD
5. LOCATE_STRONGHOLD
6. ACTIVATE_END_PORTAL
7. FIGHT_ENDER_DRAGON
8. COMPLETE

Every transition uses a fresh observation.

Checkpoint storesCopy Anchor Link

BeatGameCheckpointStore defines:

interface BeatGameCheckpointStore {
  load(runId: string): Effect.Effect<
    BeatGameCheckpoint | undefined,
    BeatGameCheckpointError
  >;

  save(
    checkpoint: BeatGameCheckpoint,
    expectedRevision: number | undefined,
  ): Effect.Effect<BeatGameCheckpoint, BeatGameCheckpointError>;

  remove(
    runId: string,
    expectedRevision?: number,
  ): Effect.Effect<void, BeatGameCheckpointError>;
}

Checkpoints include schema version, run and team identity, bot and instance identity, role, revision, connection epoch, planner state, world memory, and timestamps. The planner state retains currentActionId while work is uncertain. lastStableAction records the evidence and player and inventory revisions that made the latest action safe to checkpoint.

CoordinatorCopy Anchor Link

BeatGameCoordinator defines member registration, status updates, claims, requirement publication, discovery publication, snapshots, and reset.

Claims have expiry and fencing tokens. Team snapshots contain a fenced leader, aggregate requirements, members, active claims, and shared discoveries.

Event typesCopy Anchor Link

The ordered stream includes:

• run lifecycle events
• checkpoint save and restore
• phase and objective changes
• requirement discovery, updates, claims, and satisfaction
• action start, retry, success, and failure
• disconnect and recovery
• death and item recovery
• team claim changes
• diagnostic observation revisions
• diagnostics.

Every event has a monotonic sequence, timestamp, run ID, instance ID, bot ID, and phase.

Error classesCopy Anchor Link

Errors include run, instance, bot, phase, current action, retryability, and an underlying cause when available.

Behavior groupsCopy Anchor Link

Resource and world behaviors:

acquire, collectBlocks, excavate, explore, fish, farm, breed, buildStructure, and transferContainerItems.

Combat and safety behaviors:

attackEntity, attackNearest, rangedAttack, flee, guard, eatWhenNeeded, respawnAndRecover, equipBestArmor, and keepTotemEquipped.

Inventory behaviors:

craft, craftItem, smelt, brew, trade, and maintainLoadout.

Progression behaviors:

buildNetherPortal, castNetherPortal, enterPortal, throwEnderPearl, throwEyeOfEnder, triangulateStronghold, activateEndPortal, and fightEnderDragon.

The behavior names are TypeScript APIs, not SoulFire core RPC names.