feat(vfx): Phase C.1 — PES particle renderer + post-review fixes
Ports retail's ParticleEmitterInfo / Particle::Init / Particle::Update
(0x005170d0..0x0051d400) and PhysicsScript runtime to a C# data-layer
plus a Silk.NET billboard renderer. Sky-PES path is debug-only behind
ACDREAM_ENABLE_SKY_PES because named-retail decomp confirms GameSky
copies SkyObject.pes_id but never reads it (CreateDeletePhysicsObjects
0x005073c0, MakeObject 0x00506ee0, UseTime 0x005075b0).
Post-review fixes folded into this commit:
H1: AttachLocal (is_parent_local=1) follows live parent each frame.
ParticleSystem.UpdateEmitterAnchor + ParticleHookSink.UpdateEntityAnchor
let the owning subsystem refresh AnchorPos every tick — matches
ParticleEmitter::UpdateParticles 0x0051d2d4 which re-reads the live
parent frame when is_parent_local != 0. Drops the renderer-side
cameraOffset hack that only worked when the parent was the camera.
H3: Strip the long stale comment in GfxObjMesh.cs that contradicted the
retail-faithful (1 - translucency) opacity formula. The code was
right; the comment was a leftover from an earlier hypothesis and
would have invited a wrong "fix".
M1: SkyRenderer tracks textures whose wrap mode it set to ClampToEdge
and restores them to Repeat at end-of-pass, so non-sky renderers
that share the GL handle can't silently inherit clamped wrap state.
M2: Post-scene Z-offset (-120m) only fires when the SkyObject is
weather-flagged AND bit 0x08 is clear, matching retail
GameSky::UpdatePosition 0x00506dd0. The old code applied it to
every post-scene object — a no-op today (every Dereth post-scene
entry happens to be weather-flagged) but a future post-scene-only
sun rim would have been pushed below the camera.
M4: ParticleSystem.EmitterDied event lets ParticleHookSink prune dead
handles from the per-entity tracking dictionaries, fixing a slow
leak where naturally-expired emitters' handles stayed in the
ConcurrentBag forever during long sessions.
M5: SkyPesEntityId moves the post-scene flag bit to 0x08000000 so it
can't ever overlap the object-index range. Synthetic IDs stay in
the reserved 0xFxxxxxxx space.
New tests (ParticleSystemTests + ParticleHookSinkTests):
- UpdateEmitterAnchor_AttachLocal_ParticlePositionFollowsLiveAnchor
- UpdateEmitterAnchor_AttachLocalCleared_ParticleFrozenAtSpawnOrigin
- EmitterDied_FiresOncePerHandle_AfterAllParticlesExpire
- Birthrate_PerSec_EmitsOnePerTickWhenIntervalElapsed (retail-faithful
single-emit-per-frame behavior)
- UpdateEntityAnchor_WithAttachLocal_MovesParticleToLiveAnchor
- EmitterDied_PrunesPerEntityHandleTracking
dotnet build green, dotnet test green: 695 / 393 / 243 = 1331 passed
(up from 1325).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik
parent
1f82b7604e
commit
ec1bbb4f43
28 changed files with 2444 additions and 780 deletions
|
|
@ -4,90 +4,123 @@ using System.Numerics;
|
|||
|
||||
namespace AcDream.Core.Vfx;
|
||||
|
||||
// ─────────────────────────────────────────────────────────────────────
|
||||
// Scaffold for R4 — VFX / particle system data model.
|
||||
// Full research: docs/research/deepdives/r04-vfx-particles.md
|
||||
// Runtime GPU batching lives in AcDream.App/Rendering/Vfx (Silk.NET GL).
|
||||
// ─────────────────────────────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// 13 retail particle motion integrators. See r04 §1.
|
||||
/// Parabolic variants apply gravity with different orientation/decay rules.
|
||||
/// Retail particle motion integrators from <c>ParticleType</c> in
|
||||
/// <c>acclient.h</c>. Values are the retail dat values.
|
||||
/// </summary>
|
||||
public enum ParticleType
|
||||
{
|
||||
Still = 0, // static, fades out in place
|
||||
LocalVelocity = 1, // moves at its spawn velocity
|
||||
Parabolic = 2, // gravity arc
|
||||
ParabolicLVGV = 3, // local+global velocity parabolic
|
||||
ParabolicLVGA = 4,
|
||||
ParabolicLVLA = 5,
|
||||
ParabolicGVGA = 6,
|
||||
ParabolicGVLA = 7,
|
||||
ParabolicLALV = 8,
|
||||
Swarm = 9, // orbits spawn point with randomness
|
||||
Explode = 10, // all particles push outward
|
||||
Implode = 11, // all particles pull inward
|
||||
GlobalVelocity = 12,
|
||||
Unknown = 0,
|
||||
Still = 1,
|
||||
LocalVelocity = 2,
|
||||
ParabolicLVGA = 3,
|
||||
ParabolicLVGAGR = 4,
|
||||
Swarm = 5,
|
||||
Explode = 6,
|
||||
Implode = 7,
|
||||
ParabolicLVLA = 8,
|
||||
ParabolicLVLALR = 9,
|
||||
ParabolicGVGA = 10,
|
||||
ParabolicGVGAGR = 11,
|
||||
GlobalVelocity = 12,
|
||||
NumParticleType = 13,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Retail <c>EmitterType</c> from <c>acclient.h</c>.
|
||||
/// </summary>
|
||||
public enum ParticleEmitterKind
|
||||
{
|
||||
Unknown = 0,
|
||||
BirthratePerSec = 1,
|
||||
BirthratePerMeter = 2,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Render stage for an active particle emitter.
|
||||
/// </summary>
|
||||
public enum ParticleRenderPass
|
||||
{
|
||||
Scene = 0,
|
||||
SkyPreScene = 1,
|
||||
SkyPostScene = 2,
|
||||
}
|
||||
|
||||
[Flags]
|
||||
public enum EmitterFlags : uint
|
||||
{
|
||||
None = 0,
|
||||
Additive = 0x01, // blend mode: SrcAlpha / One (vs default SrcAlpha / InvSrcAlpha)
|
||||
Billboard = 0x02,
|
||||
None = 0,
|
||||
Additive = 0x01,
|
||||
Billboard = 0x02,
|
||||
FaceCamera = 0x04,
|
||||
AttachLocal= 0x08, // particles follow parent anchor frame
|
||||
AttachLocal = 0x08,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Per-emitter configuration from the <c>ParticleEmitterInfo</c> dat.
|
||||
/// See r04 §1 + DatReaderWriter.ParticleEmitterInfo.
|
||||
/// Per-emitter configuration from the retail <c>ParticleEmitterInfo</c>
|
||||
/// dat object.
|
||||
/// </summary>
|
||||
public sealed class EmitterDesc
|
||||
{
|
||||
public uint DatId { get; init; }
|
||||
public ParticleType Type { get; init; }
|
||||
public EmitterFlags Flags { get; init; }
|
||||
public uint TextureSurfaceId { get; init; } // 0x06xxxxxx
|
||||
public uint SoundOnSpawn { get; init; }
|
||||
public uint DatId { get; init; }
|
||||
public ParticleType Type { get; init; }
|
||||
public ParticleEmitterKind EmitterKind { get; init; } = ParticleEmitterKind.BirthratePerSec;
|
||||
public EmitterFlags Flags { get; init; }
|
||||
public uint TextureSurfaceId { get; init; }
|
||||
public uint GfxObjId { get; init; }
|
||||
public uint HwGfxObjId { get; init; }
|
||||
public uint SoundOnSpawn { get; init; }
|
||||
|
||||
// Emission behavior
|
||||
public float EmitRate { get; init; } // particles / sec
|
||||
public int MaxParticles { get; init; }
|
||||
public float LifetimeMin { get; init; }
|
||||
public float LifetimeMax { get; init; }
|
||||
public float StartDelay { get; init; }
|
||||
public float TotalDuration { get; init; } // 0 = infinite
|
||||
// Emission behavior.
|
||||
public float Birthrate { get; init; }
|
||||
public float EmitRate { get; init; }
|
||||
public int MaxParticles { get; init; }
|
||||
public int InitialParticles { get; init; }
|
||||
public int TotalParticles { get; init; }
|
||||
public float LifetimeMin { get; init; }
|
||||
public float LifetimeMax { get; init; }
|
||||
public float Lifespan { get; init; }
|
||||
public float LifespanRand { get; init; }
|
||||
public float StartDelay { get; init; }
|
||||
public float TotalDuration { get; init; }
|
||||
|
||||
// Spawn geometry (disk annulus perpendicular to OffsetDir)
|
||||
public Vector3 OffsetDir { get; init; } = new(0, 0, 1);
|
||||
public float MinOffset { get; init; }
|
||||
public float MaxOffset { get; init; }
|
||||
public float SpawnDiskRadius { get; init; }
|
||||
// Spawn geometry.
|
||||
public Vector3 OffsetDir { get; init; } = new(0, 0, 1);
|
||||
public float MinOffset { get; init; }
|
||||
public float MaxOffset { get; init; }
|
||||
public float SpawnDiskRadius { get; init; }
|
||||
|
||||
// Initial kinematics
|
||||
public Vector3 InitialVelocity { get; init; }
|
||||
public float VelocityJitter { get; init; }
|
||||
public Vector3 Gravity { get; init; } = new(0, 0, -9.8f);
|
||||
// Kinematics. A/B/C are the retail vector coefficients.
|
||||
public Vector3 InitialVelocity { get; init; }
|
||||
public float VelocityJitter { get; init; }
|
||||
public Vector3 Gravity { get; init; } = new(0, 0, -9.8f);
|
||||
public Vector3 A { get; init; }
|
||||
public float MinA { get; init; } = 1f;
|
||||
public float MaxA { get; init; } = 1f;
|
||||
public Vector3 B { get; init; }
|
||||
public float MinB { get; init; } = 1f;
|
||||
public float MaxB { get; init; } = 1f;
|
||||
public Vector3 C { get; init; }
|
||||
public float MinC { get; init; } = 1f;
|
||||
public float MaxC { get; init; } = 1f;
|
||||
|
||||
// Appearance over lifetime (retail: start + end, linearly interpolated)
|
||||
public uint StartColorArgb { get; init; } = 0xFFFFFFFF;
|
||||
public uint EndColorArgb { get; init; } = 0xFFFFFFFF;
|
||||
public float StartAlpha { get; init; } = 1f;
|
||||
public float EndAlpha { get; init; } = 0f;
|
||||
public float StartSize { get; init; } = 0.5f;
|
||||
public float EndSize { get; init; } = 0.5f;
|
||||
public float StartRotation { get; init; }
|
||||
public float EndRotation { get; init; }
|
||||
// Appearance over lifetime.
|
||||
public uint StartColorArgb { get; init; } = 0xFFFFFFFF;
|
||||
public uint EndColorArgb { get; init; } = 0xFFFFFFFF;
|
||||
public float StartAlpha { get; init; } = 1f;
|
||||
public float EndAlpha { get; init; } = 0f;
|
||||
public float StartSize { get; init; } = 0.5f;
|
||||
public float EndSize { get; init; } = 0.5f;
|
||||
public float ScaleRand { get; init; }
|
||||
public float TransRand { get; init; }
|
||||
public float StartRotation { get; init; }
|
||||
public float EndRotation { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// A PhysicsScript (0x3Axxxxxx range in retail) is a list of hooks to
|
||||
/// fire at specific start-times. Each hook creates an emitter or plays
|
||||
/// a sound. Chaining hooks at different times gives "animation".
|
||||
/// See r04 §6.
|
||||
/// </summary>
|
||||
public sealed class PhysicsScript
|
||||
{
|
||||
|
|
@ -98,34 +131,43 @@ public sealed class PhysicsScript
|
|||
public sealed record PhysicsScriptHook(
|
||||
float StartTime,
|
||||
PhysicsScriptHookType Type,
|
||||
uint RefDataId, // EmitterInfo / Sound / PartTransform
|
||||
int PartIndex, // attach to this part
|
||||
uint RefDataId,
|
||||
int PartIndex,
|
||||
Vector3 Offset,
|
||||
bool IsParentLocal);
|
||||
|
||||
public enum PhysicsScriptHookType
|
||||
{
|
||||
CreateParticle = 18, // matches retail animation-hook type
|
||||
DestroyParticle= 19,
|
||||
PlaySound = 1,
|
||||
AnimationDone = 2,
|
||||
CreateParticle = 18,
|
||||
DestroyParticle = 19,
|
||||
PlaySound = 1,
|
||||
AnimationDone = 2,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Individual runtime particle. Owned by the <c>ParticleSystem</c>;
|
||||
/// advanced per-frame.
|
||||
/// Individual runtime particle. Owned by the <c>ParticleSystem</c>.
|
||||
/// </summary>
|
||||
public struct Particle
|
||||
{
|
||||
public Vector3 Position;
|
||||
public Vector3 Velocity;
|
||||
public float SpawnedAt;
|
||||
public float Lifetime; // seconds
|
||||
public float Age;
|
||||
public uint ColorArgb; // current
|
||||
public float Size;
|
||||
public float Rotation;
|
||||
public bool Alive;
|
||||
public Vector3 EmissionOrigin;
|
||||
public Quaternion SpawnRotation;
|
||||
public Vector3 Position;
|
||||
public Vector3 Velocity;
|
||||
public Vector3 Offset;
|
||||
public Vector3 A;
|
||||
public Vector3 B;
|
||||
public Vector3 C;
|
||||
public float SpawnedAt;
|
||||
public float Lifetime;
|
||||
public float Age;
|
||||
public float StartSize;
|
||||
public float EndSize;
|
||||
public float StartAlpha;
|
||||
public float EndAlpha;
|
||||
public uint ColorArgb;
|
||||
public float Size;
|
||||
public float Rotation;
|
||||
public bool Alive;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
|
|
@ -134,16 +176,20 @@ public struct Particle
|
|||
/// </summary>
|
||||
public sealed class ParticleEmitter
|
||||
{
|
||||
public EmitterDesc Desc { get; init; } = null!;
|
||||
public Vector3 AnchorPos { get; set; }
|
||||
public Quaternion AnchorRot { get; set; } = Quaternion.Identity;
|
||||
public uint AttachedObjectId { get; set; } // 0 = world-space only
|
||||
public int AttachedPartIndex { get; set; } = -1;
|
||||
public Particle[] Particles { get; init; } = null!;
|
||||
public int ActiveCount;
|
||||
public float EmittedAccumulator; // fractional particles pending
|
||||
public float StartedAt; // game-time seconds
|
||||
public bool Finished;
|
||||
public EmitterDesc Desc { get; init; } = null!;
|
||||
public Vector3 AnchorPos { get; set; }
|
||||
public Quaternion AnchorRot { get; set; } = Quaternion.Identity;
|
||||
public uint AttachedObjectId { get; set; }
|
||||
public int AttachedPartIndex { get; set; } = -1;
|
||||
public Particle[] Particles { get; init; } = null!;
|
||||
public ParticleRenderPass RenderPass { get; init; }
|
||||
public int ActiveCount;
|
||||
public float EmittedAccumulator;
|
||||
public float StartedAt;
|
||||
public float LastEmitTime;
|
||||
public Vector3 LastEmitOffset;
|
||||
public int TotalEmitted;
|
||||
public bool Finished;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
|
|
@ -151,20 +197,25 @@ public sealed class ParticleEmitter
|
|||
/// </summary>
|
||||
public interface IParticleSystem
|
||||
{
|
||||
/// <summary>Spawn an emitter attached to a world position (or entity).</summary>
|
||||
int SpawnEmitter(EmitterDesc desc, Vector3 anchor, Quaternion? rot = null,
|
||||
uint attachedObjectId = 0, int attachedPartIndex = -1);
|
||||
/// <summary>Spawn an emitter attached to a world position or entity.</summary>
|
||||
int SpawnEmitter(
|
||||
EmitterDesc desc,
|
||||
Vector3 anchor,
|
||||
Quaternion? rot = null,
|
||||
uint attachedObjectId = 0,
|
||||
int attachedPartIndex = -1,
|
||||
ParticleRenderPass renderPass = ParticleRenderPass.Scene);
|
||||
|
||||
/// <summary>Fire a full PhysicsScript at a target (the retail PlayScript dispatch).</summary>
|
||||
/// <summary>Fire a full PhysicsScript at a target.</summary>
|
||||
void PlayScript(uint scriptId, uint targetObjectId, float modifier = 1f);
|
||||
|
||||
/// <summary>Advance all active emitters by dt seconds.</summary>
|
||||
void Tick(float dt);
|
||||
|
||||
/// <summary>Stop an emitter early (e.g. cast interrupted).</summary>
|
||||
/// <summary>Stop an emitter early.</summary>
|
||||
void StopEmitter(int handle, bool fadeOut);
|
||||
|
||||
/// <summary>Current active particle count (for HUD stats).</summary>
|
||||
/// <summary>Current active particle count.</summary>
|
||||
int ActiveParticleCount { get; }
|
||||
int ActiveEmitterCount { get; }
|
||||
int ActiveEmitterCount { get; }
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue