Workes.SaveSystem.MessagePack 1.0.0

Workes.SaveSystem.MessagePack

Optional MessagePack serializer package for Workes.SaveSystem 1.0.0.

Use this package when you want Workes.SaveSystem saves written as MessagePack instead of the core JSON serializer. The core package stays MessagePack-free; this companion package is the opt-in integration.

Install

dotnet add package Workes.SaveSystem.MessagePack --version 1.0.0

Or add the package reference directly:

<PackageReference Include="Workes.SaveSystem.MessagePack" Version="1.0.0" />

This package depends on:

• Workes.SaveSystem 1.0.0
• MessagePack

Usage

using Workes.SaveSystem;

var manager = new SaveManager<string>(
    SaveSystemOptions.Create(
        saveRootPath: saveRoot,
        serializer: new MessagePackSaveSerializer()));

MessagePack save files use the .msgpack extension. Provider payloads and save-system metadata are both written through the serializer, so a slot can contain files such as player.msgpack and metadata.msgpack.

Save-system metadata is serialized through the same MessagePack serializer. Menu or tooling code should read it through the core ReadSaveMetadata(...), ReadBackupSlotMetadata(...), or ValidateSave(...) APIs, which expose SaveMetadataInfo rather than serializer-owned implementation metadata.

State Types And Compact Maps

Plain POCO state types work directly:

public sealed class PlayerState
{
    public string Name { get; set; } = string.Empty;
    public int Level { get; set; }
    public bool HasKey { get; set; }
}

Provider payloads use serializer-owned compact field maps automatically. The serializer writes compact integer-keyed MessagePack provider data and stores the member-name map in save-system serializer metadata.

MessagePack supports the same documented non-polymorphic state model as the core JSON serializer. Provider state can be a plain object, a root list/array, a concrete root string-key dictionary, or a root scalar/simple value. Complex objects inside root collections and dictionaries are still compact mapped automatically. Generic string-key dictionary members, including read-only dictionary shapes, do not need to implement non-generic IDictionary.

Null provider state is supported for reference-type state and Nullable<T> state. Nil/null MessagePack provider data is rejected for non-nullable value-type state instead of being converted to a default value.

Capabilities

public sealed class MessagePackSaveSerializer :
    ISaveSerializer,
    IContextualSaveSerializer,
    ISaveSerializerMetadataHandler,
    ISaveApplicationMetadataSerializer

public sealed class MessagePackSaveSchematic<T> : SaveSchematic<T>

The serializer participates in core provider metadata validation, compact field-map serialization, provider migrations, and inline application metadata.

Schema Versions

Each provider payload is wrapped with a small MessagePack schema-version header. MessagePackSaveSerializer.ExtractSchemaVersion reads that header so the save manager can compare saved payload versions with registered provider versions.

Metadata

The companion serializer supports the core SaveMetadata payload contract used by Workes.SaveSystem for save-system metadata. Metadata files are written as metadata.msgpack, including core-owned provider manifest entries used by Workes.SaveSystem 1.0.0 to distinguish legacy saves from current saves with deleted or corrupt provider files. A null provider manifest remains the legacy-save signal. Corrupt or incompatible metadata is treated as invalid by the core manager.

Provider field maps are stored in SaveMetadata.SerializerMetadata. This metadata is serializer-owned implementation data used to decode compact provider payloads and migrate older saves. It is not application/menu metadata and does not contain core provider manifests.

Application metadata registered through the core ISaveMetadataProvider<T> APIs is stored inline in SaveMetadata.ApplicationMetadata.Data as MessagePack-native data, not as a separate provider file or a provider payload envelope. It uses the same automatic compact mapping as provider payloads through the synthetic serializer metadata key __workes_application_metadata, and it supports object roots, list/array roots, string-key dictionary roots, scalar roots, and null values for nullable metadata types.

Use ForceSaveToDisk(...) only when intentionally repairing or replacing a save whose existing metadata or serializer format cannot be trusted. Normal SaveToDisk(...) preserves readable core metadata, while force-save writes fresh metadata for the main save.

Validation

Use the core ValidateSave(...) API to check MessagePack saves without restoring provider state. Corrupt MessagePack provider payloads, inline application metadata, serializer metadata, or metadata files are reported as invalid by the core manager.

Migration

Provider migration is supported through the normal core ISaveMigratable and SaveMigrationStep APIs. The MessagePack serializer automatically translates compact integer-keyed payloads into named migration nodes using the saved field map, then writes migrated payloads back with the current field map.

The compact field-map metadata is automatic and invisible to save providers. Provider migrations can use member names such as SaveMigrationStep.AddIntDefault(1, "Level", 1) or SaveMigrationStep.Rename(1, "OldName", "Name"); users do not need manual compact-key handling to make those migrations work.

Migration steps operate on the provider state root directly. Object-root states expose named fields, root lists expose array nodes, root string-key dictionaries expose object nodes keyed by dictionary key, and root scalar states can be replaced through ISaveDataNode.ReplaceWith(...).

Application metadata migrations use the same ISaveMetadataMigratable and SaveMigrationStep APIs from the core package. The MessagePack companion maps inline application metadata through migration nodes without changing provider payload files.