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

feat(net): Campaign LA LA7a — CharacterDelete/CharacterRestore/CharacterError wire messages

Browse source 
Ports the three character-management wire messages LA7 (design spec §7,
plan §11 item 4) identified as missing before the character-select
screen (LA8) can be built: delete, restore, and the server error channel.
Message types + tests only — no WorldSession/Runtime/UI wiring, that is
LA7b.

CharacterDelete (0xF655): outbound account+SLOT-INDEX request per
Proto_UI::SendDeleteCharacter@0x00546b30 (retail packs the account as
String16L then writes the trailing u32 directly after — NOT the character
guid; CPlayerSystem::DeleteCharacter@0x0055f830 resolves that slot via
CharacterSet::GetSlot before sending). The server's ack reuses the same
opcode with an empty body (ACE GameMessageCharacterDelete.cs); a fresh
CharacterList follows separately per CharacterHandler.cs:322 — that
refresh flow is explicitly out of scope here (LA7b).

CharacterRestore (0xF7D9 request / 0xF643 response): guid-only request,
per ACE (CharacterHandler.cs:331-385, ReadUInt32 only) and holtburger
(CharacterRestoreRequestData, guid-only) independent consensus. The
decompiled call site (Proto_UI::SendAdminRestoreCharacter@0x00546cf0)
appears to pack two extra strings, but its only caller
(CPlayerSystem::RestoreCharacter@0x0055d760) passes an uninitialized
local (`class PStringBase<char>* edx;`, never assigned) as the second
argument and `this` (a CPlayerSystem*, not a string) as the third —
textbook decompiler register-corruption, not real arguments. No
divergence-register row: this follows the correct reading of a corrupted
decompile, not a deviation from retail (spec §11 item 4). The response
reuses opcode 0xF643, a genuine retail collision with
CharacterCreateResponse (ACE's own comment: "This is a duplicate...",
GameMessageOpcode.cs:42); GameMessageCharacterRestore.cs always writes a
success shape (flag=1 + guid + name + secondsGreyedOut), but retail's
CharacterRestore handler can also reply via the CharacterCreateResponse
path on failure (e.g. NameInUse) with a flag-only body and no trailing
fields — the parser mirrors that conditionality instead of assuming the
four fields are always present.

CharacterError (0xF659): u32 error code, confirmed directly from retail's
inbound dispatcher UIQueueManager::ProcessNetBlobData@0x0055b000 ->
CPlayerSystem::Handle_CharacterError@0x0055d5d0, which reads
`enum charError` straight off the wire. The Code enum is a verbatim port
of retail's own enum charError (docs/research/named-retail/acclient.h:
4038-4067, 26 members incl. CHAR_ERROR_NUM_ERRORS) rather than a subset
filtered through ACE — retail's header names four members ACE's C#
CharacterError enum omits (LoggedOn, NoPremade, AccountInUse,
CharacterIsBooted) because ACE's server never sends them, though a
genuine retail server could. The 32-bit storage-width compiler sentinel
FORCE_charError_32_BIT is deliberately excluded (not a real value).
Unknown codes never throw — RawErrorCode always preserves the wire value.
Today acdream cannot surface any character-stage server error; this is
the first parser for the family.

46 new tests (byte-exact builder assertions, ACE-serializer-shaped
parser fixtures via the existing AceWireWriter test helper, all 26
retail error codes round-tripped, unknown/truncated/wrong-opcode
handling). Full Core.Net.Tests suite: 951 passed, 0 failed, 0 skipped.
Release build green.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Erik 2026-08-14 15:46:48 +02:00
parent 7a839cba71
commit 6a32f37589
6 changed files with 811 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

270
src/AcDream.Core.Net/Messages/CharacterError.cs Normal file
View file

@ -0,0 +1,270 @@
using System.Buffers.Binary;
namespace AcDream.Core.Net.Messages;
/// <summary>
/// Inbound <c>CharacterError</c> GameMessage (opcode <c>0xF659</c>) — the
/// server's catch-all failure notice during the pre-world character-select
/// stage (logon conflicts, delete/restore failures, enter-world rejections,
/// subscription state). Today acdream cannot surface ANY character-stage
/// server error to the user; this is the first parser for the family.
///
/// <para>
/// Wire layout confirmed directly from retail's inbound dispatcher,
/// <c>UIQueueManager::ProcessNetBlobData</c> at <c>0x0055b000</c>, which
/// reads a u32 immediately after the opcode and passes it to
/// <c>CPlayerSystem::Handle_CharacterError</c> at <c>0x0055d5d0</c> typed
/// as <c>enum charError</c> (<c>enum charError eax_86 = *(uint32_t*)((char*)ecx + 4);</c>):
/// </para>
///
/// <code>
/// u32 opcode (0xF659)
/// u32 errorCode (enum charError)
/// </code>
///
/// <para>
/// ACE agrees: <c>GameMessageCharacterError</c>
/// (<c>ACE.Server/Network/GameMessages/Messages/GameMessageCharacterError.cs</c>)
/// writes exactly <c>opcode + (uint)error</c>, and every
/// <c>session.SendCharacterError(...)</c> call site in
/// <c>CharacterHandler.cs</c> (the two this slice's <see cref="CharacterDelete"/>
/// / <see cref="CharacterRestore"/> handlers can raise —
/// <c>CharacterError.Delete</c>, <c>CharacterError.LogonServerFull</c>,
/// <c>CharacterError.EnterGameCouldntPlaceCharacter</c>,
/// <c>CharacterError.EnterGameCharacterNotOwned</c> — plus every other
/// value the wider character-stage flow can raise) goes through this same
/// shape.
/// </para>
///
/// <para>
/// <see cref="Code"/> is a verbatim port of retail's <c>enum charError</c>
/// (<c>docs/research/named-retail/acclient.h:4038-4067</c>) — the header's
/// own numeric ground truth, not a subset filtered through ACE's C# port.
/// It is a strict superset of ACE's <c>ACE.Server.Network.Enum.CharacterError</c>
/// (<c>references/ACE/Source/ACE.Server/Network/Enum/CharacterError.cs</c>):
/// retail additionally names 0x2 (<c>LoggedOn</c>), 0x7 (<c>NoPremade</c>),
/// 0x8 (<c>AccountInUse</c>), and 0x16 (<c>CharacterIsBooted</c>), none of
/// which ACE's server ever sends but all of which retail's client can
/// receive from a genuine retail server — per the project's
/// property-enum-divergence lesson, we port the complete oracle, not just
/// what today's one server implementation emits. ACE's per-value doc
/// comments (themselves sourced from the client's <c>ID_CHAR_ERROR_*</c>
/// string table) are folded in below where they exist. One retail member,
/// <c>FORCE_charError_32_BIT = 0x7FFFFFFF</c>, is a compiler
/// storage-width pragma (MSVC's "force this enum to 32-bit backing store"
/// idiom) and not a real wire value — it is deliberately NOT ported.
/// </para>
///
/// <para>
/// Unknown values are never rejected: <see cref="Parsed.RawErrorCode"/>
/// always carries the wire value verbatim, and casting it to
/// <see cref="Code"/> (see <see cref="Parsed.AsCode"/>) can never throw in
/// C# even for a value retail itself never defined — future server
/// revisions or private servers may add codes we haven't named yet.
/// </para>
/// </summary>
public static class CharacterError
{
public const uint Opcode = 0xF659u;
/// <summary>
/// Verbatim port of retail's <c>enum charError</c>
/// (<c>acclient.h:4038-4067</c>), excluding the 32-bit storage-width
/// sentinel <c>FORCE_charError_32_BIT</c>.
/// </summary>
public enum Code : uint
{
/// <summary>0x00 — CHAR_ERROR_UNDEF.</summary>
Undefined = 0x00,
/// <summary>
/// 0x01 — CHAR_ERROR_LOGON. ACE: "Cannot have two accounts logged
/// on at the same time."
/// </summary>
Logon = 0x01,
/// <summary>0x02 — CHAR_ERROR_LOGGED_ON. Retail-only; no ACE member.</summary>
LoggedOn = 0x02,
/// <summary>
/// 0x03 — CHAR_ERROR_ACCOUNT_LOGON. ACE: "Server could not access
/// your account information. Please try again in a few minutes."
/// </summary>
AccountLogon = 0x03,
/// <summary>
/// 0x04 — CHAR_ERROR_SERVER_CRASH. ACE: "The server has
/// disconnected. Please try again in a few minutes."
/// </summary>
ServerCrash = 0x04,
/// <summary>0x05 — CHAR_ERROR_LOGOFF. ACE: "Server could not log off your character."</summary>
Logoff = 0x05,
/// <summary>
/// 0x06 — CHAR_ERROR_DELETE. ACE: "Server could not delete your
/// character." Sent by <see cref="AcDream.Core.Net.Messages.CharacterDelete"/>'s
/// server-side handler on every rejection path.
/// </summary>
Delete = 0x06,
/// <summary>0x07 — CHAR_ERROR_NO_PREMADE. Retail-only; no ACE member.</summary>
NoPremade = 0x07,
/// <summary>0x08 — CHAR_ERROR_ACCOUNT_IN_USE. Retail-only; no ACE member.</summary>
AccountInUse = 0x08,
/// <summary>
/// 0x09 — CHAR_ERROR_ACCOUNT_INVALID. ACE: "The account name you
/// specified was not valid."
/// </summary>
AccountInvalid = 0x09,
/// <summary>
/// 0x0A — CHAR_ERROR_ACCOUNT_DOESNT_EXIST. ACE: "The account you
/// specified doesn't exist."
/// </summary>
AccountDoesntExist = 0x0A,
/// <summary>
/// 0x0B — CHAR_ERROR_ENTER_GAME_GENERIC. ACE: forces the player
/// back to character-select if in 3D mode; otherwise a no-op OK
/// popup.
/// </summary>
EnterGameGeneric = 0x0B,
/// <summary>
/// 0x0C — CHAR_ERROR_ENTER_GAME_STRESS_ACCOUNT. ACE: "You cannot
/// enter the game with a stress creating character."
/// </summary>
EnterGameStressAccount = 0x0C,
/// <summary>
/// 0x0D — CHAR_ERROR_ENTER_GAME_CHARACTER_IN_WORLD. ACE: "One of
/// your characters is still in the world. Please try again in a
/// few minutes."
/// </summary>
EnterGameCharacterInWorld = 0x0D,
/// <summary>
/// 0x0E — CHAR_ERROR_ENTER_GAME_PLAYER_ACCOUNT_MISSING. ACE:
/// "Server unable to find player account. Please try again
/// later."
/// </summary>
EnterGamePlayerAccountMissing = 0x0E,
/// <summary>
/// 0x0F — CHAR_ERROR_ENTER_GAME_CHARACTER_NOT_OWNED. ACE: "You do
/// not own this character." Sent by
/// <see cref="AcDream.Core.Net.Messages.CharacterRestore"/>'s
/// server-side handler when the delete grace window has expired.
/// </summary>
EnterGameCharacterNotOwned = 0x0F,
/// <summary>
/// 0x10 — CHAR_ERROR_ENTER_GAME_CHARACTER_IN_WORLD_SERVER. ACE:
/// "One of your characters is currently in the world. Please try
/// again later. This is likely an internal server error."
/// </summary>
EnterGameCharacterInWorldServer = 0x10,
/// <summary>
/// 0x11 — CHAR_ERROR_ENTER_GAME_OLD_CHARACTER. ACE: forces the
/// player back to character-select if in 3D mode; no-op
/// otherwise.
/// </summary>
EnterGameOldCharacter = 0x11,
/// <summary>
/// 0x12 — CHAR_ERROR_ENTER_GAME_CORRUPT_CHARACTER. ACE: "This
/// character's data has been corrupted. Please delete it and
/// create a new character."
/// </summary>
EnterGameCorruptCharacter = 0x12,
/// <summary>
/// 0x13 — CHAR_ERROR_ENTER_GAME_START_SERVER_DOWN. ACE: "This
/// character's starting server is experiencing difficulties.
/// Please try again in a few minutes."
/// </summary>
EnterGameStartServerDown = 0x13,
/// <summary>
/// 0x14 — CHAR_ERROR_ENTER_GAME_COULDNT_PLACE_CHARACTER. ACE:
/// "This character couldn't be placed in the world right now.
/// Please try again in a few minutes." Sent by
/// <see cref="AcDream.Core.Net.Messages.CharacterRestore"/>'s
/// server-side handler during a shutdown-in-progress race.
/// </summary>
EnterGameCouldntPlaceCharacter = 0x14,
/// <summary>
/// 0x15 — CHAR_ERROR_LOGON_SERVER_FULL. ACE: "Sorry, but the
/// Asheron's Call server is full currently. Please try again
/// later." Sent by both
/// <see cref="AcDream.Core.Net.Messages.CharacterDelete"/> and
/// <see cref="AcDream.Core.Net.Messages.CharacterRestore"/>'s
/// server-side handlers when the world is closed to non-advocates.
/// </summary>
LogonServerFull = 0x15,
/// <summary>0x16 — CHAR_ERROR_CHARACTER_IS_BOOTED. Retail-only; no ACE member.</summary>
CharacterIsBooted = 0x16,
/// <summary>
/// 0x17 — CHAR_ERROR_ENTER_GAME_CHARACTER_LOCKED. ACE: "A save of
/// this character is still in progress. Please try again later."
/// </summary>
EnterGameCharacterLocked = 0x17,
/// <summary>
/// 0x18 — CHAR_ERROR_SUBSCRIPTION_EXPIRED. ACE: "Your
/// subscription to this game has expired."
/// </summary>
SubscriptionExpired = 0x18,
/// <summary>
/// 0x19 — CHAR_ERROR_NUM_ERRORS. Retail's own count-of-errors
/// sentinel (the array-bound idiom, one past the last real code) —
/// never sent on the wire as an actual error. Kept for verbatim
/// completeness of the enum range; do not treat a received 0x19
/// as meaningful.
/// </summary>
NumErrors = 0x19,
}
public readonly record struct Parsed(uint RawErrorCode)
{
/// <summary>
/// Best-effort named view of <see cref="RawErrorCode"/>. A plain
/// enum cast never throws in C#, so this is safe even for values
/// retail never defined — always trust <see cref="RawErrorCode"/>
/// as the source of truth.
/// </summary>
public Code AsCode => (Code)RawErrorCode;
}
/// <summary>
/// Parse a CharacterError body. <paramref name="body"/> must start
/// with the 4-byte opcode (0xF659).
/// </summary>
public static Parsed Parse(ReadOnlySpan<byte> body)
{
int pos = 0;
uint opcode = ReadU32(body, ref pos);
if (opcode != Opcode)
throw new FormatException($"expected CharacterError opcode 0x{Opcode:X4}, got 0x{opcode:X8}");
uint errorCode = ReadU32(body, ref pos);
return new Parsed(errorCode);
}
private static uint ReadU32(ReadOnlySpan<byte> source, ref int pos)
{
if (source.Length - pos < 4) throw new FormatException("truncated u32");
uint value = BinaryPrimitives.ReadUInt32LittleEndian(source.Slice(pos));
pos += 4;
return value;
}
}