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

feat(net): AppraiseInfoParser — full PropertyBundle deserializer

Browse source 
Closes the single biggest P0 gap from r08: the AppraiseInfo blob
carried by both IdentifyObjectResponse (0x00C9) and the initial
PlayerDescription (0x0013) is now parsed end-to-end for the six core
property tables.

Wire layer:
- AppraiseInfoParser.TryParse returns a Parsed record:
  (Guid, Flags, Success, PropertyBundle, SpellBook[]).
- IdentifyResponseFlags enum mirrors ACE's bitfield exactly.
- Header reader: u16 count + u16 numBuckets (ACE
  PackableHashTable.WriteHeader format).
- Per-table readers: IntStatsTable, Int64StatsTable, BoolStatsTable
  (u32 → bool), FloatStatsTable (f64 values), StringStatsTable
  (string16L values with 4-byte pad), DidStatsTable.
- SpellBook reader: u32 count followed by count u32 spell ids, with
  sanity cap at 4096 entries.

What's NOT yet parsed (deferred, noted in XML doc):
- ArmorProfile / CreatureProfile / WeaponProfile / HookProfile blobs
  require porting their respective Structure classes.
- Enchantment bitfields (u16 highlight + u16 color triplets).
- ArmorLevels block.

The parser is defensive: malformed / truncated tables raise
FormatException which is caught internally; the caller gets
whatever properties parsed successfully before the error.

Tests (7 new):
- Header-only (no tables).
- IntStatsTable round-trip with mixed sign values.
- BoolStatsTable (u32 ↔ bool conversion).
- StringStatsTable with padded-length strings.
- SpellBook parsing.
- Combined flags across multiple tables.
- Truncated payload → null.

Build green, 628 tests pass (up from 621).

This unlocks the Attributes / Skills / Paperdoll UI panels once their
renderers land — every property key the server sends now gets stored
on the target ItemInstance (or — for PlayerDescription — the player's
own property bag once wired).

Ref: ACE AppraiseInfo.Write (AppraiseInfo.cs:735), PackableHashTable.
Ref: r08 §4 payload for 0x00C9.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik 2026-04-18 17:22:00 +02:00
parent d461279207
commit e16f3315d2
2 changed files with 438 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

253
src/AcDream.Core.Net/Messages/AppraiseInfoParser.cs Normal file
View file

@ -0,0 +1,253 @@
using System;
using System.Buffers.Binary;
using System.Text;
using AcDream.Core.Items;
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>PackableHashTable.WriteHeader</c>.
///
/// <para>
/// Wire shape:
/// <code>
/// u32 flags // IdentifyResponseFlags bitfield
/// u32 success // 0 or 1
/// if (flags &amp; IntStatsTable) packedTable&lt;u32 key, i32 value&gt;
/// if (flags &amp; Int64StatsTable) packedTable&lt;u32 key, i64 value&gt;
/// if (flags &amp; BoolStatsTable) packedTable&lt;u32 key, u32 value&gt;
/// if (flags &amp; FloatStatsTable) packedTable&lt;u32 key, f64 value&gt;
/// if (flags &amp; StringStatsTable) packedTable&lt;u32 key, string16L value&gt;
/// if (flags &amp; DidStatsTable) packedTable&lt;u32 key, u32 value&gt;
/// if (flags &amp; SpellBook) u32 count, u32[count] spellIds
/// ...armor/creature/weapon/hook profile blobs follow (deferred)
/// </code>
/// </para>
///
/// <para>
/// Each packed table starts with a 4-byte header:
/// <code>
/// u16 count // how many entries follow
/// u16 numBuckets // hashtable bucket hint (ignored for parse)
/// </code>
/// Then <c>count</c> (key, value) pairs. No padding between pairs.
/// </para>
///
/// <para>
/// Returns a fully-populated <see cref="PropertyBundle"/>. Profile
/// blobs (ArmorProfile / CreatureProfile / WeaponProfile / HookProfile)
/// are recognised via the flag bits but not yet deserialized — the
/// parser seeks past them to keep the flag walk aligned.
/// </para>
/// </summary>
public static class AppraiseInfoParser
{
[Flags]
public enum IdentifyResponseFlags : uint
{
None = 0x0000_0000,
IntStatsTable = 0x0000_0001,
Int64StatsTable = 0x0000_0002,
BoolStatsTable = 0x0000_0004,
FloatStatsTable = 0x0000_0008,
StringStatsTable = 0x0000_0010,
DidStatsTable = 0x0000_0020,
SpellBook = 0x0000_0040,
ArmorProfile = 0x0000_0080,
WeaponProfile = 0x0000_0100,
HookProfile = 0x0000_0200,
ArmorEnchantmentBitfield = 0x0000_0400,
WeaponEnchantmentBitfield= 0x0000_0800,
ResistEnchantmentBitfield= 0x0000_1000,
CreatureProfile = 0x0000_2000,
ArmorLevels = 0x0000_4000,
}
public readonly record struct Parsed(
uint Guid,
IdentifyResponseFlags Flags,
bool Success,
PropertyBundle Properties,
uint[] SpellBook);
/// <summary>
/// Parse a full IdentifyObjectResponse payload.
/// The envelope has already been stripped by
/// <see cref="GameEventEnvelope.TryParse"/>, so
/// <paramref name="payload"/> begins with <c>u32 guid</c>.
/// </summary>
public static Parsed? TryParse(ReadOnlySpan<byte> payload)
{
if (payload.Length < 12) return null;
int pos = 0;
uint guid = ReadU32(payload, ref pos);
uint rawFlags= ReadU32(payload, ref pos);
uint success = ReadU32(payload, ref pos);
var flags = (IdentifyResponseFlags)rawFlags;
var bundle = new PropertyBundle();
uint[] spellBook = Array.Empty<uint>();
try
{
if (flags.HasFlag(IdentifyResponseFlags.IntStatsTable))
ReadIntTable(payload, ref pos, bundle);
if (flags.HasFlag(IdentifyResponseFlags.Int64StatsTable))
ReadInt64Table(payload, ref pos, bundle);
if (flags.HasFlag(IdentifyResponseFlags.BoolStatsTable))
ReadBoolTable(payload, ref pos, bundle);
if (flags.HasFlag(IdentifyResponseFlags.FloatStatsTable))
ReadFloatTable(payload, ref pos, bundle);
if (flags.HasFlag(IdentifyResponseFlags.StringStatsTable))
ReadStringTable(payload, ref pos, bundle);
if (flags.HasFlag(IdentifyResponseFlags.DidStatsTable))
ReadDataIdTable(payload, ref pos, bundle);
if (flags.HasFlag(IdentifyResponseFlags.SpellBook))
spellBook = ReadSpellBook(payload, ref pos);
// Profile blobs: their sizes aren't trivially predictable
// without porting the whole profile structures. We stop here
// and let the caller handle the bundle they have.
}
catch (FormatException)
{
// Malformed table — return what we got so far.
}
return new Parsed(guid, flags, success != 0, bundle, spellBook);
}
// ── Table 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 ReadFloatTable(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 uint[] ReadSpellBook(ReadOnlySpan<byte> src, ref int pos)
{
if (src.Length - pos < 4) throw new FormatException("truncated spellbook count");
uint count = ReadU32(src, ref pos);
if (count > 4096) throw new FormatException("unreasonable spellbook count");
if (src.Length - pos < count * 4) throw new FormatException("truncated spellbook body");
uint[] result = new uint[count];
for (int i = 0; i < count; i++) result[i] = ReadU32(src, ref pos);
return result;
}
// ── 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 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;
int record = 2 + len;
int pad = (4 - (record & 3)) & 3;
pos += pad;
return v;
}
}

185
tests/AcDream.Core.Net.Tests/Messages/AppraiseInfoParserTests.cs Normal file
View file

@ -0,0 +1,185 @@
using System;
using System.Buffers.Binary;
using System.IO;
using AcDream.Core.Net.Messages;
using Xunit;
namespace AcDream.Core.Net.Tests.Messages;
public sealed class AppraiseInfoParserTests
{
/// <summary>
/// Build an AppraiseInfo payload matching ACE's wire format. Starts
/// with (guid, flags, success) then per-flag tables.
/// </summary>
private static byte[] BuildPayload(
uint guid,
AppraiseInfoParser.IdentifyResponseFlags flags,
bool success,
(uint key, int value)[]? ints = null,
(uint key, bool value)[]? bools = null,
(uint key, string value)[]? strings = null,
uint[]? spellBook = null)
{
using var ms = new MemoryStream();
using var bw = new BinaryWriter(ms);
bw.Write(guid);
bw.Write((uint)flags);
bw.Write((uint)(success ? 1 : 0));
if (flags.HasFlag(AppraiseInfoParser.IdentifyResponseFlags.IntStatsTable) && ints is not null)
{
bw.Write((ushort)ints.Length);
bw.Write((ushort)16); // numBuckets hint
foreach (var (k, v) in ints)
{
bw.Write(k);
bw.Write(v);
}
}
if (flags.HasFlag(AppraiseInfoParser.IdentifyResponseFlags.BoolStatsTable) && bools is not null)
{
bw.Write((ushort)bools.Length);
bw.Write((ushort)8);
foreach (var (k, v) in bools)
{
bw.Write(k);
bw.Write(v ? 1u : 0u);
}
}
if (flags.HasFlag(AppraiseInfoParser.IdentifyResponseFlags.StringStatsTable) && strings is not null)
{
bw.Write((ushort)strings.Length);
bw.Write((ushort)8);
foreach (var (k, v) in strings)
{
bw.Write(k);
WriteString16L(bw, v);
}
}
if (flags.HasFlag(AppraiseInfoParser.IdentifyResponseFlags.SpellBook) && spellBook is not null)
{
bw.Write((uint)spellBook.Length);
foreach (var sid in spellBook) bw.Write(sid);
}
bw.Flush();
return ms.ToArray();
}
private static void WriteString16L(BinaryWriter bw, string s)
{
byte[] bytes = System.Text.Encoding.ASCII.GetBytes(s);
bw.Write((ushort)bytes.Length);
bw.Write(bytes);
int record = 2 + bytes.Length;
int pad = (4 - (record & 3)) & 3;
for (int i = 0; i < pad; i++) bw.Write((byte)0);
}
[Fact]
public void TryParse_GuidAndFlags_ExtractedCorrectly()
{
byte[] payload = BuildPayload(
guid: 0xDEADBEEFu,
flags: AppraiseInfoParser.IdentifyResponseFlags.None,
success: true);
var parsed = AppraiseInfoParser.TryParse(payload);
Assert.NotNull(parsed);
Assert.Equal(0xDEADBEEFu, parsed!.Value.Guid);
Assert.True(parsed.Value.Success);
}
[Fact]
public void TryParse_IntStatsTable_PopulatesIntProperties()
{
byte[] payload = BuildPayload(
guid: 1,
flags: AppraiseInfoParser.IdentifyResponseFlags.IntStatsTable,
success: true,
ints: new[] { ((uint)1, 100), ((uint)5, -50), ((uint)9, 42) });
var parsed = AppraiseInfoParser.TryParse(payload);
Assert.NotNull(parsed);
Assert.Equal(3, parsed!.Value.Properties.Ints.Count);
Assert.Equal(100, parsed.Value.Properties.Ints[1]);
Assert.Equal(-50, parsed.Value.Properties.Ints[5]);
Assert.Equal(42, parsed.Value.Properties.Ints[9]);
}
[Fact]
public void TryParse_BoolStatsTable_ConvertsU32ToBool()
{
byte[] payload = BuildPayload(
guid: 1,
flags: AppraiseInfoParser.IdentifyResponseFlags.BoolStatsTable,
success: true,
bools: new[] { ((uint)1, true), ((uint)2, false) });
var parsed = AppraiseInfoParser.TryParse(payload);
Assert.NotNull(parsed);
Assert.True(parsed!.Value.Properties.Bools[1]);
Assert.False(parsed.Value.Properties.Bools[2]);
}
[Fact]
public void TryParse_StringStatsTable_ParsesPaddedStrings()
{
byte[] payload = BuildPayload(
guid: 1,
flags: AppraiseInfoParser.IdentifyResponseFlags.StringStatsTable,
success: true,
strings: new[] { ((uint)1, "Excalibur"), ((uint)2, "Rusty Dagger") });
var parsed = AppraiseInfoParser.TryParse(payload);
Assert.NotNull(parsed);
Assert.Equal("Excalibur", parsed!.Value.Properties.Strings[1]);
Assert.Equal("Rusty Dagger", parsed.Value.Properties.Strings[2]);
}
[Fact]
public void TryParse_SpellBook_ReturnsSpellIdArray()
{
byte[] payload = BuildPayload(
guid: 1,
flags: AppraiseInfoParser.IdentifyResponseFlags.SpellBook,
success: true,
spellBook: new uint[] { 0x3E1, 0x3E2, 0x3E3 });
var parsed = AppraiseInfoParser.TryParse(payload);
Assert.NotNull(parsed);
Assert.Equal(3, parsed!.Value.SpellBook.Length);
Assert.Equal(0x3E1u, parsed.Value.SpellBook[0]);
}
[Fact]
public void TryParse_MultipleTables_AllParsed()
{
var flags = AppraiseInfoParser.IdentifyResponseFlags.IntStatsTable
| AppraiseInfoParser.IdentifyResponseFlags.BoolStatsTable
| AppraiseInfoParser.IdentifyResponseFlags.SpellBook;
byte[] payload = BuildPayload(
guid: 1, flags, success: true,
ints: new[] { ((uint)1, 100) },
bools: new[] { ((uint)2, true) },
spellBook: new uint[] { 42 });
var parsed = AppraiseInfoParser.TryParse(payload);
Assert.NotNull(parsed);
Assert.Single(parsed!.Value.Properties.Ints);
Assert.Single(parsed.Value.Properties.Bools);
Assert.Single(parsed.Value.SpellBook);
}
[Fact]
public void TryParse_Truncated_ReturnsNull()
{
Assert.Null(AppraiseInfoParser.TryParse(new byte[4]));
}
}