Merge pull request #33 from CoderGamester/develop

Release 2.1.0

Author: CoderGamester

AGENTS.md

@@ -128,7 +128,7 @@ flowchart TD
 
 ### Build/Version Info
 `Runtime/VersionServices.cs`
-- Static class for `version-data` Resources metadata. `VersionExternal` is always safe; `VersionInternal`, `Branch`, `Commit`, and `BuildNumber` require either `LoadVersionData()` (sync) or `LoadVersionDataAsync()` (async) to have completed successfully first.
+- Static class for `version-data` Resources metadata. `VersionExternal` is always safe. `VersionInternal`, `Branch`, `Commit`, and `BuildNumber` auto-load via a `[RuntimeInitializeOnLoadMethod(SubsystemRegistration)]` `Bootstrap` hook and additionally lazy-load on first property access (via the private `EnsureLoaded()`) when the bootstrap hook has not yet fired. Consumers do NOT need to call `LoadVersionData()` / `LoadVersionDataAsync()` explicitly for the default flow. Both load methods remain public for explicit pre-warming.
 
 ## 3. Key Directories / Files
 
@@ -243,8 +243,8 @@ The concrete `PoolService` stays in `Runtime/` root under `GameLovers.Services`
 - `VersionEditorUtils` writes `version-data.txt` on every domain reload (`[InitializeOnLoadMethod]`) and can be invoked by build pipelines. It uses git CLI; failures are handled gracefully.
 - The **write folder** is configurable per-project via `VersioningEditorSettings.instance.ResourcesFolderPath` (default `Assets/Configs/Resources`). Change it from the Versioning tab in the Services Explorer (browse + reset). The chosen folder must contain a `Resources` path segment so `Resources.Load<TextAsset>("version-data")` can locate the file at runtime.
 - `VersioningEditorSettings` persists to `ProjectSettings/VersioningEditorSettings.asset` (editor-only, not committed to version control by default).
-- `VersionExternal` is always safe (reads `Application.version` directly). `VersionInternal`, `Branch`, `Commit`, and `BuildNumber` throw `Exception("Version Data not loaded.")` if data has not been loaded — call `LoadVersionData()` (sync) or `LoadVersionDataAsync()` (async) early in boot.
-- **Sync vs async load**: `LoadVersionData()` uses `Resources.Load<TextAsset>` (synchronous, main-thread); `LoadVersionDataAsync()` uses `Resources.LoadAsync<TextAsset>` wrapped in a `TaskCompletionSource`. Both funnel into the private `ApplyTextAsset(TextAsset, bool asyncContext)` helper that parses JSON, flips `_loaded`, and calls `Resources.UnloadAsset`. Behaviour is identical apart from the wording in the failure log line (`"Could not async load …"` vs `"Could not load …"`). Sync is the recommended default for the shipping `version-data.txt` (a few hundred bytes); async is only worth the ceremony if `VersionData` is extended with large embedded blobs (e.g. a baked manifest) that would noticeably stall the main thread.
+- `VersionExternal` is always safe (reads `Application.version` directly). `VersionInternal`, `Branch`, `Commit`, and `BuildNumber` auto-bootstrap at `[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]` (private `Bootstrap` method calling `LoadVersionData()`), and additionally lazy-load on first property access via the private `EnsureLoaded()` — covering the case where a sibling-assembly `SubsystemRegistration` callback fires before this package's. When the `version-data` Resource is missing or fails to parse the accessors return their documented fallbacks (`VersionInternal` → `Application.version`, others → `string.Empty`) and a `Debug.LogError` is emitted; no exception is raised.
+- **Sync vs async load**: `LoadVersionData()` uses `Resources.Load<TextAsset>` (synchronous, main-thread); `LoadVersionDataAsync()` uses `Resources.LoadAsync<TextAsset>` wrapped in a `TaskCompletionSource`. Both funnel into the private `ApplyTextAsset(TextAsset, bool asyncContext)` helper that parses JSON, flips `_loaded`, and calls `Resources.UnloadAsset`. Behaviour is identical apart from the wording in the failure log line (`"Could not async load …"` vs `"Could not load …"`). The sync variant is what `Bootstrap` calls and what `EnsureLoaded()` falls back to; both methods remain public for callers that want explicit pre-warming. The async variant is only worth the ceremony if `VersionData` is extended with large embedded blobs (e.g. a baked manifest) that would noticeably stall the main thread.
 - `VersionServices.IsOutdatedVersion(string)` requires a 3-part `Major.Minor.Patch` semver and throws `IndexOutOfRangeException` on any 1- or 2-part input — the parser unconditionally accesses `Split('.')[0..2]`. Consumers that compare against `Application.version` must ensure `ProjectSettings.bundleVersion` is 3-part (defaults to `0.1` / `1.0` for fresh projects, which will throw). Either bump `bundleVersion` to a 3-part value, guard with `parts.Length < 3` at the call site, or harden the method itself with a length guard. Tests calling this against the host editor's `Application.version` should `Assert.Inconclusive` on shorter strings rather than `Assert.Throws` — the throw is a real production bug surface, not a documented contract.
 
 ### Editor Introspection (InternalsVisibleTo)
@@ -277,7 +277,7 @@ Services expose minimal `internal` read-only accessors so the Services Explorer
 - `MessageBrokerService.Subscribe` rejects static methods; direct `Publish<T>` can throw if the subscription list is mutated during dispatch.
 - `DataService.GetData<T>` throws when missing; `LoadData<T>` requires a parameterless constructor.
 - Duplicate `PoolService.AddPool<T>` calls throw; `AssetResolverService` requests throw `MissingMemberException` until assets/scenes are registered.
-- `VersionInternal`, `Branch`, `Commit`, and `BuildNumber` throw `Exception("Version Data not loaded.")` until version data loads successfully.
+- `VersionInternal`, `Branch`, `Commit`, and `BuildNumber` no longer throw — auto-bootstrap + lazy-load make access safe at any phase; missing-Resource cases fall back to `Application.version` / `string.Empty` with a `Debug.LogError`.
 
 ## 5. Coding Standards (Unity 6 / C# 9.0)
 - **C#**: C# 9.0 syntax; explicit namespaces; no global usings.

CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this package will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] - 2026-05-20
+
+**New**:
+- `VersionServices` now auto-bootstraps via `[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]`, populating version metadata before any scene `Awake` callback and before vendor-SDK `SubsystemRegistration` callbacks that read it. Consumers no longer need to call `LoadVersionData()` / `LoadVersionDataAsync()` explicitly for the default flow.
+
+**Changed**:
+- Property getters (`VersionInternal`, `Branch`, `Commit`, `BuildNumber`) now lazy-load via a new private `EnsureLoaded()` on first access if the auto-bootstrap hook has not yet fired — protects against undefined ordering between sibling assemblies' `[RuntimeInitializeOnLoadMethod]` callbacks at the same phase.
+- Removed the private `IsLoaded()` helper (replaced by `EnsureLoaded()` invoked from each property getter).
+
+**Docs**:
+- `docs/version-services.md` rewritten around the new auto-bootstrap contract: the recommended usage no longer includes any explicit load call, the lazy-load fallback is documented, and the Error Reference table now describes the fallback behaviour (no exception is raised).
+
 ## [2.0.2] - 2026-05-20
 
 **Fixed**:

README.md

@@ -232,13 +232,15 @@ cmd.ExecuteCommand(new LevelUpCommand());
 ### Version Services
 
 ```csharp
-// Pick one of:
-VersionServices.LoadVersionData();          // sync — recommended for tiny version-data.txt payloads
-await VersionServices.LoadVersionDataAsync(); // async — use if VersionData embeds large blobs
-
+// No setup call needed — version metadata auto-loads at SubsystemRegistration,
+// with a lazy-load fallback on first property access.
 string branch = VersionServices.Branch;
 string commit = VersionServices.Commit;
 string ext    = VersionServices.VersionExternal; // always safe, no load needed
+
+// Optional explicit pre-warm (idempotent — no-ops if already loaded):
+// VersionServices.LoadVersionData();              // sync, recommended default
+// await VersionServices.LoadVersionDataAsync();   // async — only useful for large VersionData blobs
 ```
 
 ### Asset Loading

Runtime/VersionServices.cs

@@ -31,35 +31,89 @@ public struct VersionData
 		public static string VersionExternal => Application.version;
 
 		/// <summary>
-		/// Internal version (M.m.p-b.branch.commit)
+		/// Internal version (M.m.p-b.branch.commit). Lazy-loads on first access if the
+		/// <see cref="Bootstrap"/> hook has not yet fired (see remarks on <see cref="Bootstrap"/>);
+		/// falls back to <see cref="Application.version"/> when the <c>version-data</c> Resource is
+		/// missing or fails to parse.
 		/// </summary>
-		public static string VersionInternal => IsLoaded()
-			? FormatInternalVersion(_versionData)
-			: Application.version;
+		public static string VersionInternal
+		{
+			get
+			{
+				EnsureLoaded();
+				return _loaded ? FormatInternalVersion(_versionData) : Application.version;
+			}
+		}
 
 		/// <summary>
-		/// Name of the git branch that this app was built from.
+		/// Name of the git branch that this app was built from. Lazy-loads on first access; returns
+		/// <see cref="string.Empty"/> when the <c>version-data</c> Resource is missing.
 		/// </summary>
-		public static string Branch => IsLoaded() ? _versionData.BranchName : string.Empty;
+		public static string Branch
+		{
+			get
+			{
+				EnsureLoaded();
+				return _loaded ? _versionData.BranchName : string.Empty;
+			}
+		}
 
 		/// <summary>
-		/// Short hash of the commit this app was built from.
+		/// Short hash of the commit this app was built from. Lazy-loads on first access; returns
+		/// <see cref="string.Empty"/> when the <c>version-data</c> Resource is missing.
 		/// </summary>
-		public static string Commit => IsLoaded() ? _versionData.CommitHash : string.Empty;
+		public static string Commit
+		{
+			get
+			{
+				EnsureLoaded();
+				return _loaded ? _versionData.CommitHash : string.Empty;
+			}
+		}
 
 		/// <summary>
-		/// Build number for this build of the app.
+		/// Build number for this build of the app. Lazy-loads on first access; returns
+		/// <see cref="string.Empty"/> when the <c>version-data</c> Resource is missing.
 		/// </summary>
-		public static string BuildNumber => IsLoaded() ? _versionData.BuildNumber : string.Empty;
+		public static string BuildNumber
+		{
+			get
+			{
+				EnsureLoaded();
+				return _loaded ? _versionData.BuildNumber : string.Empty;
+			}
+		}
 
 		private static VersionData _versionData;
 		private static bool _loaded;
 
 		/// <summary>
-		/// Load the internal version string from resources synchronously. Should be called once
-		/// when the app is started. Intended for tiny payloads (the default <c>version-data.txt</c>
-		/// is a few hundred bytes); use <see cref="LoadVersionDataAsync"/> if <see cref="VersionData"/>
-		/// is extended with large blobs that would noticeably stall the main thread.
+		/// Auto-bootstrap hook: populates version metadata at the earliest runtime phase Unity
+		/// exposes, before any scene <c>Awake</c> and before vendor SDK <c>SubsystemRegistration</c>
+		/// callbacks that read <see cref="VersionInternal"/> / <see cref="BuildNumber"/> (e.g.
+		/// Sentry's Option Config Script). Consumers no longer need to call
+		/// <see cref="LoadVersionData"/> / <see cref="LoadVersionDataAsync"/> explicitly for the
+		/// default flow.
+		/// </summary>
+		/// <remarks>
+		/// Ordering between <see cref="RuntimeInitializeLoadType.SubsystemRegistration"/> callbacks
+		/// across assemblies is undefined; if a sibling SDK's hook fires before this one, the
+		/// property accessors' lazy-load fallback (<see cref="EnsureLoaded"/>) covers the race.
+		/// </remarks>
+		[RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
+		private static void Bootstrap()
+		{
+			LoadVersionData();
+		}
+
+		/// <summary>
+		/// Load the internal version string from resources synchronously. Auto-invoked by
+		/// <see cref="Bootstrap"/> at <see cref="RuntimeInitializeLoadType.SubsystemRegistration"/>;
+		/// safe to call directly for explicit pre-warming. Idempotent — short-circuits via
+		/// <see cref="EnsureLoaded"/>'s caller when version data is already loaded. Intended for
+		/// tiny payloads (the default <c>version-data.txt</c> is a few hundred bytes); use
+		/// <see cref="LoadVersionDataAsync"/> if <see cref="VersionData"/> is extended with large
+		/// blobs that would noticeably stall the main thread.
 		/// </summary>
 		public static void LoadVersionData()
 		{
@@ -77,8 +131,12 @@ public static void LoadVersionData()
 		}
 
 		/// <summary>
-		/// Load the internal version string from resources async. Should be called once when the
-		/// app is started.
+		/// Load the internal version string from resources async. The synchronous
+		/// <see cref="LoadVersionData"/> is auto-invoked at
+		/// <see cref="RuntimeInitializeLoadType.SubsystemRegistration"/>, so callers only need this
+		/// async variant when explicitly pre-warming off the main thread or when
+		/// <see cref="VersionData"/> has been extended with large blobs that would noticeably stall
+		/// the main thread.
 		/// </summary>
 		public static async Task LoadVersionDataAsync()
 		{
@@ -160,9 +218,11 @@ public static string FormatInternalVersion(VersionData data)
 			return version;
 		}
 
-		private static bool IsLoaded()
+		private static void EnsureLoaded()
 		{
-			return _loaded ? true : throw new Exception("Version Data not loaded.");
+			if (_loaded) return;
+
+			LoadVersionData();
 		}
 	}
 }

Samples~/README.md

@@ -112,7 +112,7 @@ These are the mistakes most likely to bite first-time users — every sample bel
 - **`DataService` keys `PlayerPrefs` by `typeof(T).Name`.** Two types named `PlayerData` in different namespaces will collide.
 - **`PoolService.AddPool<T>` throws on duplicate registrations.** One pool per type. Call `RemovePool<T>()` first if you need to re-register.
 - **`AssetResolverService.RequestAsset` / `LoadSceneAsync` throw `MissingMemberException` until you call `AddConfigs` / `AddAssets`.** Sample 2 demonstrates the registration step.
-- **`VersionServices.VersionInternal` / `Branch` / `Commit` / `BuildNumber` throw until `LoadVersionDataAsync()` completes.** `VersionExternal` is always safe (reads `Application.version`).
+- **`VersionServices` auto-bootstraps at `SubsystemRegistration` + lazy-loads on first property access.** `VersionInternal` / `Branch` / `Commit` / `BuildNumber` are safe to read at any time; missing `version-data.txt` returns `Application.version` / `string.Empty` and logs an error. `LoadVersionData()` / `LoadVersionDataAsync()` remain available for explicit pre-warming.
 - **`TickService` and `CoroutineService` each create a `DontDestroyOnLoad` GameObject.** Always `Dispose()` them on teardown, otherwise the host objects accumulate across domain reloads. The playground bootstrap uses `MainInstaller.CleanDispose<T>()` for this.
 - **`IAsyncCoroutine.StopCoroutine(triggerOnComplete)`** — the parameter is currently not respected. The completion callback fires regardless. Do not rely on cancellation-without-callback semantics.
 

Tests/EditMode/Unit/VersionServicesSyncLoadTest.cs

@@ -1,4 +1,3 @@
-using System;
 using System.Reflection;
 using GameLovers.Services;
 using NUnit.Framework;
@@ -27,12 +26,16 @@ public void ResetStaticState()
 		}
 
 		[Test]
-		public void AccessBeforeLoad_Throws()
+		public void AccessBeforeLoad_AutoLoads()
 		{
-			Assert.Throws<Exception>(() => { var _ = VersionServices.VersionInternal; });
-			Assert.Throws<Exception>(() => { var _ = VersionServices.Branch; });
-			Assert.Throws<Exception>(() => { var _ = VersionServices.Commit; });
-			Assert.Throws<Exception>(() => { var _ = VersionServices.BuildNumber; });
+			Assert.IsFalse((bool)LoadedField.GetValue(null), "Precondition: SetUp resets _loaded to false");
+
+			Assert.DoesNotThrow(() => { var _ = VersionServices.VersionInternal; });
+			Assert.DoesNotThrow(() => { var _ = VersionServices.Branch; });
+			Assert.DoesNotThrow(() => { var _ = VersionServices.Commit; });
+			Assert.DoesNotThrow(() => { var _ = VersionServices.BuildNumber; });
+
+			Assert.IsTrue((bool)LoadedField.GetValue(null), "Accessor should auto-trigger LoadVersionData via EnsureLoaded");
 		}
 
 		[Test]

Tests/PlayMode/Integration/VersionServicesIntegrationTest.cs

@@ -1,4 +1,3 @@
-using System;
 using System.Collections;
 using System.Reflection;
 using GameLovers.Services;
@@ -26,12 +25,16 @@ public void ResetStaticState()
 		}
 
 		[UnityTest, Order(1)]
-		public IEnumerator AccessBeforeLoad_Throws()
+		public IEnumerator AccessBeforeLoad_AutoLoads()
 		{
-			Assert.Throws<Exception>(() => { var _ = VersionServices.VersionInternal; });
-			Assert.Throws<Exception>(() => { var _ = VersionServices.Branch; });
-			Assert.Throws<Exception>(() => { var _ = VersionServices.Commit; });
-			Assert.Throws<Exception>(() => { var _ = VersionServices.BuildNumber; });
+			Assert.IsFalse((bool)LoadedField.GetValue(null), "Precondition: SetUp resets _loaded to false");
+
+			Assert.DoesNotThrow(() => { var _ = VersionServices.VersionInternal; });
+			Assert.DoesNotThrow(() => { var _ = VersionServices.Branch; });
+			Assert.DoesNotThrow(() => { var _ = VersionServices.Commit; });
+			Assert.DoesNotThrow(() => { var _ = VersionServices.BuildNumber; });
+
+			Assert.IsTrue((bool)LoadedField.GetValue(null), "Accessor should auto-trigger LoadVersionData via EnsureLoaded");
 
 			yield return null;
 		}