Unity Asset Registry

The Unity Asset Registry is the bridge between the data-driven Gnosis Engine and Unity’s physical assets (Sprites, Prefabs, AudioClips, etc.). It allows services to request assets by a string ID without needing direct references to Unity objects in the core logic.

How it Works

The UnityAssetRegistry is a MonoBehaviour that lives in your Unity scene. It maintains a collection of “Custom Lists,” where each list maps a unique string ID to a specific Unity asset.

Key Responsibilities:

• Centralized Lookups: Services like Audio, UI, and Animation use the registry to find the assets they need to display or play.
• Decoupling: The core C# services only know about IDs (e.g., "sword_icon", "hit_sfx"). The registry is responsible for providing the actual Sprite or AudioClip.
• Dynamic Organization: Assets are organized into logical lists (e.g., a “Boons” list for sprites, a “Feedbacks” list for MMF players).

[!WARNING] Global ID Uniqueness is Required. Even though assets are organized into multiple “Custom Lists,” every ID must be unique across the entire registry. The engine uses a single global lookup cache for each asset type (e.g., all Sprites are stored in one dictionary regardless of which list they came from). If you have the same ID in two different lists of the same type, the engine will keep the first one and log a warning for the duplicate.

Supported Asset Types

The registry can store and provide various Unity types:

• Sprites: Used by UI and game objects for icons and visuals.
• Prefabs: Spawning entities, VFX, or UI elements.
• AudioClips: Sound effects and music tracks used by the Audio service.
• Materials: Swapping visuals at runtime.
• Particle Systems: Specific references for the Animation service.
• Scene Objects: Bindings to existing objects in the hierarchy (e.g., a specific Camera or a UI Root).

Usage in Services

When a service needs an asset, it calls the registry through its Unity adapter.

Example: Audio Service

1. A rule triggers a CALL_SERVICE to Audio.PlaySound with clipId: "level_up".
2. The GnosisAudioService (Core) receives the request.
3. The UnityAudioAdapter (Unity) asks the UnityAssetRegistry: "Do you have an AudioClip with ID 'level_up'?".
4. If found, the adapter plays the returned AudioClip.

Example: UI Icon Binding

// Inside a Unity Component
string iconId = node["iconId"]; // e.g., "fire_blast"
Sprite icon = assetRegistry.GetSprite(iconId);
image.sprite = icon;

Setting up the Registry

1. Locate the UnityAssetRegistry component in your scene (usually on the same object as UnityGnosisEngine).
2. In the Registry Lists section, add a new AssetDynamicList.
3. Give it an ID (e.g., "Items") and an Entry Type (e.g., Sprite).
4. Add your assets to the Entries list, assigning each a unique string ID.

Special List: Feedbacks

The ID "Feedbacks" is reserved for integration with the Animation service. Any asset (usually an MMF_Player or a ParticleSystem) placed in this list can be triggered via the REQUEST_ANIMATION_PLAY_FEEDBACK event.

Best Practices

• Consistent Naming: Use the same IDs in your JSON configuration as you do in the registry.
• Logical Grouping: Use multiple lists to organize your assets (e.g., "UI_Icons", "VFX_Prefabs", "Boon_Sprites").
• Case Sensitivity: By default, lookups are case-sensitive. Ensure your IDs match exactly.
• Pre-warming: The registry builds its lookup caches on Awake. If you add assets dynamically at runtime, call RebuildLookupCaches() to update the dictionaries.