chore: new lods through ISS descriptor

[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	aab87d9
Logs	https://github.com/decentraland/unity-explorer/actions/runs/26926662942
Download Windows	https://github.com/decentraland/unity-explorer/suites/72268513087/artifacts/7402045331
Download Windows S3	https://explorer-artifacts.decentraland.org/@dcl/unity-explorer/branch/chore/iss-v2/pr-22713-aab87d9/Decentraland_windows64.zip
Download Mac	https://github.com/decentraland/unity-explorer/suites/72268513087/artifacts/7401981611
Download Mac S3	https://explorer-artifacts.decentraland.org/@dcl/unity-explorer/branch/chore/iss-v2/pr-22713-aab87d9/Decentraland_macos.zip
Built on	2026-06-04T03:10:22Z

[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

[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%	🔴

[m3taphysics]

PR #8870, run #26733266952

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.6 ms	0.0 ms	-0.1%	⚪
CPU 0.1% worst	35.5 ms	33.8 ms	1.7 ms	-5.1%	🔴
GPU average	8.6 ms	7.8 ms	0.7 ms	-9.6%	🔴
GPU 1% worst	17.8 ms	21.8 ms	-4.0 ms	18.4%	🟢
GPU 0.1% worst	22.6 ms	25.7 ms	-3.1 ms	11.9%	🟢

[m3taphysics]

PR #8870, run #26754277020

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	34.0 ms	33.8 ms	0.3 ms	-0.7%	⚪
CPU 0.1% worst	38.3 ms	36.0 ms	2.3 ms	-6.4%	🔴
GPU average	7.2 ms	7.0 ms	0.2 ms	-2.9%	⚪
GPU 1% worst	19.7 ms	19.6 ms	0.1 ms	-0.3%	⚪
GPU 0.1% worst	23.5 ms	22.2 ms	1.3 ms	-5.9%	🔴

[m3taphysics]

PR #8870, run #26864130749

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

Framework 13 i7

Values are the median across 3 run(s); the (min–max) range shows how much the runs varied. A metric is only flagged when the change is larger than both the 3% threshold and that run-to-run variation.

Metric	Change	Baseline	Delta	Improvement
Samples	2701 (×3)	2701 (×3)
CPU average	33.3 ms	33.3 ms	-0.0 ms	0.0%	⚪
CPU 1% worst	33.5 ms (33.4–33.9)	33.8 ms (33.5–34.1)	-0.3 ms	1.0%	⚪
CPU 0.1% worst	35.0 ms (33.7–36.4)	36.3 ms (34.4–40.0)	-1.3 ms	3.7%	⚪
GPU average	8.0 ms (7.6–8.2)	7.4 ms (7.2–8.1)	0.6 ms	-8.0%	⚪
GPU 1% worst	18.5 ms	19.8 ms (17.0–19.8)	-1.3 ms	6.6%	⚪
GPU 0.1% worst	24.8 ms (23.6–25.2)	24.7 ms (20.8–25.0)	0.1 ms	-0.4%	⚪
Exceptions logged	44	66	-22		🟢

[DafGreco]

✔️ PR reviewed and approved by QA on both platforms following instructions playing both happy and un-happy path

Regressions for this ticket had been performed in order to verify that the normal flow is working as expected:

• [ ✔️] Backpack and wearables in world
• [ ✔️] Emotes in world and in backpack
• [✔️ ] Teleport with map/coordinates/Jump In
• [ ✔️] Chat and multiplayer
• [ ✔️] Profile card
• [ ✔️] Camera
• [ ✔️] Skybox
• [✔️ ] Settings
• [✔️] Smart wearables

⚠️ Important comment ⚠️
We found and issue regarding the amount of memory consumed between prd and zone and juani will be investigating this one and address it right after.
Also the color of the trees can be seen being modified but this will be addresed later.

Evidence:

20260603-1339-23.7488649.mp4

20260603-1554-07.2178340.mp4

[m3taphysics]

PR #8870, run #26896170576

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

How to read this table

• Each build is measured 3 times. The values are the median, and (min–max) is the lowest and highest of those runs — a wide range means the metric is noisy and small differences are not trustworthy.
• Δ is Change minus Baseline (a negative Δ means Change is faster).
• 🟢 faster / 🔴 slower — a real difference: larger than both 3% and the run-to-run range.
• ⚪ within noise — the difference is smaller than how much the build varies between its own runs, so it cannot be told apart from random variation. Treat it as no change.
• Exceptions logged — exceptions found in the run logs; more than the baseline is flagged 🔴 even when frame times look fine.

Framework 13 i7

Metric	Baseline	Change	Δ	Result
Samples	2700 (×3)	2701 (×3)
CPU average	33.3 ms	33.3 ms	-0.0 ms	⚪ within noise
CPU 1% worst	34.2 ms (34.2–34.5)	33.5 ms (33.5–33.6)	-0.7 ms	⚪ within noise
CPU 0.1% worst	42.2 ms (41.2–44.0)	34.5 ms (33.8–34.7)	-7.7 ms	🟢 18% faster
GPU average	8.0 ms (7.4–8.0)	8.3 ms (8.2–9.8)	0.3 ms	⚪ within noise
GPU 1% worst	20.4 ms (18.0–21.0)	18.0 ms (17.7–18.0)	-2.4 ms	⚪ within noise
GPU 0.1% worst	24.9 ms (24.0–25.5)	25.0 ms (19.4–25.1)	0.0 ms	⚪ within noise
Exceptions logged	48	42	-6	🟢 fewer errors

[claude]

Claude finished @dalkia's task in 1m 46s —— View job

---

Claude finished @juanignaciomolteni's task in 3m ——

---

Tasks

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

---

Code Review

What this PR fixes: Migrates the ISS descriptor from an embedded asset-bundle to a standalone JSON fetched from the LOD manifest CDN, sharing the descriptor as an ECS component across the LOD and SDK runtime paths.

---

New Commit Review (aab87d96)

"chore: route ISS descriptor fetch through LodGeneratorCDN" (4 files, +10/-5)

This commit resolves the last outstanding blocker from the previous review: the hardcoded dev S3 URL in LoadISSDescriptorSystem.cs.

Changes:

• DecentralandUrl.cs — adds LodGeneratorCDN = 94 (correct sequential value after Discord = 93)
• DecentralandUrlsSource.cs — maps it to https://lod-generator-unity-cdn.decentraland.{ENV} (environment-aware, matches the existing CDN pattern)
• LoadISSDescriptorSystem.cs — replaces the hardcoded DESCRIPTOR_BASE_URL const with descriptorBaseUrl injected via constructor; path prefix "lods-unity/manifests/" is extracted as a const string and matches the old URL structure exactly
• GlobalWorldFactory.cs — wires urlsSource.Url(DecentralandUrl.LodGeneratorCDN) → LoadISSDescriptorSystem.InjectToWorld

GatewayUrlsSource check: LodGeneratorCDN is correctly absent from SUPPORTED_URLS — the LOD descriptor CDN is a public endpoint and doesn't need gateway routing. The GatewayUrlsSource.RawUrl override falls through to the base class resolution cleanly.

The fix is correct and complete. No new issues introduced.

---

Remaining Non-Blocking Items (do not block merge)

Location	Item
ISSDescriptorDiskSerializer.cs:3	Stale using System.Text; — no System.Text symbols used in the file
ISSDescriptorDiskSerializer.cs:28	async UniTask wraps a path that calls UniTask.FromResult(...) — state machine over a synchronous return

---

Full Issue Tracker

Issue	Status
Per-asset helper entities leak on world teardown	✅ Fixed — AbortISSHelperEntities in UnloadSceneLODSystem.FinalizeComponents
Spurious bridge-release warning on first LOD load	✅ Fixed — TryReleaseBridgeSlot silent no-op when count ≤ 0
Null-forgiving ! on potentially-null manifest	✅ Fixed — ?? AssetBundleManifestVersion.CreateFailed()
_NoISS suffix on all assets	✅ Fixed — neutral AB:{name}_{version}_{source} format
ParentContainer alive on PROCESSING cancellation	✅ Fixed — UnityObjectUtils.SafeDestroy(ParentContainer) in ForgetLoading
IISSDescriptor interface (single impl, no tests)	✅ Removed
GetISSDescriptor.cs not Intention-suffixed	✅ Renamed
SceneId nullable annotation inconsistency	✅ Non-nullable enforced
hashCapacity not readonly	✅ private readonly
Log for failed descriptor resolution	✅ ReportHub.Log in ResolveISSDescriptorSystem.cs:47
ISSDescriptorResolution union-type concern	✅ Class removed entirely
Intermediate task in LoadSceneSystemLogicBase	✅ Direct await
StaticContainer concrete type	✅ DiskCache<ISSDescriptorMetadata, ...>
ISSDescriptorDiskCache decorator silent-drop	✅ Class removed entirely
Disk serializer optimization note	✅ //TODO (opti): comment present
TODO markers in LoadISSDescriptorSystem	✅ Both present
iss.json file extension	✅ Present in GlobalWorldFactory.cs
UTF16 serialization (no UTF8 buffer)	✅ Fixed
Hardcoded dev URL	✅ Fixed in this commit — now routed through DecentralandUrl.LodGeneratorCDN
Duplicate GltfContainerAssetsCache construction	✅ Fixed (22cd3390)
SceneFacade leak for banned scenes	✅ Fixed — BannedSceneComponent guard
Ref-count / bridge-slot balance coverage	✅ Tests added in ResolveISSLODSystemShould.cs

---

No New Blocking Issues

All previously-identified blocking issues are now resolved. The PR is ready to merge.

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 #26927931131

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

How to read this table

• Each build is measured 3 times. The values are the median, and (min–max) is the lowest and highest of those runs — a wide range means the metric is noisy and small differences are not trustworthy.
• Δ is Change minus Baseline (a negative Δ means Change is faster).
• 🟢 faster / 🔴 slower — a real difference: larger than both 3% and the run-to-run range.
• ⚪ within noise — the difference is smaller than how much the build varies between its own runs, so it cannot be told apart from random variation. Treat it as no change.
• Exceptions logged — exceptions found in the run logs; more than the baseline is flagged 🔴 even when frame times look fine.

Framework 13 i7

Metric	Baseline	Change	Δ	Result
Samples	2700 (×3)	2701 (×3)
CPU average	33.3 ms	33.3 ms	-0.0 ms	⚪ within noise
CPU 1% worst	34.3 ms (33.7–34.4)	33.6 ms (33.5–33.8)	-0.8 ms	⚪ within noise
CPU 0.1% worst	43.7 ms (35.7–44.0)	35.9 ms (35.0–36.1)	-7.8 ms	⚪ within noise
GPU average	7.6 ms (7.4–7.7)	8.6 ms (8.4–8.6)	1.0 ms	🔴 13% slower
GPU 1% worst	19.1 ms (18.8–20.0)	17.9 ms (17.3–18.2)	-1.1 ms	⚪ within noise
GPU 0.1% worst	24.1 ms (23.5–25.2)	23.7 ms (20.3–24.6)	-0.4 ms	⚪ within noise
Exceptions logged	46	46	0	⚪ none new