Visitor Relay: a public API consumer#

The optional SimLOD Visitor Relay package provides one persistent three-person contact reached from a buildable relay in Architect → Misc. Enable SimLOD, SimLOD Example: Expedition, then SimLOD Visitor Relay. Build the relay for 20 wood, select it and choose Visitor contact. Developer mode is not required.

Choose Invite team, close the window and unpause. Arrivals progress through the framework's ordinary native queue. Send visitors away retains the actual individuals and their possessions; inviting again returns those same bodies. Every relay reaches the same world contact, including a replacement built after the first relay is destroyed. This pilot does not provide trading, rewards, travel, visitor Lord behavior or a balance progression. The borrowed comms-console graphic is resolved from the installed Core resources and is not distributed in the package.

If an encounter cannot finish, correct its blocker and Resume visit, or Review interrupted visit. Review preserves the observed deaths, transfers, deployed visitors and retained individuals. Confirm outcomes commits those observations once; it does not move visitors. Changed observations require Update observed outcomes before confirming again. After a partially completed departure is settled, Send visitors away creates a fresh departure key for the remaining deployed members.

The roster is explicitly labelled Last committed roster. A prepared death can still show the former committed state there; Proposed outcomes shows the observations awaiting confirmation. Failed invitation admission preserves the previous visit number and saved receipt keys.

The window pauses the game. Close it and unpause to advance queued work or let overdue abstract updates catch up. While away, retained Pawns receive no automatic Pawn ticks and continue to cost native memory. Chronological age and other global-time-derived properties may advance. Expedition supply credits are abstract accounting, not inventory food or native starvation. See the expedition contract.

Independent package and saved intent#

Consumers/SimLOD.VisitorRelay/Source/SimLOD.VisitorRelay.csproj references the staged framework DLL. It has no project reference, framework source link, friend access or CLR dependency on the Expedition assembly. The test consumer fixture is likewise compiled against packaged DLLs without framework internals. The provider's schema-1 payload and model version are an explicit integration contract; a different provider with similar fields is not interchangeable.

The consumer owns a separate saved VisitorContact WorldComponent: entity ID, visit number, phase, destination, monotonic departure/preparation counters, and current request/settlement keys. The framework owns authoritative population, operation history, native identities and ownership. Consumer updates observe receipts; they never invoke an internal queue pump. Removing the Expedition package while keeping the framework and relay enabled preserves both roots. Restoring the matching provider lets pending queued work continue; faulted or prepared work still requires explicit recovery or settlement.

Keep the framework and consumer enabled in saves containing their state. Provider removal is tested; removing a consumer that owns a native WorldComponent is a different save operation and does not promise to preserve its encounter metadata. No uninstall conversion is supplied.

The API addition is GetNativeOperation(EntityId entity, string requestKey). It returns the same immutable receipt shape as GetNativeOperations(entity) and throws KeyNotFoundException for an unknown entity/key pair. Use the indexed lookup for current encounter progress. Listing the full operation history allocates every matching receipt and is intended for inspection. Both require the normal main-thread, non-reentrant framework call context.

Reproduce integration validation#

./tools/build.ps1
./tools/test-visitors.ps1 -Profile Core
./tools/test-visitors.ps1 -Profile Royalty
./tools/test-visitors.ps1 -Profile Biotech
./tools/test-visitors.ps1 -Profile AllDlc
./tools/test-visitors.ps1 -Profile Frameworks
./tools/test-visitors.ps1 -Mode churn -Profile Core

The launcher copies the installed game and selected packages into a fresh temporary profile. Lifecycle tests use developer mode disabled, normal queue updates, partial arrival/provider removal/incompatibility/restoration, partial departure reload, prepared death settlement reload, repeated commit, a second departure after settlement, transfer and relay replacement. Frameworks copies the installed Harmony, HugsLib and Vanilla Expanded Framework inputs; its audit pins their assembly and About hashes. The exact loaded mod list is verified in each saved file. These are sampled lifecycle configurations, not blanket compatibility claims.

The churn mode runs 500 return visits with every fifth arrival settled after one member, then waits until at least three native game days have elapsed. It uses actual unpaused game updates at native Ultrafast speed, the same three Pawn identities, saves/reloads at checkpoints, and an independent piecewise supply integral. The scale fixture places its relay away from initial colony drop pods and gives all spawned map Pawns native Wait jobs. It disables storyteller events and automatic speed slowdowns, and sets automatic saving to 1,000 days while taking explicit checkpoint saves; native Pawn/world ticks continue. These workload controls run outside measured queue work and prevent ambient movement from occupying reserved cells. Lifecycle profiles hold only the test visitors. Raw work, storage, lookup and load measurements are retained. Run timing measurements sequentially without other game fixtures. See the compatibility/support policy and implementation status for the selected evidence.

Candidate installation and text scope#

Dependency metadata links to the public project. Enable the framework before the Expedition provider and relay, then restart RimWorld. The provider is an optional CLR dependency so a saved contact can survive its absence; a fresh contact explains that the provider must be enabled. The framework itself is mandatory.

The candidate ships English text. Def labels can be translated through RimWorld Def-injected translations; the relay window and diagnostics currently use English literals. Full keyed localization is not claimed for 1.0. Native blueprint/frame/material/completion paths are exercised with developer mode off; the fixture supplies resources and completes work through native methods, so it is not a test of colonist hauling or construction job timing.

Native visit behavior in 1.0#

The relay assigns its factionless visitors a saved native defend-point duty near the invitation anchor. They can walk and satisfy ordinary needs, rather than falling through to the neutral guest exit-map job. On return a native Pawn-lost notification removes them from the consumer-owned Lord and disposes of the group when empty. Pawns with another faction, Lord, map or native holder are not reassigned. Provider removal preserves the existing native Lord along with saved visit intent. Rebuilding a relay reconnects the contact; the current visit remains anchored at its original invitation position.

This closes a beta failure where an unassigned visitor disappeared during a longer ordinary visit. It cannot reconstruct a Pawn already lost in an older save. Mental states, forced map exits, foreign ownership and unusual native injuries remain explicit recovery cases; this pilot is not a full hospitality or recruitment system.