SaveState.Policy
0.1.0-alpha.1
See the version list below for details.
dotnet add package SaveState.Policy --version 0.1.0-alpha.1
NuGet\Install-Package SaveState.Policy -Version 0.1.0-alpha.1
<PackageReference Include="SaveState.Policy" Version="0.1.0-alpha.1" />
<PackageVersion Include="SaveState.Policy" Version="0.1.0-alpha.1" />
<PackageReference Include="SaveState.Policy" />
paket add SaveState.Policy --version 0.1.0-alpha.1
#r "nuget: SaveState.Policy, 0.1.0-alpha.1"
#:package SaveState.Policy@0.1.0-alpha.1
#addin nuget:?package=SaveState.Policy&version=0.1.0-alpha.1&prerelease
#tool nuget:?package=SaveState.Policy&version=0.1.0-alpha.1&prerelease
SaveState
Project-agnostic state + save/load framework for .NET: an incremental source generator that turns plain classes into strongly-typed save files, plus a runtime with lenient, self-healing loading.
- No engine dependency. Contracts are
netstandard2.0; the file store is an interface (ISaveStore), so Godot (user://), a console/server-side directory or an in-memory dictionary for tests all work the same way. - No singleton assumption. Generated code reads services from an explicit
SaveRegistry(works with a DI container, hand-writtennew, or lazy singletons). - Declared by the host, not by the library. A save file is a host class (
[SaveFile("global.json")]), so adding a file never requires a new version of this package. - Missing sections are repaired, never
null. A section that is absent from an old file is filled with a default instance and reported asLoadStatus.Repaired— the framework never writesnullinto your service state (that was a real, painful bug class). - Corrupt files are never overwritten by defaults:
LoadStatus.Failed≠LoadStatus.Missing. - Compile-time diagnostics. Bad file names, duplicate section keys, non-instantiable state types and
missing setters are generator errors (
SAV001–SAV013), not runtime surprises.
Documentation
docs/ — start here for anything beyond the quick start:
| Document | Contents |
|---|---|
| Getting started | a working save file in five minutes; the first-launch / save / load flow; testing your host |
| API reference | every public type and member, the generated members, the diagnostics, the file format |
| Migrations | versioning rules and the declarative "old field → new field + conversion" upgrades |
| Adapters | writing an ISaveStore for your engine, the Godot adapter, container wiring, host-side write policy |
| Distribution | build/test/pack, local feeds, the same-version NuGet cache pitfall, release checklist |
Runnable example: samples/SaveState.Samples.Console (first launch → atomic write → reload → legacy file repair).
Packages
| Package | Target | What it is |
|---|---|---|
SaveState.Shared |
netstandard2.0, net10.0 |
attributes, SaveFileDefinition, SaveRegistry, ISaveStore, ISaveLogger, StateBase, LoadResult |
SaveState.Generator |
analyzer (netstandard2.0) |
incremental source generator |
SaveState.Runtime |
netstandard2.0, net10.0 |
SaveFileSession<TFile>, FileSystemStore, InMemoryStore, SaveGate, JSON policy, migrations |
SaveState.Policy (optional) |
netstandard2.0, net10.0 |
SaveScheduler (coalesce/debounce) and AsyncSaveScheduler (move the disk write off the game thread) |
SaveState.Godot |
net10.0 (Godot 4.7) |
user:// store, Godot output logger, runtime-process gate |
SaveState.DependencyInjection |
netstandard2.0, net10.0 |
AddSaveState(...) + GetSaveFileSession<TFile>() |
Quick start
using System.Collections.Generic;
using SaveState;
// 1) A state object: plain serializable data + change notification.
public sealed class ProfileState : StateBase
{
public int Coins { get; set; } = 100;
public HashSet<int> Unlocked { get; set; } = new HashSet<int>();
}
// 2) A service: its State lives in the "Profile" section of "profile.json".
[SaveService]
public partial class PlayerProfile
{
[SavedState(File = "profile.json", Key = "Profile")]
public ProfileState State { get; private set; } = new ProfileState();
}
// 3) One save file (the generator fills in the implementation).
[SaveFile("profile.json")]
public sealed partial class ProfileSaveFile : SaveFileDefinition
{
}
var store = new FileSystemStore(GetSaveDirectory()); // engine-specific root
var registry = new SaveRegistry().Add(playerProfile);
var session = new SaveFileSession<ProfileSaveFile>(store, registry, logger);
session.EnsureCreated(); // first launch: write a complete default file
session.Save(); // unlock / end of run: explicit write point
LoadResult result = session.Load(); // Missing | Loaded | Repaired | Failed
The generator adds this to your partial class ProfileSaveFile:
public const string FileNameValue = "profile.json";
public override string GetFileName() => FileNameValue;
public override int Version { get; set; } = 1;
public ProfileState Profile { get; set; } = null!;
public override void CollectFrom(SaveRegistry registry) { /* service -> DTO */ }
public override void RestoreTo(SaveRegistry registry) { /* DTO -> service, null-checked per section */ }
public override bool FillMissingDefaults(out IReadOnlyList<string> missingSections) { /* repair */ }
Godot
using SaveState.Godot;
var store = new GodotSaveStore(); // rooted at user:// (or "saves" subdirectory)
var logger = GodotSaveLogger.Instance; // GD.PushError / PushWarning / Print
var gate = GodotSavePolicy.CreateRuntimeGate(logger); // no auto-save in the editor or headless tools
var session = new SaveFileSession<ProfileSaveFile>(store, new SaveRegistry().Add(profile), logger);
session.EnsureCreated(); // first launch: a human asked for it -> not gated
gate.TrySave(session.Save); // event-driven (unlock, end of run) -> gated
Dependency injection
services.AddSaveService<PlayerProfile>(); // your services, registered normally
services.AddSaveState(options =>
{
options.Store = new GodotSaveStore();
options.Logger = GodotSaveLogger.Instance;
// The generator emits AddGeneratedServices next to your services: no reflection, no forgotten service.
options.RegisterServices = (registry, resolve) => registry.AddGeneratedServices(resolve);
});
var session = provider.GetSaveFileSession<ProfileSaveFile>();
Coalescing writes
When one settlement unlocks three items, writing three times is wasteful — and writing only on exit
risks losing progress. SaveScheduler collapses a burst of requests into a single write:
using var scheduler = new SaveScheduler(session.Save, logger, TimeSpan.FromMilliseconds(400));
scheduler.RequestSave(); // ×3 in the same window -> one write
scheduler.Flush(); // before quitting (Dispose also flushes)
Moving the write off the game thread
Disk writes can hitch a frame, but serializing game state on a background thread races with the game
mutating it. AsyncSaveScheduler splits the two: the snapshot happens on the calling thread, the
write on a worker, and a burst of requests collapses into the newest state.
using var async = session.ScheduleAsync(logger);
async.RequestSave(); // snapshot here, write on a worker; safe to call in a burst
async.Flush(); // before quitting: blocks until the pending write lands
SaveFileSession exposes the two halves directly (SerializeSnapshot() / WriteSnapshot(json)) if you
want to shape the policy yourself. The two policies compose - the gate decides whether, the scheduler
decides when:
using var asyncSave = session.ScheduleAsync(logger);
var gate = GodotSavePolicy.CreateRuntimeGate(logger);
gate.TryRun(asyncSave.RequestSave); // event-driven: skipped in editors/tools, written on a worker otherwise
Migrating old save files
A save file's shape changes over time, and old files must keep loading. Bump [SaveFile("profile.json", Version = 2)]
and register one FieldMigration per version step: old field → new field (+ a conversion function). The framework
applies them to the JSON before deserializing, so an old file arrives in the current shape.
var migrations = new ISaveMigration[]
{
// v1 -> v2: a section was renamed, a field changed type, one field was added, one was dropped.
new FieldMigration("profile.json", fromVersion: 1)
.Rename("OldProfile", "Profile")
.Convert("Profile/PlayTimeSeconds", "Profile/PlayTime", JsonUpgrade.SecondsToClockText())
.Convert("Profile/Coins", "Profile/Coins", JsonUpgrade.ToInt()) // "12" -> 12
.SetDefault("Profile/Title", JsonValue.Create("Newcomer"))
.Remove("Profile/LegacyFlag"),
};
var session = new SaveFileSession<ProfileSaveFile>(store, registry, logger, migrations);
- Paths are
/-separated ("Profile/Coins"); dots are not separators, because keys such as mod package names contain dots. - The conversion function gets the old JSON node (or
nullwhen the field is absent) and returns the new one; returningnulldrops the field.JsonUpgradecovers the everyday type changes (ToInt/ToNumber/ToText/ToBool/ToArray/SecondsToClockText) and never throws on a garbled value - it falls back instead. - Silent no-ops are reported: if the old field name does not match anything (a typo is the usual reason), the migration records a warning and the session logs it, instead of quietly keeping the default value.
- Intermediate objects are created as needed, so a value can move into a new nested object.
- Migrations only touch JSON; they never reference the old C# types.
Build, test, pack
dotnet build SaveState.sln -c Debug
dotnet test SaveState.sln -c Debug
dotnet pack SaveState.sln -c Release -o artifacts # packages, generator packaged as analyzer
Consume locally without a feed round-trip:
<add key="savestate-local" value="./artifacts" />
Re-packing the same version? NuGet caches packages in the global packages folder (
~/.nuget/packages/savestate.*), so a consumer keeps resolving the old build even afterdotnet packwrote a new file with the same version. Bumpbuild/Version.props(recommended), or clear that folder before restoring again.scripts/verify-packages.shdoes this automatically when it checks that the packages work for an outside consumer.
Roadmap
SaveState.Testing(a temp-directory store, so host tests can assert on real files)- an optional queued writer that survives shutdown by itself (today
Flush/Disposemust be called)
MIT licensed.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
| .NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
| .NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen40 was computed. tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- SaveState.Runtime (>= 0.1.0-alpha.1)
- SaveState.Shared (>= 0.1.0-alpha.1)
-
net10.0
- SaveState.Runtime (>= 0.1.0-alpha.1)
- SaveState.Shared (>= 0.1.0-alpha.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.1.0 | 104 | 9/29/2026 |
| 0.1.0-alpha.1 | 56 | 9/29/2026 |