refactor(world): extract live projection mechanics

Move appearance rebinding, collision construction, default-pose resolution, local shadow ownership, and exact leave-world presentation into focused owners. Preserve retail parent ordering with staged validation, committed recovery, recursive attached-subtree withdrawal, and retryable exact teardown across parent, pickup, position, unwield, and pose-loss edges.

Co-Authored-By: OpenAI Codex <codex@openai.com>

tests/AcDream.App.Tests/World/GameWindowLiveEntityCompositionTests.cs

@@ -0,0 +1,51 @@
+using System.Collections;
+using System.Reflection;
+using AcDream.App.Physics;
+using AcDream.App.Rendering;
+using AcDream.App.World;
+
+namespace AcDream.App.Tests.World;
+
+public sealed class GameWindowLiveEntityCompositionTests
+{
+    private const BindingFlags PrivateImplementation =
+        BindingFlags.Instance | BindingFlags.Static | BindingFlags.NonPublic;
+
+    [Theory]
+    [InlineData("RegisterLiveEntityCollision")]
+    [InlineData("MotionTableDefaultPose")]
+    [InlineData("LeaveWorldLiveEntityRuntimeComponents")]
+    [InlineData("WithdrawLiveEntityWorldProjection")]
+    [InlineData("RebindAnimatedEntityForAppearance")]
+    public void GameWindow_DoesNotReacquireExtractedLiveEntityBodies(string methodName)
+    {
+        Assert.Null(typeof(GameWindow).GetMethod(methodName, PrivateImplementation));
+    }
+
+    [Fact]
+    public void GameWindow_DoesNotOwnAnAppearanceUpdateStateType()
+    {
+        Assert.Null(typeof(GameWindow).GetNestedType(
+            "AppearanceUpdateState",
+            BindingFlags.NonPublic));
+    }
+
+    [Theory]
+    [InlineData(typeof(LiveEntityCollisionBuilder))]
+    [InlineData(typeof(LiveEntityDefaultPoseResolver))]
+    [InlineData(typeof(LiveEntityProjectionWithdrawalController))]
+    [InlineData(typeof(LocalPlayerShadowState))]
+    [InlineData(typeof(LiveEntityAppearanceBinding))]
+    public void ExtractedHelpers_DoNotOwnGuidIndexesOrBackendState(Type helperType)
+    {
+        foreach (FieldInfo field in helperType.GetFields(
+                     BindingFlags.Instance | BindingFlags.Static | BindingFlags.NonPublic))
+        {
+            Assert.False(typeof(IDictionary).IsAssignableFrom(field.FieldType),
+                $"{helperType.Name}.{field.Name} must resolve identity through LiveEntityRuntime.");
+            string typeName = field.FieldType.FullName ?? field.FieldType.Name;
+            Assert.DoesNotContain("Silk.NET", typeName, StringComparison.Ordinal);
+            Assert.DoesNotContain("OpenGL", typeName, StringComparison.OrdinalIgnoreCase);
+        }
+    }
+}

tests/AcDream.App.Tests/World/InboundPhysicsStateControllerTests.cs

@@ -208,7 +208,7 @@ public sealed class InboundPhysicsStateControllerTests
     }
 
     [Fact]
-    public void ParentEventWaitsForParent_ThenConsumesChildPositionOnce()
+    public void ParentEventWaitsForParent_ThenStagesTimestampUntilValidatedCommit()
     {
         var controller = new InboundPhysicsStateController();
         controller.AcceptCreate(Spawn(
@@ -219,7 +219,17 @@ public sealed class InboundPhysicsStateControllerTests
         Assert.False(controller.TryApplyParent(update, out _));
         controller.AcceptCreate(Spawn(
             0x70000004u, 9, 1, 1, Position(0x0101FFFFu, 15f), 0x408u));
-        Assert.True(controller.TryApplyParent(update, out WorldSession.EntitySpawn attached));
+        Assert.True(controller.TryApplyParent(update, out WorldSession.EntitySpawn staged));
+        Assert.Null(staged.ParentGuid);
+        Assert.NotNull(staged.Position);
+        Assert.Equal((ushort)5, staged.PositionSequence);
+        Assert.True(controller.TryCommitParent(
+            update.ChildGuid,
+            update.ParentGuid,
+            update.ParentLocation,
+            update.PlacementId,
+            update.ChildPositionSequence,
+            out WorldSession.EntitySpawn attached));
         Assert.Equal(0x70000004u, attached.ParentGuid);
         Assert.Null(attached.Position);
         Assert.False(controller.TryApplyParent(update, out _));

tests/AcDream.App.Tests/World/LiveEntityProjectionWithdrawalControllerTests.cs

@@ -0,0 +1,289 @@
+using System.Numerics;
+using AcDream.App.Physics;
+using AcDream.App.Rendering.Vfx;
+using AcDream.App.Streaming;
+using AcDream.App.World;
+using AcDream.Core.Net;
+using AcDream.Core.Net.Messages;
+using AcDream.Core.Physics;
+using AcDream.Core.Plugins;
+using AcDream.Core.World;
+using AcDream.Plugin.Abstractions;
+using DatReaderWriter.DBObjs;
+
+namespace AcDream.App.Tests.World;
+
+public sealed class LiveEntityProjectionWithdrawalControllerTests
+{
+    private const uint Guid = 0x70000200u;
+    private const uint Cell = 0x01010001u;
+
+    [Fact]
+    public void ComponentFailure_StopsBeforeCanonicalWithdrawal_AndRetryConverges()
+    {
+        var fixture = new Fixture();
+        LiveEntityRecord record = fixture.Spawn(instance: 1);
+        fixture.Poses.EffectPoseChanged += ThrowOnPoseChange;
+
+        Assert.Throws<InvalidOperationException>(() =>
+            fixture.Controller.Withdraw(Guid, localPlayerGuid: 0u));
+
+        Assert.True(record.IsSpatiallyProjected);
+        Assert.Empty(fixture.GameState.Entities);
+        Assert.Equal(0, fixture.Poses.Count);
+        Assert.DoesNotContain(
+            fixture.Physics.ShadowObjects.GetObjectsInCell(Cell),
+            entry => entry.EntityId == record.WorldEntity!.Id);
+        Assert.Equal(1, fixture.Physics.ShadowObjects.SuspendedRegistrationCount);
+
+        fixture.Poses.EffectPoseChanged -= ThrowOnPoseChange;
+        Assert.True(fixture.Controller.Withdraw(Guid, localPlayerGuid: 0u));
+        Assert.False(record.IsSpatiallyProjected);
+
+        static void ThrowOnPoseChange(uint _) =>
+            throw new InvalidOperationException("fixture pose observer failure");
+    }
+
+    [Fact]
+    public void RuntimeObserverFailure_CommitsCanonicalWithdrawalAfterComponentsRemoved()
+    {
+        var fixture = new Fixture();
+        LiveEntityRecord record = fixture.Spawn(instance: 1);
+        fixture.Live.ProjectionVisibilityChanged += ThrowOnHidden;
+
+        Assert.ThrowsAny<Exception>(() =>
+            fixture.Controller.Withdraw(Guid, localPlayerGuid: 0u));
+
+        Assert.False(record.IsSpatiallyProjected);
+        Assert.False(record.IsSpatiallyVisible);
+        Assert.Empty(fixture.GameState.Entities);
+        Assert.Equal(0, fixture.Poses.Count);
+
+        static void ThrowOnHidden(LiveEntityRecord _, bool visible)
+        {
+            if (!visible)
+                throw new InvalidOperationException("fixture runtime observer failure");
+        }
+    }
+
+    [Fact]
+    public void OrdinaryLeaveWorld_SuspendsRetainedShadow_AndReentryRestoresIt()
+    {
+        var fixture = new Fixture();
+        LiveEntityRecord record = fixture.Spawn(instance: 1);
+        uint localId = record.WorldEntity!.Id;
+        Assert.Contains(
+            fixture.Physics.ShadowObjects.GetObjectsInCell(Cell),
+            entry => entry.EntityId == localId);
+
+        Assert.True(fixture.Controller.Withdraw(Guid, localPlayerGuid: 0u));
+        Assert.DoesNotContain(
+            fixture.Physics.ShadowObjects.GetObjectsInCell(Cell),
+            entry => entry.EntityId == localId);
+
+        Assert.True(fixture.Live.RebucketLiveEntity(Guid, Cell));
+        Assert.Contains(
+            fixture.Physics.ShadowObjects.GetObjectsInCell(Cell),
+            entry => entry.EntityId == localId);
+    }
+
+    [Fact]
+    public void ComponentCallbackReplacesGuid_DoesNotWithdrawReplacement()
+    {
+        var fixture = new Fixture();
+        LiveEntityRecord old = fixture.Spawn(instance: 1);
+        LiveEntityRecord? replacement = null;
+        bool replacing = false;
+        fixture.LocalShadow.Set(Vector3.One, Quaternion.Identity, Cell);
+        fixture.Poses.EffectPoseChanged += OnPoseChanged;
+
+        Assert.False(fixture.Controller.Withdraw(Guid, localPlayerGuid: Guid));
+
+        Assert.NotNull(replacement);
+        Assert.True(fixture.Live.TryGetRecord(Guid, out LiveEntityRecord current));
+        Assert.Same(replacement, current);
+        Assert.True(current.IsSpatiallyProjected);
+        Assert.Equal(new Vector3(9f, 9f, 9f), current.WorldEntity!.Position);
+        Assert.NotNull(fixture.LocalShadow.Current);
+        Assert.NotSame(old, current);
+
+        void OnPoseChanged(uint localId)
+        {
+            if (replacement is not null || replacing || localId != old.WorldEntity!.Id)
+                return;
+            replacing = true;
+            replacement = fixture.Spawn(instance: 2, position: new Vector3(9f, 9f, 9f));
+            fixture.LocalShadow.Set(new Vector3(9f), Quaternion.Identity, Cell);
+        }
+    }
+
+    [Fact]
+    public void ComponentCallbackReprojectsSameIncarnation_DoesNotWithdrawNewPosition()
+    {
+        var fixture = new Fixture();
+        LiveEntityRecord record = fixture.Spawn(instance: 1);
+        bool reentered = false;
+        fixture.Poses.EffectPoseChanged += OnPoseChanged;
+
+        Assert.False(fixture.Controller.Withdraw(Guid, localPlayerGuid: 0u));
+
+        Assert.True(record.IsSpatiallyProjected);
+        Assert.True(record.IsSpatiallyVisible);
+        Assert.Equal(new Vector3(8f, 7f, 6f), record.WorldEntity!.Position);
+        Assert.Contains(fixture.GameState.Entities, entity => entity.Id == record.WorldEntity.Id);
+        Assert.Equal(1, fixture.Poses.Count);
+
+        void OnPoseChanged(uint localId)
+        {
+            if (reentered || localId != record.WorldEntity!.Id)
+                return;
+            reentered = true;
+            var position = new WorldSession.EntityPositionUpdate(
+                Guid,
+                new CreateObject.ServerPosition(
+                    Cell, 8f, 7f, 6f, 1f, 0f, 0f, 0f),
+                Velocity: null,
+                PlacementId: null,
+                IsGrounded: true,
+                InstanceSequence: 1,
+                PositionSequence: 2,
+                TeleportSequence: 0,
+                ForcePositionSequence: 0);
+            Assert.True(fixture.Live.TryApplyPosition(
+                position,
+                isLocalPlayer: false,
+                forcePositionRotation: null,
+                currentLocalVelocity: null,
+                out PositionTimestampDisposition disposition,
+                out WorldSession.EntitySpawn accepted,
+                out _));
+            Assert.Equal(PositionTimestampDisposition.Apply, disposition);
+            record.WorldEntity.SetPosition(new Vector3(8f, 7f, 6f));
+            Assert.True(fixture.Live.RebucketLiveEntity(
+                Guid,
+                accepted.Position!.Value.LandblockId));
+            var snapshot = new WorldEntitySnapshot(
+                record.WorldEntity.Id,
+                record.WorldEntity.SourceGfxObjOrSetupId,
+                record.WorldEntity.Position,
+                record.WorldEntity.Rotation);
+            fixture.GameState.Add(snapshot);
+            fixture.Events.UpsertCurrent(snapshot);
+            fixture.Poses.PublishMeshRefs(record.WorldEntity);
+        }
+    }
+
+    [Fact]
+    public void LogicalLocalPlayerTeardownWithoutReplacement_ClearsShadowSnapshot()
+    {
+        var fixture = new Fixture();
+        fixture.Spawn(instance: 1);
+        fixture.LocalShadow.Set(Vector3.One, Quaternion.Identity, Cell);
+
+        Assert.True(fixture.Live.UnregisterLiveEntity(
+            new DeleteObject.Parsed(Guid, InstanceSequence: 1),
+            isLocalPlayer: false));
+
+        Assert.Null(fixture.LocalShadow.Current);
+    }
+
+    private sealed class Fixture
+    {
+        internal Fixture()
+        {
+            Spatial.AddLandblock(new LoadedLandblock(
+                (Cell & 0xFFFF0000u) | 0xFFFFu,
+                new LandBlock(),
+                Array.Empty<WorldEntity>()));
+            var lifecycle = new DeferredLiveEntityRuntimeComponentLifecycle();
+            Live = new LiveEntityRuntime(
+                Spatial,
+                new DelegateLiveEntityResourceLifecycle(_ => { }, _ => { }),
+                lifecycle);
+            Projectiles = new ProjectileController(
+                Live,
+                Physics,
+                _ => null,
+                _ => { },
+                () => (0, 0));
+            Controller = new LiveEntityProjectionWithdrawalController(
+                Live,
+                Projectiles,
+                GameState,
+                Events,
+                Physics.ShadowObjects,
+                Poses,
+                LocalShadow);
+            Presentation = new LiveEntityPresentationController(
+                Live,
+                Physics.ShadowObjects,
+                (_, _, _) => false);
+            lifecycle.Bind(new DelegateLiveEntityRuntimeComponentLifecycle(
+                record => Controller.LeaveWorld(record, Guid)));
+        }
+
+        internal GpuWorldState Spatial { get; } = new();
+        internal LiveEntityRuntime Live { get; }
+        internal PhysicsEngine Physics { get; } = new();
+        internal ProjectileController Projectiles { get; }
+        internal WorldGameState GameState { get; } = new();
+        internal WorldEvents Events { get; } = new();
+        internal EntityEffectPoseRegistry Poses { get; } = new();
+        internal LocalPlayerShadowState LocalShadow { get; } = new();
+        internal LiveEntityProjectionWithdrawalController Controller { get; }
+        internal LiveEntityPresentationController Presentation { get; }
+
+        internal LiveEntityRecord Spawn(ushort instance, Vector3? position = null)
+        {
+            WorldSession.EntitySpawn spawn = new(
+                Guid,
+                new CreateObject.ServerPosition(Cell, 1f, 2f, 3f, 1f, 0f, 0f, 0f),
+                0x02000200u,
+                Array.Empty<CreateObject.AnimPartChange>(),
+                Array.Empty<CreateObject.TextureChange>(),
+                Array.Empty<CreateObject.SubPaletteSwap>(),
+                BasePaletteId: null,
+                ObjScale: 1f,
+                Name: "projection fixture",
+                ItemType: null,
+                MotionState: null,
+                MotionTableId: null,
+                InstanceSequence: instance);
+            LiveEntityRecord record = Live.RegisterLiveEntity(spawn).Record!;
+            WorldEntity entity = Live.MaterializeLiveEntity(
+                Guid,
+                Cell,
+                id => new WorldEntity
+                {
+                    Id = id,
+                    ServerGuid = Guid,
+                    SourceGfxObjOrSetupId = 0x02000200u,
+                    Position = position ?? new Vector3(1f, 2f, 3f),
+                    Rotation = Quaternion.Identity,
+                    MeshRefs = Array.Empty<MeshRef>(),
+                    ParentCellId = Cell,
+                })!;
+            var snapshot = new WorldEntitySnapshot(
+                entity.Id,
+                entity.SourceGfxObjOrSetupId,
+                entity.Position,
+                entity.Rotation);
+            GameState.Add(snapshot);
+            Events.UpsertCurrent(snapshot);
+            Poses.PublishMeshRefs(entity);
+            Physics.ShadowObjects.Register(
+                entity.Id,
+                entity.SourceGfxObjOrSetupId,
+                entity.Position,
+                entity.Rotation,
+                radius: 0.5f,
+                worldOffsetX: 0f,
+                worldOffsetY: 0f,
+                landblockId: Cell,
+                seedCellId: Cell,
+                isStatic: false);
+            Assert.True(Presentation.OnLiveEntityReady(Guid));
+            return record;
+        }
+    }
+}

tests/AcDream.App.Tests/World/LiveEntityRuntimeTests.cs

@@ -659,7 +659,7 @@ public sealed class LiveEntityRuntimeTests
     }
 
     [Fact]
-    public void InitialChildCreate_PreservesParentEventQueuedForMissingChild()
+    public void InitialChildCreate_PreservesParentEventQueuedForRenderValidation()
     {
         const uint parentGuid = 0x70000020u;
         const uint childGuid = 0x70000021u;
@@ -676,7 +676,9 @@ public sealed class LiveEntityRuntimeTests
             childGuid, out ParentAttachmentRelation relation));
         Assert.Equal(parentGuid, relation.ParentGuid);
         Assert.True(runtime.TryGetSnapshot(childGuid, out WorldSession.EntitySpawn child));
-        Assert.Null(child.Position);
+        Assert.NotNull(child.Position);
+        Assert.Null(child.ParentGuid);
+        Assert.Equal((ushort)5, child.PositionSequence);
     }
 
     [Fact]

tests/AcDream.App.Tests/World/ParentAttachmentStateTests.cs

@@ -27,9 +27,12 @@ public sealed class ParentAttachmentStateTests
         Assert.True(relations.TryGetProjection(childGuid, out ParentAttachmentRelation projection));
         Assert.Equal(parentGuid, projection.ParentGuid);
         Assert.True(inbound.TryGetSnapshot(childGuid, out WorldSession.EntitySpawn child));
+        Assert.NotNull(child.Position);
+        Assert.Null(child.ParentGuid);
+        Assert.Equal((ushort)5, child.PositionSequence);
+        Assert.True(Commit(relations, inbound, projection, out child));
         Assert.Null(child.Position);
         Assert.Equal(parentGuid, child.ParentGuid);
-        Assert.Equal((ushort)5, child.PositionSequence);
     }
 
     [Fact]
@@ -50,9 +53,24 @@ public sealed class ParentAttachmentStateTests
             update => gate.TryAcceptPositionChannelEvent(3, update.ChildPositionSequence));
 
         Assert.True(relations.TryGetProjection(childGuid, out ParentAttachmentRelation projection));
+        Assert.Equal((ushort)5, projection.ChildPositionSequence);
+        Assert.Equal((uint)2, projection.PlacementId);
+        Assert.True(relations.CommitProjection(projection));
+        relations.MarkProjected(
+            projection,
+            ParentProjectionCandidateKind.Recovery);
+        relations.Resolve(
+            childGuid,
+            _ => true,
+            guid => guid == parentGuid ? (ushort)9 : null,
+            update => gate.TryAcceptPositionChannelEvent(3, update.ChildPositionSequence));
+        Assert.True(relations.TryGetStagedProjection(childGuid, out projection));
         Assert.Equal((ushort)6, projection.ChildPositionSequence);
         Assert.Equal((uint)3, projection.PlacementId);
-        relations.MarkProjected(childGuid);
+        Assert.True(relations.CommitProjection(projection));
+        relations.MarkProjected(
+            projection,
+            ParentProjectionCandidateKind.Recovery);
         Assert.True(relations.RestoreLastAccepted(childGuid));
         Assert.True(relations.TryGetProjection(childGuid, out projection));
         Assert.Equal((ushort)6, projection.ChildPositionSequence);
@@ -136,6 +154,7 @@ public sealed class ParentAttachmentStateTests
         Assert.Equal(parentGuid, projection.ParentGuid);
         Assert.Equal((ushort)10, projection.ParentInstanceSequence);
         Assert.Equal((ushort)5, projection.ChildPositionSequence);
+        Assert.True(Commit(relations, inbound, projection, out _));
         Assert.True(inbound.TryGetSnapshot(childGuid, out WorldSession.EntitySpawn child));
         Assert.Equal(parentGuid, child.ParentGuid);
     }
@@ -257,6 +276,20 @@ public sealed class ParentAttachmentStateTests
                 : null,
             update => inbound.TryApplyParent(update, out _));
 
+    private static bool Commit(
+        ParentAttachmentState relations,
+        InboundPhysicsStateController inbound,
+        ParentAttachmentRelation relation,
+        out WorldSession.EntitySpawn accepted) =>
+        inbound.TryCommitParent(
+            relation.ChildGuid,
+            relation.ParentGuid,
+            relation.ParentLocation,
+            relation.PlacementId,
+            relation.ChildPositionSequence,
+            out accepted)
+        && relations.CommitProjection(relation);
+
     private static WorldSession.EntitySpawn Spawn(
         uint guid,
         ushort instance,