t1k:unity:tof:addressables

Field	Value
Module	`tof`
Version	`2.2.2`
Effort	`low`
Tools	—

Keywords: addressable, addressables, asset group, blueprints group, theonefeature, tof, TOFAudios, TOFSprites, TOFUIs

How to invoke

/t1k:unity:tof:addressables

TheOneFeature Addressables Groups

TOF assets are organized into a fixed set of Addressables groups in Assets/AddressableAssetsData/AssetGroups/. Placement is by asset type, not by feature — a single feature’s assets fan out across multiple groups.

Canonical Groups

Group	Holds	Example contents
`TOFAudios.asset`	Audio clips bundled with TOF	Reward jingles, UI clicks shipped from TOF features
`TOFButtons.asset`	Button prefabs with TOF dependencies	Feature-entry buttons, claim buttons
`TOFSkins.asset`	Theme/skin prefabs	Recolor variants, themed panels
`TOFSprites.asset`	UI sprites + atlases	Reward icons, banner sprites
`TOFUIs.asset`	TOF UI screens and popups	BattlePass screen, RaceEvent panel, PeriodRewardAds popup
`Blueprints.asset`	Plaintext `Assets/Blueprints/*.csv`	`CollectibleObjectBlueprint.csv`, `PeriodRewardAdsBlueprint.csv`
`Currencies.asset`	Currency icons + ScriptableObjects	Coin, gem, key icons

Where Things Go — Decision Tree

New TOF asset
├── .csv blueprint?           → Blueprints group
├── currency icon/SO?         → Currencies group
├── audio clip?               → TOFAudios
├── button prefab?            → TOFButtons
├── UI screen / popup prefab? → TOFUIs
├── sprite / atlas?           → TOFSprites
└── skin / themed prefab?     → TOFSkins

If an asset doesn’t cleanly fit any group, do not create a new group reflexively — first check whether the asset belongs in the project’s main UI groups (non-TOF). New TOF groups should only be created with explicit user approval, since group renames break Addressables address keys.

Adding an Asset

Recommended: do this via the Unity Addressables Editor window (drag asset → group). The .asset YAML files in Assets/AddressableAssetsData/AssetGroups/ are owned by Addressables and hand-editing is risky — see unity-text-config gotchas on YAML edits.

If you must edit the group .asset text:

Each entry is a m_SerializeEntries block with the asset GUID. The GUID must match the asset’s .meta file. A mismatched GUID silently drops the entry at build time.
Preserve the existing order — Addressables does not require it, but minimal diffs make review tractable.

Group Settings Snapshot

All TOF groups use the default BundledAssetGroupSchema — no remote catalog, no compression overrides.
Labels are not used to gate TOF assets; presence in the group is sufficient.
Duplicate Asset Isolation*.asset groups: Unity auto-generates these during analyze. Delete only after running Analyze → Fix Duplicates; deleting a populated isolation group orphans the duplicated assets.

Verification

After adding entries, run Addressables → Build → New Build → Default Build Script to surface schema errors.
Use Addressables → Analyze to confirm no duplicates spilled into the default Local group.
IAssetsManager.LoadAsync<T>("<address>") at runtime should resolve — a null return usually means the address key is wrong or the asset isn’t in any group.

Gotchas

Address key = filename without extension by default. Renaming an asset breaks every runtime LoadAsync<>() call. Use explicit address overrides if a rename is required.
_Game/ folders are NOT TOF. Per consumer governance (AI_GOVERNANCE.md), Assets/_Game/* belongs to MainGame. Do not move MainGame assets into TOF groups — and vice versa.
Submodule assets (under Assets/TheOneFeature/, Assets/UITemplate/) often ship with their own Addressables entries. Do not duplicate them into the consumer’s TOF groups — Addressables will warn on duplicate addresses.