Extending NexusForge

The seams in the order you are likely to need them — serializers, storage, resolvers, prefab factories — and what each one obliges you to keep true.

Why seams rather than plugins#

The framework has no plugin registry. It has interfaces where a decision genuinely belongs to the game or the platform, and each one is small on purpose: a seam that is easy to implement is a seam that gets implemented correctly.

Custom serializers#

Available Replace the JSON serializer by implementing the serializer seam and composing the service with yours. Two obligations:

produce a deterministic, culture-independent representation of values that have a text form (dates, decimals, integers) — this is exactly where an early culture bug came from;
keep the document neutral, because migration, integrity, compression and encryption all operate on it.

The shipped implementation is JsonSaveSerializer over com.unity.nuget.newtonsoft-json. See Serialization.

Custom storage#

Available Implement ISaveStorage when the platform's storage is not a file system with atomic renames — WebGL is the classic case. The interface is where atomicity, verification, backup and recovery are provided, so an implementation must preserve those properties, not merely write bytes:

text

stage -> flush -> verify -> promote -> rotate

LocalFileStorage and MemoryStorage both implement it; MemoryStorage runs the same pipeline over an in-memory file system, which is how disk-full and partial-write faults are injected deterministically in tests. StorageCapabilities lets your implementation state what the platform can do honestly, and StoragePromotionStrategy records what it actually did.

Custom resolvers#

Available Implement IPersistenceIdentifierResolver to control how a stored persistent id becomes a live object — for pooled objects, addressables, or a scene assembled at runtime. Resolution order is: the resolver passed to the restore call, then the injected one, then the session index. See References.

Custom prefab factories#

Available Implement IPersistencePrefabFactory so reconstruction goes through your catalogue rather than through Instantiate in the package. The factory, and nothing else here, creates objects, and a recreated instance adopts the identity from the save. See Prefabs.

Also available#

IPathProvider and IProductContext (where the writable root is, and who this build is), IClock (where "now" comes from, so conflict logic never trusts the wall clock), IMainThreadDispatcher, IMonotonicSequenceProvider, IPersistenceLogger, ICloudTransport, ICloudSaveProvider, ICloudConflictResolver, ICloudAuthenticationProvider, ISaveKeyProvider, ISaveStateSource, ISaveMigration and IStoragePayloadValidator.

A seam may change where something happens. It may not change what is guaranteed: atomicity, ordered migration, verification before parsing, bounded decompression and "only one write at a time" survive every substitution, because the rest of the framework depends on them.

Next#

API overview — the full public surface.
Threading — which seams are called from which thread.
Support — reporting a defect found in one of these.