Simulation Framework
Get v1.3 ↗

Build and inspect SimLOD#

The framework starts empty. The optional synthetic example adds three provider types and a developer action; it does not automatically create entities or alter existing pawns/maps. Its command meter is a source/API example; the developer creation action still creates the counter and accumulator only.

Build#

Prerequisites: the installed RimWorld 1.6 managed assemblies and .NET SDK 8.0.424. The game-facing libraries target net472; the standalone test runner targets net8. Copy local.props.example to the ignored local.props if the game lives elsewhere. No game assembly is copied into the packages.

From the repository root in PowerShell:

./tools/build.ps1

This builds the framework, separate examples, the public API consumer and test-only fixtures; runs the standalone tests; and stages six strictly checked packages under artifacts/SimLOD, artifacts/SimLOD.Example.Synthetic, artifacts/SimLOD.Example.Herds, artifacts/SimLOD.Example.Expeditions, artifacts/SimLOD.VisitorRelay, and artifacts/SimLOD.SurveyRelay, plus ZIPs and the MIT license. Fixtures are not shipped. The consumer compiles against the staged framework DLL. It also packages SimLOD.ProviderStarter.zip as source and checks a fresh extraction outside the checkout. The starter ZIP needs its own build before installation. The build does not install or enable anything in the real game.

Install 1.3#

Download the packages and checksums from the 1.3 GitHub release, or build this checkout with the command above. The documentation website provides a guided starting point. Extract each selected ZIP so the game sees Mods/SimLOD/About/About.xml (and the equivalent path for each optional package), with no extra nesting or duplicate versions. Enable SimLOD → SimLOD Example: Expedition → SimLOD Visitor Relay, then restart RimWorld. For the independent survey pilot, enable SimLOD → SimLOD Survey Relay. Use matching packages; the synthetic example now requires the 1.3 command API. The synthetic/herd packages are optional laboratories and are not required for either relay or Frontier.

Version 1.3 saves accepted command receipts and pause intent in archive 4. Formats 1–3 load without command history; formats 1–2 default to unpaused. Paused surveys stop reports and catch up missed hours when resumed. Completed surveys pause automatically while their history remains saved. Keep a pre-upgrade backup if you need to return to older framework versions; they preserve the newer archive as blocked. The actual published 1.2 DLL was checked against a native-generated archive 4 and refused it without rewriting its bytes.

Command consumers use the provider-command contract. A consumer supporting old frameworks must detect the public SimLOD.API.ProviderCommandContract.Version literal by name before loading command-dependent types; CLR assembly identity remains 0.1.0.0. Frontier's local dependency and integration responsibilities are described in the 1.3 handoff. Steam publication is not required for this local dependency.

Keep a pre-upgrade save backup. Replace complete package folders between game sessions; do not combine DLLs from different builds. Restore a missing provider in the mod list and reload the preserved save. Never remove the framework or consumer and save over the only copy of a world that contains their state. Ordinary relay construction and recovery are described in the consumer guide.

Developer use#

For an ordinary gameplay entry point, enable SimLOD, its Expedition example provider and Visitor Relay, build the relay under Misc and choose Visitor contact. The consumer guide explains inviting, returning and resolving a visit without developer mode.

Use a separate test installation/profile and a disposable save for candidate acceptance. Enable SimLOD, optionally followed by SimLOD Example: Synthetic. In RimWorld developer actions, the SimLOD category provides:

  • Create synthetic examples (example mod): creates one randomized counter and one logical-time accumulator.
  • Inspect abstract entities (framework): shows IDs, providers, status, schema, model, revision, logical/deadline ticks and RNG state.
  • Log abstract entity diagnostics (framework): writes the same summary to Player.log.
  • Inspect native ownership and recovery (framework): choose an entity to inspect member owners, pins, pending work and recovery blockers. The guarded retry button becomes available only when preflight allows it.

Let time advance, save and reload; the records continue from their saved deadlines. Without the example mod, its saved entities become ProviderMissing and remain preserved. Restoring it makes compatible records eligible to resume. Dependencies link to the public project; the native dependency and load-order checks are part of acceptance.

Begin provider authoring with the standalone starter and concise guide, then use the abstract API reference. UI text and language contributions are covered by localization. The implementation status states exactly what has been validated and what remains unimplemented.

The optional SimLOD Example: Herd Laboratory adds developer actions under SimLOD laboratory: create 31 disposable Muffalo, reconcile the latest herd, and inspect native members. Healthy eligible anonymous fixture returns are permanently discarded and added to the aggregate; named/injured/pinned returns preserve the actual Pawn. Use a disposable save. Unknown mods or active DLC disable destructive aggregation in this provider. The pawn lifecycle API guide covers retained rematerialization, request keys, failures and explicit recovery. The recovery window diagnoses, retries and prepares explicit settlements; it does not force native ownership changes.

The optional SimLOD Example: Expedition adds actions under SimLOD expedition: Create three-member expedition, Deploy latest expedition, Return latest deployed members, and Inspect supplies and roster. Create, deploy, return, let time advance, save/reload and deploy again. The same native NPCs and possessions return. The initial reserve is 12 person-days; only uncreated/retained members consume abstract credits. Credits do not create inventory food or impose native starvation effects. See the expedition contract for time and conservation semantics.

Version 0.4 also provides Queue latest expedition deployment and Queue latest expedition return. These admit work immediately and perform one member operation per unpaused update. Pause and save midway, reload, then unpause to continue. Inspect queued/synchronous mode and progress in the recovery window. Faulted queued work requires explicit Resume queued work after its blockers are corrected. See the queued API and timing contract.

Version 0.5 adds Prepare settlement and Commit settlement in the recovery window. Review observed outcomes, save if desired, then commit. A changed owner blocks a stale commit; preparing a new key preserves the earlier attempt as superseded. See the settlement contract.

Retained Pawns receive no automatic Pawn ticks. Health, needs and biological aging are not actively simulated by the holder; chronological age and other native properties derived from global time can still advance.

Automated validation#

dotnet run --project Tests/SimLOD.ModelTests/SimLOD.ModelTests.csproj -c Release
./tools/test-game.ps1
./tools/test-game.ps1 -Suite pawns
./tools/test-game.ps1 -Suite expedition -TimeoutSeconds 900
./tools/test-game.ps1 -Suite expedition -RenderUI -TimeoutSeconds 900
./tools/test-game.ps1 -Suite benchmark -TimeoutSeconds 900
./tools/test-game.ps1 -Suite queue -RenderUI -TimeoutSeconds 600
./tools/test-game.ps1 -Suite settlement -RenderUI -TimeoutSeconds 600
./tools/test-game.ps1 -Suite queueschema -TimeoutSeconds 300
./tools/test-game.ps1 -Suite queuebenchmark -TimeoutSeconds 600
# Supply an actual archived 0.3, 0.4 or 0.5 expedition save for the upgrade fixture:
./tools/test-game.ps1 -Suite legacy -LegacySavePath 'C:\path\to\archived\SimLODExpedition.rws'
# Or use the checked-in, checksummed native save fixtures:
./tools/test-upgrades.ps1
./tools/test-upgrades.ps1 -VerifyOnly
./tools/test-visitor-upgrades.ps1
./tools/test-api.ps1 -NegativeControl
./tools/test-starter.ps1
./tools/test-beta.ps1 -Suite Starter
./tools/test-survey-upgrade.ps1
python tools/verify-localization.py --negative-control
./tools/test-beta.ps1 -Suite Colony -PseudoLocalization
./tools/test-beta.ps1 -Suite Survey
./tools/test-beta.ps1 -Suite Command
./tools/test-beta.ps1 -Suite Command -Profile AllDlc
./tools/test-beta.ps1 -Suite Colony
./tools/test-beta.ps1 -Suite Colony -Profile AllDlc
./tools/test-visitors.ps1 -Mode installation
./tools/test-visitors.ps1 -Mode scale
./tools/test-visitors.ps1 -Profile Core
./tools/test-visitors.ps1 -Profile AllDlc
./tools/test-visitors.ps1 -Profile Frameworks
./tools/test-visitors.ps1 -Mode churn -Profile Core

The game test requires staged packages from build.ps1. It creates a fresh temporary game copy and normally runs three graphics-enabled batch phases with Core only: create/save/reload, remove provider/load/save, and restore provider/resume/save/reload. The expedition and queue suites add an incompatible-provider phase. The expedition advances three actual game days; the queue suite saves at partial materialization, return, rematerialization and resumed-work boundaries. -RenderUI omits Unity batch mode, keeps the launched window hidden and captures the recovery window for visual inspection. Each phase has separate configuration/save data, and the loaded mod list is checked from the actual native save. Results and logs go to docs/validation/<run-id>; large game copies and fixture saves remain in %TEMP%.

Run benchmarks separately from other game fixtures to avoid contention during measurement. The original benchmark suite writes scheduler histograms and save/memory observations; queuebenchmark compares synchronous calls, queued admission and individual work turns. Run the latter in five independent launches and use tools/summarize-queue-benchmark.py to validate and summarize the raw observations. Read the 0.3 baseline and 0.4 queued measurements for their distinct protocols and limits. queueschema separately exercises a pending plan under a newer schema and restoration of its original provider.

The launcher leaves the original game, existing mods and user saves untouched. It checks original assembly/config hashes afterward and only terminates its own test process on timeout. A failed phase preserves evidence and stops the chain. These checks do not establish broad mod/DLC compatibility.

The beta scenarios use real work jobs and native save/load sessions in generated colonies. The harness supplies blueprint designations, starting wood, work priorities and selected commands. It does not claim unassisted human playtesting, colony balance or independent community adoption.