feat(vfx): bind effects to live animated poses

This commit is contained in:
Erik 2026-07-14 10:56:01 +02:00
parent 96ddfdf175
commit 542dcfc384
41 changed files with 3246 additions and 741 deletions

View file

@ -7,9 +7,14 @@ namespace AcDream.Core.Tests.Vfx;
public sealed class ParticleHookSinkTests
{
private static EmitterDesc MakeDesc(uint id, bool attachLocal, int totalParticles = 0)
{
return new EmitterDesc
private const uint Owner = 0xCAFEu;
private static EmitterDesc MakeDesc(
uint id,
bool attachLocal,
int totalParticles = 0,
float totalDuration = 0f) =>
new()
{
DatId = id,
Type = ParticleType.Still,
@ -18,158 +23,350 @@ public sealed class ParticleHookSinkTests
MaxParticles = 4,
InitialParticles = 1,
TotalParticles = totalParticles,
LifetimeMin = 0.05f, LifetimeMax = 0.05f, Lifespan = 0.05f,
StartSize = 1f, EndSize = 1f,
StartAlpha = 1f, EndAlpha = 1f,
Birthrate = 1000f, // effectively never re-emit
TotalDuration = totalDuration,
LifetimeMin = 0.05f,
LifetimeMax = 0.05f,
Lifespan = 0.05f,
StartSize = 1f,
EndSize = 1f,
StartAlpha = 1f,
EndAlpha = 1f,
Birthrate = 1000f,
};
private static (ParticleSystem System, ParticleHookSink Sink, MutablePoseSource Poses) Harness(
uint emitterId,
bool attachLocal = false,
int totalParticles = 0,
float totalDuration = 0f)
{
var registry = new EmitterDescRegistry();
registry.Register(MakeDesc(emitterId, attachLocal, totalParticles, totalDuration));
var system = new ParticleSystem(registry, new Random(42));
var poses = new MutablePoseSource();
poses.Publish(Owner, Matrix4x4.Identity, Matrix4x4.Identity);
return (system, new ParticleHookSink(system, poses), poses);
}
private static CreateParticleHook Create(uint emitterInfoId, uint logicalId, int partIndex = 0) =>
new()
{
EmitterInfoId = emitterInfoId,
EmitterId = logicalId,
PartIndex = unchecked((uint)partIndex),
Offset = new Frame(),
};
[Fact]
public void RefreshAttachedEmitters_WithAttachLocal_MovesExistingParticleToCurrentPose()
{
const uint emitterId = 0x32000010u;
var (system, sink, poses) = Harness(emitterId, attachLocal: true);
sink.OnHook(Owner, Vector3.Zero, Create(emitterId, 0));
system.Tick(0.01f);
Assert.Equal(Vector3.Zero, system.EnumerateLive().Single().Emitter.Particles[0].Position);
poses.Publish(Owner, Matrix4x4.CreateTranslation(5, 7, 0), Matrix4x4.Identity);
sink.RefreshAttachedEmitters();
system.Tick(0.01f);
Assert.Equal(new Vector3(5, 7, 0),
system.EnumerateLive().Single().Emitter.Particles[0].Position);
}
[Fact]
public void UpdateEntityAnchor_WithAttachLocal_MovesParticleToLiveAnchor()
public void WorldReleasedParticles_KeepBirthPosition_WhileNewAnchorMoves()
{
var registry = new EmitterDescRegistry();
registry.Register(MakeDesc(0x32000010u, attachLocal: true));
var sys = new ParticleSystem(registry, new System.Random(42));
var sink = new ParticleHookSink(sys);
const uint emitterId = 0x32000011u;
var (system, sink, poses) = Harness(emitterId, attachLocal: false);
sink.OnHook(Owner, Vector3.Zero, Create(emitterId, 0));
system.Tick(0.01f);
var hook = new CreateParticleHook
poses.Publish(Owner, Matrix4x4.CreateTranslation(9, 0, 0), Matrix4x4.Identity);
sink.RefreshAttachedEmitters();
system.Tick(0.01f);
Assert.Equal(Vector3.Zero,
system.EnumerateLive().Single().Emitter.Particles[0].Position);
}
[Fact]
public void Spawn_UsesCurrentIndexedPartAndRoot_WithRowVectorComposition()
{
const uint emitterId = 0x32000030u;
var (system, sink, poses) = Harness(emitterId);
Matrix4x4 root = Matrix4x4.CreateRotationZ(MathF.PI / 2f)
* Matrix4x4.CreateTranslation(10, 20, 30);
poses.Publish(
Owner,
root,
Matrix4x4.Identity,
Matrix4x4.CreateTranslation(0, 0, 2));
var hook = Create(emitterId, 0, partIndex: 1);
hook.Offset = new Frame
{
EmitterInfoId = 0x32000010u,
Origin = new Vector3(1, 0, 0),
// Retail retains but does not consume this quaternion in
// Particle::Init 0x0051C930.
Orientation = Quaternion.CreateFromAxisAngle(Vector3.UnitX, 1.1f),
};
sink.OnHook(Owner, Vector3.Zero, hook);
system.Tick(0.001f);
Vector3 position = system.EnumerateLive().Single().Emitter.Particles[0].Position;
Assert.InRange(position.X, 9.99f, 10.01f);
Assert.InRange(position.Y, 20.99f, 21.01f);
Assert.InRange(position.Z, 31.99f, 32.01f);
}
[Fact]
public void PartMinusOne_UsesRoot_AndInvalidIndexedPartDoesNotFallback()
{
const uint emitterId = 0x32000031u;
var (system, sink, poses) = Harness(emitterId);
poses.Publish(
Owner,
Matrix4x4.CreateTranslation(3, 4, 5),
Matrix4x4.CreateTranslation(50, 0, 0));
sink.OnHook(Owner, Vector3.Zero, Create(emitterId, 0, partIndex: -1));
sink.OnHook(Owner, Vector3.Zero, Create(emitterId, 0, partIndex: 99));
system.Tick(0.001f);
Assert.Single(system.EnumerateLive());
Assert.Equal(new Vector3(3, 4, 5),
system.EnumerateLive().Single().Emitter.Particles[0].Position);
}
[Fact]
public void NormalLogicalId_Replaces_BlockingSuppresses_ThenCreatesAfterRetirement()
{
const uint emitterId = 0x32000040u;
const uint logicalId = 0x1234u;
var (system, sink, _) = Harness(emitterId);
var normal = Create(emitterId, logicalId);
var blocking = new RetailCreateBlockingParticleHook
{
EmitterInfoId = emitterId,
EmitterId = logicalId,
PartIndex = 0,
Offset = new Frame(),
};
sink.OnHook(Owner, Vector3.Zero, normal);
sink.OnHook(Owner, Vector3.Zero, blocking);
Assert.Equal(1, system.ActiveEmitterCount);
sink.OnHook(Owner, Vector3.Zero, normal);
system.Tick(0.001f);
Assert.Equal(1, system.ActiveEmitterCount);
sink.OnHook(Owner, Vector3.Zero,
new DestroyParticleHook { EmitterId = logicalId });
system.Tick(0.001f);
Assert.Equal(0, system.ActiveEmitterCount);
sink.OnHook(Owner, Vector3.Zero, blocking);
Assert.Equal(1, system.ActiveEmitterCount);
}
[Fact]
public void BlockingLogicalIdZero_AlwaysCreatesAnonymousEmitter()
{
const uint emitterId = 0x32000041u;
var (system, sink, _) = Harness(emitterId);
var blocking = new RetailCreateBlockingParticleHook
{
EmitterInfoId = emitterId,
EmitterId = 0,
PartIndex = 0,
Offset = new Frame(),
};
// First spawn at world origin.
sink.OnHook(entityId: 0xCAFEu, entityWorldPosition: Vector3.Zero, hook);
sys.Tick(0.01f);
var live1 = System.Linq.Enumerable.Single(sys.EnumerateLive());
Assert.Equal(Vector3.Zero, live1.Emitter.Particles[live1.Index].Position);
// Move the parent to (5, 7, 0) — UpdateEntityAnchor must propagate.
sink.UpdateEntityAnchor(0xCAFEu, new Vector3(5, 7, 0), Quaternion.Identity);
sys.Tick(0.01f);
var live2 = System.Linq.Enumerable.Single(sys.EnumerateLive());
Assert.Equal(new Vector3(5, 7, 0), live2.Emitter.Particles[live2.Index].Position);
sink.OnHook(Owner, Vector3.Zero, blocking);
sink.OnHook(Owner, Vector3.Zero, blocking);
Assert.Equal(2, system.ActiveEmitterCount);
}
[Fact]
public void EmitterDied_PrunesPerEntityHandleTracking()
public void StopLogicalEmitter_RemainsBlockingUntilFinalParticleRetires()
{
// M4: ConcurrentBag<int> couldn't drop entries when a particle
// emitter expired naturally, so per-entity tracking grew without
// bound. The sink now subscribes to ParticleSystem.EmitterDied
// and prunes both the (entity,key) map and the per-entity set.
var registry = new EmitterDescRegistry();
registry.Register(MakeDesc(0x32000020u, attachLocal: false, totalParticles: 1));
var sys = new ParticleSystem(registry, new System.Random(42));
var sink = new ParticleHookSink(sys);
var hook = new CreateParticleHook
const uint emitterId = 0x32000042u;
const uint logicalId = 0x777u;
var (system, sink, _) = Harness(emitterId);
var blocking = new RetailCreateBlockingParticleHook
{
EmitterInfoId = 0x32000020u,
EmitterId = 0xABCDu, // logical key
EmitterInfoId = emitterId,
EmitterId = logicalId,
PartIndex = 0,
Offset = new Frame(),
};
sink.OnHook(0xCAFEu, Vector3.Zero, hook);
Assert.Equal(1, sys.ActiveEmitterCount);
// TotalParticles=1 cap hit immediately by the InitialParticles spawn,
// so the emitter Finishes once its single particle expires (0.05s
// lifetime). After this, EmitterDied has fired and tracking is pruned.
for (int i = 0; i < 5; i++) sys.Tick(0.05f);
Assert.Equal(0, sys.ActiveEmitterCount);
sink.OnHook(Owner, Vector3.Zero, Create(emitterId, logicalId));
sink.OnHook(Owner, Vector3.Zero, new StopParticleHook { EmitterId = logicalId });
sink.OnHook(Owner, Vector3.Zero, blocking);
// A fresh spawn for the same (entity, key) succeeds and is the only
// live emitter — i.e., the previous handle was pruned cleanly.
sink.OnHook(0xCAFEu, Vector3.Zero, hook);
Assert.Equal(1, sys.ActiveEmitterCount);
sink.StopAllForEntity(0xCAFEu, fadeOut: false);
sys.Tick(0.01f);
Assert.Equal(0, sys.ActiveEmitterCount);
Assert.Equal(1, system.ActiveEmitterCount);
}
[Fact]
public void SpawnFromHook_AppliesPartTransform_WhenRegistered()
public void StopLogicalEmitter_NormalCreateStillReplacesIt()
{
// C.1.5b #56: when SetEntityPartTransforms has been called for
// entityId, SpawnFromHook must transform the hook offset through
// the part-local matrix before applying entity rotation.
// Part 1 is lifted +Z=1; hook offset = (1, 0, 0), PartIndex=1.
// Expected world position: (1, 0, 1) with identity rotation.
var registry = new EmitterDescRegistry();
registry.Register(MakeDesc(0x32000030u, attachLocal: false));
var sys = new ParticleSystem(registry, new System.Random(42));
var sink = new ParticleHookSink(sys);
const uint emitterId = 0x32000043u;
const uint logicalId = 0x778u;
var (system, sink, _) = Harness(emitterId);
var partTransforms = new Matrix4x4[]
{
Matrix4x4.Identity,
Matrix4x4.CreateTranslation(0f, 0f, 1f),
};
sink.SetEntityRotation(0xCAFEu, Quaternion.Identity);
sink.SetEntityPartTransforms(0xCAFEu, partTransforms);
sink.OnHook(Owner, Vector3.Zero, Create(emitterId, logicalId));
sink.OnHook(Owner, Vector3.Zero, new StopParticleHook { EmitterId = logicalId });
sink.OnHook(Owner, Vector3.Zero, Create(emitterId, logicalId));
system.Tick(0.001f);
sink.OnHook(0xCAFEu, Vector3.Zero, new CreateParticleHook
{
EmitterInfoId = 0x32000030u,
EmitterId = 0,
PartIndex = 1,
Offset = new Frame
{
Origin = new Vector3(1f, 0f, 0f),
Orientation = Quaternion.Identity,
},
});
sys.Tick(0.001f);
var live = System.Linq.Enumerable.Single(sys.EnumerateLive());
var pos = live.Emitter.Particles[live.Index].Position;
Assert.InRange(pos.X, 0.99f, 1.01f);
Assert.InRange(pos.Y, -0.01f, 0.01f);
Assert.InRange(pos.Z, 0.99f, 1.01f);
Assert.Equal(1, system.ActiveEmitterCount);
}
[Fact]
public void SpawnFromHook_FallsBackToIdentity_WhenPartIndexOutOfBounds()
public void NaturalRetirement_PrunesLogicalIdForBlockingReuse()
{
// Out-of-bounds PartIndex must NOT crash and must NOT apply a
// wrong matrix; falls back to no part transform (Identity), so
// the offset is applied in entity-local space as pre-C.1.5b.
var registry = new EmitterDescRegistry();
registry.Register(MakeDesc(0x32000031u, attachLocal: false));
var sys = new ParticleSystem(registry, new System.Random(42));
var sink = new ParticleHookSink(sys);
var partTransforms = new Matrix4x4[]
const uint emitterId = 0x32000020u;
const uint logicalId = 0xABCDu;
var (system, sink, _) = Harness(emitterId, totalParticles: 1);
var blocking = new RetailCreateBlockingParticleHook
{
Matrix4x4.Identity,
Matrix4x4.CreateTranslation(0f, 0f, 1f),
EmitterInfoId = emitterId,
EmitterId = logicalId,
PartIndex = 0,
Offset = new Frame(),
};
sink.SetEntityRotation(0xCAFEu, Quaternion.Identity);
sink.SetEntityPartTransforms(0xCAFEu, partTransforms);
sink.OnHook(Owner, Vector3.Zero, blocking);
for (int i = 0; i < 5; i++)
system.Tick(0.05f);
Assert.Equal(0, system.ActiveEmitterCount);
sink.OnHook(0xCAFEu, Vector3.Zero, new CreateParticleHook
sink.OnHook(Owner, Vector3.Zero, blocking);
Assert.Equal(1, system.ActiveEmitterCount);
}
[Fact]
public void MissingEmitterAsset_ReportsDiagnosticWithoutFabricatingEffect()
{
const uint registeredId = 0x32000020u;
const uint missingId = 0x32DEAD00u;
var (system, sink, _) = Harness(registeredId);
var diagnostics = new List<string>();
sink.DiagnosticSink = diagnostics.Add;
sink.OnHook(Owner, Vector3.Zero, Create(missingId, logicalId: 7u));
Assert.Equal(0, system.ActiveEmitterCount);
string diagnostic = Assert.Single(diagnostics);
Assert.Contains($"0x{missingId:X8}", diagnostic, StringComparison.Ordinal);
Assert.Contains($"0x{Owner:X8}", diagnostic, StringComparison.Ordinal);
}
[Fact]
public void MissingLivePose_HidesPresentationWithoutEndingEmitterLifetime()
{
const uint emitterId = 0x32000055u;
var (system, sink, poses) = Harness(emitterId);
sink.OnHook(Owner, Vector3.Zero, Create(emitterId, logicalId: 11u));
ParticleEmitter emitter = system.EnumerateLive().Single().Emitter;
Assert.True(emitter.PresentationVisible);
poses.Remove(Owner);
sink.RefreshAttachedEmitters();
Assert.Equal(1, system.ActiveEmitterCount);
Assert.False(emitter.PresentationVisible);
poses.Publish(Owner, Matrix4x4.CreateTranslation(8, 0, 0), Matrix4x4.Identity);
sink.RefreshAttachedEmitters();
Assert.True(emitter.PresentationVisible);
}
[Fact]
public void PendingProjection_HidesPresentationWhileContinuingLiveAnchorRefresh()
{
const uint emitterId = 0x32000056u;
var (system, sink, poses) = Harness(emitterId, totalDuration: 0.05f);
sink.OnHook(Owner, Vector3.Zero, Create(emitterId, logicalId: 12u));
ParticleEmitter emitter = system.EnumerateLive().Single().Emitter;
int emittedBeforePause = emitter.TotalEmitted;
float spawnedAt = emitter.Particles[0].SpawnedAt;
sink.SetEntityPresentationVisible(Owner, false);
poses.Publish(
Owner,
Matrix4x4.CreateTranslation(12, 3, 0),
Matrix4x4.Identity);
sink.RefreshAttachedEmitters();
system.Tick(1f);
Assert.Equal(1, system.ActiveEmitterCount);
Assert.Equal(new Vector3(12, 3, 0), emitter.AnchorPos);
Assert.Equal(emittedBeforePause, emitter.TotalEmitted);
Assert.Equal(spawnedAt, emitter.Particles[0].SpawnedAt);
Assert.Equal(new Vector3(12, 3, 0), emitter.LastEmitOffset);
Assert.False(emitter.SimulationEnabled);
Assert.False(emitter.PresentationVisible);
sink.SetEntityPresentationVisible(Owner, true);
sink.RefreshAttachedEmitters();
Assert.True(emitter.SimulationEnabled);
Assert.True(emitter.PresentationVisible);
Assert.Equal(spawnedAt, emitter.Particles[0].SpawnedAt);
system.Tick(0.01f);
Assert.Equal(0, system.ActiveEmitterCount);
}
[Fact]
public void LogicalTeardown_RemovesEmitterThatWasSpatiallyPaused()
{
const uint emitterId = 0x32000057u;
var (system, sink, _) = Harness(emitterId);
sink.OnHook(Owner, Vector3.Zero, Create(emitterId, logicalId: 13u));
sink.SetEntityPresentationVisible(Owner, false);
int deathNotices = 0;
system.EmitterDied += _ => deathNotices++;
sink.StopAllForEntity(Owner, fadeOut: false);
Assert.Equal(0, system.ActiveEmitterCount);
Assert.Equal(1, deathNotices);
}
private sealed class MutablePoseSource : IEntityEffectPoseSource
{
private readonly Dictionary<uint, (Matrix4x4 Root, Matrix4x4[] Parts)> _poses = new();
public void Publish(uint id, Matrix4x4 root, params Matrix4x4[] parts) =>
_poses[id] = (root, parts);
public void Remove(uint id) => _poses.Remove(id);
public bool TryGetRootPose(uint localEntityId, out Matrix4x4 rootWorld)
{
EmitterInfoId = 0x32000031u,
EmitterId = 0,
PartIndex = 99, // way past the 2-part array
Offset = new Frame
if (_poses.TryGetValue(localEntityId, out var pose))
{
Origin = new Vector3(2f, 0f, 0f),
Orientation = Quaternion.Identity,
},
});
sys.Tick(0.001f);
rootWorld = pose.Root;
return true;
}
rootWorld = default;
return false;
}
var live = System.Linq.Enumerable.Single(sys.EnumerateLive());
var pos = live.Emitter.Particles[live.Index].Position;
Assert.InRange(pos.X, 1.99f, 2.01f);
Assert.InRange(pos.Y, -0.01f, 0.01f);
Assert.InRange(pos.Z, -0.01f, 0.01f);
public bool TryGetPartPose(uint localEntityId, int partIndex, out Matrix4x4 partLocal)
{
if (_poses.TryGetValue(localEntityId, out var pose)
&& partIndex >= 0
&& partIndex < pose.Parts.Length)
{
partLocal = pose.Parts[partIndex];
return true;
}
partLocal = default;
return false;
}
}
}

View file

@ -239,12 +239,11 @@ public sealed class ParticleSystemTests
}
[Fact]
public void EmitterDescRegistry_FallsBackToDefault_ForUnknownId()
public void EmitterDescRegistry_RejectsUnknownIdWithoutInventingFallback()
{
var reg = new EmitterDescRegistry();
var desc = reg.Get(0xDEADBEEFu); // not registered
Assert.NotNull(desc);
Assert.Equal(0xFFFFFFFFu, desc.DatId); // matches default sentinel
Assert.False(reg.TryGet(0xDEADBEEFu, out _));
Assert.Throws<KeyNotFoundException>(() => reg.Get(0xDEADBEEFu));
}
[Fact]