docs+feat: 13 retail-AC deep-dives (R1-R13) + C# port scaffolds + roadmap E-H
78,000 words of grounded, citation-backed research across 13 major AC
subsystems, produced by 13 parallel Opus-4.7 high-effort agents. Plus
compact C# port scaffolds for the top-5 systems and a phase-E-through-H
roadmap update sequencing the work.
Research (docs/research/deepdives/):
- 00-master-synthesis.md (navigation hub + dependency graph)
- r01-spell-system.md 5.4K words (fizzle sigmoid, 8 tabs, 0x004A wire)
- r02-combat-system.md 5.9K words (damage formula, crit, body table)
- r03-motion-animation.md 8.2K words (450+ commands, 27 hook types)
- r04-vfx-particles.md 5.8K words (13 ParticleType, PhysicsScript)
- r05-audio-sound.md 5.6K words (DirectSound 8, CPU falloff)
- r06-items-inventory.md 7.4K words (ItemType flags, EquipMask 31 slots)
- r07-character-creation.md 6.3K words (CharGen dat, 13 heritages)
- r08-network-protocol-atlas 9.7K words (63+149+94 opcodes mapped)
- r09-dungeon-portal-space.md 6.3K words (EnvCell, PlayerTeleport flow)
- r10-quest-dialogs.md 7.1K words (emote-script VM, 122 actions)
- r11-allegiance.md 5.4K words (tree + XP passup + 5 channels)
- r12-weather-daynight.md 4.5K words (deterministic client-side)
- r13-dynamic-lighting.md 4.9K words (8-light cap, hard Range cutoff)
Every claim cites a FUN_ address, ACE file path, DatReaderWriter type,
or holtburger/ACViewer reference. The master synthesis ties them into a
dependency graph and phase sequence.
Key architectural finding: of 94 GameEvents in the 0xF7B0 envelope,
ZERO are handled today — that's the largest network-protocol gap and
blocks F.2 (items) + F.5 (panels) + H.1 (chat).
C# scaffolds (src/AcDream.Core/):
- Items/ItemInstance.cs — ItemType/EquipMask enums, ItemInstance,
Container, PropertyBundle, BurdenMath
- Spells/SpellModel.cs — SpellDatEntry, SpellComponentEntry,
SpellCastStateMachine, ActiveBuff,
SpellMath (fizzle sigmoid + mana cost)
- Combat/CombatModel.cs — CombatMode/AttackType/DamageType/BodyPart,
DamageEvent record, CombatMath (hit-chance
sigmoids, power/accuracy mods, damage formula),
ArmorBuild
- Audio/AudioModel.cs — SoundId enum, SoundEntry, WaveData,
IAudioEngine / ISoundCache contracts,
AudioFalloff (inverse-square)
- Vfx/VfxModel.cs — 13 ParticleType integrators, EmitterDesc,
PhysicsScript + hooks, Particle struct,
ParticleEmitter, IParticleSystem contract
All Core-layer data models; platform-backed engines live in AcDream.App.
Compiles clean; 470 tests still pass.
Roadmap (docs/plans/2026-04-11-roadmap.md):
- Phase E — "Feel alive": motion-hooks + audio + VFX
- Phase F — Fight + cast + gear: GameEvent dispatch, inventory,
combat, spell, core panels
- Phase G — World systems: sky/weather, dynamic lighting, dungeons
- Phase H — Social + progression: chat, allegiance, quests, char creation
- Phase J — Long-tail (renumbered from old Phase E)
Quick-lookup table updated with 10+ new rows mapping observations to
new phase letters.
This commit is contained in:
Erik
parent
7230c1590f
commit
3f913f1999
20 changed files with 15312 additions and 17 deletions
170
src/AcDream.Core/Vfx/VfxModel.cs
Normal file
170
src/AcDream.Core/Vfx/VfxModel.cs
Normal file
|
|
@ -0,0 +1,170 @@
|
|||
using System;
|
||||
using System.Collections.Generic;
|
||||
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.
|
||||
/// </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,
|
||||
}
|
||||
|
||||
[Flags]
|
||||
public enum EmitterFlags : uint
|
||||
{
|
||||
None = 0,
|
||||
Additive = 0x01, // blend mode: SrcAlpha / One (vs default SrcAlpha / InvSrcAlpha)
|
||||
Billboard = 0x02,
|
||||
FaceCamera = 0x04,
|
||||
AttachLocal= 0x08, // particles follow parent anchor frame
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Per-emitter configuration from the <c>ParticleEmitterInfo</c> dat.
|
||||
/// See r04 §1 + DatReaderWriter.ParticleEmitterInfo.
|
||||
/// </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; }
|
||||
|
||||
// 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
|
||||
|
||||
// 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; }
|
||||
|
||||
// Initial kinematics
|
||||
public Vector3 InitialVelocity { get; init; }
|
||||
public float VelocityJitter { get; init; }
|
||||
public Vector3 Gravity { get; init; } = new(0, 0, -9.8f);
|
||||
|
||||
// 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; }
|
||||
}
|
||||
|
||||
/// <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
|
||||
{
|
||||
public uint ScriptId { get; init; }
|
||||
public IReadOnlyList<PhysicsScriptHook> Hooks { get; init; } = Array.Empty<PhysicsScriptHook>();
|
||||
}
|
||||
|
||||
public sealed record PhysicsScriptHook(
|
||||
float StartTime,
|
||||
PhysicsScriptHookType Type,
|
||||
uint RefDataId, // EmitterInfo / Sound / PartTransform
|
||||
int PartIndex, // attach to this part
|
||||
Vector3 Offset,
|
||||
bool IsParentLocal);
|
||||
|
||||
public enum PhysicsScriptHookType
|
||||
{
|
||||
CreateParticle = 18, // matches retail animation-hook type
|
||||
DestroyParticle= 19,
|
||||
PlaySound = 1,
|
||||
AnimationDone = 2,
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Individual runtime particle. Owned by the <c>ParticleSystem</c>;
|
||||
/// advanced per-frame.
|
||||
/// </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;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// One active emitter instance. The <c>ParticleSystem</c> holds a pool
|
||||
/// of these; each one maintains its own particle array.
|
||||
/// </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;
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Top-level particle orchestrator. App-layer renderer batches these.
|
||||
/// </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>Fire a full PhysicsScript at a target (the retail PlayScript dispatch).</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>
|
||||
void StopEmitter(int handle, bool fadeOut);
|
||||
|
||||
/// <summary>Current active particle count (for HUD stats).</summary>
|
||||
int ActiveParticleCount { get; }
|
||||
int ActiveEmitterCount { get; }
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue