Fork RIMAPI mod and add write endpoints for agent control

[jkbennitt]

Problem

The upstream IlyaChichkov/RIMAPI mod exposes a read-only REST API on localhost:8765. RLE agents need to act — pause/unpause the game, assign jobs, draft colonists, place blueprints, set research targets. This requires forking the mod and adding write endpoints.

Required Write Endpoints (Core 8)

These are blocking for the turn-based game loop:

Endpoint	Method	Purpose
/game/pause	POST	Pause game (start of each tick)
/game/unpause	POST	Resume game (end of each tick)
/colonists/{id}/job	POST	Assign a colonist to a specific job
/colonists/{id}/draft	POST	Draft/undraft a colonist for combat
/colonists/{id}/priorities	POST	Set work type priorities
/blueprints	POST	Place a building blueprint
/designations/{id}	DELETE	Cancel a blueprint/designation
/research/target	POST	Set the active research project

Additional Endpoints (Full Coverage)

For all 16 agent action types to work:

Endpoint	Method	Purpose	Agent
/colonists/{id}/move	POST	Move/reposition a colonist	DefenseCommander
/colonists/{id}/haul	POST	Create a haul job	ResourceManager
/zones/growing	POST	Create/modify growing zone	ResourceManager
/power/toggle	POST	Toggle power on a building	ResourceManager
/colonists/{id}/research	POST	Assign colonist as researcher	ResearchDirector
/colonists/{id}/recreation	POST	Set recreation schedule	SocialOverseer
/colonists/{id}/social	POST	Assign joy activity	SocialOverseer
/colonists/{id}/bed-rest	POST	Assign to medical bed	MedicalOfficer
/medical/administer	POST	Doctor tends patient	MedicalOfficer

Technical Notes

• The upstream mod uses a producer-consumer queue pattern: HTTP requests arrive on a background thread, get enqueued, and are processed on Unity's main thread via Update(). Write endpoints inherit this thread safety.
• The Python side currently mocks all write responses in tests, so the C# fork can be developed in parallel.
• The Python client (src/rle/rimapi/client.py) already has 7 stubbed write methods raising NotImplementedError — ready to wire up once the mod is forked.

Approach

1. Fork IlyaChichkov/RIMAPI
2. Add an RLE-specific controller with the endpoints above
3. Use existing upstream services where possible (game speed, pawn edit, builder)
4. Add new Harmony patches / RimWorld API calls for novel operations (research target, growing zones, medical)
5. Test in-game with curl / Python test script

Related

• Python integration work: tracked in Implement RIMAPI write methods and wire all 16 action types #2
• Implementation plan: logical-swinging-popcorn.md in this repo

@CalebisGross — wanted to discuss approach and priority on this. This is the main blocker before we can do live testing (Phase 6). The Python side works fully with mocks through Phase 5, so this can be developed in parallel. What are your thoughts on timeline and who should own the C# work?

🤖 Generated with Claude Code

[jkbennitt]

The Python integration counterpart is tracked in #2. The dependency flow:

1. This issue (Fork RIMAPI mod and add write endpoints for agent control #1): Fork RIMAPI, add C# write endpoints
2. Implement RIMAPI write methods and wire all 16 action types #2: Wire Python client to those endpoints, update tests

#2 can start now (mock transport), but full integration testing is blocked on this.

@CalebisGross tagging you for discussion on approach and ownership.

[CalebisGross]

Research: Upstream RIMAPI Write Capability Assessment

Hey @jkbennitt — did a deep dive into the upstream RIMAPI mod before scoping the fork work, and there's some good news that significantly changes the calculus here.

Upstream Is Not Read-Only

The assumption in this issue was based on an earlier version of RIMAPI. As of v1.8.2 (last pushed Feb 21, 2026), upstream has grown to 145+ endpoints across 25 controllers, with extensive write support already in place. The mod has been through rapid iteration — 50 merged PRs since October 2025.

Mapping Our Requirements Against Upstream

Here's how the Core 8 from this issue map to what already exists:

Our Requirement	Upstream Coverage	Notes
POST /game/pause	Covered — POST /api/v1/game/speed	Set speed to 0 for pause
POST /game/unpause	Covered — POST /api/v1/game/speed	Set speed to 1/2/3 for unpause
POST /colonists/{id}/job	Partial — PawnEditService can modify skills/status	No direct "assign to job" endpoint; needs work
POST /colonists/{id}/draft	Gap	No draft/undraft endpoint exists upstream
POST /colonists/{id}/priorities	Gap	No work priority endpoint; ColonistsWorkController exists but appears read-only
POST /blueprints	Covered — POST /api/v1/builder/blueprint	BuilderService handles copy/paste/blueprint placement
DELETE /designations/{id}	Partial — POST /api/v1/order/designate/area	Designation support exists but cancellation needs verification
POST /research/target	Gap	ResearchController reads tree/progress/finished but has no write

And the Additional 9:

Our Requirement	Upstream Coverage	Notes
POST /colonists/{id}/move	Covered — POST /api/v1/pawn/edit/position	Teleport/reposition via PawnEditService
POST /colonists/{id}/haul	Gap	No direct haul job creation
POST /zones/growing	Gap	No growing zone endpoint
POST /power/toggle	Gap	No power toggle for buildings
POST /colonists/{id}/research	Gap	Tied to research target gap above
POST /colonists/{id}/recreation	Partial — POST /api/v1/pawn/edit/needs	Can set need levels but not schedule policies
POST /colonists/{id}/social	Partial — same as above
POST /colonists/{id}/bed-rest	Partial — POST /api/v1/pawn/edit/status	Status editing exists, bed assignment unclear
POST /medical/administer	Gap	No medical job creation

Bottom line: ~6 of the Core 8 are covered or partially covered upstream. The real gaps are draft/undraft, work priorities, research target, growing zones, haul jobs, and medical job creation.

Upstream Architecture (Relevant for Adding Endpoints)

The mod is well-structured for extension:

• Producer-consumer queue: HTTP requests arrive on a background thread, get enqueued, and are processed on Unity's main thread via Update() (up to 10 per frame). Any new write endpoints inherit this thread safety automatically.
• Service/Controller pattern: Each domain has an interface + service + controller. Adding a new endpoint means: write a service method that calls the RimWorld API, expose it via a controller action with a [Post] attribute. The router auto-discovers controllers via reflection.
• DI container: Services are singletons registered at startup. Standard pattern.
• Harmony 2.4 on .NET Framework 4.7.2 / Mono — no surprises here, same stack the community uses.

Three Possible Approaches

Option A — Contribute upstream (recommended)
Add the ~6 missing endpoints as a PR to IlyaChichkov/RIMAPI. The author is clearly active and receptive (50 PRs merged, no stale issues). Benefits: no fork maintenance, upstream gets better, community benefits, we stay in sync with future improvements. The missing endpoints (draft/undraft, work priorities, research target) are general-purpose enough that upstream would likely accept them.

Option B — Fork and extend
What this issue originally proposed. Gives us full control but creates a maintenance burden — upstream is moving fast and we'd need to rebase regularly.

Option C — Companion mod
Use upstream as-is for the ~10 endpoints that already work. Write a small separate RLE-specific mod that adds only the missing endpoints. Avoids forking upstream entirely while still filling our gaps. Slightly more complex deployment (two mods instead of one) but cleanest separation of concerns.

Other Findings Worth Noting

• RimAPI MCP Server (M4x28/RimAPI_MCP_Server) already exists — wraps RIMAPI's REST API for AI tool integration via MCP. Worth looking at for patterns, though our felix-agent-sdk approach is architecturally different.
• ARROM is a simpler read-only alternative mod on the Steam Workshop. Not relevant for us but confirms there's community interest in RimWorld API access.
• Helo3301's fork adds bearer token auth to RIMAPI — worth considering if we ever expose beyond localhost.
• SSE support in upstream means we could potentially move from polling to push-based state updates for the game loop. The mod publishes events for colonist actions, game state changes, incidents, map events, etc. This could improve tick efficiency significantly.
• RimWorld 1.6 (Odyssey expansion, July 2025) had some modding API changes but nothing that breaks RIMAPI's approach. Harmony 2.4 handles it fine.

Recommended Next Steps

1. Audit the actual endpoint gap — clone upstream, read the controller code, and confirm exactly which of our 17 actions need new endpoints vs. can be mapped to existing ones. Some of the "partial" items above might be fully covered with the right request body.
2. Decide on approach (A/B/C above) — I'm leaning Option A, but if we need endpoints that are too RLE-specific for upstream, Option C is a clean fallback.
3. Wire up the Python client to the endpoints that already exist — we can unblock a chunk of issue Implement RIMAPI write methods and wire all 16 action types #2 immediately, no C# work needed. The 7 stubbed write methods in client.py can start being implemented against upstream's existing API.
4. Prototype SSE integration — the push-based event stream could replace our polling pattern and give us richer game state awareness.

What are your thoughts? Happy to start on the upstream audit or the Python client wiring — both can proceed in parallel.

[jkbennitt]

Decision: Option A — Contribute Upstream

Great research @CalebisGross. Going with Option A (contribute upstream PRs). But after auditing the actual C# source code, your gap list needs a correction — the gaps are smaller than you estimated.

Work Priorities & Time Assignment Exist Upstream

You flagged work priorities and time assignment as gaps, but they're actually implemented in PawnController.cs (not the empty ColonistsWorkController.cs):

• POST /api/v1/colonist/work-priority — {"id": int, "work": string, "priority": int} (single)
• POST /api/v1/colonists/work-priority — {"Priorities": [...]} (bulk)
• POST /api/v1/colonist/time-assignment — {"PawnId": int, "Hour": int, "Assignment": string}

These are in the PawnController, which also has SetTimeAssignment, MakeJobEquip, etc. The ColonistsWorkController is an empty shell — looks like the author moved the endpoints but kept the class.

Corrected Gap List (Only 5 real gaps)

Need	Status
Work priorities	EXISTS — POST /api/v1/colonist/work-priority
Draft/undraft	EXISTS — POST /api/v1/pawn/edit/status with IsDrafted
Time assignment	EXISTS — POST /api/v1/colonist/time-assignment
set_research_target()	GAP — ResearchController is read-only
set_colonist_job()	GAP — only jobs/make/equip exists
haul_resource()	GAP
set_growing_zone()	GAP — read exists at /api/v1/map/zone/growing
toggle_power()	GAP — read exists at /api/v1/map/power/info
assign_bed_rest()	GAP
administer_medicine()	GAP

Immediate Next Steps

1. Now: Wiring the Python client to all existing upstream endpoints (pause, draft, move, work priorities, time assignment, blueprints, designations). This unblocks the core game loop.
2. Then: Submit upstream PRs for the 5 real gaps, starting with set_research_target (simplest — just Find.ResearchManager.SetCurrentProject()).

The upstream author is clearly active (50 PRs merged since Oct 2025), so contributing should be smooth.

🤖 Generated with Claude Code

[jkbennitt]

Update: Fork Created + Python Client Wired

Fork: https://github.com/AppSprout-dev/RIMAPI

Python client wired (commit 887fdcf): All existing upstream write endpoints are now connected — pause/unpause, draft/undraft, work priorities, move colonist, blueprints, time assignments, area designations. 202 tests passing.

Remaining gaps to contribute upstream (in priority order):

1. POST /api/v1/research/target — set active research project
2. POST /api/v1/pawn/job — generic job assignment (haul, tend, etc.)
3. POST /api/v1/map/zone/growing — create/modify growing zones
4. POST /api/v1/building/power — toggle power on buildings
5. POST /api/v1/medical/tend — medical job creation (bed rest + administer)

Starting with #1 (research target) — simplest endpoint, one-liner in RimWorld API.

🤖 Generated with Claude Code

[jkbennitt]

Live Game Testing Complete — Fork Build Deployed

Bypassed the upstream PR wait by merging all 3 feature branches into AppSprout-dev/RIMAPI:rle-testing, building the DLL, and deploying over the Workshop install.

All 6 fork endpoints verified in-game (RimWorld 1.6.4633)

Endpoint	Status	Notes
POST /api/v1/research/target (PR #52)	PASS	Requires Content-Length header (empty body works)
POST /api/v1/map/building/power (PR #53)	PASS	Correct error for non-existent buildings
POST /api/v1/map/zone/growing (PR #53)	PASS	Created potato zone, visible in-game. Plant def must be Plant_Potato format
POST /api/v1/pawn/job (PR #54)	PASS	Moved colonist to target position via Goto job
POST /api/v1/pawn/medical/tend (PR #54)	PASS	Auto-selected best doctor by Medicine skill
POST /api/v1/pawn/medical/bed-rest (PR #54)	PASS	Assigned patient to bed rest

Key integration finding: SnakeCaseContractResolver

All request bodies must use snake_case field names — RIMAPI's ReadBodyAsync uses SnakeCaseContractResolver (Newtonsoft.Json). E.g., pawn_id not PawnId, patient_pawn_id not PatientPawnId. Integer IDs required (not strings).

5-tick live benchmark

6 LLM agents (Nemotron 3 Nano 4B) controlling a Crashlanded colony:

• 41 total actions, 36 executed (87% rate)
• Composite score: 0.705, all colonists alive
• Remaining failures are agent prompt issues, not endpoint issues (tracked in Fix agent action failures from live game testing #5)

What's left on this issue

• Upstream PRs #52, #53, #54 reviewed and merged by @IlyaChichkov (posted live test results on each)
• Swap back from fork DLL to official Workshop release after merge
• Delete rle-testing branch

@CalebisGross — RIMAPI integration is done. The fork is our bridge until upstream merges. Prompt/action quality work is in #5.

🤖 Generated with Claude Code

[jkbennitt]

PR #52 Merged Upstream

Ilya merged the research target endpoint into RIMAPI develop. He also:

• Opened issue #55 on RIMAPI to document the SnakeCaseContractResolver finding we reported
• Thanked us for the contribution and testing details

PR #53 Update

Ilya reviewed and requested changing growing zone from cell list to rect coordinates (PointA/PointB). Updated and force-pushed. Python client updated in commit ce3edb4.

PR #54 Update

Ilya asked us to join the RIMAPI Discord to sync with another contributor working on similar features. Also noted that "Haul" isn't a valid JobDef — he added /api/v1/def/all to expose all valid defs. Rebased onto latest develop.

Both PRs rebased onto latest develop (which now includes PR #52 + Ilya's new Bruno collection and def endpoint).

Updated checklist

• PR #52 (research target) — MERGED
• PR #53 (power + zones) — updated per review, awaiting re-review
• PR #54 (jobs + medical) — rebased, awaiting review after Discord sync
• Swap back to Workshop DLL after all merge
• Delete rle-testing branch

🤖 Generated with Claude Code

[jkbennitt]

All Upstream PRs Merged — Fork No Longer Needed

Every endpoint we needed is now in upstream RIMAPI develop:

PR	Endpoint	Status
#52	POST /api/v1/research/target	MERGED
#53	Power toggle + growing zones (rect coords)	MERGED
#54	Job assignment + medical tend/bed-rest	MERGED
#60	Fix growing zone 500 on occupied cells	MERGED

Fork status: AppSprout-dev/RIMAPI:rle-testing is now 0 commits ahead of upstream develop. DLL deployed from pure upstream build. Once Ilya cuts a release, we switch back to Steam Workshop auto-updates.

One remaining upstream bug: POST /api/v1/colonists/work-priority (bulk endpoint) has a NullRef deserialization issue — filed as IlyaChichkov/RIMAPI#61. We use the singular endpoint as a workaround, which works correctly.

Checklist

• PR #52 (research target) — merged
• PR #53 (power + zones) — merged
• PR #54 (jobs + medical) — merged
• PR #60 (growing zone fix) — merged
• Deploy fork DLL for local testing — done, now pure upstream
• Upstream bug #61 (bulk work-priority NullRef) — workaround in place
• Switch to Workshop DLL when Ilya cuts next release
• Delete rle-testing branch after Workshop release

This issue can be closed once the Workshop release drops.

🤖 Generated with Claude Code