C# SDK Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.20.1] - 2026-10-18

Fixed

• Godot: The Inspector now rebuilds when the editor plugin is enabled or disabled, so the config ID dropdowns appear or disappear without reopening the scene.

[0.20.0] - 2026-10-07

Added

• SDK: Added the Clone method to WeightedPool<T>.

Changed

• SDK: I18n.Text now returns the key instead of throwing ArchmageException when no translation is found.

[0.19.0] - 2026-10-01

Added

• Godot: Added the Shadop.Archmage.Godot package with GodotFileAccessFS, GodotAtlasLogger, GodotJsonSettingsFactory, and conversions to Godot types.
• Godot: Added the ArchmageDev project with integration tests, a ConfLoader demo, and demos of config ID dropdowns in the Inspector.
• SDK: Added UnityAddressablesGreedyFS, which caches all files of a bundle on the first read to avoid one frame per file on WebGL.
• SDK: Added AtlasOptions.WithMainThreadParsing. When enabled, each atlas item is parsed on the main thread after its read completes, rather than on a thread pool thread. Unity WebGL builds always parse this way.
• SDK: Added workerThreadLoading to LoadAtlasAsync, which runs the whole load on the thread pool and only OnLoaded on the caller’s context.
• SDK: Added IFS.MainThreadOnly, which indicates whether a file system is restricted to the main thread and therefore cannot run on worker threads.
• SDK: Added ValueWrapperTypeConverter.Register, which the generated ConfigAtlas calls so that CfgId dictionary keys can be read in Godot.

Changed

• SDK: The loader calls IFS on the caller’s context, without ConfigureAwait(false), so Unity file systems use main-thread-only APIs directly.
• SDK: Atlas items load concurrently: the files of an item are read together, then the item is deserialized on the thread pool while reading continues. WithMaxConcurrency (default 32) limits the items in flight.
• SDK: IFS.FileExists and IFS.DirectoryExists may return true for a missing path; the loader skips override files that turn out to be missing. ReadAllBytes and ReadAllBytesAsync must throw FileNotFoundException for a missing file.
• SDK: MergeL10nFileAsync parses l10n files on the thread pool.
• Unity: UnityAddressablesFS resolves the location before loading, so a missing override file no longer logs an InvalidKeyException, and UnityAddressablesFS reads the result directly from a completed handle instead of resuming a frame later.
• Unity: UnityStreamingAssetsFS treats a 404 response as a missing file, and any other failure as a load failure.

Removed

• SDK: Removed WithLoadStrategy and WithAsyncLoadStrategy.

Fixed

• SDK: Loading no longer mutates the caller’s JsonSerializerSettings or AtlasOptions.
• SDK: On Unity WebGL, LoadAtlas no longer hangs and LoadAtlasAsync completes.

[0.18.0] - 2026-09-24

Changed

• Tests: Rebuilt the integration tests on the self-contained SDK test data shared with the Go SDK, and check every XRef binding after each golden scenario.
• Unity: ArchmageDev now uses the SDK test data, with its scripts moved into the ArchmageDevCore assembly.

Fixed

• SDK: Dumped enum-keyed dictionaries now use numeric keys, matching the exported JSON and the Go SDK, instead of Newtonsoft’s enum names.

[0.17.0] - 2026-09-09

Added

• Added AtlasOptions.WithVariant(key, variant) for non-default variant selection.
• MinMax: Added Duration support to MinMax<T>, including Sample extension methods for .NET and Unity.

[0.16.0] - 2026-07-31

Changed

• SDK: Renamed the single/multiple mapping strategies to variant/many in atlas.json.
• Unity Editor: ArchmageEditorTools now binds CfgId drawers to the runtime atlas once it appears instead of loading a separate editor copy.

[0.15.2] - 2026-07-12

Added

• SDK: Added SampleWith and SampleIndexWith methods to WeightedPool<T>.

[0.15.0] - 2026-06-11

Added

• SDK: Added WeightedPool<T> for weighted random sampling, with WeightedPoolExtensions.

Changed

• I18n: Annotated GetText out parameter with [NotNullWhen(true)].

[0.14.0] - 2026-05-31

Added

• SDK: Added MinMax<T> struct for representing a numeric range with Min and Max values.
• SDK: Added MinMaxExtensions containing System.Random-based Sample overloads for all numeric types.
• Unity: Added UnityMinMaxExtensions containing Sample overloads using Unity’s global Random generator.

Changed

• Unity: Renamed RgbaExtensions to UnityRgbaExtensions and VecExtensions to UnityVecExtensions for consistency.

[0.13.1] - 2026-05-24

Changed

• SDK: Made Tup1–7 mutable by restoring setters ({ get; } → { get; set; }) to all ItemX properties.
• SDK: Removed IEquatable interface implementation from Tup1 through Tup7 classes.
• SDK: Deleted custom Equals, GetHashCode, and equality operator overloads in Tup1 through Tup7.

[0.13.0] - 2026-05-24

Changed

• SDK: Made Tup1–7 item properties read-only ({ get; set; } → { get; }).
• SDK: Replaced custom Newtonsoft.Json converters for Vec2/3/4 with [JsonProperty] attributes.
• Unity: Simplified UnityVector2/3/4JsonConverter to delegate serialization through Vec2/3/4, removing manual property-by-property read/write logic.

[0.12.0] - 2026-05-07

Added

• Logger: Implement ARCHMAGE_DISABLE_DEFAULT_LOGGER conditional compilation symbol to allow manual suppression of default console logging (automatically disabled in Unity environments).

Changed

• SDK: Changed vector (Vec2/3/4) and Unity vector types to use object-based JSON serialization instead of arrays, ensuring null deserializes to zero vectors.
• SDK: Added unmanaged constraint to vector types and optimized equality comparisons.

[0.11.0] - 2026-04-24

Added

• Unity: Vec2/3/4 extension methods to convert to UnityEngine.Vector2/3/4 and Vector2/3Int with zero-allocation support for 10 numeric types.
• Docs: Documentation for Unity Inspector dropdowns and ArchmageEditorTools.cs examples.

[0.10.0] - 2026-04-10

Added

• Unity Editor: CfgIdDrawer<TValue> abstract base, IntCfgIdDrawer<TId, TValue>, StrCfgIdDrawer<TId> property drawers, and EasyDropdown<TValue> IMGUI dropdown for config ID selection.
• AtlasLoadEvent.ItemsQueued stage to report total item count before loading begins.
• WithOverrideFS: optional rootPath parameter to resolve override files relative to a subdirectory within a custom filesystem.

Changed

• Unity: flattened SDK files from Runtime/Sdk/ to Runtime/.

[0.9.0] - 2026-04-07

Added

• Rgba struct with hex string parsing (#RRGGBB / #RRGGBBAA), equality, IZero support, and RgbaJsonConverter for Newtonsoft.Json; alpha is omitted from output when A == 0xFF.
• Unity: RgbaExtensions.ToColor() maps Rgba channels [0, 255] to UnityEngine.Color [0, 1].

[0.8.0] - 2026-04-06

Changed

• Renamed namespace and assembly from Shadop.Archmage to Shadop.Archmage.Sdk.

[0.7.0] - 2026-04-01

Added

• Docs: GitHub Package Manager git URL as primary Unity install method.

Changed

• Renamed XRef.RawValue to XRef.CfgId.

[0.6.0] - 2026-03-29

Changed

• Unity: Removed Samples~ directory; integration adapters are now first-class Runtime assemblies.
• Config tables now include id in JSON serialization output.

[0.5.0] - 2026-03-22

Added

• Added NullLogger that discards all log output.

[0.4.0] - 2026-03-18

Added

• Added UnityJsonSettingsFactory for JSON serialization of Unity types.

Changed

• Refactored JSON settings handling: renamed CreateJsonSerializerSettings() to CreateJsonDumpSettings().

[0.3.1] - 2026-03-17

Fixed

• Fixed typo GetPreferredLanguge to GetPreferredLanguage in L10n.

[0.3.0] - 2026-03-17

Added

• Added IZero interface and ValueWrapperJsonConverter / ValueWrapperTypeConverter for better primitive wrapper support.
• Added IFS support and MergeL10nFileAsync variant to MergeL10nFile in I18n.
• New documentation site built with Astro and Starlight.

Changed

• Improved L10n API: replaced Text(lang) with a Text property that uses GetPreferredLanguage.
• Removed [Archmage] prefix from UnityAtlasLogger for cleaner logs.

[0.2.0] - 2026-03-14

Added

• Unity: Resources, StreamingAssets, and Addressables file system implementations
• Unity: Integration samples and changelogUrl added to package.json

[0.1.1] - 2026-03-12

Added

• NuGet package publishing support: package metadata, Source Link, and XML documentation generation

Changed

• Clarified override merge rules in documentation
• Updated OpenUPM scoped registry configuration in installation docs

[0.1.0] - 2026-03-11

Added

• Initial release
• Atlas loading system with sync/async support, layered overrides, and whitelist/blacklist filtering
• JSON serialization via Newtonsoft.Json (com.unity.nuget.newtonsoft-json)
• Duration type with nanosecond precision
• Vec2, Vec3, Vec4 typed vectors
• Tup1–Tup7 heterogeneous tuples
• XRef type for cross-table references
• I18n internationalization with language fallback
• DateTimeOffset JSON converter