RimBridgeServer

RimBridgeServer is a RimWorld mod that turns the running game into a bridge an external tool can use.

In practice, that means a test harness, developer tool, or AI agent can start RimWorld, inspect live game state, drive built-in UI, manage mods and mod settings, execute debug actions, take targeted screenshots, and verify behavior against the real game instead of a simulation.

This project is aimed at automated mod development and testing:

• integration testing against a real RimWorld session
• UI and UX verification through semantic dialogs, targets, and screenshots
• faster repro loops for debug actions, saves, settings, and load-order changes
• AI-assisted mod development through GABS or direct bridge connections

Architecture and design notes live in docs/architecture.md, docs/lua-frontend-design.md, docs/semantic-state-design.md, and docs/attention-policy.md.

What It Does

RimBridgeServer runs inside RimWorld and exposes a tool surface for:

• reading game, map, camera, selection, notification, and UI state
• driving high-level game actions such as debug actions, main tabs, Architect designators, and selection changes
• changing mod settings and mod load order
• capturing screenshots, including clipped screenshots for known UI or screen targets
• running small automation scripts through JSON or Lua front-ends

It is designed to stay as close as possible to RimWorld's own logical seams instead of reimplementing gameplay logic outside the game.

Installation

Recommended: Use GABS

GABS is the best way to use RimBridgeServer from an AI or automation harness.

Why this is the recommended mode:

• GABS can start and stop RimWorld for you
• GABS can discover the live bridge tool surface after the game connects
• you do not need to manage ports or tokens manually
• this is the cleanest setup for autonomous mod testing

Basic setup:

1. Install RimBridgeServer into your RimWorld Mods folder.
2. Enable RimBridgeServer in RimWorld's mod list.
3. Install and configure GABS.
4. Start RimWorld through GABS and connect to the running game.

Once RimWorld is up, GABS exposes the game-management tools (games.start, games.connect, games.call_tool) and then the live RimBridgeServer tool surface behind them.

RimBridgeServer now also publishes blocking attention when severe async failures happen after a call boundary, such as hard log errors or failed bridge operations. In GABS this surfaces through games.get_attention and games.ack_attention: ordinary game calls pause until the attention item is reviewed and acknowledged, while rimbridge/get_bridge_status, rimbridge/list_operation_events, and rimbridge/list_logs remain available for diagnosis. The current built-in policy is documented in docs/attention-policy.md.

RimWorld Mod Debugging Stack

If you want the same stack used for real mod repro-and-fix sessions, use:

1. Harmony plus the mod you are testing
2. RimBridgeServer inside RimWorld for live game inspection and control
3. GABS to launch RimWorld and surface the live tools to your AI client
4. DecompilerServer to inspect Assembly-CSharp.dll and related managed code while debugging

There is a short setup order here: docs/rimworld-mod-debugging-stack.md.

Direct Mode

Direct mode still works if you do not want to use GABS.

Basic setup:

1. Install RimBridgeServer into your RimWorld Mods folder.
2. Enable RimBridgeServer in RimWorld's mod list.
3. Start RimWorld normally.
4. Read the RimWorld log for the bridge startup lines.

In direct mode, RimBridgeServer logs lines like:

[RimBridge] GABP server running standalone on port 5174
[RimBridge] Bridge token: 

... [View full README on GitHub](https://github.com/pardeike/RimBridgeServer#readme)