IlyaChichkov ecosystem integration — HeadlessRim, dashboard, SSE

[jkbennitt]

Context

While waiting for upstream RIMAPI PRs (#52, #53, #54) to merge, we researched IlyaChichkov's full GitHub ecosystem. Three of his projects have direct value for RLE, and there are several contribution opportunities.

Workstreams

HeadlessRim — Headless Benchmark Infrastructure (HIGH)

Repo: IlyaChichkov/HeadlessRim

Harmony patches that decouple RimWorld from Unity rendering/audio. Enables server-side execution with Docker support. If compatible with RIMAPI, this unlocks:

• Automated benchmarks without GPU/display
• CI/CD integration testing via GitHub Actions
• Batch scenario runs across multiple configs
• Docker containerization for reproducible environments

SSE Integration — Event-Driven State Updates (MEDIUM)

RIMAPI has Server-Sent Events support publishing game events in real-time. Currently RLE polls via REST each tick. SSE could supplement or replace polling for richer, faster state awareness.

rimapi-dashboard — Livestream Overlay (LOW priority, HIGH demo impact)

Repo: IlyaChichkov/rimapi-dashboard

React dashboard consuming RIMAPI live. Could be extended with RLE-specific widgets: agent decision log, conflict resolution view, composite score timeline. Perfect for the AppSprout livestream overlay.

MCP Server Gap (FUTURE)

No one has built a proper RIMAPI MCP server. An official one would let any MCP-compatible AI control RimWorld — great community contribution opportunity.

Tasks

• Evaluate HeadlessRim compatibility with RIMAPI (clone, read Harmony patches, check if Find.Maps/Find.ResearchManager survive headless mode)
• Prototype SSE listener in Python client alongside REST polling
• Fork rimapi-dashboard, add RLE agent activity widgets
• Explore MCP server gap — assess if worth building
• Engage Ilya: comment on HeadlessRim introducing RLE, invite to AppSprout Discord

Background

Ilya is an embedded/systems engineer (MIET student) with 65 public repos and deep RimWorld modding expertise but no AI/ML background. RLE is the first AI project building on his infrastructure — a compelling story for both sides. He's been very responsive on our RIMAPI PRs (responded same day).

🤖 Generated with Claude Code

[jkbennitt]

Research Findings

HeadlessRim Evaluation

Repo structure: Dockerfile + entrypoint.sh only — no C# Harmony patch source files in repo. The "headless" approach uses:

• Xvfb virtual framebuffer (:99 at 1280x720) — not truly GPU-free but lightweight
• RimWorld flags: -batchmode -nographics -noshaders -force-opengl
• Dummy audio driver (SDL_AUDIODRIVER=dummy)
• Debian bookworm-slim base image with Mesa software rendering

RIMAPI integration: Explicitly designed for it. README says "interaction with the game is handled via RimAPI". Docker compose exposes port 8765.

Open questions (asked in IlyaChichkov/HeadlessRim#1):

1. Do Find.Maps, Find.ResearchManager, etc. survive headless mode?
2. Where are the Harmony patches (precompiled assembly)?
3. Auto-loading saves without UI?
4. Max tick speed headlessly?

RIMAPI SSE Event System

SSE is well-implemented. Events published via Harmony hooks:

Event Type	Source	What It Fires On
game_state	GameStateHooks	Game load, new game, save, exit, settings change
letter_received	IncidentHooks	Raids, events, quest letters
message_received	IncidentHooks	In-game messages
colonist_ate	ColonistsHooks	Pawn eats food
colonist_crafted	ColonistsHooks	Pawn completes recipe
colonist_bill_work	ColonistsHooks	Pawn works on bill
colonist_died	ColonistsHooks	Pawn death
colonist_mental_break	ColonistsHooks	Mental break starts
pawn_entered_map	MapEventsHooks	Pawn spawns/enters
pawn_killed	MapEventsHooks	Pawn killed by another
plant_harvested	MapEventsHooks	Plant harvested
fog_revealed	FogGridHook	Map fog cleared
log_message	DevToolsHooks	Debug log entries
heartbeat	SseService	Every 3 seconds with current tick

RLE opportunity: The letter_received event is gold — it fires on raids, toxic fallout, plague, etc. Our agents could react to incidents in real-time via SSE instead of discovering them on the next poll. colonist_died and colonist_mental_break would directly feed MedicalOfficer and SocialOverseer.

SSE endpoint: GET /api/v1/events/stream (text/event-stream). Python client would use httpx-sse or aiohttp SSE client.

🤖 Generated with Claude Code

[jkbennitt]

Dashboard Evaluation

Fork: https://github.com/AppSprout-dev/rimapi-dashboard

Tech stack: React 19 + TypeScript, react-grid-layout (drag-drop widgets), Chart.js, Three.js (3D map), craco, bun

Existing widgets (8):

• ColonistCard, ColonySummary, GameInfoCard, DashboardResearchCard
• FactionRelationsCard, MessageFeedCard, SseStatusCard, TopIncidentsCard
• Plus: full 3D world map, caravan tracking, map viewer

SSE already integrated: sseService.ts is a singleton that connects to /api/v1/events with auto-reconnect. Existing widgets consume events. This means adding RLE widgets that react to game events is straightforward.

Extensibility: Widget pattern is simple — each is a standalone .tsx + .css pair registered in the dashboard layout. Adding an "Agent Activity" widget would follow the exact same pattern.

RLE widgets to add:

1. AgentDecisionLog — real-time feed of agent ActionPlans (role, actions, confidence)
2. ConflictResolutionView — shows when agents conflict on same pawn, who won
3. CompositeScoreTimeline — Chart.js line chart of the 8 scoring metrics over time
4. HelixPhaseIndicator — current macro helix position (exploration/analysis/synthesis)

These would consume a WebSocket or SSE feed from the RLE Python orchestrator, separate from the RIMAPI SSE stream.

---

MCP Server Gap Assessment

Status: No RIMAPI MCP server exists publicly.

Searched GitHub, MCP Registry (registry.modelcontextprotocol.io), mcpservers.org, PulseMCP (12,230+ servers indexed) — zero results for RimWorld or RIMAPI.

Effort estimate:

• Minimal (4-8 hours): FastMCP Python framework + wrap 10-15 high-level RIMAPI tools grouped by domain
• Moderate (2-3 days): Custom error handling, session state, RLE-specific tool design, docs, registry submission

Existing patterns: Godot-MCP, Unity-MCP, Unreal-MCP all exist. REST → MCP wrapper is a well-documented pattern. FastMCP framework (now part of official Python MCP SDK) handles schema generation.

Recommendation: Worth building as a community contribution AFTER RLE core is stable. Not urgent for RLE itself (direct HTTP is faster), but would let any MCP-compatible AI (Claude Desktop, etc.) play RimWorld out of the box.

---

Summary — All 5 Tasks Addressed

• HeadlessRim evaluation — Docker + Xvfb approach, RIMAPI compat questions asked (HeadlessRim#1)
• SSE research — 14+ event types mapped, letter_received and colonist_died directly useful
• Dashboard fork + evaluation — forked, widget system assessed, 4 RLE widgets spec'd
• MCP gap assessment — confirmed no server exists, effort estimated, recommended as future work
• Engage Ilya — HeadlessRim#1 opened, 3 RIMAPI PRs in review

🤖 Generated with Claude Code

[jkbennitt]

SSE Client Implemented

Commit ed90f39 adds RimAPISSEClient — an async SSE listener that connects to RIMAPI's /api/v1/events endpoint and buffers game events in real-time.

What it does:

• Connects to SSE stream with auto-reconnect (exponential backoff)
• Buffers events in a thread-safe deque (max 500)
• GameStateManager drains buffer each tick → pending_events, has_event(), get_events()
• Callback registration via sse.on("letter_received", handler)
• Type-filtered draining: drain_by_type("letter_received", "colonist_died")

Event types supported (from upstream Harmony hooks):

• Incidents: letter_received, message_received (raids, toxic fallout, plague)
• Colonist: colonist_died, colonist_mental_break, colonist_ate, colonist_crafted
• Map: pawn_entered_map, pawn_killed, plant_harvested
• System: heartbeat (every 3s with tick count), game_state, connected

Impact: Agents can now react to raids/deaths/mental breaks the instant they happen instead of discovering them on the next poll cycle. DefenseCommander sees letter_received with raid data immediately; MedicalOfficer sees colonist_died without waiting.

Updating checklist:

• Evaluate HeadlessRim for headless benchmark support
• Prototype SSE listener in Python client alongside REST polling ← done
• Fork rimapi-dashboard, add RLE agent activity widgets
• Explore MCP server gap — assess if worth building
• Engage Ilya: comment on HeadlessRim, invite to AppSprout Discord

🤖 Generated with Claude Code

[jkbennitt]

Dashboard + Live Game Integration Complete

What shipped

RLE Python side (commits 10e8659 → 1f3bb44):

• Game loop writes latest_tick.json each tick via dashboard_export_dir param
• State adapters rewritten to use real RIMAPI data (resources, incidents, weather, mood, food)
• CORS-enabled file server (scripts/serve_dashboard.py) on :9000
• System prompt updated for data limitations (skills/traits not available from RIMAPI)

Dashboard (feature/rle-widgets branch on AppSprout-dev/rimapi-dashboard):

• 5 new RLE widgets: Agent Decisions, Agent Status, Helix Phase, Score Timeline, Conflict Resolution
• useRleTickData hook polls :9000/latest_tick.json every 2s
• Wired into DashboardCardRegistry + CARD_DEFINITIONS (add via + button)
• Chart.js score timeline with 8 metrics + composite over ticks

Live test results

Before (hardcoded state): Composite 0.706, flat metrics, agents made repetitive decisions

After (real RIMAPI data): Composite 0.843, metrics actually move between ticks:

• food_security: 0.500 → 0.950
• mood: 0.500 → 0.606
• efficiency: 0.888 → 0.968
• self_sufficiency: 0.333 → 0.667

How to run the full stack

1. RimWorld + RIMAPI mod on :8765
2. LM Studio + Nemotron 3 Nano 4B on :1234
3. python scripts/run_scenario.py crashlanded_survival --provider openai --model unsloth/nvidia-nemotron-3-nano-4b --base-url http://localhost:1234/v1 --no-think --visualize --output results/live/ --ticks 10
4. python scripts/serve_dashboard.py results/live
5. cd rimapi-dashboard && bun run start
6. Open localhost:3000, add the 5 RLE widgets

Remaining from issue #4

• HeadlessRim evaluation (Docker-based headless RimWorld for CI)
• MCP server gap exploration
• Engage Ilya on HeadlessRim

Dashboard and SSE integration tasks from this issue are complete.