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
143
src/AcDream.Core/Audio/AudioModel.cs
Normal file
143
src/AcDream.Core/Audio/AudioModel.cs
Normal file
|
|
@ -0,0 +1,143 @@
|
|||
using System;
|
||||
using System.Collections.Generic;
|
||||
|
||||
namespace AcDream.Core.Audio;
|
||||
|
||||
// ─────────────────────────────────────────────────────────────────────
|
||||
// Scaffold for R5 — audio data model + engine interface.
|
||||
// Full research: docs/research/deepdives/r05-audio-sound.md
|
||||
// Runtime backend (Silk.NET.OpenAL) lives in AcDream.App.
|
||||
// ─────────────────────────────────────────────────────────────────────
|
||||
|
||||
/// <summary>
|
||||
/// Enumerated retail sound IDs. See r05 §5 for the full 204-entry list.
|
||||
/// Only the commonly-fired ones are given names here.
|
||||
/// </summary>
|
||||
public enum SoundId : uint
|
||||
{
|
||||
None = 0,
|
||||
FootstepDefault = 0x02,
|
||||
FootstepGrass = 0x03,
|
||||
FootstepWater = 0x04,
|
||||
FootstepDirt = 0x05,
|
||||
FootstepStone = 0x06,
|
||||
FootstepWood = 0x07,
|
||||
SwingSword = 0x10,
|
||||
SwingAxe = 0x11,
|
||||
HitMetalOnMetal = 0x20,
|
||||
HitMetalOnLeather = 0x21,
|
||||
HitFlesh = 0x22,
|
||||
ArrowWhoosh = 0x30,
|
||||
ArrowThud = 0x31,
|
||||
SpellCastWar = 0x40,
|
||||
SpellCastLife = 0x41,
|
||||
SpellCastItem = 0x42,
|
||||
SpellCastCreature = 0x43,
|
||||
PortalWhoosh = 0x50,
|
||||
LifestoneTie = 0x51,
|
||||
Death = 0x60,
|
||||
PotionDrink = 0x70,
|
||||
BuffApplied = 0x80,
|
||||
// More constants populated during R5 audio port.
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Per-SoundId entry from the SoundTable dat (0x20000000..0x2000FFFF).
|
||||
/// One Sound can have multiple entries with probabilities — that's
|
||||
/// retail's variation mechanism (e.g. 3 different footstep clips).
|
||||
/// </summary>
|
||||
public sealed class SoundEntry
|
||||
{
|
||||
public uint WaveId { get; init; } // → Wave dat (0x0A000000..0x0A00FFFF)
|
||||
public int Priority { get; init; } // eviction ordering (0..7)
|
||||
public float Probability{ get; init; } // for entries with multiple alternatives
|
||||
public float VolumeBase { get; init; } // 0..1 multiplier applied before falloff
|
||||
public float PitchMin { get; init; }
|
||||
public float PitchMax { get; init; }
|
||||
public bool Loop { get; init; }
|
||||
public bool Is3D { get; init; } // 3D positional vs UI/music flat
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Raw decoded PCM data from a Wave dat. Set by <c>WaveDecoder</c> at
|
||||
/// load time. Retail supports both PCM and MP3 source; we decode MP3
|
||||
/// to PCM once at load (same as retail does for long clips).
|
||||
/// </summary>
|
||||
public sealed class WaveData
|
||||
{
|
||||
public int ChannelCount { get; init; }
|
||||
public int SampleRate { get; init; }
|
||||
public int BitsPerSample{ get; init; } // 8 or 16
|
||||
public byte[] PcmBytes { get; init; } = Array.Empty<byte>();
|
||||
public TimeSpan Duration { get; init; }
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Falloff math (r05 §2). Retail is CPU-side inverse-square, NOT
|
||||
/// DirectSound3DBuffer. No doppler, no cone, no HRTF.
|
||||
/// </summary>
|
||||
public static class AudioFalloff
|
||||
{
|
||||
/// <summary>
|
||||
/// Attenuation factor based on distance. Retail uses pure inverse-square
|
||||
/// above a minimum-distance threshold.
|
||||
/// </summary>
|
||||
public static float AttenuationAt(float distanceMeters, float minDistance = 1.0f)
|
||||
{
|
||||
if (distanceMeters < minDistance) return 1.0f;
|
||||
float att = (minDistance * minDistance) / (distanceMeters * distanceMeters);
|
||||
return Math.Clamp(att, 0f, 1f);
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Stereo pan from listener-relative X coord. ±1.0 fully panned.
|
||||
/// </summary>
|
||||
public static float PanFromRelative(float relativeX, float panRange = 20f)
|
||||
{
|
||||
if (panRange <= 0) return 0f;
|
||||
return Math.Clamp(relativeX / panRange, -1f, 1f);
|
||||
}
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Interface the platform audio engine (AcDream.App layer) implements.
|
||||
/// Core defines the contract; App implements via Silk.NET.OpenAL.
|
||||
/// </summary>
|
||||
public interface IAudioEngine : IDisposable
|
||||
{
|
||||
/// <summary>Set master volume [0..1].</summary>
|
||||
float MasterVolume { get; set; }
|
||||
float SfxVolume { get; set; }
|
||||
float MusicVolume { get; set; }
|
||||
float AmbientVolume{ get; set; }
|
||||
|
||||
/// <summary>Update listener pose (called per frame from player position).</summary>
|
||||
void SetListener(float posX, float posY, float posZ,
|
||||
float forwardX, float forwardY, float forwardZ,
|
||||
float upX, float upY, float upZ);
|
||||
|
||||
/// <summary>Play a 2D UI sound (no falloff).</summary>
|
||||
void PlayUi(SoundId id);
|
||||
|
||||
/// <summary>Play a 3D sound at a world position.</summary>
|
||||
void Play3D(SoundId id, float x, float y, float z);
|
||||
|
||||
/// <summary>Start a looped ambient sound (landblock-attached).</summary>
|
||||
int StartAmbient(SoundId id, float x, float y, float z);
|
||||
void StopAmbient(int handle);
|
||||
|
||||
/// <summary>Start music (fades out previous if any).</summary>
|
||||
void PlayMusic(string resourceName, bool loop);
|
||||
void StopMusic();
|
||||
}
|
||||
|
||||
/// <summary>
|
||||
/// Cache of decoded waves + SoundTable lookups. Owned by the App-layer
|
||||
/// AudioEngine; Core exposes the interface.
|
||||
/// </summary>
|
||||
public interface ISoundCache
|
||||
{
|
||||
WaveData GetWave(uint waveId);
|
||||
IReadOnlyList<SoundEntry> GetSoundEntries(SoundId id);
|
||||
IReadOnlyList<SoundEntry> GetSoundEntries(uint soundTableId, SoundId id);
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue