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<Character, object> / Func<Scene, object> 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 SpeciesFloats/SpeciesYaw are consumed by Beastwhispering.Core. DonorKit references that game-ref-free COMPUTE assembly, never the CompanionKit plugin.

Dev verbs (`BepInEx/config/DonorKit_cmd.txt`)

photondump · audiodump · audioprune · terraindump · terrainfix · scenedump · selftest

Consumers also register the first five on their own channel via DonorVerbs.RegisterAll(registry).

Config

BepInEx/config/cobalt.donorkit.cfg, created on first launch. Two sections, eight keys, all shown here at their shipped defaults:

[Rig]
## Rebuild a dormant clone's skinned-bone bindings so it renders. Moved here from
## cobalt.companionkit.cfg along with SkeletonRig, its only reader.
RepairSkinnedBones = true

[Expedition]
## Run the capture payload in place when you enter an oversized scene that still has
## uncached species. OFF by default — it is the only path where the kit does heavy
## work nobody asked for.
CaptureOnSceneEntry = false
## One-time template warm at the first player-ready of a launch: needed | all | off.
AutoWarmAtBoot = needed
## Comma-separated species warmed regardless of the mode. Empty = the species installed
## consumer mods register in code; a non-empty list REPLACES those; "none" disables all warming.
AlwaysWarmSpecies =
## How long the boot warm may wait for a busy loader before giving up (0 = don't wait).
AutoWarmRetrySeconds = 60
## Safety net for the RETURN leg — re-request the trip home if no load has started.
ReturnRetrySeconds = 20
## Allow an expedition to start with guests connected. OFF: each leg ends in a per-machine
## continue gate nothing host-side can pass, and one AFK guest wedges the whole party.
AllowCoop = false
## Guest-side auto-pass for those gates while a host-run expedition is in flight. Inert
## otherwise, so it is safe to leave on.
GuestAutoContinue = true

Each generated entry carries its own # Default value: comment and a much longer description than the summaries above. BepInEx never migrates a changed default into an existing cfg — if behaviour doesn't match, compare against those comments before assuming a bug.

Expedition manifest — BepInEx/config/ck_expeditions.txt (the historical filename is kept so existing installs keep their record). ⚠ Known bug (docs/expedition-harvest-testplan.md V42, confirmed live 2026-07-25, open): the manifest reports captured scenes in memory but the file is never written, so the record does not survive a relaunch.

API sketch

[BepInDependency("cobalt.donorkit", BepInDependency.DependencyFlags.HardDependency)]

if (DonorHarvest.TryGetDonorScenes("Pearlbird", out var scenes, out var term))
    StartCoroutine(DonorHarvest.HarvestChain(scenes, term,
        use:      src => Object.Instantiate(src.gameObject, MyHolder().transform),
        onResult: r  => UseOrFailLoudly(r as GameObject)));

The payload runs while the donor is loaded and frozen, must be synchronous, and must not keep references into the donor scene. Use DonorHarvest.IdentityFor(key, src) rather than src.Name — a pinned row's frozen donor reports its serialized base-prefab name.

Details