Targets, stable IDs, and references

Prefab patches need a stable way to identify what they change. Stock objects and patch-owned objects use different identities.

Stock objects

Visual patches record the stock object's position in the linked prefab and a structural fingerprint of the source prefab. This is more reliable than relying only on a GameObject name.

C# and Lua authoring target stock objects with a slash-separated hierarchy path, for example:

KSP2UIWindow/Root/Window-App/Background

If two children under the same parent have the same name, a hierarchy path is ambiguous. Visual authoring is the safer choice for those targets.

Components are identified by the GameObject plus their type and zero-based ordinal. The ordinal matters when one object has several components of the same type.

Patch-owned objects

An object added by a visual patch must have a PrefabPatchAuthoringObjectId. C# and Lua object fragments have an equivalent ObjectId.

Patch-owned identity consists of the owning patch ID and the local object ID. A patch called toolbar in mod BetterUI owns IDs under BetterUI:toolbar.

This namespacing lets two mods both add an object called icon without collision.

Cross-patch targets

A later patch can target an object introduced by another patch, but it must declare that patch with NeedsPatch. This guarantees that the owner exists and is ordered early enough.

Use the full mod-id:patch-name when referring to another mod's patch. A short patch name refers to a patch in your own mod.

Reference choices

A prefab property can reference:

  • a stock object or component in the effective prefab

  • a patch-owned object or component

  • a stock linked Addressable

  • a mod-owned Addressable

The composer creates all patch-owned objects and components before restoring references, so references between newly added objects are allowed.

Keeping patches durable

  • Keep patch names, operation IDs, object IDs, and component IDs stable after release.

  • Prefer visual authoring when stock hierarchy names are duplicated.

  • Recompile visual patches after updating the game SDK or stock content.

  • Do not depend on a patch-owned target without NeedsPatch.

  • Use Addressables for external assets; a direct reference to an arbitrary project file is not distributable.