Low-level client for the Spring/Recoil engine's autohost UDP interface (feature 039, see specs/039-hub-admin-channel/contracts/autohost-wire.md). Owns a single UdpClient bound on 127.0.0.1, encode/decode, and a receive pump on a dedicated thread. Intended to be consumed by FSBar.Hub.AdminChannelHost, which layers coalescing and hub-level status semantics on top.

Parses the engine-generated `ArchiveCache20.lua` to recover the engine-registered map name for each installed `.sd7` map archive. The engine does NOT accept archive filename stems as the `MapName` in start scripts — it requires the map's *declared* name (e.g. "Avalanche 3.4"), which is typically `name_pure + " " + version` but can include bespoke formatting inside `mapinfo.lua`. The engine's archive cache is the authoritative source for this string; this module mirrors the exact value the engine will match against at start time.

Convenience module functions for creating and starting BarClient instances.

High-level client for orchestrating a BAR AI game session. Manages the full lifecycle: engine launch, proxy connection, handshake, frame stepping, and cleanup.

Declarative building layout: resolves named slot lists into placement decisions that honour terrain, clearance, builder reach, and wall-in constraints.

A named, reusable base plan consumed by resolvePlan.

Engine callback functions that query live game state via the HighBar V2 proxy. Each function sends a callback request over the Unix domain socket and returns the parsed result. All functions require an active NetworkStream connection to the proxy.

A detected chokepoint descriptor.

Stable identifier for a chokepoint, derived deterministically from the grid dimensions and ridge cell index. Two calls to findChokepoints with the same inputs produce the same Id values.

Query parameters bounding a chokepoint search.

Distance-transform-based chokepoint detection. Returns stable-ID, width-annotated descriptors for corridors that approach a specified base centre.

Represents a validated engine installation found during directory scanning.

Represents a resolved game version from the rapid versioning system.

Eight-field resource snapshot returned inside a GameStateSnapshotResult.

Snapshot of a single resource type's economy.

Functions for creating and querying EngineConfig values.

Configuration record for a BAR engine session. Controls engine launch parameters, socket communication, game setup (map, factions, opponent), and timeout behavior.

Functions for discovering and resolving BAR engine installations.

Specifies whether the BAR engine runs headless (no GUI) or with a graphical window.

The result of the full engine resolution process.

Functions for converting protobuf engine events to typed GameEvent values.

Friendly unit entry in a GameStateSnapshotResult (spec 045).

Discriminated union representing all game events that the BAR engine can emit during an AI session. Each case corresponds to a protobuf event from the HighBar V2 proxy.

A single simulation frame received from the engine, containing the frame number and all events that occurred during that frame.

Functions for creating and updating game state.

Central game state record, updated each frame from the event stream.

Per-tick atomic game-state snapshot returned by CALLBACK_GAME_GET_STATE = 15. Replaces the legacy per-unit / per-enemy / per-resource refresh loop in GameState.processEvent's GameEvent.Update branch.

LOS-visible enemy entry in a GameStateSnapshotResult. Has a concrete Health because the engine reports it.

Thread-safe caching layer for MapGrid and passability data. Avoids redundant engine callbacks by caching results using Lazy for safe concurrent access.

Functions for loading, refreshing, and querying MapGrid data. Provides terrain classification, passability analysis, and active patterns for pattern matching.

Bundled map data layers from the BAR engine, stored as 2D arrays. Contains height, slope, resource, line-of-sight, and radar data. Dimensions are in heightmap grid squares unless otherwise noted.

Elmo-coordinate query functions for MapGrid data. All functions accept world-space elmo coordinates and handle the conversion to grid indices internally.

Unit movement type for passability computation. Each type has different slope and water traversal thresholds.

Footprint of a placed own structure used as an impassable mask overlay when pathing. Consumed by both Pathing and WallIn.

A resolved path from start to goal (or a partial path under budget exhaustion).

Search budget limiting wall-clock time, node expansions, and slope weighting.

Reasons findPath can return Error.

Slope-aware A* pathing over a MapGrid with friendly-structure masking. Pure over inputs; never blocks beyond the configured budget.

Completion status of a findPath call.

Plan-consumption state. Immutable — replaced after each incremental resolve.

One structure slot in a named plan.

Strategy for picking a slot's world position during plan resolution.

Raised by Protocol.sendCallback when CallbackResponse.RequestId does not match the in-flight CallbackRequest.RequestId. Distinct from EngineDisconnectedException so callers can tell "proxy sent the wrong response" apart from "socket went away".

Raised when the HighBar proxy does not advertise a callback id that FSBar requires (currently only CALLBACK_GAME_GET_STATE = 15 from spec 045). Pre-0.1.5 proxies reject callback 15 with "Unknown callback id" and the session terminates — no legacy fallback. RequiredVersion names the minimum HighBarV2 proxy version in the message ("0.1.5").

Radar-only enemy entry in a GameStateSnapshotResult. Carries NO Health field by design — radar contacts cannot have a concrete health value and callers must never synthesize one.

Indicates how the engine was resolved.

Inputs to resolvePlan packaged so callers can pre-compute expensive values (chokepoints, metal spots) once and reuse them across successive resolve calls.

Output of resolvePlan: one record per input slot.

Generates Spring engine startup scripts from an EngineConfig.

Represents the lifecycle state of a BarClient session.

Reason a slot failed to resolve. Used for diagnostic logging and retry decisions.

A parsed Spring Map File (SMF). Structurally compatible with MapGrid so downstream primitives can consume either source without branching.

Errors surfaced by the SMF parser. Callers pattern-match for diagnostics.

Parses BAR Spring Map Files (.sd7 / .smf) from disk into an SmfMap value that downstream primitives can consume without a running engine.

Terrain classification based on height and slope data. Used to categorize map cells for AI decision-making.

A known enemy unit tracked by the game state.

A friendly unit tracked by the game state.

Functions for loading and querying unit definitions.

Cache of all unit definitions, providing instant lookup by ID or name.

Cached unit definition data loaded from the engine at initialization.

Pure connectivity predicate that shares passability rules with Pathing. Used by BasePlan.resolvePlan and directly by bots evaluating ad-hoc placements.

Query parameters controlling wouldWallIn semantics.

Why a proposed placement would wall in the base.

Result of a wouldWallIn check.