erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(player): #5 PlayerDescription parser — Stam/Mana via attribute block

Browse source 
Visual-verified — Vitals window now shows three bars (HP/Stam/Mana)
with live values. Closes ISSUES.md #5; ~95% reading on Stam/Mana
traced to active buff multipliers, filed as #6.

Why the rewrite

The first attempt (commit d42bf57) routed PlayerDescription (0x0013)
through AppraiseInfoParser, trusting a misleading xmldoc claim.
Live diagnostics proved the format is wrong — ACE source
(GameEventPlayerDescription.WriteEventBody) hand-writes a body
distinct from IdentifyObjectResponse's AppraiseInfo: property
hashtables gated on DescriptionPropertyFlag, vector-flag-gated
attribute / skill / spell blocks, then a long options + inventory
trailer. Vitals only arrive via the attribute block at login.
Holtburger's events.rs:220-625 has the canonical client-side
unpacker; this commit ports the early-section walker through spells.

What landed

  PlayerDescriptionParser.cs (new — 350 LOC):
    Walks propertyFlags + weenieType, then property hashtables
    (Int32/Int64/Bool/Double/String/Did/Iid) + Position table —
    each gated on a property flag bit, header is `u16 count, u16
    buckets`. Then vectorFlags + has_health + the attribute block
    (primary attrs 1..6 = 12 B each, vitals 7..9 = 16 B with
    `current`), then optional Skill + Spell tables. Stops cleanly
    before the options/shortcuts/hotbars/inventory trailer (filed
    as #7 — heuristic alignment search needed for gameplay_options).

  PrivateUpdateVital.cs (new — 95 LOC):
    Wire parsers for the GameMessage opcodes 0x02E7 (full snapshot)
    and 0x02E9 (current-only delta), per holtburger UpdateVital +
    UpdateVitalCurrent. WorldSession dispatches each to a session-
    level event the GameWindow forwards into LocalPlayerState.

  LocalPlayerState (full redesign):
    VitalKind (Health/Stamina/Mana) + AttributeKind (six primary).
    VitalSnapshot stores ranks/start/xp/current; AttributeSnapshot
    stores ranks/start/xp with `Current = ranks+start` per
    holtburger. GetMaxApprox computes the retail formula
        vital.(ranks+start) + attribute_contribution
    where the contribution is hardcoded from retail's
    SecondaryAttributeTable: Endurance/2 for Health, Endurance for
    Stamina, Self for Mana. Enchantment buffs not yet folded in
    (filed as #6). VitalIdToKind now accepts both ID systems
    (1..6 wire, 7..9 PD attribute block); AttributeIdToKind covers
    primary attrs 1..6.

  GameEventWiring:
    PlayerDescription handler. Walks parsed.Attributes, routes
    primary attrs (id 1..6) to OnAttributeUpdate and vitals
    (id 7..9) to OnVitalUpdate. Player's full learned spellbook
    also lands here. ACDREAM_DUMP_VITALS=1 traces every PD attribute
    + every PrivateUpdateVital(Current) opcode for diagnostics.

  WorldSession:
    Dispatch chain re-ordered — the diagnostic else-if for
    ACDREAM_DUMP_OPCODES=1 was originally placed before
    GameEventEnvelope.Opcode, which silently intercepted 0xF7B0 and
    broke UpdateHealth dispatch when the env var was set. Moved to
    the very end of the chain so it only fires for genuinely
    unhandled opcodes. (Diagnostic-only regression; production
    launches without the env var were unaffected.)

Test deltas

  Added:
    - PlayerDescriptionParserTests (6 — empty header, full attribute
      block, partial flags, post-property-table walk, spell table)
    - PrivateUpdateVitalTests (7 — fixture round-trip, vital ID
      coverage, opcode rejection, truncation)
    - LocalPlayerStateTests rewritten (20 — VitalIdToKind +
      AttributeIdToKind theories, Endurance/Self formula coverage,
      delta semantics, change events)
    - GameEventWiringTests for PlayerDescription dispatch (2 —
      end-to-end populate + spellbook feed)
  Updated:
    - VitalsVMTests rephrased onto the new OnVitalUpdate API.
  Total: 765 → 817 tests passing.

Diagnostics

  ACDREAM_DUMP_VITALS=1 — log every PD attribute extracted,
    every 0x02E7/0x02E9 dispatch.
  ACDREAM_DUMP_OPCODES=1 — log first occurrence of any unhandled
    GameMessage opcode (now correctly placed at end of chain).

Visual verify

  $env:ACDREAM_DEVTOOLS = "1"
  dotnet run --project src\AcDream.App\AcDream.App.csproj -c Debug

  Vitals window shows three bars; HP at 100%, Stam/Mana at ~95%
  (the gap is buff enchantments — filed as #6 with the holtburger
  multiplier+additive aggregator pattern as the reference for the
  fix).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik 2026-04-25 16:42:24 +02:00
parent d42bf5735d
commit 7da2a027d4
14 changed files with 1660 additions and 272 deletions
Download patch file Download diff file Expand all files Collapse all files

7
src/AcDream.App/Rendering/GameWindow.cs
View file

@ -1184,6 +1184,13 @@ public sealed class GameWindow : IDisposable
senderGuid: speech.SenderGuid,
isRanged: speech.IsRanged);
// Issue #5: feed PrivateUpdateVital + PrivateUpdateVitalCurrent
// into LocalPlayer so VitalsPanel can draw Stam / Mana bars.
_liveSession.VitalUpdated += v =>
LocalPlayer.OnVitalUpdate(v.VitalId, v.Ranks, v.Start, v.Xp, v.Current);
_liveSession.VitalCurrentUpdated += v =>
LocalPlayer.OnVitalCurrent(v.VitalId, v.Current);
Chat.OnSystemMessage($"connecting to {host}:{portStr} as {user}", chatType: 1);
_liveSession.Connect(user, pass);
Chat.OnSystemMessage("connected — character list received", chatType: 1);

78
src/AcDream.Core.Net/GameEventWiring.cs
View file

@ -160,37 +160,75 @@ public static class GameEventWiring
// Merge parsed properties into the item if we know about it.
if (items.GetItem(p.Value.Guid) is not null)
items.UpdateProperties(p.Value.Guid, p.Value.Properties);
// Spell book from appraise: for ITEMS (caster / scrolls) this
// lists cast-on-use effects; for players (PlayerDescription)
// it's the whole learned spellbook. Both mutate the spellbook
// by adding any not-yet-known ids.
// Spellbook from appraise: for caster items / scrolls this is
// the cast-on-use list. The local player's full learned
// spellbook arrives via PlayerDescription (0x0013), which uses
// a different wire format (see WorldSession + LocalPlayerState
// — feeds vitals from PrivateUpdateVital instead).
foreach (uint sid in p.Value.SpellBook)
spellbook.OnSpellLearned(sid);
});
// ── Player ────────────────────────────────────────────────
// PlayerDescription (0x0013) carries the same AppraiseInfo body as
// IdentifyObjectResponse (0x00C9), but it's targeted at the local
// player. Issue #5: feed CreatureProfile.{Stamina, Mana, *Max}
// into LocalPlayerState so the Vitals HUD can render those bars.
// Spellbook + properties get the same downstream treatment as
// IdentifyObjectResponse so the player's full learned spellbook
// also lands here.
// PlayerDescription (0x0013) — full local-player snapshot at
// login. Distinct wire format from IdentifyObjectResponse
// (0x00C9): hand-written body with property hashtables,
// vector-flag-gated blocks, attribute block (where vitals 7/8/9
// carry their absolute current values), skills, spells, and a
// long trailer of options + inventory. See
// PlayerDescriptionParser for the full layout reference (mirrors
// holtburger events.rs:220-625).
//
// Two outputs from each parsed PlayerDescription:
// 1. LocalPlayerState absorbs vital ids 7/8/9 (Health/Stam/Mana).
// This is the ONLY way these arrive at login; PrivateUpdateVital
// delta opcodes only fire on rank-up / Enlightenment / admin
// changes — not initial sync.
// 2. Spellbook absorbs the learned spell list — for the local
// player this is the authoritative source (the per-item
// SpellBook flag in IdentifyObjectResponse is for caster
// items / scrolls only).
bool dumpPd = Environment.GetEnvironmentVariable("ACDREAM_DUMP_VITALS") == "1";
dispatcher.Register(GameEventType.PlayerDescription, e =>
{
var p = AppraiseInfoParser.TryParse(e.Payload.Span);
if (p is null || !p.Value.Success) return;
var p = PlayerDescriptionParser.TryParse(e.Payload.Span);
if (dumpPd)
Console.WriteLine($"vitals: PlayerDescription body.len={e.Payload.Length} parsed={(p is null ? "NULL" : $"vec={p.Value.VectorFlags} attrs={p.Value.Attributes.Count} spells={p.Value.Spells.Count}")}");
if (p is null) return;
if (localPlayer is not null && p.Value.CreatureProfile is { } profile)
if (localPlayer is not null)
{
localPlayer.OnPlayerDescription(
currentStamina: profile.Stamina,
maxStamina: profile.StaminaMax,
currentMana: profile.Mana,
maxMana: profile.ManaMax);
foreach (var attr in p.Value.Attributes)
{
if (attr.Current is uint cur)
{
// Vital entry (id 7/8/9) — has absolute current.
if (dumpPd)
Console.WriteLine($"vitals: PD-vital id={attr.AtType} ranks={attr.Ranks} start={attr.Start} cur={cur}");
localPlayer.OnVitalUpdate(
vitalId: attr.AtType,
ranks: attr.Ranks,
start: attr.Start,
xp: attr.Xp,
current: cur);
}
else
{
// Primary attribute (id 1..6) — Endurance+Self feed
// the vital max formula (Endurance/2 for Health,
// Endurance for Stamina, Self for Mana).
if (dumpPd)
Console.WriteLine($"vitals: PD-attr id={attr.AtType} ranks={attr.Ranks} start={attr.Start}");
localPlayer.OnAttributeUpdate(
atType: attr.AtType,
ranks: attr.Ranks,
start: attr.Start,
xp: attr.Xp);
}
}
}
foreach (uint sid in p.Value.SpellBook)
foreach (uint sid in p.Value.Spells.Keys)
spellbook.OnSpellLearned(sid);
});
}

16
src/AcDream.Core.Net/Messages/AppraiseInfoParser.cs
View file

@ -7,12 +7,22 @@ namespace AcDream.Core.Net.Messages;
/// <summary>
/// Parser for the full <c>AppraiseInfo</c> blob carried by
/// <c>GameEventType.IdentifyObjectResponse</c> (0x00C9) and also as
/// part of <c>GameEventType.PlayerDescription</c> (0x0013). Format
/// source: ACE <c>AppraiseInfo.Write</c> (Structure/AppraiseInfo.cs:735)
/// <c>GameEventType.IdentifyObjectResponse</c> (0x00C9). Format source:
/// ACE <c>AppraiseInfo.Write</c> (Structure/AppraiseInfo.cs:735)
/// + <c>PackableHashTable.WriteHeader</c>.
///
/// <para>
/// <b>Not</b> usable for <c>PlayerDescription (0x0013)</c> — that opcode
/// has its own wire format (DescriptionPropertyFlag-driven property
/// hashtables, DescriptionVectorFlag block, hand-written attribute /
/// skill / spell layout). See ACE
/// <c>GameEventPlayerDescription.WriteEventBody</c>. Player vitals come
/// in instead via <c>PrivateUpdateVital (0x02E7)</c> +
/// <c>PrivateUpdateVitalCurrent (0x02E9)</c>, which are top-level
/// GameMessage opcodes (not 0xF7B0 sub-opcodes).
/// </para>
///
/// <para>
/// Wire shape:
/// <code>
/// u32 flags // IdentifyResponseFlags bitfield

464
src/AcDream.Core.Net/Messages/PlayerDescriptionParser.cs Normal file
View file

@ -0,0 +1,464 @@
using System;
using System.Buffers.Binary;
using System.Collections.Generic;
using System.Text;
using AcDream.Core.Items;
namespace AcDream.Core.Net.Messages;
/// <summary>
/// Parser for <c>GameEventType.PlayerDescription (0x0013)</c> — the
/// load-bearing post-EnterWorld message that hands the client the local
/// player's full state (properties, attributes, vitals, skills, spells,
/// enchantments, options, hotbars, inventory, equipped objects).
///
/// <para>
/// <b>Wire format reference:</b> holtburger
/// <c>crates/holtburger-protocol/src/messages/player/events.rs</c>
/// (<c>PlayerDescriptionEventData::unpack</c>, lines 220-625). ACE
/// producer: <c>GameEventPlayerDescription.WriteEventBody</c>.
/// </para>
///
/// <para>
/// <b>NOT</b> the same wire format as
/// <c>IdentifyObjectResponse (0x00C9)</c> — that uses
/// <c>AppraiseInfo.Write</c>'s flag-driven format
/// (<see cref="AppraiseInfoParser"/>). PlayerDescription has its own
/// hand-written body with property hashtables (<c>DescriptionPropertyFlag</c>),
/// vector-flag-gated blocks (<c>DescriptionVectorFlag</c>), and a long
/// trailer of options + hotbars + inventory. Don't conflate the two.
/// </para>
///
/// <para>
/// <b>Body layout</b> (all little-endian):
/// </para>
/// <code>
/// // Header (8 B):
/// u32 propertyFlags // DescriptionPropertyFlag — gates the property hashtables
/// u32 wee_type // ACE WeenieType enum
///
/// // Property hashtables — each gated on a propertyFlags bit. Header is
/// // u16 count, u16 buckets then `count` × (u32 key, value).
/// if (propertyFlags &amp; PROPERTY_INT32): table&lt;i32&gt;
/// if (propertyFlags &amp; PROPERTY_INT64): table&lt;i64&gt;
/// if (propertyFlags &amp; PROPERTY_BOOL): table&lt;u32&gt; (treated as bool)
/// if (propertyFlags &amp; PROPERTY_DOUBLE): table&lt;f64&gt;
/// if (propertyFlags &amp; PROPERTY_STRING): table&lt;string16L&gt;
/// if (propertyFlags &amp; PROPERTY_DID): table&lt;u32&gt;
/// if (propertyFlags &amp; PROPERTY_IID): table&lt;u32&gt;
/// if (propertyFlags &amp; POSITION): table&lt;WorldPosition (32 B)&gt;
///
/// // Vector flags + has_health (8 B):
/// u32 vectorFlags // DescriptionVectorFlag — Attribute=0x01, Skill=0x02, Spell=0x100, Enchantment=0x200
/// u32 has_health // 0 or 1
///
/// // Attribute block (gated on Attribute vector flag):
/// u32 attributeFlags // AttributeCache bitmask — bit (i-1) ⇒ entry i present
/// for i = 1..=6 (primary attrs Strength..Self), if bit set:
/// u32 ranks, u32 start, u32 xp // 12 B per entry
/// for i = 7..=9 (vitals Health/Stamina/Mana), if bit set:
/// u32 ranks, u32 start, u32 xp, u32 current // 16 B per entry
///
/// // Skills (gated on Skill vector flag): packed table&lt;CreatureSkill (32 B)&gt;
/// // Spells (gated on Spell vector flag): packed table&lt;u32 spellId, f32 power&gt;
/// // Enchantments (gated on Enchantment vector flag): EnchantmentMask + per-section count + N×Enchantment(60 or 64 B)
/// // ... then options / shortcuts / hotbars / desired_comps / spellbook_filters / options2 / gameplay_options / inventory / equipped
/// </code>
///
/// <para>
/// <b>Scope of this port:</b> walks all sections through enchantments;
/// the trailing options / inventory / equipped sections are partial
/// because they involve variable-length opaque blobs that holtburger
/// uses heuristics to skip. The early termination still leaves the
/// parser useful for its primary purpose — populating
/// <see cref="AcDream.Core.Player.LocalPlayerState"/> from the
/// attribute block — and a follow-up issue can extend it once the
/// remaining sections become consumed by panels.
/// </para>
/// </summary>
public static class PlayerDescriptionParser
{
[Flags]
public enum DescriptionPropertyFlag : uint
{
None = 0x0000,
PropertyInt32 = 0x0001,
PropertyBool = 0x0002,
PropertyDouble = 0x0004,
PropertyDid = 0x0008,
PropertyString = 0x0010,
Position = 0x0020,
PropertyIid = 0x0040,
PropertyInt64 = 0x0080,
}
[Flags]
public enum DescriptionVectorFlag : uint
{
None = 0x0000,
Attribute = 0x0001,
Skill = 0x0002,
Spell = 0x0100,
Enchantment = 0x0200,
}
/// <summary>One entry from the attribute block. Entries 1-6 are
/// primary attributes; 7-9 are vitals (Current is non-null only for
/// vitals).</summary>
public readonly record struct AttributeEntry(
uint AtType,
uint Ranks,
uint Start,
uint Xp,
uint? Current);
/// <summary>One skill entry — see ACE
/// <c>CreatureSkill</c> + holtburger
/// <c>messages/player/skills.rs</c>.</summary>
public readonly record struct SkillEntry(
uint SkillId,
uint Ranks,
uint Status,
uint Xp,
uint Init,
uint Resistance,
double LastUsed);
public readonly record struct WorldPosition(
uint LandblockId,
float X, float Y, float Z,
float Qw, float Qx, float Qy, float Qz);
public readonly record struct Parsed(
uint WeenieType,
DescriptionPropertyFlag PropertyFlags,
DescriptionVectorFlag VectorFlags,
bool HasHealth,
PropertyBundle Properties,
IReadOnlyDictionary<uint, WorldPosition> Positions,
IReadOnlyList<AttributeEntry> Attributes,
IReadOnlyList<SkillEntry> Skills,
IReadOnlyDictionary<uint, float> Spells);
/// <summary>
/// Parse a PlayerDescription payload. The 0xF7B0 envelope has been
/// stripped by <see cref="GameEventEnvelope.TryParse"/> so the
/// payload starts at the property-flags placeholder u32 — i.e. the
/// first byte after the GameEvent header.
/// </summary>
public static Parsed? TryParse(ReadOnlySpan<byte> payload)
{
if (payload.Length < 8) return null;
int pos = 0;
try
{
DescriptionPropertyFlag propertyFlags = (DescriptionPropertyFlag)ReadU32(payload, ref pos);
uint weenieType = ReadU32(payload, ref pos);
var bundle = new PropertyBundle();
var positions = new Dictionary<uint, WorldPosition>();
var attributes = new List<AttributeEntry>();
var skills = new List<SkillEntry>();
var spells = new Dictionary<uint, float>();
// ── Property hashtables (each gated on a flag bit) ──────────────
if (propertyFlags.HasFlag(DescriptionPropertyFlag.PropertyInt32))
ReadIntTable(payload, ref pos, bundle);
if (propertyFlags.HasFlag(DescriptionPropertyFlag.PropertyInt64))
ReadInt64Table(payload, ref pos, bundle);
if (propertyFlags.HasFlag(DescriptionPropertyFlag.PropertyBool))
ReadBoolTable(payload, ref pos, bundle);
if (propertyFlags.HasFlag(DescriptionPropertyFlag.PropertyDouble))
ReadDoubleTable(payload, ref pos, bundle);
if (propertyFlags.HasFlag(DescriptionPropertyFlag.PropertyString))
ReadStringTable(payload, ref pos, bundle);
if (propertyFlags.HasFlag(DescriptionPropertyFlag.PropertyDid))
ReadDataIdTable(payload, ref pos, bundle);
if (propertyFlags.HasFlag(DescriptionPropertyFlag.PropertyIid))
ReadInstanceIdTable(payload, ref pos, bundle);
if (propertyFlags.HasFlag(DescriptionPropertyFlag.Position))
ReadPositionTable(payload, ref pos, positions);
// ── Vector flags + has_health ───────────────────────────────────
if (payload.Length - pos < 8) return BuildPartial(weenieType, propertyFlags,
DescriptionVectorFlag.None, hasHealth: false, bundle, positions, attributes, skills, spells);
DescriptionVectorFlag vectorFlags = (DescriptionVectorFlag)ReadU32(payload, ref pos);
bool hasHealth = ReadU32(payload, ref pos) != 0;
// ── Attribute block (Health/Stam/Mana live at ids 7/8/9) ───────
if (vectorFlags.HasFlag(DescriptionVectorFlag.Attribute))
ReadAttributeBlock(payload, ref pos, attributes);
// ── Skills ──────────────────────────────────────────────────────
if (vectorFlags.HasFlag(DescriptionVectorFlag.Skill))
ReadSkillTable(payload, ref pos, skills);
// ── Spells (learned spellbook) ──────────────────────────────────
if (vectorFlags.HasFlag(DescriptionVectorFlag.Spell))
ReadSpellTable(payload, ref pos, spells);
// Enchantments + options + shortcuts + hotbars + inventory +
// equipped follow. Holtburger's full unpacker handles them with
// ~250 lines of additional logic and some heuristic fallbacks
// for variable-length blobs (gameplay_options). Issue #5 only
// needs through the attribute block; we stop here cleanly and
// expose what we've parsed. A follow-up can extend.
return new Parsed(
weenieType, propertyFlags, vectorFlags, hasHealth,
bundle, positions, attributes, skills, spells);
}
catch (FormatException)
{
// Truncation mid-walk — return null so caller knows parse failed.
return null;
}
}
private static Parsed BuildPartial(
uint weenieType, DescriptionPropertyFlag pFlags, DescriptionVectorFlag vFlags,
bool hasHealth, PropertyBundle bundle,
Dictionary<uint, WorldPosition> positions,
List<AttributeEntry> attributes, List<SkillEntry> skills,
Dictionary<uint, float> spells)
{
return new Parsed(weenieType, pFlags, vFlags, hasHealth,
bundle, positions, attributes, skills, spells);
}
// ── Attribute block reader ──────────────────────────────────────────────
private static void ReadAttributeBlock(
ReadOnlySpan<byte> src, ref int pos, List<AttributeEntry> attributes)
{
// u32 attributeFlags bitmask — see ACE AttributeCache:
// bit 0 → Strength (id=1), ..., bit 5 → Self (id=6),
// bit 6 → Health (id=7), bit 7 → Stamina (id=8), bit 8 → Mana (id=9).
uint attrFlags = ReadU32(src, ref pos);
// Primary attributes (1..=6): 12-byte entries (ranks, start, xp).
for (uint i = 1; i <= 6; i++)
{
uint bit = 1u << (int)(i - 1);
if ((attrFlags & bit) == 0) continue;
uint ranks = ReadU32(src, ref pos);
uint start = ReadU32(src, ref pos);
uint xp = ReadU32(src, ref pos);
attributes.Add(new AttributeEntry(i, ranks, start, xp, Current: null));
}
// Vitals (7..=9): 16-byte entries (ranks, start, xp, current).
for (uint i = 7; i <= 9; i++)
{
uint bit = 1u << (int)(i - 1);
if ((attrFlags & bit) == 0) continue;
uint ranks = ReadU32(src, ref pos);
uint start = ReadU32(src, ref pos);
uint xp = ReadU32(src, ref pos);
uint current = ReadU32(src, ref pos);
attributes.Add(new AttributeEntry(i, ranks, start, xp, current));
}
}
// ── Property hashtable readers ──────────────────────────────────────────
private static (ushort count, ushort buckets) ReadHeader(ReadOnlySpan<byte> src, ref int pos)
{
if (src.Length - pos < 4) throw new FormatException("truncated table header");
ushort count = BinaryPrimitives.ReadUInt16LittleEndian(src.Slice(pos));
ushort buckets = BinaryPrimitives.ReadUInt16LittleEndian(src.Slice(pos + 2));
pos += 4;
return (count, buckets);
}
private static void ReadIntTable(ReadOnlySpan<byte> src, ref int pos, PropertyBundle bundle)
{
var (count, _) = ReadHeader(src, ref pos);
for (int i = 0; i < count; i++)
{
uint key = ReadU32(src, ref pos);
int val = (int)ReadU32(src, ref pos);
bundle.Ints[key] = val;
}
}
private static void ReadInt64Table(ReadOnlySpan<byte> src, ref int pos, PropertyBundle bundle)
{
var (count, _) = ReadHeader(src, ref pos);
for (int i = 0; i < count; i++)
{
uint key = ReadU32(src, ref pos);
long val = ReadI64(src, ref pos);
bundle.Int64s[key] = val;
}
}
private static void ReadBoolTable(ReadOnlySpan<byte> src, ref int pos, PropertyBundle bundle)
{
var (count, _) = ReadHeader(src, ref pos);
for (int i = 0; i < count; i++)
{
uint key = ReadU32(src, ref pos);
uint val = ReadU32(src, ref pos);
bundle.Bools[key] = val != 0;
}
}
private static void ReadDoubleTable(ReadOnlySpan<byte> src, ref int pos, PropertyBundle bundle)
{
var (count, _) = ReadHeader(src, ref pos);
for (int i = 0; i < count; i++)
{
uint key = ReadU32(src, ref pos);
double val = ReadF64(src, ref pos);
bundle.Floats[key] = val;
}
}
private static void ReadStringTable(ReadOnlySpan<byte> src, ref int pos, PropertyBundle bundle)
{
var (count, _) = ReadHeader(src, ref pos);
for (int i = 0; i < count; i++)
{
uint key = ReadU32(src, ref pos);
string val = ReadString16L(src, ref pos);
bundle.Strings[key] = val;
}
}
private static void ReadDataIdTable(ReadOnlySpan<byte> src, ref int pos, PropertyBundle bundle)
{
var (count, _) = ReadHeader(src, ref pos);
for (int i = 0; i < count; i++)
{
uint key = ReadU32(src, ref pos);
uint val = ReadU32(src, ref pos);
bundle.DataIds[key] = val;
}
}
private static void ReadInstanceIdTable(ReadOnlySpan<byte> src, ref int pos, PropertyBundle bundle)
{
var (count, _) = ReadHeader(src, ref pos);
for (int i = 0; i < count; i++)
{
uint key = ReadU32(src, ref pos);
uint val = ReadU32(src, ref pos);
bundle.InstanceIds[key] = val;
}
}
// ── Position table (one position keyed by PositionType u32) ─────────────
private static void ReadPositionTable(
ReadOnlySpan<byte> src, ref int pos, Dictionary<uint, WorldPosition> positions)
{
var (count, _) = ReadHeader(src, ref pos);
for (int i = 0; i < count; i++)
{
uint key = ReadU32(src, ref pos);
positions[key] = ReadWorldPosition(src, ref pos);
}
}
private static WorldPosition ReadWorldPosition(ReadOnlySpan<byte> src, ref int pos)
{
// 32 bytes: u32 landblockId + 3 f32 coords + 4 f32 quaternion (w,x,y,z).
uint landblockId = ReadU32(src, ref pos);
float x = ReadF32(src, ref pos);
float y = ReadF32(src, ref pos);
float z = ReadF32(src, ref pos);
float qw = ReadF32(src, ref pos);
float qx = ReadF32(src, ref pos);
float qy = ReadF32(src, ref pos);
float qz = ReadF32(src, ref pos);
return new WorldPosition(landblockId, x, y, z, qw, qx, qy, qz);
}
// ── Skill table ─────────────────────────────────────────────────────────
private static void ReadSkillTable(ReadOnlySpan<byte> src, ref int pos, List<SkillEntry> skills)
{
var (count, _) = ReadHeader(src, ref pos);
for (int i = 0; i < count; i++)
{
// 32-byte CreatureSkill — holtburger skills.rs:23-46.
uint sk_type = ReadU32(src, ref pos);
// ranks is u16 not u32; constant 1u then status u32.
if (src.Length - pos < 4) throw new FormatException("truncated skill ranks/const");
uint ranks = BinaryPrimitives.ReadUInt16LittleEndian(src.Slice(pos)); pos += 2;
// u16 const_one — discarded.
BinaryPrimitives.ReadUInt16LittleEndian(src.Slice(pos)); pos += 2;
uint status = ReadU32(src, ref pos);
uint xp = ReadU32(src, ref pos);
uint init = ReadU32(src, ref pos);
uint resistance = ReadU32(src, ref pos);
double lastUsed = ReadF64(src, ref pos);
skills.Add(new SkillEntry(sk_type, ranks, status, xp, init, resistance, lastUsed));
}
}
// ── Spell table (learned spells) ────────────────────────────────────────
private static void ReadSpellTable(
ReadOnlySpan<byte> src, ref int pos, Dictionary<uint, float> spells)
{
var (count, _) = ReadHeader(src, ref pos);
for (int i = 0; i < count; i++)
{
uint spellId = ReadU32(src, ref pos);
float power = ReadF32(src, ref pos);
spells[spellId] = power;
}
}
// ── Primitive readers ───────────────────────────────────────────────────
private static uint ReadU32(ReadOnlySpan<byte> src, ref int pos)
{
if (src.Length - pos < 4) throw new FormatException("truncated u32");
uint v = BinaryPrimitives.ReadUInt32LittleEndian(src.Slice(pos));
pos += 4;
return v;
}
private static long ReadI64(ReadOnlySpan<byte> src, ref int pos)
{
if (src.Length - pos < 8) throw new FormatException("truncated i64");
long v = BinaryPrimitives.ReadInt64LittleEndian(src.Slice(pos));
pos += 8;
return v;
}
private static float ReadF32(ReadOnlySpan<byte> src, ref int pos)
{
if (src.Length - pos < 4) throw new FormatException("truncated f32");
float v = BinaryPrimitives.ReadSingleLittleEndian(src.Slice(pos));
pos += 4;
return v;
}
private static double ReadF64(ReadOnlySpan<byte> src, ref int pos)
{
if (src.Length - pos < 8) throw new FormatException("truncated f64");
double v = BinaryPrimitives.ReadDoubleLittleEndian(src.Slice(pos));
pos += 8;
return v;
}
private static string ReadString16L(ReadOnlySpan<byte> src, ref int pos)
{
if (src.Length - pos < 2) throw new FormatException("truncated string length");
ushort len = BinaryPrimitives.ReadUInt16LittleEndian(src.Slice(pos));
pos += 2;
if (src.Length - pos < len) throw new FormatException("truncated string body");
string v = Encoding.ASCII.GetString(src.Slice(pos, len));
pos += len;
// String16L records pad to 4-byte alignment per AppraiseInfoParser convention.
int record = 2 + len;
int pad = (4 - (record & 3)) & 3;
pos += pad;
return v;
}
}

105
src/AcDream.Core.Net/Messages/PrivateUpdateVital.cs Normal file
View file

@ -0,0 +1,105 @@
using System;
using System.Buffers.Binary;
namespace AcDream.Core.Net.Messages;
/// <summary>
/// Inbound vital-update <c>GameMessage</c>s for the local player.
/// These do NOT ride the <c>0xF7B0</c> GameEvent envelope — they're
/// standalone GameMessages dispatched the same way as
/// <see cref="HearSpeech"/> / <c>CreateObject</c> / <c>UpdateMotion</c>.
///
/// <para>
/// Wire format reference: holtburger
/// <c>crates/holtburger-protocol/src/messages/player/types.rs</c>
/// <c>UpdateVital</c> + <c>UpdateVitalCurrent</c>. ACE producers:
/// <c>GameMessagePrivateUpdateVital</c> +
/// <c>GameMessagePrivateUpdateAttribute2ndLevel</c>. The "sequence"
/// field is a <b>single byte</b> per ACE
/// <c>ByteSequence.NextBytes</c>; not 4 bytes despite some ACE writer
/// signatures looking like <c>uint</c>.
/// </para>
///
/// <para>Wire layouts (private flavour, no object_guid):</para>
/// <code>
/// PrivateUpdateVital (0x02E7):
/// u32 opcode = 0x02E7
/// u8 sequence
/// u32 vital // ACE Vital enum (1=MaxHealth..6=Mana)
/// u32 ranks
/// u32 start // StartingValue
/// u32 xp // ExperienceSpent
/// u32 current
/// </code>
/// <code>
/// PrivateUpdateVitalCurrent (0x02E9) — current-only delta (regen / drain):
/// u32 opcode = 0x02E9
/// u8 sequence
/// u32 vital
/// u32 current
/// </code>
///
/// <para>
/// Vital ID semantics live in
/// <see cref="AcDream.Core.Player.LocalPlayerState.VitalIdToKind"/>.
/// </para>
/// </summary>
public static class PrivateUpdateVital
{
public const uint FullOpcode = 0x02E7u;
public const uint CurrentOpcode = 0x02E9u;
/// <summary>Parsed full-update message.</summary>
public readonly record struct ParsedFull(
byte Sequence,
uint VitalId,
uint Ranks,
uint Start,
uint Xp,
uint Current);
/// <summary>Parsed current-only delta.</summary>
public readonly record struct ParsedCurrent(
byte Sequence,
uint VitalId,
uint Current);
/// <summary>
/// Parse a raw <c>PrivateUpdateVital (0x02E7)</c> body. Returns
/// <c>null</c> if opcode mismatch or truncated.
/// </summary>
public static ParsedFull? TryParseFull(ReadOnlySpan<byte> body)
{
// 4 (opcode) + 1 (seq) + 5 * 4 (uints) = 25 bytes minimum.
if (body.Length < 25) return null;
uint opcode = BinaryPrimitives.ReadUInt32LittleEndian(body);
if (opcode != FullOpcode) return null;
int pos = 4;
byte seq = body[pos]; pos += 1;
uint vital = BinaryPrimitives.ReadUInt32LittleEndian(body[pos..]); pos += 4;
uint ranks = BinaryPrimitives.ReadUInt32LittleEndian(body[pos..]); pos += 4;
uint start = BinaryPrimitives.ReadUInt32LittleEndian(body[pos..]); pos += 4;
uint xp = BinaryPrimitives.ReadUInt32LittleEndian(body[pos..]); pos += 4;
uint current = BinaryPrimitives.ReadUInt32LittleEndian(body[pos..]);
return new ParsedFull(seq, vital, ranks, start, xp, current);
}
/// <summary>
/// Parse a raw <c>PrivateUpdateVitalCurrent (0x02E9)</c> body. Returns
/// <c>null</c> if opcode mismatch or truncated.
/// </summary>
public static ParsedCurrent? TryParseCurrent(ReadOnlySpan<byte> body)
{
// 4 (opcode) + 1 (seq) + 2 * 4 (uints) = 13 bytes minimum.
if (body.Length < 13) return null;
uint opcode = BinaryPrimitives.ReadUInt32LittleEndian(body);
if (opcode != CurrentOpcode) return null;
int pos = 4;
byte seq = body[pos]; pos += 1;
uint vital = BinaryPrimitives.ReadUInt32LittleEndian(body[pos..]); pos += 4;
uint current = BinaryPrimitives.ReadUInt32LittleEndian(body[pos..]);
return new ParsedCurrent(seq, vital, current);
}
}

56
src/AcDream.Core.Net/WorldSession.cs
View file

@ -109,6 +109,23 @@ public sealed class WorldSession : IDisposable
/// </summary>
public event Action<HearSpeech.Parsed>? SpeechHeard;
/// <summary>
/// Issue #5: fires when a <c>PrivateUpdateVital (0x02E7)</c> arrives
/// — full per-vital snapshot (ranks / start / xp / current).
/// Subscribers typically feed
/// <see cref="AcDream.Core.Player.LocalPlayerState.OnVitalUpdate"/>.
/// Wire layout: see <see cref="PrivateUpdateVital"/>.
/// </summary>
public event Action<PrivateUpdateVital.ParsedFull>? VitalUpdated;
/// <summary>
/// Issue #5: fires when a <c>PrivateUpdateVitalCurrent (0x02E9)</c>
/// arrives — current-only delta (regen ticks, drains).
/// Subscribers typically feed
/// <see cref="AcDream.Core.Player.LocalPlayerState.OnVitalCurrent"/>.
/// </summary>
public event Action<PrivateUpdateVital.ParsedCurrent>? VitalCurrentUpdated;
/// <summary>
/// Phase 6 — server-broadcast PhysicsScript trigger. Fires when the
/// server sends a <c>PlayScriptId</c> (opcode 0xF754) packet —
@ -209,6 +226,15 @@ public sealed class WorldSession : IDisposable
private readonly IPEndPoint _connectEndpoint;
private readonly FragmentAssembler _assembler = new();
// Issue #5 diagnostics (env-var-gated):
// ACDREAM_DUMP_OPCODES=1 → log first occurrence of each unhandled opcode
// ACDREAM_DUMP_VITALS=1 → log every PrivateUpdateVital(Current) parse
private static readonly bool DumpOpcodesEnabled =
Environment.GetEnvironmentVariable("ACDREAM_DUMP_OPCODES") == "1";
private static readonly bool DumpVitalsEnabled =
Environment.GetEnvironmentVariable("ACDREAM_DUMP_VITALS") == "1";
private readonly System.Collections.Generic.HashSet<uint> _seenUnhandledOpcodes = new();
private IsaacRandom? _inboundIsaac;
private IsaacRandom? _outboundIsaac;
private ushort _sessionClientId;
@ -589,6 +615,27 @@ public sealed class WorldSession : IDisposable
if (parsed is not null)
SpeechHeard?.Invoke(parsed.Value);
}
else if (op == PrivateUpdateVital.FullOpcode)
{
// Issue #5: full per-vital snapshot from the server. Wire
// format per holtburger UpdateVital<false> — see
// PrivateUpdateVital.TryParseFull.
var parsed = PrivateUpdateVital.TryParseFull(body);
if (DumpVitalsEnabled)
Console.WriteLine($"vitals: 0x02E7 PrivateUpdateVital body.len={body.Length} parsed={(parsed is null ? "null" : $"v{parsed.Value.VitalId} ranks={parsed.Value.Ranks} start={parsed.Value.Start} cur={parsed.Value.Current}")}");
if (parsed is not null)
VitalUpdated?.Invoke(parsed.Value);
}
else if (op == PrivateUpdateVital.CurrentOpcode)
{
// Issue #5: current-only delta (regen ticks / drains).
// Wire format per holtburger UpdateVitalCurrent<false>.
var parsed = PrivateUpdateVital.TryParseCurrent(body);
if (DumpVitalsEnabled)
Console.WriteLine($"vitals: 0x02E9 PrivateUpdateVitalCurrent body.len={body.Length} parsed={(parsed is null ? "null" : $"v{parsed.Value.VitalId} cur={parsed.Value.Current}")}");
if (parsed is not null)
VitalCurrentUpdated?.Invoke(parsed.Value);
}
else if (op == GameEventEnvelope.Opcode)
{
// Phase F.1: 0xF7B0 is the GameEvent envelope. Parse the
@ -645,6 +692,15 @@ public sealed class WorldSession : IDisposable
_teleportSequence = sequence; // track for outbound movement messages
TeleportStarted?.Invoke(sequence);
}
else if (DumpOpcodesEnabled)
{
// ACDREAM_DUMP_OPCODES=1 — emit a one-line trace per
// genuinely-unhandled opcode (deduped to first occurrence).
// MUST be the LAST else-if so it doesn't intercept handled
// opcodes when the env var is set.
if (_seenUnhandledOpcodes.Add(op))
Console.WriteLine($"opcodes: unhandled 0x{op:X4} (body.len={body.Length})");
}
}
}

306
src/AcDream.Core/Player/LocalPlayerState.cs
View file

@ -1,79 +1,265 @@
using System.Collections.Generic;
namespace AcDream.Core.Player;
/// <summary>
/// Cache of the local player's stamina + mana absolute values, populated
/// from the <c>CreatureProfile</c> blob inside <c>PlayerDescription
/// (0x0013)</c>. Health stays in <see cref="AcDream.Core.Combat.CombatState"/>
/// because it has its own delta opcode (<c>UpdateHealth 0x01C0</c>); stam
/// and mana don't, so without this cache <c>VitalsVM</c> can't surface
/// percent-of-max bars even though the parser already decodes the
/// absolute values.
/// Local player's attribute + vital snapshot, populated from the
/// <c>PlayerDescription (0x0013)</c> attribute block at login and
/// kept fresh by <c>PrivateUpdateVital (0x02E7)</c> +
/// <c>PrivateUpdateVitalCurrent (0x02E9)</c> deltas.
///
/// <para>
/// Filed by issue <c>#5</c> in <c>docs/ISSUES.md</c>. Once future delta
/// opcodes for stam/mana arrive (or are recognised in the existing event
/// stream) they update through the same <see cref="OnPlayerDescription"/>
/// surface — keep the cache the single point of truth so VM consumers
/// don't have to subscribe to multiple sources.
/// Wire format references:
/// </para>
/// <list type="bullet">
/// <item>holtburger
/// <c>crates/holtburger-protocol/src/messages/player/events.rs</c>
/// for PlayerDescription body layout (vitals at attribute-block
/// ids 7/8/9 with <c>ranks/start/xp/current</c>).</item>
/// <item>holtburger
/// <c>crates/holtburger-world/src/player/stats_calc.rs</c>
/// <c>calculate_vital_current</c> for the max formula —
/// <c>(ranks + start + attribute_contribution) × multiplier + additive</c>.
/// We implement the unenchanted base case with retail-faithful
/// hardcoded attribute coefficients (no portal.dat
/// <c>SecondaryAttributeTable</c> port yet — see remarks).</item>
/// </list>
///
/// <para>
/// <b>Max derivation</b> (retail base case, no enchantments):
/// </para>
/// <code>
/// MaxHealth = vital.ranks + vital.start + Endurance.current / 2
/// MaxStamina = vital.ranks + vital.start + Endurance.current
/// MaxMana = vital.ranks + vital.start + Self.current
/// </code>
///
/// <para>
/// Primary attribute <c>current = ranks + start</c> per holtburger
/// <c>mutations.rs</c>. Attribute coefficients come from retail's
/// <c>SecondaryAttributeTable</c> (portal.dat 0x0E0..0x0E2). The
/// values are hardcoded here as well-known constants; a future port
/// of the dat object can replace the hardcodes if those coefficients
/// ever turn out to vary.
/// </para>
///
/// <para>
/// <b>Enchantment buffs</b> (multiplicative + additive) and the
/// 5-min-vital clamp are <b>not yet applied</b> — adding those
/// requires the <see cref="AcDream.Core.Spells.Spellbook"/>'s active
/// enchantment list. The unenchanted max is correct for clean
/// characters; buffed players will read percent slightly higher than
/// retail until enchantment integration lands.
/// </para>
/// </summary>
public sealed class LocalPlayerState
{
/// <summary>Current stamina (absolute), or <c>null</c> if never received.</summary>
public uint? CurrentStamina { get; private set; }
/// <summary>Max stamina (absolute), or <c>null</c> if never received.</summary>
public uint? MaxStamina { get; private set; }
/// <summary>Current mana (absolute), or <c>null</c> if never received.</summary>
public uint? CurrentMana { get; private set; }
/// <summary>Max mana (absolute), or <c>null</c> if never received.</summary>
public uint? MaxMana { get; private set; }
/// <summary>Fires after any field update via <see cref="OnPlayerDescription"/>.</summary>
public event Action<LocalPlayerState>? Changed;
/// <summary>
/// Stamina as a 0..1 fraction, or <c>null</c> when either current or max
/// is missing or max is zero. Clamps to 1.0 if current &gt; max (which
/// the server can briefly report during buff transitions).
/// </summary>
public float? StaminaPercent => Percent(CurrentStamina, MaxStamina);
/// <summary>
/// Mana as a 0..1 fraction, or <c>null</c> when either current or max
/// is missing or max is zero. Same clamp rules as
/// <see cref="StaminaPercent"/>.
/// </summary>
public float? ManaPercent => Percent(CurrentMana, MaxMana);
/// <summary>
/// Apply a slice of the latest <c>CreatureProfile</c>. Each field is
/// nullable: <c>null</c> means "no information" — preserve any previously
/// known good value rather than wipe it. Fires <see cref="Changed"/> once
/// after the update.
/// </summary>
public void OnPlayerDescription(
uint? currentStamina,
uint? maxStamina,
uint? currentMana,
uint? maxMana)
/// <summary>Three vital types — mirrors holtburger <c>VitalType</c>.</summary>
public enum VitalKind
{
if (currentStamina.HasValue) CurrentStamina = currentStamina.Value;
if (maxStamina.HasValue) MaxStamina = maxStamina.Value;
if (currentMana.HasValue) CurrentMana = currentMana.Value;
if (maxMana.HasValue) MaxMana = maxMana.Value;
Changed?.Invoke(this);
Health,
Stamina,
Mana,
}
private static float? Percent(uint? current, uint? max)
/// <summary>Six primary attributes — ACE <c>PropertyAttribute</c>.</summary>
public enum AttributeKind
{
if (current is not uint c) return null;
Strength,
Endurance,
Quickness,
Coordination,
Focus,
Self,
}
/// <summary>Primary-attribute snapshot. <c>Current = Ranks + Start</c>
/// per retail; we don't track an independent "current attribute"
/// because PlayerDescription doesn't expose one.</summary>
public readonly record struct AttributeSnapshot(uint Ranks, uint Start, uint Xp)
{
public uint Current => Ranks + Start;
}
/// <summary>Per-vital snapshot. Max comes from
/// <see cref="LocalPlayerState.GetMaxApprox"/> because it depends
/// on primary-attribute state held elsewhere on the cache.</summary>
public readonly record struct VitalSnapshot(uint Ranks, uint Start, uint Xp, uint Current);
private VitalSnapshot? _health;
private VitalSnapshot? _stamina;
private VitalSnapshot? _mana;
private readonly Dictionary<AttributeKind, AttributeSnapshot> _attrs = new();
/// <summary>Fires after any vital field changes.</summary>
public event System.Action<VitalKind>? Changed;
/// <summary>Fires after any primary-attribute field changes (rare —
/// only at PlayerDescription / future <c>PrivateUpdateAttribute</c>).</summary>
public event System.Action<AttributeKind>? AttributeChanged;
/// <summary>
/// Map a vital-id (across both ID systems) to a <see cref="VitalKind"/>.
/// <list type="bullet">
/// <item><c>1..=6</c> — wire-opcode <c>Vital</c> enum
/// (MaxHealth=1, Health=2, MaxStamina=3, Stamina=4, MaxMana=5, Mana=6).</item>
/// <item><c>7..=9</c> — PlayerDescription attribute-block ids
/// (Health=7, Stamina=8, Mana=9).</item>
/// </list>
/// </summary>
public static VitalKind? VitalIdToKind(uint vitalId) => vitalId switch
{
1u or 2u or 7u => VitalKind.Health,
3u or 4u or 8u => VitalKind.Stamina,
5u or 6u or 9u => VitalKind.Mana,
_ => null,
};
/// <summary>
/// Map a primary-attribute id (1..=6) to <see cref="AttributeKind"/>.
/// Returns <c>null</c> for ids outside that range — vital ids 7-9
/// don't map.
/// </summary>
public static AttributeKind? AttributeIdToKind(uint atType) => atType switch
{
1u => AttributeKind.Strength,
2u => AttributeKind.Endurance,
3u => AttributeKind.Quickness,
4u => AttributeKind.Coordination,
5u => AttributeKind.Focus,
6u => AttributeKind.Self,
_ => null,
};
/// <summary>Snapshot for a vital, or <c>null</c> if never received.</summary>
public VitalSnapshot? Get(VitalKind kind) => kind switch
{
VitalKind.Health => _health,
VitalKind.Stamina => _stamina,
VitalKind.Mana => _mana,
_ => null,
};
/// <summary>Snapshot for a primary attribute, or <c>null</c> if never received.</summary>
public AttributeSnapshot? GetAttribute(AttributeKind kind) =>
_attrs.TryGetValue(kind, out var a) ? a : null;
/// <summary>
/// Compute the unenchanted max for a vital, using the retail formula:
/// <c>vital.(ranks+start) + attribute_contribution</c>. Returns
/// <c>null</c> if the vital snapshot doesn't exist yet.
/// </summary>
public uint? GetMaxApprox(VitalKind kind)
{
var v = Get(kind);
if (v is null) return null;
uint baseMax = v.Value.Ranks + v.Value.Start;
uint contrib = AttributeContribution(kind);
return baseMax + contrib;
}
/// <summary>Stamina percent (0..1) or null when not yet received.</summary>
public float? StaminaPercent => Percent(VitalKind.Stamina);
/// <summary>Mana percent (0..1) or null when not yet received.</summary>
public float? ManaPercent => Percent(VitalKind.Mana);
/// <summary>Health percent (0..1) or null when not yet received.</summary>
public float? HealthPercent => Percent(VitalKind.Health);
private float? Percent(VitalKind kind)
{
var v = Get(kind);
if (v is null) return null;
uint? max = GetMaxApprox(kind);
if (max is not uint m || m == 0) return null;
float r = (float)c / m;
float r = (float)v.Value.Current / m;
if (r < 0f) r = 0f;
else if (r > 1f) r = 1f;
return r;
}
/// <summary>
/// Apply a full vital update — replaces ranks / start / xp / current
/// for the matching <see cref="VitalKind"/>. Accepts both wire-opcode
/// ids (1..=6) and PlayerDescription attribute-block ids (7..=9).
/// </summary>
public void OnVitalUpdate(uint vitalId, uint ranks, uint start, uint xp, uint current)
{
if (VitalIdToKind(vitalId) is not VitalKind kind) return;
var snap = new VitalSnapshot(ranks, start, xp, current);
switch (kind)
{
case VitalKind.Health: _health = snap; break;
case VitalKind.Stamina: _stamina = snap; break;
case VitalKind.Mana: _mana = snap; break;
}
Changed?.Invoke(kind);
}
/// <summary>
/// Apply a current-only delta. Silently ignored if no full update
/// has been received for this vital yet (matches holtburger's
/// <c>get_mut(&amp;kind)</c> miss-as-noop semantics).
/// </summary>
public void OnVitalCurrent(uint vitalId, uint current)
{
if (VitalIdToKind(vitalId) is not VitalKind kind) return;
VitalSnapshot? existing = Get(kind);
if (existing is not VitalSnapshot prev) return;
var snap = prev with { Current = current };
switch (kind)
{
case VitalKind.Health: _health = snap; break;
case VitalKind.Stamina: _stamina = snap; break;
case VitalKind.Mana: _mana = snap; break;
}
Changed?.Invoke(kind);
}
/// <summary>
/// Apply a primary-attribute update from PlayerDescription's
/// attribute block (ids 1..=6). Vital ids (7..=9) here are silently
/// dropped — feed them through <see cref="OnVitalUpdate"/> instead.
/// </summary>
public void OnAttributeUpdate(uint atType, uint ranks, uint start, uint xp)
{
if (AttributeIdToKind(atType) is not AttributeKind kind) return;
_attrs[kind] = new AttributeSnapshot(ranks, start, xp);
AttributeChanged?.Invoke(kind);
}
// ── Retail attribute contribution ──────────────────────────────────────
//
// Source: ACE Source/ACE.Server/Entity/AttributeFormula.cs +
// SecondaryAttributeTable (portal.dat 0x0E0..0x0E2). Coefficients are
// hardwired in retail and re-confirmed by holtburger's
// calculate_vital_attribute_contribution.
//
// MaxHealth formula = Endurance × 0.5
// MaxStamina formula = Endurance × 1.0
// MaxMana formula = Self × 1.0
//
// Unknown attribute → contribution 0 → max underestimated. Once the
// SecondaryAttributeTable port lands these can shift to dat-driven
// coefficients, but the values themselves don't change between dat
// versions in retail.
private uint AttributeContribution(VitalKind kind)
{
switch (kind)
{
case VitalKind.Health:
return GetAttrCurrent(AttributeKind.Endurance) / 2u;
case VitalKind.Stamina:
return GetAttrCurrent(AttributeKind.Endurance);
case VitalKind.Mana:
return GetAttrCurrent(AttributeKind.Self);
default:
return 0u;
}
}
private uint GetAttrCurrent(AttributeKind kind) =>
_attrs.TryGetValue(kind, out var a) ? a.Current : 0u;
}