panel/modules/empyrion-bridge/README.md

panel-empyrion-bridge

A small .NET 8 ASP.NET Core sidecar that proxies Empyrion's native Mod API (TCP/protobuf-net) into a JSON REST surface for the panel dashboard.

Why this exists

Empyrion's only first-class admin tool is a Windows-only desktop app (Empyrion Admin Helper / EAH) speaking protobuf-net to an in-process mod called EPM. Re-implementing protobuf-net contract decoding in Go is a losing battle — every Empyrion update could shift [ProtoMember] tags.

Instead, this bridge:

• References Eleon's Mif.dll directly (the official mod-API SDK).
• Re-uses EPMConnector (TCP framing + protobuf-net dispatch) by compiling its source files in.
• Exposes a thin REST API the panel calls.

Build

docker build -t panel-empyrion-bridge:latest modules/empyrion-bridge

Run

The bridge needs network reach to wherever EPM is listening on each Empyrion instance. On a single-host setup with network_mode: host empyrion containers, hostname 127.0.0.1 works:

docker run -d --name panel-bridge --network host \
  -e BRIDGE_URLS=http://127.0.0.1:8090 \
  panel-empyrion-bridge:latest

For multi-host setups, pass each Empyrion's LAN IP + EAH_API_PORT in the query string per request.

API (Phase 2 — read-only)

All endpoints take ?host=…&port=… query parameters identifying the Empyrion EPM instance.

Method	Path	Returns
GET	/healthz	bridge health + version
GET	/api/v1/factions	[{ origin, factionId, name, abbrev }]
GET	/api/v1/players	{ playerIds: [int], count }
GET	/api/v1/players/{id}	full PlayerInfo (raw protobuf-net contract)
GET	/api/v1/playfields	{ playfields: [name] }
GET	/api/v1/playfields/{name}/entities	{ entities: [...] }
POST	/api/v1/console	fire-and-forget; body is the console line

POST /api/v1/console is currently EXPERIMENTAL — see "Known issues" below.

Known issues / Phase 3+ work

• Console command cmd-byte truncation suspected. Empyrion's CmdId enum has grown past 255 entries; the legacy EPMConnector.ModProtocol writes cmd as a single byte, which means commands with id > 255 alias to other commands. Symptom seen: sending Request_ConsoleCommand shows up on the EPM side as Event_ChatMessageEx. Fix: extend the protocol encoding to use a UInt16 cmd OR build a tested mapping table from Mif.dll's CmdId enum values. Tracked for Phase 3.
• Authentication. EPM has none. The bridge currently has none either. Before exposing any port to the WAN, add a shared-secret bearer token matching the panel's existing service-API pattern.
• Streaming events. Right now unsolicited Event_* packages (chat, player join, etc) are dropped. A GET /api/v1/stream SSE endpoint will fan these out to subscribers in Phase 4.
• Connection persistence. The pool reaps idle connections after 5 minutes. If Empyrion restarts, we don't yet auto-reconnect; the next request opens a fresh connection but in-flight requests fail. Phase 5.

Source layout

empyrion-bridge/
  bridge/                  ASP.NET Core minimal API project
    Bridge.csproj
    Program.cs             endpoint definitions
    BridgePool.cs          per-(host,port) connection cache
    BridgeConnection.cs    request/response correlation by (seq, expectedCmd)
    EPMConnector/          source files compiled in (from MichaelGoulding/sample-empyrion-mod, MIT)
  lib/
    Mif.dll                Eleon Modding SDK reference
  Dockerfile               multi-stage build, alpine runtime

Verified end-to-end on 2026-04-30

curl 'http://<agent-host>:8090/api/v1/factions?host=127.0.0.1&port=7028'
→ {"factions":[{"origin":1,"factionId":1,"name":"Human","abbrev":"Hum"}]}