CompanionKit — persistent-companion mechanics for Outward mods

A BepInEx library for modders. It doesn't add anything a player sees on its own — install it because a mod you're using (a follower, a summon, a spawner) declares it as a dependency.

It exists because Outward has no way to spawn a fresh creature at runtime: every creature is baked into the scene it lives in. CompanionKit's answer is donor-scene harvesting — any area is an ordinary scene you can load additively, clone a live creature out of, and unload again in about a second. DonorHarvest wraps that whole recipe, plus the audio/Photon/save guards that make it safe, behind one call. On top of that sits everything needed to turn a cloned body into a companion that follows, fights, and survives zone changes.

Requires: BepInEx 5 (Outward's Mono branch — see Compatibility) and ForgeKit. No SideLoader.

Installing (for players)

Drop the CompanionKit folder into BepInEx/plugins/, alongside ForgeKit/. A mod manager does this for you. On its own the kit does nothing except expose the expedition command channel and config described below.

What's in the kit

CompanionKit.Core is a game-reference-free, unit-tested compute layer: weld policy, target selection, the attribute codec, the donor table, the expedition manifest and warm policy, plus scene/species helpers.

Expeditions — the creature-supply chain

Most creatures can be fetched on demand by loading their dungeon scene in the background. But open-world regions and towns are too large to load that way (it crashes the game), so creatures that live only out in a region need a different route: an expedition — a real round trip through the vanilla loading screen that caches body templates for every species that scene can donate. Pay it once, and those creatures are available for the rest of the session.

Verbs — CompanionKit polls BepInEx/config/ck_cmd.txt (write a line, it runs on the next poll; works while paused):

Config ([Expedition] in cobalt.companionkit.cfg):

• CaptureOnSceneEntry (default off) — when on, walking into a region that still has uncached species runs the capture in place, costing zero loading screens. It is off by default because it is the one path where the kit does substantial work the player never asked for, on every region entry. Turn it on if you'd rather stock creatures opportunistically than run expedition <species>.
• AutoWarmAtBoot = off | needed | all — a once-per-launch warm at first player-ready. needed only fires when the consumer's active companion actually needs a body it hasn't got.
• AlwaysWarmSpecies — comma-separated species warmed regardless of the mode; the packaging knob for a mod whose headline creature is region-only.

Manifest — BepInEx/config/ck_expeditions.txt records every scene whose capture completed. Safe to edit or delete.

Consumer seams: ExpeditionOrchestrator.ActiveSpeciesProvider (a Func<string> naming the active companion's species; feeds needed-mode warm) and ExpeditionOrchestrator.AutoWarmDeferred (set true in your Awake to fire AutoWarm() yourself once your own save state is loaded).

Consuming the kit

<!-- your .csproj — both kit DLLs ship from the kit's own folder, never copy them into yours -->
<ProjectReference Include="..\CompanionKit\CompanionKit.csproj" Private="false" />
<ProjectReference Include="..\..\core\CompanionKit.Core\CompanionKit.Core.csproj" Private="false" />

[BepInPlugin(GUID, NAME, VERSION)]
[BepInDependency(CompanionKit.Plugin.GUID, BepInDependency.DependencyFlags.HardDependency)]
public class Plugin : BaseUnityPlugin
{
    void Awake()
    {
        CompanionRuntime.Log = Logger;                       // or leave the kit's own logger
        CompanionRuntime.DefaultSettings = new MySettings(); // ICompanionSettings over YOUR config
    }
}

Lifecycle:

var companion = new Companion();                          // or your subclass with policy state
companion.Anchor.OnAnchorDeath += ...;                    // your downed policy
companion.Anchor.OnAnchorCriticallyHurt += ...;

// acquire a body (any path):
CompanionBody body = BodyFactory.BuildPuppet(src, owner, consume: true);   // consumes the wild one
CompanionBody body = BodyFactory.BuildPuppet(src, owner, consume: false);  // the wild one survives
// or DonorHarvest.HarvestChain(scenes, species, owner, b => ...)          // no wild source needed
// or the ghost stand-in trio: SpawnGhostActive / GhostVisualReady / FinishGhostPuppet

companion.Body = body;
var combat = body.gameObject.AddComponent<CompanionCombat>();
combat.Anchor = companion.Anchor;
combat.Stance = companion.Stance;
combat.OnEnemyDefeated += ...;                            // your kill-credit policy
companion.Anchor.AttachBody(body);                        // welds the anchor to body.OnAfterMove

// on your tick:
companion.Anchor.Upkeep(owner, host, bodyFighting: body.CombatTarget != null);
companion.Anchor.ApplyVoice(body);

// stat seam (idempotent, re-push any time):
companion.Anchor.ApplyVitals(maxHealth);
companion.Anchor.ApplyCreatureStats(effectiveAttributes); // null = clear back to defaults
combat.SetAttackProfile(effectiveAttributes);

// orders:
companion.Stance.CommandEngage(target);   // priority 0, any range
companion.Stance.CommandDisengage();      // passive + run-home grace

// persistence is YOURS: store the species + Attributes (CreatureAttributes.Flatten/Parse is one
// save-safe string) in your own save file. The kit ships no save format.

Scope and caveats

• The API is instance-based, but one companion per owner is what's actually been proven in play. Several at once should work and is unexercised — the vanilla summon slot is one-per-player, and multi-anchor aggro is untested.
• The kit ships the attribute codec and every body-acquisition path, but no save file — consumers own their own format.
• Special attacks stay consumer-side; CompanionCombat.DealDamage is the public seam.
• Beast bodies are the well-trodden path. Humanoid bodies use a different (ghost stand-in) route that should work but has had far less mileage.

Compatibility

Outward must be on its Mono Steam beta branch, not the default IL2CPP build. If your game runs but no BepInEx mods load and there's no crash log, this is almost always why (Properties → Betas → select mono in Steam).

License

Apache License 2.0 — see LICENSE. You may use, modify, and redistribute this kit (including in commercial mods) provided you keep the copyright/license notice; see the license text for the full terms.