Workes.SaveSystem.MessagePack 1.0.0-preview.1

Workes.SaveSystem.MessagePack

Optional MessagePack serializer package for Workes.SaveSystem.

Use this package when you want Workes.SaveSystem saves written as MessagePack instead of the core JSON serializer. The core Workes.SaveSystem package does not depend on MessagePack; this package is the opt-in integration.

Install

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

Or add the package reference directly:

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

This package depends on:

• Workes.SaveSystem
• 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 without MessagePack attributes:

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. Users do not need [MessagePackObject] or [Key] attributes because this package owns the compact mapping.

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.

Public API

public sealed class MessagePackSaveSerializer : ISaveSerializer
public sealed class MessagePackSaveSerializer : IContextualSaveSerializer
public sealed class MessagePackSaveSerializer : ISaveSerializerMetadataHandler
public sealed class MessagePackSaveSchematic<T> : SaveSchematic<T>

Schema Versions

Each provider payload is wrapped with a 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, and 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.

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 or metadata files are reported as invalid/corrupt by the core manager.

Migration

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 MessagePack attributes or 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(...).