chore: iss via standalone descriptor (descriptor-only, bundle deferred)

[dalkia]

Pull Request Description

What is "Initial Scene State (ISS)"?

When you walk through Decentraland and a scene comes into view, the runtime needs to fetch, instantiate, and render every asset in that scene before you see anything. For a complex parcel that can take seconds — the scene "pops in" once it's ready. ISS is a streaming optimization that gives the player something to look at while the real scene loads: a lightweight, pre-baked snapshot of the scene's static geometry that the LOD pipeline can show immediately, then seamlessly hand off to the SDK runtime once the real scene is ready.

How it relates to the existing LOD pipeline

Decentraland already has a distance-based LOD system: each scene has multiple progressively-simpler versions baked (LOD_0 and LOD_1). Until ISS, LOD_0 (the closest, highest-quality version) was a separate copy that the client downloaded in full, instantiated as its own GameObjects, and then threw away and re-downloaded the same assets again once the player walked close enough to trigger the real SDK scene — so we paid the bandwidth and instantiation cost twice for the same geometry.

ISS replaces LOD_0 with a smarter representation: instead of duplicating the scene's assets in a separate LOD bundle, the descriptor points at the same per-asset bundles the SDK runtime will load anyway, plus the transforms needed to show them at preview time. The LOD path and the SDK runtime now share the underlying GameObjects via a "bridge" — when the LOD instance is no longer needed (the player walked close enough), it transitions into the running scene instead of being destroyed and re-created. No double download, no double instantiation.

LOD_1+ are unchanged and still used as-is for far-distance fallback. They're produced by the new LOD generator: https://github.com/decentraland/lod-generator-unity

How the descriptor reaches the client

For each scene the bake pipeline can publish a small JSON descriptor next to the asset bundles. The descriptor lists which GLTF assets to show as the "initial state" and where to place them (position / rotation / scale). The client fetches the descriptor as soon as the scene starts coming into range, instantiates the listed assets at LOD distance, and reuses them via the bridge described above when the SDK scene starts.

The two paths an ISS descriptor can take:

• Descriptor mode (this PR): the descriptor is a standalone JSON file at the LOD manifest bucket; the client fetches each listed asset as its own asset bundle from the standard AB CDN.
• Bundle mode (legacy, deferred to a follow-up): the descriptor + every listed asset are packed into one shared staticscene_<sceneId><platform> AB.

What does this PR change?

The old ISS shipped the descriptor inside the single bundled AB (the staticscene_* one). To read the descriptor, the client had to download and open that whole AB. With ISS evolving toward shared GameObjects between LOD and SDK runtime, two things changed:

1. The descriptor is now a standalone JSON file at the LOD manifest bucket — small, easy to fetch, easy to disk-cache, no AB unpack required.
2. The Bundle-mode AB is not currently being built. There are asset bundles reusability concerns to be solved in the asset bundle converter before we can publish the shared staticscene_* bundles correctly. So for now the per-asset bundles produced by the converter for the regular scene load are what gets served; the shared bundle is deferred to a follow-up PR + bake-side coordination.

Most of the diff in this PR is the consequence of those two shifts: the descriptor moves from embedded-in-AB to a freestanding JSON loader with its own disk cache, an ECS component on each scene entity that the radius gate consults lazily, and a digest-aware shared GLTF cache so the LOD path and the SDK runtime hit the same underlying assets without colliding in Unity's AB tracker.

The Bundle-mode plumbing is structurally kept (state enum, dormant queries) so reviving it later is a small targeted change.

Highlights

• ISSDescriptor is an ECS component on each scene entity (class with mutable internal state — same reference for the scene's lifetime). Constructed in Uninitialized for scenes that may have ISS, or None for opt-outs (PX / static-pointer / smart-wearable previews). The resolver mutates state in place via MarkResolved, so cached references in OrderedDataManaged and GetSceneFacadeIntention see the resolved state without a re-fetch — no World.Get in the gate hot path.
• Radius-gated resolution. ResolveSceneStateByIncreasingRadiusSystem attaches the resolver promise on the first SHOWING_LOD / SHOWING_SCENE transition for an Uninitialized scene, then bails for one tick until ResolveISSDescriptorSystem consumes the promise. Scenes that never come into range never trigger a descriptor lookup.
• ResolveISSLODSystem (descriptor mode) spawns one AB promise per descriptor entry, applies the transform, counts failures via AddFailedAsset so AllAssetsInstantiated settles even when individual assets 404. Bridge handoff to the SDK runtime is reservation-based (ISSDescriptor.TryReserveBridgeSlot) capped at the descriptor's per-hash multiplicity, so SDK-instantiated copies of the same hash at runtime never pollute the bridge.
• Digest-aware GLTF cache reuse. Both LOD and SDK runtime paths key the GLTF container cache by hash@digest via AssetBundleManifestVersionExtensions.ComposeCacheKey, so bridged assets round-trip cleanly between the two without spawning duplicate instances. Per-asset AB promises also populate GetAssetBundleIntention.DepsDigest from the manifest, making the (Hash, DepsDigest) cache key match the SDK runtime's — this eliminated the "asset bundle already loaded" Unity error from parallel loads of the same physical bundle.
• SupportsISS() on AssetBundleManifestVersion mirrors SupportsDepsDigests(). Cached version-number check; gates the descriptor lookup so pre-v49 manifests skip the network round-trip.
• Disk-cached descriptors with text-editor-readable JSON. None results are not persisted (decorator skips).

Files of interest

• Explorer/Assets/DCL/Infrastructure/ECS/StreamableLoading/AssetBundles/InitialSceneState/ISSDescriptor.cs — descriptor + bridge state + JSON DTOs + MarkResolved (in-place mutation)
• Explorer/Assets/DCL/Infrastructure/ECS/StreamableLoading/AssetBundles/InitialSceneState/LoadISSDescriptorSystem.cs — LoadSystemBase<ISSDescriptor, GetISSDescriptor> hitting the LOD bucket
• Explorer/Assets/DCL/Infrastructure/ECS/SceneLifeCycle/IncreasingRadius/ResolveSceneStateByIncreasingRadiusSystem.cs — the gate that spawns the resolver promise on first LOD/Scene transition
• Explorer/Assets/DCL/Infrastructure/ECS/SceneLifeCycle/SceneDefinition/Systems/ResolveISSDescriptorSystem.cs — consumes the promise, mutates the entity's descriptor in place
• Explorer/Assets/DCL/LOD/Systems/ResolveISSLODSystem.cs — descriptor mode + digest-aware cache reuse + bridge slot reservation

Removed: EarlySceneRequestSystem + EarlyAssetBundleRequestSystem

Removed until we decide how to use them effectively just with the descriptor. For cognitive and scope reasons, this will be done on a later PR.

Deferred to a follow-up PR: Bundle mode

The legacy single-bundle ISS path (one shared staticscene_<sceneID><platform> AB containing every listed asset) is structurally kept but disabled at the loader level. LoadISSDescriptorSystem.IsBundleReachableAsync is commented out and every ISS-capable scene resolves directly to IISSDescriptor.State.Descriptor for now. ISSDescriptor.SupportsBundle() returns false so the ResolveISSLODSystem bundle branch is dormant. The plumbing (Bundle state enum value, bundle-mode query, helper functions) is left in place so re-enabling is a one-line restore in a later PR.

Doing this in two steps keeps the cognitive load of the current review focused on the descriptor pipeline; bundle mode will come back with its own targeted PR + bake-side coordination.

Important: AB Converter doesn't bake ISS bundles yet

The asset bundle converter doesn't currently have ISS bundle baking enabled. This PR can be exercised end-to-end against v49+ manifests for the descriptor-only path — but if you point it at a realm whose scenes were not baked with descriptor JSONs in the LOD bucket, you'll just see scenes resolve to None (no ISS) and fall through to the legacy LOD path. The descriptor-mode happy path requires both the descriptor JSON and per-asset bundles to exist at the expected URLs.

Test Instructions

Steps (standard run):

metaforge explorer run XXXX  # ← replace with this PR number

Test Steps

1. Genesis Plaza (zone) — ISS happy path.
   Spawn into Genesis Plaza on zone and explore: walk around, move outward and back, change directions.

   • LOD preview pops in early via ISS (less noticeable blank moments before geometry shows).
   • When you walk close enough to trigger the real scene, the LOD geometry transitions into the SDK scene without duplicate copies of the same asset, and without "asset bundle already loaded" errors in the log.
   • Scenes outside your loading radius unload cleanly and re-load on the way back.
   • Spawn on a remote coordinate (-15,-20 ie) and walk towards Genesis Plaza. See that the scene loads correctly
   • Go to 100,100. Press the Memory Full Button in the debug menu. The memory should go down considerably.
     When it stabilizes, go back to 0,0. Repeat the previous steps, all should work

2. Regression — every other scene-loading path. Sanity-check that nothing else broke:

   • Genesis City on org — descriptors don't exist there yet, so every scene should fall through to the legacy LOD path (one 403 per scene from the LOD bucket is expected and now suppressed in the log; behavior should otherwise be identical to main).
   • LSD scene (Local Scene Development) — load a scene locally; should never touch the descriptor pipeline (static-pointer scenes opt out at construction with State.None).
   • Worlds (fixed-realm) — connect to a Worlds realm. Fixed-pointer scenes go through the descriptor gate too, so missing descriptors should yield the same fall-through behavior as Genesis on org. The world should still load.
   • Portable experiences — equip / spawn a PX. Smart wearables count here too. Both opt out of ISS at construction; they should load exactly as on main.

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

Code Review Reference

Please review our Branch & PR Standards before submitting.

🤖 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	7b3acfb
Logs	https://github.com/decentraland/unity-explorer/actions/runs/26663542849
Download Windows	https://github.com/decentraland/unity-explorer/suites/71468440530/artifacts/7302165495
Download Windows S3	https://explorer-artifacts.decentraland.org/@dcl/unity-explorer/branch/chore/iss-v2/pr-22653-7b3acfb/Decentraland_windows64.zip
Download Mac	https://github.com/decentraland/unity-explorer/suites/71468440530/artifacts/7302143213
Download Mac S3	https://explorer-artifacts.decentraland.org/@dcl/unity-explorer/branch/chore/iss-v2/pr-22653-7b3acfb/Decentraland_macos.zip
Built on	2026-05-29T22:18:03Z

[m3taphysics]

PR #8870, run #26555773261

Builds: Windows change, Windows baseline, macOS change, macOS baseline

Framework 13 i7

Metric	Change	Baseline	Delta	Improvement
Samples	2700	2700
CPU average	33.3 ms	33.3 ms	0.0 ms	-0.0%	⚪
CPU 1% worst	34.4 ms	33.8 ms	0.7 ms	-2.0%	⚪
CPU 0.1% worst	41.1 ms	35.4 ms	5.7 ms	-16.0%	🔴
GPU average	7.4 ms	8.1 ms	-0.6 ms	7.9%	🟢
GPU 1% worst	20.0 ms	17.2 ms	2.8 ms	-16.5%	🔴
GPU 0.1% worst	23.3 ms	20.5 ms	2.8 ms	-13.5%	🔴

[m3taphysics]

PR #8870, run #26557791876

Builds: Windows change, Windows baseline, macOS change, macOS baseline

Framework 13 i7

Metric	Change	Baseline	Delta	Improvement
Samples	2701	2700
CPU average	33.3 ms	33.3 ms	-0.0 ms	0.0%	⚪
CPU 1% worst	33.5 ms	33.6 ms	-0.1 ms	0.3%	⚪
CPU 0.1% worst	35.2 ms	36.0 ms	-0.8 ms	2.3%	⚪
GPU average	8.5 ms	8.7 ms	-0.3 ms	2.9%	⚪
GPU 1% worst	17.2 ms	18.0 ms	-0.8 ms	4.5%	🟢
GPU 0.1% worst	25.2 ms	24.2 ms	1.0 ms	-4.3%	🔴

[NickKhalow]

Solid work! Please address the comments below

[NickKhalow]

Why do we need UTF8 representation? The data can be stored as UTF16 without allocating additional buffers. MemoryIterator can read directly on str bytes

[NickKhalow]

Stepping further, we could store the blob without serializing it into json. Please add a note for the potential optimization

[dalkia]

Not sure how would I address this one. Are you reffering on doing a simple Encoding.Unicode.GetBytes(json) and Encoding.Unicode.GetString(data.Memory.Span), respectively?

[NickKhalow]

Good question, I'm referring to pinning the string and reading it via char*

unsafe
{
    fixed (char* p = json)
    {
        byte* bytes = (byte*)p;
        int byteCount = json.Length * sizeof(char);
    }
}

[NickKhalow]

Hm, it catches all the exceptions. There could be network or parsing errors as well. Is that intended it will swallow them too?

[dalkia]

For now, I dont think a retry mechanism is needed. Its okay for any given exception to consinder the ISS as failed

[NickKhalow]

Thanks for clarification, I would add Log|Warning/Error| at least for UNITY_EDITOR || DEBUG. WDYT?

[dalkia]

Keep in mind that this is already in the ResolveISSSystem.cs

It wont be swallowed, but rather surface on the system responsible for the resolve

[m3taphysics]

PR #8870, run #26617613074

Builds: Windows change, Windows baseline, macOS change, macOS baseline

Framework 13 i7

Metric	Change	Baseline	Delta	Improvement
Samples	2701	2700
CPU average	33.3 ms	33.3 ms	0.0 ms	-0.0%	⚪
CPU 1% worst	33.8 ms	33.5 ms	0.3 ms	-1.0%	⚪
CPU 0.1% worst	37.2 ms	34.2 ms	3.0 ms	-8.8%	🔴
GPU average	8.6 ms	8.1 ms	0.5 ms	-6.2%	🔴
GPU 1% worst	17.8 ms	16.9 ms	0.9 ms	-5.5%	🔴
GPU 0.1% worst	25.9 ms	18.3 ms	7.6 ms	-41.6%	🔴

[claude]

[WARNING] Spurious bridge-release warning on first LOD load (unchanged)

ReleaseBridgeSlot is called unconditionally for every gltfCache.TryGet hit. On the first LOD load of a scene — before any SDK run has ever called TryReserveBridgeSlot — bridgedCount is empty, so n > 0 is false and the "no outstanding reservation" warning fires.

The comment says "We just consumed one bridged copy" but a cache hit on first load doesn't mean a slot was ever reserved. Consider guarding:

if (gltfCache.TryGet(cacheKey, out var asset))
{
    // Only release if a bridge slot was actually reserved (SDK→LOD bridge path).
    // On first-ever LOD load the cache may have the asset from a prior context but no reservation.
    issDescriptor.ReleaseBridgeSlot(entry.hash);  // silently no-ops if count is 0; no warning needed
    PositionAsset(...);
    continue;
}

Or change ReleaseBridgeSlot to silently clamp at 0 without warning (remove the log call), since it is also hit legitimately on cache-warm second loads.

[m3taphysics]

PR #8870, run #26619640424

Builds: Windows change, Windows baseline, macOS change, macOS baseline

Framework 13 i7

Metric	Change	Baseline	Delta	Improvement
Samples	2700	2699
CPU average	33.3 ms	33.3 ms	0.0 ms	-0.0%	⚪
CPU 1% worst	33.9 ms	33.9 ms	-0.0 ms	0.0%	⚪
CPU 0.1% worst	37.3 ms	36.8 ms	0.5 ms	-1.3%	⚪
GPU average	7.4 ms	7.3 ms	0.1 ms	-1.5%	⚪
GPU 1% worst	19.3 ms	19.9 ms	-0.6 ms	3.1%	🟢
GPU 0.1% worst	22.9 ms	23.0 ms	-0.1 ms	0.6%	⚪

[m3taphysics]

PR #8870, run #26620771499

Builds: Windows change, Windows baseline, macOS change, macOS baseline

Framework 13 i7

Metric	Change	Baseline	Delta	Improvement
Samples	2701	2700
CPU average	33.3 ms	33.3 ms	-0.0 ms	0.0%	⚪
CPU 1% worst	33.5 ms	33.7 ms	-0.2 ms	0.5%	⚪
CPU 0.1% worst	35.2 ms	37.1 ms	-1.8 ms	4.9%	🟢
GPU average	8.3 ms	8.3 ms	-0.0 ms	0.3%	⚪
GPU 1% worst	18.1 ms	17.9 ms	0.2 ms	-1.2%	⚪
GPU 0.1% worst	25.0 ms	24.8 ms	0.2 ms	-0.9%	⚪

[github-actions]

🔍 Claude reviewed this PR and found no blocking issues, but assessed it as complex — human DEV review is still required before merging.

[m3taphysics]

PR #8870, run #26657522104

Builds: Windows change, Windows baseline, macOS change, macOS baseline

Framework 13 i7

Metric	Change	Baseline	Delta	Improvement
Samples	2701	2699
CPU average	33.3 ms	33.3 ms	-0.0 ms	0.0%	⚪
CPU 1% worst	33.6 ms	34.2 ms	-0.7 ms	1.9%	⚪
CPU 0.1% worst	35.5 ms	41.3 ms	-5.9 ms	14.2%	🟢
GPU average	8.2 ms	7.1 ms	1.1 ms	-16.2%	🔴
GPU 1% worst	18.7 ms	20.5 ms	-1.8 ms	8.7%	🟢
GPU 0.1% worst	26.7 ms	24.6 ms	2.1 ms	-8.5%	🔴

[claude]

Claude finished @dalkia's task in 3m 20s —— View job

---

Claude finished @dalkia's task —— View job

---

Tasks

• Gather context (CLAUDE.md, docs/README.md)
• Read key changed files
• Check new commits since last review
• Analyze diff for blocking issues
• Post review findings

---

Code Review

What this PR fixes: Migrates the ISS descriptor from being embedded inside a shared staticscene_* asset bundle to a standalone JSON file fetched from the LOD manifest bucket. The descriptor is now an ECS component on each scene entity with radius-gated resolution, a digest-aware GLTF cache, and bridge-slot reservation for LOD↔SDK handoff.

---

Sync Commit Review

The latest trigger is 7b3acfb4 — a merge of dev into the ISS branch. The merge diff is entirely unrelated to ISS: it brings in backpack thumbnail exception handling improvements (ECSThumbnailProvider.cs, BackpackGridController.cs, StreamableLoadingResult.cs). No ISS concerns introduced.

The two ISS-specific commits (3ec67bfd, 03537df7) were already reviewed in the previous round.

---

Full Issue Tracker

Issue	Source	Status
Per-asset helper entities leak on world teardown	Claude review	✅ Fixed — AbortISSHelperEntities in UnloadSceneLODSystem.FinalizeComponents (UnloadSceneLODSystem.cs:60-65)
Spurious bridge-release warning on first LOD load	Claude review	✅ Fixed — TryReleaseBridgeSlot is silent no-op when count ≤ 0 (ISSDescriptor.cs:84-88)
Null-forgiving ! on potentially-null manifest	Claude review	✅ Fixed — ?? AssetBundleManifestVersion.CreateFailed() (GetISSDescriptorIntention.cs:37)
_NoISS suffix on all assets	Claude review	✅ Fixed — neutral AB:{name}_{version}_{source} format
ParentContainer alive on PROCESSING cancellation	Claude review	✅ Fixed — UnityObjectUtils.SafeDestroy(ParentContainer) in ForgetLoading (InitialSceneStateLOD.cs:56)
IISSDescriptor interface (single impl, no tests)	NickKhalow	✅ Removed
GetISSDescriptor.cs not Intention-suffixed	NickKhalow	✅ Renamed to GetISSDescriptorIntention.cs
SceneId nullable annotation inconsistency	NickKhalow	✅ Non-nullable enforced at For() call site
hashCapacity not readonly	NickKhalow	✅ private readonly Dictionary<string, int> hashCapacity
Log for failed descriptor resolution	NickKhalow	✅ ReportHub.Log in ResolveISSDescriptorSystem.cs:47
ISSDescriptorResolution union-type concern	NickKhalow	✅ Class removed entirely
Intermediate task in LoadSceneSystemLogicBase	NickKhalow	✅ Direct await LoadMainCrdtAsync(...) (LoadSceneSystemLogicBase.cs:45)
StaticContainer use concrete type	NickKhalow	✅ DiskCache<ISSDescriptorMetadata, ...> (StaticContainer.cs:139)
ISSDescriptorDiskCache decorator silent-drop	NickKhalow	✅ Class removed entirely
Disk serializer optimization note	NickKhalow	✅ //TODO (opti): We could serialize as blobs and not jsons added
TODO markers in LoadISSDescriptorSystem	NickKhalow	✅ Both TODO comments present (LoadISSDescriptorSystem.cs:35, :91)
iss.json file extension	NickKhalow	✅ "iss.json" in GlobalWorldFactory.cs:172
Hardcoded dev URL	Claude review	⚠️ Acknowledged — author explicitly deferred to follow-up PR

---

No New Issues

The merge commit is unrelated to ISS. All previously identified blocking issues are resolved. No new blocking issues introduced.

---

REVIEW_RESULT: PASS ✅
COMPLEXITY: COMPLEX
COMPLEXITY_REASON: Touches ECS scene lifecycle, LOD pipeline, async AB loading, GLTF container caching, and cross-system component state across multiple subsystems.
QA_REQUIRED: YES

[m3taphysics]

PR #8870, run #26665063028

Builds: Windows change, Windows baseline, macOS change, macOS baseline

Framework 13 i7

Metric	Change	Baseline	Delta	Improvement
Samples	2701	2700
CPU average	33.3 ms	33.3 ms	-0.0 ms	0.0%	⚪
CPU 1% worst	33.6 ms	33.9 ms	-0.3 ms	0.9%	⚪
CPU 0.1% worst	35.0 ms	37.3 ms	-2.3 ms	6.2%	🟢
GPU average	8.2 ms	8.2 ms	-0.0 ms	0.4%	⚪
GPU 1% worst	18.4 ms	17.6 ms	0.8 ms	-4.3%	🔴
GPU 0.1% worst	27.1 ms	23.3 ms	3.8 ms	-16.3%	🔴