Unity Addressables

Crystal Save can load its configuration assets through Unity’s Addressables system once you replace the default Resources workflow with Addressable entries.

Prerequisites

  • Unity Addressables package installed through the Package Manager. The DefineSymbols utility detects the UnityEngine.AddressableAssets namespace and sets the REMEMBERME_ADDRESSABLES_PRESENT scripting define automatically.

  • Existing Crystal Save assets generated by the onboarding wizard (for example SaveSettings, PrefabRegistry, TagRegistry, SceneObjectRegistry, MigrationManager, SaveSlotMetadata) under Assets/Plugins/CrystalSave/Resources/

1. Install and verify Addressables

  1. Open Window ▸ Package Manager, add Addressables.

  2. Wait for the editor to recompile

2. Relocate the Crystal Save assets

Move the generated assets out of every Resources folder so Addressables can own their lifecycle. A common pattern is Assets/My Settings/Crystal Save/. The settings window already looks for assets anywhere in the project, so relocation will not break the editor tooling.

Assets to relocate:

  • SaveSettings

  • PrefabRegistry

  • TagRegistry

  • SceneObjectRegistry

  • MigrationManager

  • SaveSlotMetadata

  • Any module-specific registries you rely on (e.g., audio, texture, quest registries).

3. Mark the assets as Addressable

  1. Open Window ▸ Asset Management ▸ Addressables ▸ Groups.

  2. Drag each Crystal Save asset into an Addressables group.

  3. For each asset, change the Address field to the key Crystal Save expects:

    • SaveSettings

    • PrefabRegistry

    • TagRegistry

    • SceneObjectRegistry

    • MigrationManager

    • SaveSlotMetadata

    • Add matching keys for any module registry assets you use (audio clips, textures, quests, etc.).

  1. Ensure no duplicate addresses remain; Crystal Save loads each asset via AssetProvider.Load("<key>") at runtime.​

The Addressables help window (question-mark button) summarizes these steps if you need a refresher.​

4. Enable Addressables inside Crystal Save

  1. Open Tools ▸ Crystal Save ▸ Settings ▸ Crystal Save Settings.

  2. In either the settings window or the inspector, enable Use Addressables.

  • This flag drives SaveSettings.useAddressables and toggles the runtime AssetProvider to prefer Addressables over Resources.

5. Build or update the Addressables catalog

Whenever you add or move the Crystal Save assets, rebuild the catalog:

  1. Open the Addressables Groups window.

  2. Choose Build ▸ New Build ▸ Default Build Script (or Update a Previous Build).​

6. Verify the setup

  • Enter Play Mode and watch the console: AssetProvider logs an error if a key is missing from the Addressables catalog, reminding you to mark the asset and set its address correctly.​

    • WRONG SETUP:

    • CORRECT SETUP:

  • Prefab pooling, tag lookups, scene-object spawning, migrations, and metadata retrieval all rely on the assets listed above. If any feature fails, double-check that the corresponding asset is Addressable and shares the expected key.

Troubleshooting

  • Addressables toggle disabled – Install the Addressables package; the UI is hidden when the scripting define is missing.​

  • Assets still created under Resources – Delete or move the old Resources copy; keep a single authoritative asset to avoid ambiguity.

  • Runtime still loading Resources – Verify Use Addressables remains enabled on the SaveSettings asset and that the Addressables catalog was rebuilt after the change.​

PreviousStreaming Deferred Prefabs & Scene GameObjectsNextV1.6 – Live Conflict Resolver

Last updated