feat: smooth transition between LODs (#8949)

* feat: Only enable the LOD 0 when all assets are instantiated

* fix: now renderers are supressed instead of gameobjects

* fix: tests

Author: alejandro-jimenez-dcl

Explorer/Assets/DCL/Infrastructure/ECS/Unity/GLTFContainer/Asset/Components/GltfContainerAsset.cs

@@ -83,6 +83,17 @@ public void SetCastingShadows(bool newValue)
                 Renderers[i].shadowCastingMode = newValue ? ShadowCastingMode.On : ShadowCastingMode.Off;
         }
 
+        /// <summary>
+        ///     Suppresses or restores rendering without touching the GameObject's active state, so colliders
+        ///     stay registered. Uses <see cref="Renderer.forceRenderingOff" />, the same mechanism the emote
+        ///     and landscape culling paths rely on.
+        /// </summary>
+        public void ToggleRendering(bool newState)
+        {
+            for (var i = 0; i < Renderers.Count; i++)
+                Renderers[i].forceRenderingOff = !newState;
+        }
+
         public void ToggleAnimationState(bool newState)
         {
             foreach (Animation animation in Animations)

Explorer/Assets/DCL/LOD/Components/InitialSceneStateLOD.cs

@@ -67,7 +67,13 @@ private void Clear()
             foreach (ISSStoredAsset gltfContainerAsset in Assets)
             {
                 if (gltfContainerAsset.succeded)
+                {
+                    // Restore rendering before handing the asset back: on an aborted run RevealAssembledAssets
+                    // never ran, so the asset would otherwise return to the cache with forceRenderingOff stuck
+                    // on and reappear invisible on its next reuse (bridge handoff or fresh instantiate).
+                    gltfContainerAsset.Asset.ToggleRendering(true);
                     gltfCache.Dereference(gltfContainerAsset.AssetHash, gltfContainerAsset.Asset, AssetsShouldGoToTheBridge);
+                }
             }
 
             Assets.Clear();
@@ -122,6 +128,21 @@ private void EnsureParentContainer(string sceneID, Vector3 sceneGeometryBaseParc
             ParentContainer.transform.position = sceneGeometryBaseParcelPosition;
         }
 
+        /// <summary>
+        ///     Atomically reveals the fully assembled LOD_0 once <see cref="AllAssetsInstantiated" /> is true.
+        ///     Each asset streamed in with rendering suppressed (but its GameObject active, so colliders stay
+        ///     registered); this restores rendering so the LODGroup the caller wires up in the same frame can
+        ///     cull LOD_1 by distance. No overlap window, no empty frame.
+        /// </summary>
+        public void RevealAssembledAssets()
+        {
+            foreach (ISSStoredAsset storedAsset in Assets)
+            {
+                if (storedAsset.succeded)
+                    storedAsset.Asset.ToggleRendering(true);
+            }
+        }
+
         public void AddFailedAsset(string creationHelperAssetHash)
         {
             Assets.Add(new ISSStoredAsset

Explorer/Assets/DCL/LOD/Systems/InstantiateSceneLODInfoSystem.cs

@@ -81,6 +81,11 @@ private void ResolveInitialSceneStateDescriptorLOD(in SceneDefinitionComponent s
         {
             if (sceneLODInfo.InitialSceneStateLOD.AllAssetsInstantiated())
             {
+                // Reveal LOD_0 in the same frame it joins the LODGroup. The container streamed in hidden,
+                // so up to this point the player has been seeing LOD_1; from here the LODGroup culls LOD_1
+                // by distance. No overlap, no empty frame.
+                sceneLODInfo.InitialSceneStateLOD.RevealAssembledAssets();
+
                 sceneLODInfo.AddSuccessLOD(sceneLODInfo.InitialSceneStateLOD.ParentContainer, null, defaultFOV, defaultLodBias,
                     realmPartitionSettings.MaxLoadingDistanceInParcels, sceneDefinitionComponent.Parcels.Count);
                 sceneLODInfo.InitialSceneStateLOD.CurrentState = InitialSceneStateLOD.State.RESOLVED;

Explorer/Assets/DCL/LOD/Systems/ResolveISSLODSystem.cs

@@ -168,6 +168,12 @@ private static void PositionAsset(InitialSceneStateLOD initialSceneStateLOD, ISS
 
             asset.ToggleAnimationState(false);
 
+            // Suppress rendering while LOD_0 streams in asset-by-asset so the half-assembled LOD_0 never
+            // draws on top of the still-visible LOD_1. The GameObject stays active so its colliders remain
+            // registered; RevealAssembledAssets restores rendering once every asset is in place and the
+            // LODGroup takes over distance-based culling.
+            asset.ToggleRendering(false);
+
             // Store under the digest-aware cache key so the eventual Dereference in InitialSceneStateLOD.Clear
             // matches what the SDK runtime would look up — that's what allows bridging round-trips between
             // LOD and the real scene without spawning a second copy of the same asset.

Explorer/Assets/DCL/LOD/Tests/EditMode/ResolveISSLODSystemShould.cs

@@ -201,6 +201,72 @@ public void RecordFailedAssetWithoutTouchingCache()
             Assert.That(cache.Outstanding("MISSING_HASH"), Is.EqualTo(0));
         }
 
+        [Test]
+        public void SuppressRenderingButKeepObjectsActiveUntilRevealed()
+        {
+            // Guards the LOD_1 -> LOD_0 atomic-swap fix: while descriptor assets stream in, their rendering
+            // must be suppressed so the half-assembled LOD_0 never draws on top of the still-visible LOD_1.
+            // Crucially the GameObjects stay active so colliders remain registered; the reveal (owned by
+            // InstantiateSceneLODInfoSystem at the swap) restores rendering, not GameObject activation.
+            const string HASH_A = "ITEM_A";
+            const string HASH_B = "ITEM_B";
+
+            GltfContainerAsset assetA = MakeFakeGltfWithRenderer(HASH_A, out Renderer rendererA);
+            GltfContainerAsset assetB = MakeFakeGltfWithRenderer(HASH_B, out Renderer rendererB);
+            cache.Stash(HASH_A, assetA);
+            cache.Stash(HASH_B, assetB);
+
+            var descriptor = ISSDescriptor.CreateUninitialized();
+
+            descriptor.MarkResolved(new[]
+            {
+                NewDescriptorEntry(HASH_A),
+                NewDescriptorEntry(HASH_B),
+            });
+
+            InitialSceneStateLOD lod = CreateLODEntity(descriptor);
+
+            system.Update(0);
+
+            Assert.That(lod.AllAssetsInstantiated(), Is.True);
+
+            Assert.That(rendererA.forceRenderingOff, Is.True, "Rendering must be suppressed while LOD_0 assembles");
+            Assert.That(rendererB.forceRenderingOff, Is.True, "Rendering must be suppressed while LOD_0 assembles");
+            Assert.That(assetA.Root.activeInHierarchy, Is.True, "GameObject must stay active so colliders survive");
+            Assert.That(assetB.Root.activeInHierarchy, Is.True, "GameObject must stay active so colliders survive");
+
+            lod.RevealAssembledAssets();
+
+            Assert.That(rendererA.forceRenderingOff, Is.False, "Reveal must hand rendering back so the LODGroup can cull by distance");
+            Assert.That(rendererB.forceRenderingOff, Is.False, "Reveal must hand rendering back so the LODGroup can cull by distance");
+
+            lod.Dispose(world);
+        }
+
+        [Test]
+        public void RestoreRenderingWhenAbortedBeforeReveal()
+        {
+            // An aborted run (ForgetLoading while PROCESSING) dereferences positioned assets back to the
+            // cache. They must not return with forceRenderingOff stuck on, or they reappear invisible on reuse.
+            const string HASH = "ITEM_A";
+
+            GltfContainerAsset asset = MakeFakeGltfWithRenderer(HASH, out Renderer renderer);
+            cache.Stash(HASH, asset);
+
+            var descriptor = ISSDescriptor.CreateUninitialized();
+            descriptor.MarkResolved(new[] { NewDescriptorEntry(HASH) });
+
+            InitialSceneStateLOD lod = CreateLODEntity(descriptor);
+
+            system.Update(0);
+            Assert.That(renderer.forceRenderingOff, Is.True);
+
+            lod.Dispose(world);
+
+            Assert.That(renderer.forceRenderingOff, Is.False,
+                "Clear must restore rendering before the asset is handed back to the cache");
+        }
+
         [Test]
         public void ReleaseBridgeSlotOnCacheHit()
         {
@@ -263,6 +329,15 @@ private static ISSDescriptorAsset NewDescriptorEntry(string hash) =>
         private static GltfContainerAsset MakeFakeGltf(string label) =>
             GltfContainerAsset.Create(new GameObject($"fake_{label}"), IStreamableRefCountData.Null.INSTANCE);
 
+        private static GltfContainerAsset MakeFakeGltfWithRenderer(string label, out Renderer renderer)
+        {
+            var go = new GameObject($"fake_{label}");
+            renderer = go.AddComponent<MeshRenderer>();
+            GltfContainerAsset asset = GltfContainerAsset.Create(go, IStreamableRefCountData.Null.INSTANCE);
+            asset.Renderers.Add(renderer);
+            return asset;
+        }
+
         /// <summary>
         ///     Pool-style stub mirroring <see cref="GltfContainerAssetsCache" />: <c>TryGet</c> removes,
         ///     <c>Dereference</c> returns. Per-key counters are what the tests assert against.
@@ -309,6 +384,14 @@ public void Dereference(in string key, GltfContainerAsset asset, bool putInBridg
                     stash[key] = entries = new Stack<GltfContainerAsset>();
 
                 entries.Push(asset);
+
+                // Mirror GltfContainerAssetsCache.DereferenceFinalOperation: the real cache reparents the
+                // asset's Root out of the LOD container when it is returned to the pool. Without this the
+                // pooled asset stays a child of InitialSceneStateLOD.ParentContainer, so Dispose's
+                // SafeDestroy(ParentContainer) cascades into it and destroys its renderers — the asset (and
+                // its renderers) must survive intact for reuse.
+                if (asset.Root != null)
+                    asset.Root.transform.SetParent(null, true);
             }
 
             public void Unload(IPerformanceBudget frameTimeBudget, int maxUnloadAmount) { }