f8-features-assetmanager-workflow

name	f8-features-assetmanager-workflow
description	Use when implementing or troubleshooting AssetManager feature workflows — asset loading, AB mapping, runtime resource retrieval, and scene loading in F8Framework.

AssetManager Feature Workflow

⚠️ IMPORTANT: Before using this feature, you MUST formally initialize F8Framework in the launch sequence. Ensure ModuleCenter.Initialize(this); has run first, then create the required module, for example FF8.Asset = ModuleCenter.CreateModule<AssetManager>();.

Use this skill when

• The task is about asset loading (sync/async), AB mapping, and runtime resource retrieval.
• The user asks about Resources vs AssetBundle loading strategies.
• The user needs to load scenes, sprites, prefabs, or remote assets at runtime.
• Troubleshooting asset loading failures, purple shaders, or missing assets.

Path resolution

1. Prefer project source at Assets/F8Framework.
2. If F8Framework is installed as a package, use Packages/F8Framework.
3. For usage docs, read: Assets/F8Framework/Tests/AssetManager/README.md

Sources of truth

• Runtime module: Assets/F8Framework/Runtime/AssetManager
• Editor module: Assets/F8Framework/Editor/AssetManager
• Asset index files: Assets/F8Framework/AssetMap
• Test docs: Assets/F8Framework/Tests/AssetManager

Key classes and interfaces

Class	Role
AssetManager	Core module. Access via FF8.Asset. Handles all loading/unloading.
AssetBundleManager	Manages AB manifest, AB loading/caching, and dependencies.
BaseLoader	Async load handle. Supports yield / await / callback patterns.
BaseDirLoader	Async folder load handle.
SceneLoader	Async scene load handle with AllowSceneActivation() support.

API quick reference

Configuration

FF8.Asset.IsEditorMode = true;  // Skip AB, load from AssetDatabase (Editor only)

Sync loading

GameObject cube = FF8.Asset.Load<GameObject>("Cube");
// Full path (needs F5 setting enabled)
GameObject prefab = FF8.Asset.Load<GameObject>("AssetBundles/Prefabs/Cube");
// Sub-asset (e.g., Multiple-mode Sprite)
Sprite sp = FF8.Asset.Load<Sprite>("PackForest01", "PackForest01_12");
// Force remote
Sprite remote = FF8.Asset.Load<Sprite>("PackForest01", "PackForest01_12",
    AssetManager.AssetAccessMode.REMOTE_ASSET_BUNDLE);

Async loading

// Callback
FF8.Asset.LoadAsync<GameObject>("Cube", (go) => { Instantiate(go); });
// Coroutine
yield return FF8.Asset.LoadAsync<GameObject>("Cube");
// async/await (WebGL compatible)
await FF8.Asset.LoadAsync<GameObject>("Cube");
// Loader handle
BaseLoader loader = FF8.Asset.LoadAsync<GameObject>("Cube");
yield return loader;
GameObject result = loader.GetAssetObject<GameObject>();

Batch loading

FF8.Asset.LoadDir("UI/Prefabs");                         // Sync folder
FF8.Asset.LoadDirAsync("UI/Prefabs", () => { });          // Async folder
BaseDirLoader dirLoader = FF8.Asset.LoadDirAsync("UI/Prefabs"); // Loader handle
// Interate progress
foreach (var progress in FF8.Asset.LoadDirAsyncCoroutine("UI/Prefabs"))
{
    yield return progress;
}
FF8.Asset.LoadAll("Cube");                                // All assets in same AB
FF8.Asset.LoadSub("Atlas");                               // All sub-assets

Scene loading

FF8.Asset.LoadScene("MainScene");                         // Sync
SceneLoader sl = FF8.Asset.LoadSceneAsync("MainScene");   // Async
// Manual activation
SceneLoader sl2 = FF8.Asset.LoadSceneAsync("MainScene",
    new LoadSceneParameters(LoadSceneMode.Single), allowSceneActivation: false);
sl2.AllowSceneActivation();

Resource management

float p = FF8.Asset.GetLoadProgress("Cube");   // Single asset progress
float t = FF8.Asset.GetLoadProgress();          // Total progress
GameObject cachedCube = FF8.Asset.GetAssetObject<GameObject>("Cube"); // Get cached
FF8.Asset.Unload("Cube", false);               // Keep dependencies
FF8.Asset.Unload("Cube", true);                // Full unload
FF8.Asset.UnloadAsync("Cube", false, () => {}); // Async unload
FF8.Asset.UnloadScene("Scene");
FF8.Asset.UnloadUnused(true);
FF8.Asset.UnloadSceneAsync("Scene");
FF8.Asset.UnloadUnusedAsync(true);

Workflow

1. Ensure F8 has been pressed at least once to generate asset index and AB names.
2. Configure Editor mode if in development: FF8.Asset.IsEditorMode = true.
3. Choose loading strategy: sync for gameplay-critical, async for large resources.
4. For SpriteAtlas: load atlas first, or set atlas and sprites to same AB name.
5. For remote assets: configure remote address in F5 build tool first.
6. Track loading progress via GetLoadProgress() for loading screens.
7. Unload unused assets to manage memory.

Common error handling

Error	Cause	Solution
Purple shaders on Android/iOS AB in Editor	Loading cross-platform AB	Enable Editor mode: FF8.Asset.IsEditorMode = true
Scene load fails from AB	Cross-platform AB issue	Enable Editor mode or build AB for current platform
Sprite loads as null but Texture2D works	Asset was first loaded as Texture2D	Load as correct type first, or use Load<Sprite>
WebGL sync AB load fails	WebGL cannot sync-load AB	Use Resources for sync or switch to async AB loading
Same-name asset conflict	Two assets share the same name	Enable full-path loading in F5 build tool
AB not found after moving files	Stale AB names on moved files	Manually clear AB names on moved files
Skybox purple after scene load	Missing skybox material in build	Include skybox material in a loadable directory
Resources scene load fails	Scene in Resources folder	Move scene out of Resources or use Build Settings

Cross-module dependencies

• ExcelTool: Config binary/json files are loaded via AssetManager.
• HotUpdateManager: Uses AssetManager for hot update asset downloads.
• Audio: Audio clips loaded through AssetManager.
• UI: UI prefabs loaded through AssetManager.
• Localization: Localization resources loaded through AssetManager.

Output checklist

• Effective loading method selected (sync/async/batch).
• Editor mode configuration documented.
• Files changed and why.
• Validation status and remaining risks.