feat: load local asset bundles in local scene development (local-ab)

[dalkia]

Pull Request Description

What does this PR change?

Local scene development (LSD) always loads raw GLTFs, so creators never preview a scene the way it renders in production (compressed BC7/BC5 textures, Unity-native meshes, converted materials). This PR adds an opt-in mode where the local scene's asset bundles are loaded from a locally running abgen server (an ab-cdn-compatible JIT converter) instead:

• New --local-ab app arg (also a "Use Local Asset Bundles" toggle in the Main Scene Loader inspector when Initial Realm is Localhost), exposed as FeatureId.LSD_LOCAL_ASSET_BUNDLES.
• In this mode the scene's asset-bundle manifest is fetched from --optimized-assets-url (which now defaults to http://127.0.0.1:5147, abgen's default port, when the flag is on and no URL is given) instead of using the manual LSD manifest. Real v49 manifests mean the existing URL/cache-key logic applies unchanged.
• Graceful degrade: if the manifest fetch fails (abgen not running), the whole scene falls back to today's raw-GLTF loading.
• Skips TryOverrideWithCDNAsync in LSD so scene code always comes from the live preview server (a real manifest version would otherwise make CDN HEAD-probes eligible).
• Disables Unity's asset-bundle disk cache in LSD — the dev server's hashes are path-based, not content-based, so any disk cache can serve stale bundles across reloads/sessions.
• --local-ab takes precedence over --lsd-use-remote-ab if both are passed (logs a warning); hybrid-scene behavior is untouched.

This is the explorer half of the Creator Hub "Optimized Assets" preview feature: Creator Hub spawns abgen as a sidecar and passes these params via deeplink; the same flags also enable a pure editor/CLI workflow.

Docs: docs/how-to-connect-to-a-local-scene.md has a new "Local asset bundles (abgen)" section.

Test Instructions

Steps (standard run — regression):

metaforge explorer run 9459

Expected result:
Normal Genesis City play mode is unchanged (asset bundles from ab-cdn as usual). Local scene development without the new flag is unchanged (raw GLTFs).

Prerequisites

• An SDK7 scene running locally: npm run start -- -p 8000 in the scene folder
• An abgen server pointed at it (from the abgen repo, cargo build --release --bin abgen):

ABGEN_CATALYST_URL=http://127.0.0.1:8000/content \
ABGEN_MANIFEST_CONTENT_SERVER_URL=http://127.0.0.1:8000/content \
ABGEN_JIT_CONTENT_DIGEST=1 ABGEN_DEPS_DIGEST=0 \
ABGEN_UPSTREAM_AB_CDN=https://ab-cdn.decentraland.org \
./target/release/abgen

Test Steps

1. Launch the build with --realm http://127.0.0.1:8000 --position 0,0 --local-scene true --local-ab true --debug --skip-version-check true (no --optimized-assets-url needed — it defaults to abgen's port 5147). In the Unity Editor: Main Scene Loader → Initial Realm = Localhost, tick Use Local Asset Bundles, Play.
2. The scene loads with asset bundles: abgen's console shows the manifest GET, ABGEN_BUILD conversion lines, then one bundle GET per asset; scene textures inspect as BC7 (raw GLTF path produces RGBA32). curl -s http://127.0.0.1:5147/metrics | grep abgen_http_requests_total shows the client's requests.
3. Degrade test: stop abgen, reload the scene (edit a file or relaunch) → scene still renders via raw GLTFs, no exception spam.
4. Hot reload: with abgen running, overwrite a .glb in the scene → scene reloads → only that asset reconverts (abgen logs a revalidate: content changed line) and the updated model appears.
5. Avatars/wearables render normally (served through abgen's upstream ab-cdn read-through).

Additional Testing Notes

• First scene load with abgen waits on JIT conversion of every GLB (seconds, cached afterward); subsequent loads are instant.
• --local-ab + --lsd-use-remote-ab together: local wins, warning logged.
• Known follow-up (out of scope): per-asset AB→raw fallback — today a single failed bundle marks that GltfContainer as failed; only a failed manifest triggers the whole-scene raw degrade.

Quality Checklist

• Changes have been tested locally
• Documentation has been updated (if required)
• Performance impact has been considered
• For SDK features: Test scene is included

🤖 Generated with Claude Code

[github-actions]

Windows and Mac build successful in Unity Cloud! You can find a link to the downloadable artifact below.

Name	Link
Commit	1603abc
Logs	https://github.com/decentraland/unity-explorer/actions/runs/29864325460
Download Windows	https://github.com/decentraland/unity-explorer/suites/80891001739/artifacts/
Download Windows S3	https://explorer-artifacts.decentraland.org/@dcl/unity-explorer/branch/feat/lsd-local-asset-bundles/pr-24084-1603abc/Decentraland_windows64.zip
Download Mac	https://github.com/decentraland/unity-explorer/suites/80891001739/artifacts/8510368148
Download Mac S3	https://explorer-artifacts.decentraland.org/@dcl/unity-explorer/branch/feat/lsd-local-asset-bundles/pr-24084-1603abc/Decentraland_macos.zip
Built on	2026-07-21T21:16:09Z