DonorKit

DonorKit

📖 Full documentation: DonorKit wiki page

The donor-scene harvest engine — "get me a live body for species X, from anywhere in the game".

Extracted from CompanionKit on 2026-07-26 (static-analysis wave, lane 5E) so SpawnKit no longer has

to depend on the pet library for its creature supply.

Requires: BepInEx 5 (BepInExPack_Outward), ForgeKit and NetKit — both hard

dependencies ([BepInDependency]), so BepInEx refuses to load DonorKit if either folder is missing

from BepInEx/plugins. NetKit is needed for the auto-warm room-left re-arm. No SideLoader;

DonorKit builds on a clean runner.

What it owns

• DonorHarvest — the guarded cycle: additive load → freeze at sceneLoaded → payload →

unload → repair. Generic Func / Func payloads, so one load

can stock many species (light-probe cycles are the scarce resource).

• DonorSceneTable (+ the embedded DonorScenes.txt) — the species→scene roster, pins,

identity resolution, and build-scene name matching. DonorScenes.txt is generated by

bwspecies build; see tools/BwSpeciesTool/Paths.cs.

• DonorCreatureFinder — exact-then-substring live-donor lookup within a loaded scene.
• The guards, each of which exists because the un-guarded version broke a real session:

DonorPhotonGuard (view-id collisions), DonorSaveGuard (mid-harvest saves, deferred via the

game's own SetSaveRequired re-arm), DonorSingletonRestore (the four Instance-hijack

restores), AmbienceGuard + DonorAudioRegistry (the persistent audio registries),

SoulSpotGuard (duplicate-UID throw mid-Awake), DonorDisplayRepair (skybox / display chain),

TerrainGuard (LOD render holes), DonorNetworkInitGuard (guest replica conversion).

• SkeletonRig / RagdollRig — the rig surgery a dormant clone needs to render and ragdoll.
• The expedition tier (lane 5E-2, 2026-07-26 — moved here from CompanionKit): ExpeditionHarvest

(the vanilla-loader round-trip state machine for region/town scenes too large to load additively),

ExpeditionOrchestrator (the expedition verb body, batch capture payload, in-place capture,

once-per-launch boot auto-warm), ExpeditionManifest (ck_expeditions.txt — the historical

filename is kept so existing installs keep their record), StorySense (the prologue/first-visit

story-safety reads). Config: [Expedition] in cobalt.donorkit.cfg. The expedition/

templateclear/expeditionreset/templateprobe verbs stay on CONSUMER channels (ck_cmd.txt +

BW twins) — templateclear's full reset must also re-arm CompanionKit's effigy gate, which only

the consumer can reach.

• The K2 template store (TemplateStore + BodyTemplateStore, lane 5E-2): ONE store with

per-consumer KINDS. The companion-body kind (BodyTemplateStore) carries identity + captured

stats, eager-prunes, refuses substitutes on identity lookups, keeps unhealthy rigs; the spawn kind

(SpawnKit's SpawnTemplates layers on it) holds bare normalized GameObjects with opt-in LRU cap

eviction and rejects unrepairable rigs. The kinds share only the FABRIC (holder/registry/recency/

orphan-proof clear) — unifying the policies would change behavior, so they stay at their call

sites. E3 seams for third mods: TemplateStore.RegisterSpecies(key, scenes) (runtime donor-table

row) and TemplateStore.RegisterTemplate(key, dormantBody) (parks a body in the spawn kind

through SpawnKit's own normalization seam).

What it deliberately does NOT own

• Puppet-shaped code (the 5E permanent-shim rule — a DonorKit→CompanionKit edge is forbidden):

BodyTemplateCache.PuppetFrom (template → CompanionBody via BodyFactory.BuildPuppet),

ClearAllAndForgetMisses (also resets the effigy harvest gate), and the stat capture itself —

the store calls back through BodyTemplateStore.StatCapturer, which CompanionKit wires to

AttributeCapture.From in its Awake.

• The pure donor logic — DonorTable, DonorChain, RigSurgery, TerrainMaintenance, the

Expedition* planners — which stays in core/CompanionKit.Core. DonorTable cannot be split

from SpeciesTable/Species/Regions, and its file-mates SpeciesF