perf(vfx): port retail particle visibility degradation

Resolve DAT-authored particle ranges from the hardware GfxObj, apply retail distance and completed-cell visibility gates, and preserve the exact finite/infinite off-view update semantics. This removes dense-world simulation work without shortening terrain, entity, fog, or streaming distance.

Publish doorway-clipped outdoor cells through a focused frame controller, retain effect cell identity for outdoor statics, reject hidden emitters before particle-slot scans, and offer an explicit opt-in Extended particle range.

Release build succeeds and all 5,857 tests pass with five intentional skips. Retail-conformance, architecture, and adversarial review cycles are clean; connected Aerlinthe visual/performance gate pending.

Co-authored-by: OpenAI Codex <codex@openai.com>
This commit is contained in:
Erik 2026-07-17 15:27:36 +02:00
parent 82789eea88
commit f1ba147ac5
29 changed files with 1810 additions and 125 deletions

View file

@ -1,6 +1,7 @@
using System.Linq;
using System.Numerics;
using AcDream.Core.Vfx;
using DatReaderWriter.Types;
using Xunit;
namespace AcDream.Core.Tests.Vfx;
@ -22,7 +23,8 @@ public sealed class ParticleSystemTests
LifetimeMin = lifetime,
LifetimeMax = lifetime,
OffsetDir = Vector3.UnitZ,
MinOffset = 0, MaxOffset = 0,
MinOffset = 0,
MaxOffset = 0,
SpawnDiskRadius = 0,
InitialVelocity = new Vector3(0, 0, 1f),
VelocityJitter = 0,
@ -142,11 +144,14 @@ public sealed class ParticleSystemTests
Type = ParticleType.ParabolicLVGA,
EmitRate = 10f,
MaxParticles = 100,
LifetimeMin = 2f, LifetimeMax = 2f,
LifetimeMin = 2f,
LifetimeMax = 2f,
OffsetDir = Vector3.UnitZ,
InitialVelocity = new Vector3(0, 0, 5f), // straight up
StartSize = 0.5f, EndSize = 0.5f,
StartAlpha = 1f, EndAlpha = 0f,
StartSize = 0.5f,
EndSize = 0.5f,
StartAlpha = 1f,
EndAlpha = 0f,
Gravity = new Vector3(0, 0, -10f), // strong gravity
};
sys.SpawnEmitter(desc, Vector3.Zero);
@ -179,13 +184,17 @@ public sealed class ParticleSystemTests
Type = ParticleType.Explode,
EmitRate = 20f,
MaxParticles = 100,
LifetimeMin = 2f, LifetimeMax = 2f,
LifetimeMin = 2f,
LifetimeMax = 2f,
OffsetDir = Vector3.UnitZ,
MinOffset = 0.5f, MaxOffset = 0.5f,
MinOffset = 0.5f,
MaxOffset = 0.5f,
SpawnDiskRadius = 0.5f,
InitialVelocity = new Vector3(1, 0, 0), // magnitude = 1
StartSize = 0.5f, EndSize = 0.5f,
StartAlpha = 1f, EndAlpha = 0f,
StartSize = 0.5f,
EndSize = 0.5f,
StartAlpha = 1f,
EndAlpha = 0f,
};
sys.SpawnEmitter(desc, Vector3.Zero);
@ -377,6 +386,383 @@ public sealed class ParticleSystemTests
Assert.True((desc.Flags & EmitterFlags.AttachLocal) != 0);
}
[Fact]
public void EmitterDescRegistry_DoesNotSubstituteSoftwareGfxForMissingHardwareGfx()
{
var dat = new DatReaderWriter.DBObjs.ParticleEmitter
{
GfxObjId = 0x01000001u,
HwGfxObjId = 0u,
};
Assert.Equal(0u, EmitterDescRegistry.GetRetailHardwareGfxObjId(dat));
}
[Fact]
public void RetailParticleDegradeDistance_MatchesRetailEntrySelection()
{
var one = new List<GfxObjInfo>
{
new() { MaxDist = 11f },
};
var two = new List<GfxObjInfo>
{
new() { MaxDist = 21f },
new() { MaxDist = 22f },
};
var four = new List<GfxObjInfo>
{
new() { MaxDist = 31f },
new() { MaxDist = 32f },
new() { MaxDist = 33f },
new() { MaxDist = 34f },
};
Assert.Equal(100f, RetailParticleDegradeDistance.FromEntries(null));
Assert.Equal(11f, RetailParticleDegradeDistance.FromEntries(one));
Assert.Equal(21f, RetailParticleDegradeDistance.FromEntries(two));
Assert.Equal(33f, RetailParticleDegradeDistance.FromEntries(four));
}
[Fact]
public void RetailParticleDegradeDistance_PreservesRawAuthoredValue()
{
Assert.Equal(-1f, RetailParticleDegradeDistance.FromEntries(
new List<GfxObjInfo> { new() { MaxDist = -1f } }));
Assert.Equal(float.PositiveInfinity, RetailParticleDegradeDistance.FromEntries(
new List<GfxObjInfo> { new() { MaxDist = float.PositiveInfinity } }));
Assert.True(float.IsNaN(RetailParticleDegradeDistance.FromEntries(
new List<GfxObjInfo> { new() { MaxDist = float.NaN } })));
}
[Fact]
public void ApplyRetailView_UsesOwnerVisibilityAndInclusiveAuthoredDistance()
{
var sys = MakeSystem();
var desc = new EmitterDesc
{
DatId = 0x32000076u,
Type = ParticleType.Still,
MaxDegradeDistance = 10f,
MaxParticles = 1,
InitialParticles = 1,
LifetimeMin = 10f,
LifetimeMax = 10f,
StartSize = 1f,
EndSize = 1f,
StartAlpha = 1f,
EndAlpha = 1f,
};
int handle = sys.SpawnEmitter(
desc,
new Vector3(10f, 0f, 0f),
attachedObjectId: 7u);
sys.UpdateEmitterOwnerCell(handle, 0x01010001u);
sys.ApplyRetailView(Vector3.Zero, new HashSet<uint> { 0x01010001u }, true);
Assert.True(Assert.Single(sys.EnumerateEmitters()).ViewEligible);
sys.ApplyRetailView(Vector3.Zero, new HashSet<uint>(), true);
Assert.False(Assert.Single(sys.EnumerateEmitters()).ViewEligible);
sys.ApplyRetailView(
Vector3.Zero,
new HashSet<uint> { 0x01010001u },
true,
rangeMultiplier: 0.5f);
Assert.False(Assert.Single(sys.EnumerateEmitters()).ViewEligible);
}
[Fact]
public void ApplyRetailView_UnorderedOwnerDistanceMatchesRetailX87Comparison()
{
var sys = MakeSystem();
int handle = sys.SpawnEmitter(
new EmitterDesc
{
DatId = 0x32000079u,
Type = ParticleType.Still,
MaxDegradeDistance = 100f,
MaxParticles = 1,
},
Vector3.Zero,
attachedObjectId: 12u);
sys.UpdateEmitterOwnerPosition(handle, new Vector3(float.NaN, 0f, 0f));
sys.UpdateEmitterOwnerCell(handle, 0x0101000Cu);
sys.ApplyRetailView(
Vector3.Zero,
new HashSet<uint> { 0x0101000Cu },
true);
Assert.True(Assert.Single(sys.EnumerateEmitters()).ViewEligible);
}
[Fact]
public void ApplyRetailView_UsesOverflowSafeDirectDistanceAndRawRange()
{
var visible = new HashSet<uint> { 0x0101000Du };
static ParticleSystem Spawn(float maxDistance, Vector3 owner, out int handle)
{
var system = MakeSystem();
handle = system.SpawnEmitter(
new EmitterDesc
{
DatId = 0x3200007Au,
Type = ParticleType.Still,
MaxDegradeDistance = maxDistance,
MaxParticles = 1,
},
owner,
attachedObjectId: 13u);
system.UpdateEmitterOwnerPosition(handle, owner);
system.UpdateEmitterOwnerCell(handle, 0x0101000Du);
return system;
}
ParticleSystem huge = Spawn(float.MaxValue, new Vector3(1e20f, 0f, 0f), out _);
huge.ApplyRetailView(Vector3.Zero, visible, true);
Assert.True(Assert.Single(huge.EnumerateEmitters()).ViewEligible);
ParticleSystem negative = Spawn(-1f, Vector3.Zero, out _);
negative.ApplyRetailView(Vector3.Zero, visible, true);
Assert.False(Assert.Single(negative.EnumerateEmitters()).ViewEligible);
ParticleSystem zero = Spawn(0f, Vector3.Zero, out _);
zero.ApplyRetailView(Vector3.Zero, visible, true);
Assert.True(Assert.Single(zero.EnumerateEmitters()).ViewEligible);
ParticleSystem nan = Spawn(float.NaN, new Vector3(100f, 0f, 0f), out _);
nan.ApplyRetailView(Vector3.Zero, visible, true);
Assert.True(Assert.Single(nan.EnumerateEmitters()).ViewEligible);
ParticleSystem infinity = Spawn(float.PositiveInfinity, new Vector3(float.MaxValue, 0f, 0f), out _);
infinity.ApplyRetailView(Vector3.Zero, visible, true);
Assert.True(Assert.Single(infinity.EnumerateEmitters()).ViewEligible);
}
[Fact]
public void InfiniteEmitter_DegradedTimeFreezesParticleAgeWithoutCatchUp()
{
var sys = MakeSystem();
var desc = new EmitterDesc
{
DatId = 0x32000077u,
Type = ParticleType.Still,
MaxDegradeDistance = 5f,
MaxParticles = 1,
InitialParticles = 1,
TotalParticles = 0,
TotalDuration = 0f,
LifetimeMin = 10f,
LifetimeMax = 10f,
StartSize = 1f,
EndSize = 1f,
StartAlpha = 1f,
EndAlpha = 1f,
};
int handle = sys.SpawnEmitter(desc, Vector3.Zero, attachedObjectId: 9u);
sys.UpdateEmitterOwnerCell(handle, 0x01010009u);
var visible = new HashSet<uint> { 0x01010009u };
sys.ApplyRetailView(Vector3.Zero, visible, true);
sys.Tick(1f);
Assert.Equal(1f, Assert.Single(sys.EnumerateLive()).Emitter.Particles[0].Age, 4);
sys.ApplyRetailView(new Vector3(6f, 0f, 0f), visible, true);
sys.Tick(5f);
Assert.True(Assert.Single(sys.EnumerateEmitters()).DegradedOut);
sys.ApplyRetailView(Vector3.Zero, visible, true);
sys.Tick(1f);
ParticleEmitter emitter = Assert.Single(sys.EnumerateEmitters());
Assert.False(emitter.DegradedOut);
Assert.Equal(2f, emitter.Particles[0].Age, 4);
}
[Fact]
public void ApplyRetailView_ExaminationAndPassOwnedEmittersBypassWorldGate()
{
var sys = MakeSystem();
var desc = new EmitterDesc
{
DatId = 0x3200007Cu,
Type = ParticleType.Still,
MaxDegradeDistance = 1f,
MaxParticles = 1,
};
sys.SpawnEmitter(
desc,
new Vector3(100f, 0f, 0f),
visibilityPolicy: ParticleVisibilityPolicy.Examination);
sys.SpawnEmitter(
desc,
new Vector3(100f, 0f, 0f),
renderPass: ParticleRenderPass.SkyPreScene,
visibilityPolicy: ParticleVisibilityPolicy.PassOwned);
sys.ApplyRetailView(Vector3.Zero, new HashSet<uint>(), false);
Assert.All(sys.EnumerateEmitters(), emitter => Assert.True(emitter.ViewEligible));
}
[Fact]
public void FiniteEmitter_DegradedBranchExpiresAndRemovesIt()
{
var sys = MakeSystem();
var desc = new EmitterDesc
{
DatId = 0x32000078u,
Type = ParticleType.Still,
MaxDegradeDistance = 1f,
MaxParticles = 1,
InitialParticles = 1,
TotalParticles = 1,
LifetimeMin = 0.5f,
LifetimeMax = 0.5f,
StartSize = 1f,
EndSize = 1f,
StartAlpha = 1f,
EndAlpha = 1f,
};
int handle = sys.SpawnEmitter(desc, Vector3.Zero, attachedObjectId: 10u);
sys.UpdateEmitterOwnerCell(handle, 0x0101000Au);
sys.ApplyRetailView(
new Vector3(2f, 0f, 0f),
new HashSet<uint> { 0x0101000Au },
true);
sys.Tick(1f);
Assert.Equal(1, sys.ActiveEmitterCount);
Assert.True(Assert.Single(sys.EnumerateEmitters()).Finished);
sys.Tick(0.01f);
Assert.Equal(0, sys.ActiveEmitterCount);
}
[Fact]
public void FiniteEmitter_DegradedBranchDoesNotStopBeforeAuthoredLimit()
{
var sys = MakeSystem();
int handle = sys.SpawnEmitter(
new EmitterDesc
{
DatId = 0x3200007Du,
Type = ParticleType.Still,
EmitterKind = ParticleEmitterKind.BirthratePerSec,
Birthrate = 10f,
MaxDegradeDistance = 1f,
MaxParticles = 4,
InitialParticles = 1,
TotalParticles = 4,
TotalDuration = 100f,
LifetimeMin = 50f,
LifetimeMax = 50f,
},
Vector3.Zero,
attachedObjectId: 15u);
sys.UpdateEmitterOwnerCell(handle, 0x0101000Fu);
sys.ApplyRetailView(
new Vector3(2f, 0f, 0f),
new HashSet<uint> { 0x0101000Fu },
true);
sys.Tick(1f);
ParticleEmitter emitter = Assert.Single(sys.EnumerateEmitters());
Assert.False(emitter.Finished);
Assert.Equal(1, emitter.ActiveCount);
Assert.Equal(1, emitter.TotalEmitted);
}
[Fact]
public void FiniteEmitter_DegradedDueEmissionRecordsBothRetailCounters()
{
var sys = MakeSystem();
int handle = sys.SpawnEmitter(
new EmitterDesc
{
DatId = 0x3200007Eu,
Type = ParticleType.Still,
EmitterKind = ParticleEmitterKind.BirthratePerSec,
Birthrate = 0.5f,
MaxDegradeDistance = 1f,
MaxParticles = 4,
TotalParticles = 3,
TotalDuration = 100f,
LifetimeMin = 5f,
LifetimeMax = 5f,
},
Vector3.Zero,
attachedObjectId: 16u);
sys.UpdateEmitterOwnerCell(handle, 0x01010010u);
sys.ApplyRetailView(
new Vector3(2f, 0f, 0f),
new HashSet<uint> { 0x01010010u },
true);
sys.Tick(0.25f);
ParticleEmitter beforeDue = Assert.Single(sys.EnumerateEmitters());
Assert.Equal(0, beforeDue.ActiveCount);
Assert.Equal(0, beforeDue.TotalEmitted);
Assert.False(beforeDue.Finished);
sys.Tick(0.5f);
ParticleEmitter afterDue = Assert.Single(sys.EnumerateEmitters());
Assert.Equal(1, afterDue.ActiveCount);
Assert.Equal(1, afterDue.TotalEmitted);
Assert.False(afterDue.Finished);
Assert.Empty(sys.EnumerateLive());
}
[Fact]
public void FiniteEmitter_DegradedRecordedCountPersistsUntilOwnerTeardownLikeRetail()
{
var sys = MakeSystem();
int handle = sys.SpawnEmitter(
new EmitterDesc
{
DatId = 0x3200007Fu,
Type = ParticleType.Still,
EmitterKind = ParticleEmitterKind.BirthratePerSec,
Birthrate = 0.5f,
MaxDegradeDistance = 1f,
MaxParticles = 1,
TotalParticles = 1,
TotalDuration = 100f,
LifetimeMin = 5f,
LifetimeMax = 5f,
},
Vector3.Zero,
attachedObjectId: 17u);
sys.UpdateEmitterOwnerCell(handle, 0x01010011u);
sys.ApplyRetailView(
new Vector3(2f, 0f, 0f),
new HashSet<uint> { 0x01010011u },
true);
sys.Tick(0.75f);
ParticleEmitter stopped = Assert.Single(sys.EnumerateEmitters());
Assert.True(stopped.Finished);
Assert.Equal(1, stopped.ActiveCount);
Assert.Empty(sys.EnumerateLive());
// Retail RecordParticleEmission (0x0051C870) increments
// num_particles without allocating a PhysicsPart. The already-stopped
// UpdateParticles branch (0x0051D180) therefore keeps returning true
// until the owning physics object explicitly destroys the emitter.
sys.Tick(10f);
Assert.True(sys.IsEmitterAlive(handle));
Assert.Equal(1, Assert.Single(sys.EnumerateEmitters()).ActiveCount);
Assert.Empty(sys.EnumerateLive());
sys.StopEmitter(handle, fadeOut: false);
Assert.False(sys.IsEmitterAlive(handle));
}
[Fact]
public void UpdateEmitterAnchor_AttachLocal_ParticlePositionFollowsLiveAnchor()
{
@ -392,9 +778,13 @@ public sealed class ParticleSystemTests
Flags = EmitterFlags.AttachLocal | EmitterFlags.Billboard,
MaxParticles = 1,
InitialParticles = 1,
LifetimeMin = 100f, LifetimeMax = 100f, Lifespan = 100f,
StartSize = 1f, EndSize = 1f,
StartAlpha = 1f, EndAlpha = 1f,
LifetimeMin = 100f,
LifetimeMax = 100f,
Lifespan = 100f,
StartSize = 1f,
EndSize = 1f,
StartAlpha = 1f,
EndAlpha = 1f,
// Zero motion + zero offset so position == origin == AnchorPos.
};
int handle = sys.SpawnEmitter(desc, anchor: new Vector3(10, 0, 0));
@ -425,9 +815,13 @@ public sealed class ParticleSystemTests
Flags = EmitterFlags.Billboard, // NO AttachLocal
MaxParticles = 1,
InitialParticles = 1,
LifetimeMin = 100f, LifetimeMax = 100f, Lifespan = 100f,
StartSize = 1f, EndSize = 1f,
StartAlpha = 1f, EndAlpha = 1f,
LifetimeMin = 100f,
LifetimeMax = 100f,
Lifespan = 100f,
StartSize = 1f,
EndSize = 1f,
StartAlpha = 1f,
EndAlpha = 1f,
};
int handle = sys.SpawnEmitter(desc, anchor: new Vector3(10, 0, 0));
sys.Tick(0.01f);
@ -473,9 +867,13 @@ public sealed class ParticleSystemTests
Birthrate = 0.05f, // 50ms minimum between emits
EmitRate = 0f, // disable the EmitRate fallback path
MaxParticles = 100,
LifetimeMin = 100f, LifetimeMax = 100f, Lifespan = 100f,
StartSize = 1f, EndSize = 1f,
StartAlpha = 1f, EndAlpha = 1f,
LifetimeMin = 100f,
LifetimeMax = 100f,
Lifespan = 100f,
StartSize = 1f,
EndSize = 1f,
StartAlpha = 1f,
EndAlpha = 1f,
};
sys.SpawnEmitter(desc, Vector3.Zero);