Introduction

This book explains the internal design of the Dark Ages 4.21 Stone client. It follows the program from process startup into its main loop, then separates the client into rendering, audio, input, user interface, file, event, and network systems.

Each subsystem is explained at two levels. The high-level section describes responsibilities, lifecycle, and data flow in approachable language. The code-level section follows function calls, decisions, addresses, arguments, and state. A function table closes each subsystem for readers who want a compact technical reference.

This is a living reverse engineering reference. Empty sections are intentional at the start of the project. They define where understood behavior will go without filling gaps with speculation.

Audience

The book is written primarily for people in the Dark Ages developer community. It assumes that many readers already understand the game, its terminology, and the broad shape of its clients and protocol. It does not assume that every reader is comfortable reading disassembly or following compiler-generated C++.

Ways to use this book

Understand a client system

Start with a subsystem’s high-level section to see its responsibilities, lifecycle, and connections to the rest of the client. Continue into the code-level section when you need the actual call path, arguments, decisions, and state.

Connect network behavior to client behavior

Protocol and networking pages connect message framing and fields to the client functions that parse, dispatch, and act on them. This path is intended for proxy and server developers who already know the wire side and want to understand what happens after a message reaches the client.

Investigate a quirk or version difference

Use subsystem headings and function tables to move from visible behavior to the responsible code. Where differences with another client version are established, the relevant page should state what changed and link the comparison to exact functions or data structures.

Implement a file format

Format pages provide field layouts, byte order, string rules, reader and writer behavior, validation, and parser quirks. They are intended to remain useful for formats that continue to appear in other clients and community tools.

Familiarity with C-like code is helpful for the technical sections. Platform-specific Windows, DirectX, compiler, and networking details are explained when they affect the client behavior being discussed.

Current state

Repository structure and documentation conventions are established. Subsystem behavior has not yet been mapped.

Scope and Method

Scope

The project covers behavior implemented by the analyzed Darkages.exe, including:

• Process initialization, configuration, main loop, state changes, and shutdown
• Rendering, surface management, palette behavior, sprites, text, and presentation
• Sound effects, music, resource lifetime, and playback control
• Keyboard, mouse, Win32 messages, and internal event delivery
• File lookup, archive or container access, decoding, parsing, and serialization
• Socket lifetime, connection states, packet framing, message dispatch, and field serialization
• Byte transformations such as XOR when their exact behavior and order are understood
• Compiler and runtime mechanisms when they materially explain application behavior

Compatibility wrappers such as cnc-ddraw are outside the client architecture unless their interaction reveals a client requirement worth documenting.

Clean-room policy

The repository contains original documentation, diagrams, tables, and limited explanatory pseudocode derived from analysis. It does not contain the executable, supporting DLLs, game assets, private runtime captures, an IDA database, or reconstructed source code.

Local copies may be used as analysis inputs. Proprietary materials must never be committed. The ignored .local/ directory may hold a private working IDA database.

Two levels of explanation

Every subsystem chapter has a high-level section and a code-level section.

The high-level section explains responsibilities, lifecycle, data flow, and interactions with other parts of the client. It should be understandable without following assembly or decompiler output.

The code-level section follows the real implementation. It records call trees, function addresses, prototypes, arguments, return values, branches, state changes, important data, and cleanup paths. The chapter ends with a function table for readers who need a compact technical reference.

What belongs in the book

The book contains behavior confirmed through direct code analysis or supported with high confidence when code patterns and observed behavior agree. Speculative leads remain in local notes or tentative IDA names until they are understood well enough to explain clearly.

The decompiler is a useful view of the program, but its types and reconstructed control flow are not automatically correct. Disassembly and call sites should be checked whenever signedness, ownership, object layout, calling convention, or optimizer behavior affects the explanation.

Address and naming conventions

A function reference uses the form Darkages.exe:0x00401234, current IDA name net_receive_packet. Unless a page says otherwise, addresses are virtual addresses from the analyzed image rather than file offsets or RVAs.

IDA names are descriptive research names. They are not presented as original source symbols. The function address remains the stable reference if a name improves later.

Legal Disclaimer

Ownership

Dark Ages and all original game software, code, artwork, music, sound, text, characters, names, logos, trademarks, and related materials are the property of their respective copyright and trademark owners. Nothing in this project transfers, limits, or challenges those rights.

The contributors claim authorship only over the original documentation, diagrams, research notes, and explanatory pseudocode created for this project. References to the game and its behavior are included only where needed to explain the research.

Independent project

This is an independent and unofficial research project. It is not affiliated with, sponsored by, approved by, or endorsed by the developers, publishers, operators, or rights holders of Dark Ages.

Purpose and fair use

This project is undertaken in good faith for noncommercial education, scholarship, preservation, commentary, and interoperability research. The maintainers believe that the limited analysis, factual descriptions, and necessary references presented here are consistent with fair-use principles under 17 U.S.C. Section 107.

Fair use is determined from the facts of each use. An educational or noncommercial purpose does not automatically make every use fair. The U.S. Copyright Office Fair Use Index provides general information and examples, but this project does not offer legal advice or guarantee that every possible use of its material will qualify as fair use.

What is not distributed

This repository does not distribute the game executable, supporting DLLs, game assets, music, artwork, private packet captures, IDA databases, license material, or reconstructed proprietary source code. Contributors must never force-add or commit such material. A local IDA database may remain in the ignored .local/ workspace described in the README.

The documentation is not a substitute for obtaining the game or any other copyrighted work through lawful means. Users are responsible for ensuring that their own research, implementations, and distribution choices comply with applicable law and any agreements that apply to them.

Rights-holder concerns

A rights holder who believes this repository contains material that should not be present may contact the repository maintainers through the GitHub project. Please identify the material and explain the concern so it can be reviewed promptly.

Client Overview

This chapter connects the major runtime systems and explains how control and data move through the client as a whole.

High-level architecture

This section will describe the top-level application state, major subsystem boundaries, screen or game states, shared services, thread ownership, and the order in which input, networking, game logic, audio, and rendering are processed.

The client architecture has not been mapped yet.

Code-level coordination

This section will begin at the application entry point and follow the functions that construct, connect, update, and destroy the major systems. It will record global state, top-level objects, dispatch points, main-loop decisions, and cross-subsystem calls.

No top-level call tree is documented yet.

Function table

UI, Input, and Packet Flows

This page connects visible in-game UI behavior to the internal Event system and the client and server packet actions that drive it. The most important distinction is ownership. Some panes are persistent and are only shown or hidden. Some are allocated in response to a server packet. Bulletin and mail use a longer-lived session object that repeatedly replaces its active child dialog.

The packet action byte is the first byte of the decoded logical packet. Packet offsets in this page are relative to that action byte unless stated otherwise.

High-level operation

End-to-end architecture

flowchart LR
    win["Win32 mouse and key messages"] --> queue["EventMan input queue"]
    queue --> input["Pane Event types 0 through 8"]
    input --> local["Pane mouse and key handlers"]
    local --> transition["Create, show, hide, or remove pane"]
    local --> builder["Client packet builder"]
    builder --> send["net_c_queue_send"]
    send --> encode["Sequence, XOR, and TCP frame"]
    encode --> server["Game server"]

    server --> tcp["TCP frame receive and XOR decode"]
    tcp --> socket["Pane socket Event type 9"]
    socket --> map["MapPane and registered child handlers"]
    map --> parser["Server-action parser"]
    parser --> transition
    parser --> state["Persistent pane or dialog fields"]
    state --> transition

    timer["Pane timers"] --> delay["Spell delay controller"]
    delay --> builder

Win32 messages do not call game panes directly. win_main_window_proc queues input in EventMan. The event worker converts it to internal Events, and the dispatcher calls the relevant pane virtual handler. Client packet builders then submit logical packets to net_c_queue_send.

The reverse path begins when the Socket worker completes and decodes a frame. EventMan creates Event type 9 and traverses the registered pane hierarchy. MapPane owns most in-game server actions, while persistent child panes such as the equipment, skill, and spell panes claim the actions that update their own state.

Pane transition models

Server actions that affect UI

No established server action directly selects the persistent A/S/D/F/G content pane. Server status, skill, spell, and equipment actions update those panes even while another content pane is visible.

Client actions that affect UI or packets

Bulletin and mail child replacement

The session owns a ten-entry dialog history array beginning at session +0xF8, the current index at +0xF5, and the active child at +0x120. Each successful response constructs a new dialog, detaches or queues deletion of superseded children, stores the new child in the history, sets the child’s back-pointer to the session, and invokes the child’s class-specific build/register virtual.

Article-list and mail-list responses are accepted only while the session’s request-wait flag at +0x124 is set. This prevents an unsolicited list response from replacing the active child.

Spell-delay sequence

The spell slot builds the final action before the delay begins. The delay controller copies that logical packet into its own buffer and records its length, so the final timer callback does not reconstruct the cast.

sequenceDiagram
    participant Input as Spell slot input
    participant Delay as Spell delay controller
    participant Queue as Client send queue
    participant Server as Server

    Input->>Delay: Hold packet 0x0F, slot
    alt delay is zero
        Delay->>Queue: Queue held 0x0F packet
    else delay is positive
        Delay->>Queue: CSpellDelayRequest 0x4D, seconds
        loop once per second
            Delay->>Queue: CSpellDelaySay 0x4E, configured phrase
            Delay->>Delay: Schedule next 1000 ms timer
        end
        Delay->>Queue: Queue held 0x0F packet
    end
    Queue->>Server: Sequence, XOR, and frame each logical packet

The phrases are loaded from SpellBook.cfg and matched against the current spell name. A runtime packet hook that only watches the initial mouse event will therefore miss the later timer-owned final send.

Runtime observation roots and useful fields

The Runtime UI Memory Map gives the complete read-only Screen and Event tree traversal, vtable discriminators, field layouts, and stable snapshot procedure.

The virtual addresses below assume image base 0x00400000. External tools should use loaded_module_base + RVA.

These pointers are observation roots, not synchronization primitives. Dialog removal may use deferred deletion, and the Screen and Event registries can change while another thread reads them. Validate the pane vtable and take a stable registry snapshot before following dynamic children. Writing a visible flag alone is unsafe because Screen composition, Event eligibility, capture, timers, and owner pointers must agree.

Code-level flow

Persistent content selection

ui_game_buttons_handle_key_event accepts Event type 8 and maps A/S/D/F/G to indices 0 through 4. ui_game_buttons_select_content dispatches to the relevant selector. A selector hides the previous pane through vslot +0x18, shows the new pane through +0x14, stores it at owner +0x124, updates the associated button layout, and redraws.

Equipment has an additional same-pane branch. ui_game_buttons_select_inventory calls ui_pane_is_visible. A visible current equipment pane is hidden. A hidden current pane causes net_c_send_self_look to queue action 0x2D, then the pane is shown. This order means the old equipment data can become visible before the asynchronous SSelfLook reply arrives.

Equipment and self-look

ui_equip_pane_ctor publishes ui_equip_pane, while its destructor clears the pointer. ui_equip_pane_handle_server_packet claims only actions 0x37, 0x38, and 0x39.

ui_equip_pane_add_item reads the slot at packet +1, a big-endian identifier at +2, the name length at +4, and name bytes at +5. ui_equip_pane_remove_item reads the slot at +1 and clears the corresponding fields. ui_equip_pane_apply_self_look replaces the larger appearance, identity, and legend state before invalidating the pane.

Skill and spell inventories

ui_skill_inventory_handle_server_packet dispatches 0x2C, 0x2D, and 0x3F. ui_spell_inventory_handle_server_packet dispatches 0x17, 0x18, and 0x3F. Both add handlers first remove an existing pane at the packet-selected index, then allocate a class-specific slot object and add it to both registries. Both remove handlers perform the inverse sequence and clear the slot pointer.

ui_skill_slot_handle_mouse_event constructs SkillBookDialog on right-button down inside the slot. The activation branch sends the optional action 0x4E phrase and then net_c_send_use_skill, which emits [0x3E, slot].

ui_spell_slot_handle_mouse_event constructs SpellBookDialog on right-button up inside the slot. Its activation dispatcher selects immediate cast, targeted cast, or an input dialog from the spell type at slot +0xF8. ui_spell_slot_begin_cast builds [0x0F, slot] and passes it to ui_spell_delay_begin. A nonzero configured delay sends action 0x4D, installs a 1000 ms callback, emits action 0x4E phrases, and releases the held cast in ui_spell_delay_handle_timer.

Bulletin and mail

ui_window_buttons_show_bulletin_session allocates 0x12C bytes and calls ui_bulletin_session_ctor in client-opened mode. The constructor publishes ui_bulletin_session, adds and registers the session below BackgroundPane, then calls net_c_send_bulletin_start.

An unsolicited SBulletin reaches ui_map_handle_bulletin. When no session exists and the packet flag allows creation, the map handler allocates the same object in server-opened mode and passes the original packet to the constructor. When a session already exists, its registered socket handler claims the packet directly.

ui_bulletin_session_process_packet reads packet +1 and dispatches to the five child processors. Each processor handles history cleanup, attaches the new child, sets the session back-pointer, and calls the child build virtual. Article and mail identifiers of zero produce a small “No More” dialog instead of an Article or Mail child.

Users, paper, and server menus

Window button Q calls ui_window_buttons_show_option_pane, which allocates 0x578 bytes and constructs OptionPane. ui_option_pane_ctor installs ui_option_pane_vtable, builds the controls, and adds and registers the pane below BackgroundPane. Its mouse, key, socket, and timer vslots are all class-specific. Option controls call net_c_send_user_setting; a registered OptionPane claims SSelfSaveOk and constructs the local confirmation dialog. Its X shortcut constructs the exit-wait pane, beginning the two-step CQuit and SReconnect orderly-exit exchange.

Window button E always calls net_c_send_who_request. On first use it also allocates Users Dialog Pane, publishes ui_users_dialog_pane, adds and registers it, and immediately calls vslot +0x18 to keep it hidden. ui_map_handle_show_users later obtains that static object, calls ui_users_dialog_parse_server_list, and then ui_users_dialog_show.

ui_map_handle_show_paper allocates Paper in mode 1. SEnterEditingMode uses the same constructor in mode 0. Both parsers eventually call ui_paper_dialog_build_content, which creates the controls, adds the dialog below BackgroundPane, and registers it.

ui_paper_dialog_handle_completion reads the text control, changes carriage returns to tab bytes, serializes CExitEditingMode, and closes the dialog when its completion conditions permit submission. net_c_send_exit_editing_mode uses the same packet layout without owning the close transition.

ui_map_handle_screen_menu allocates and constructs one full-screen menu pane for action 0x2F. Menu interaction functions serialize CMenuCode action 0x39. ui_map_handle_pursuit_menu reads packet +1 and allocates one of seven message classes. The two friendly question class names are proven by constructor diagnostics and vtable installation. Their answer virtuals serialize CMessage action 0x3A.

Function table

Startup and Shutdown

The client uses a conventional Win32 process entry and a blocking GetMessageA loop, but its recurring game and timer work does not run in that loop. WinMain owns process checks, the main window, subsystem construction, and orderly teardown. A separate internal event worker supplies periodic callbacks. See Internal Event Routing for that worker.

High-level lifecycle

Process entry and window class

Windows enters the executable through the Microsoft Visual C++ runtime stub. The stub initializes the heap, multithreading runtime, standard I/O, command-line arguments, environment, and C initializers. It derives the command tail and the initial show command from STARTUPINFOA, obtains the module handle, and calls app_win_main. It always passes a null previous_instance, so the window-class registration path is taken in normal execution.

The client registers the ANSI window class DAClass with these established properties:

If the first RegisterClassA call fails, the code calls RegisterClassA a second time while forming a diagnostic assertion, sets app_error_code to 1, and returns 0 from app_win_main. The second call does not recover startup.

Preflight checks and single-instance enforcement

app_win_main performs the following checks in order before it creates the window:

1. It examines three values under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\RunServices: the unnamed default value, " .EXE" with a leading space, and "UMGR32.EXE". The key is requested with KEY_ALL_ACCESS. For the first value whose returned data begins with a nonzero byte, the client displays a message box with type 0x44. Selecting IDNO deletes that value and stops startup. Any other response permits startup. Failure to open the key permits startup.
2. It checks a process-name list and two files. A match displays a yes-or-no prompt. Selecting IDNO returns 0 and stops startup; the other response continues the scan.
3. It calls FindWindowExA(NULL, NULL, "#32770", "Brothers Speeder"). Finding that top-level dialog stops startup without creating the client window.
4. It creates the initially owned mutex Nexon.SingleInstance. ERROR_ALREADY_EXISTS causes an immediate _exit(0). A mutex creation failure with another error is not treated as fatal, so this check fails open.

The process scan dynamically resolves CreateToolhelp32Snapshot, Process32First, and Process32Next from Kernel32.DLL. It runs on Windows 9x, or on the NT platform when the major version is at least 5. Executable paths are compared case-insensitively by suffix against this exact list:

The implementation passes a local PROCESSENTRY32A to Process32First without first assigning its required dwSize field. It also does not close the process snapshot handle. Failure to load the library, resolve an entry point, create the snapshot, or begin enumeration skips to the file checks and therefore permits startup unless a later check rejects it.

The file checks use fopen(..., "rb") on <system-directory>\grcframe.exe and <windows-directory>\KeyHook.dll. Each existing file produces its own yes-or-no prompt.

These checks are documented as observed control flow. The runtime strings used for several prompts do not establish a broader intent for the checks.

Window creation

After the checks pass, app_win_main creates a topmost Dark Ages window of class DAClass. The extended style is WS_EX_TOPMOST. The style value 0x90880000 combines WS_POPUP, WS_VISIBLE, WS_BORDER, and WS_SYSMENU. Both coordinates are CW_USEDEFAULT, and the requested outer size is 642 by 482 pixels. The client later creates a 640 by 480 screen pane for presentation.

The return from CreateWindowExA is stored in app_main_window but is not validated. The code still calls SetForegroundWindow, ShowWindow, UpdateWindow, and app_initialize if the handle is null.

Subsystem initialization

app_initialize runs only after the window creation attempt. Its established setup order is:

1. Fill a 1024-byte global buffer with ASCII spaces.
2. Read physical-memory status and request a process working-set range from half of physical memory to all physical memory. Return values are ignored.
3. Remove the IME context from the main window with ImmAssociateContext(window, NULL).
4. Set the current directory from the executable path parsed out of the raw command line.
5. Set the process priority class to HIGH_PRIORITY_CLASS, create the client memory manager, and seed rand with time(NULL).
6. Open Legend.dat, seo.dat, and khan.dat. All three must open for that archive set to be accepted. Otherwise the client tries the single fallback archive DarkAges.dat.
7. Create the rendering and media singletons, initialize rendering support, and load Skill.tbl.
8. Construct the remaining service objects, the sound manager, and configuration. The sound path opened here is .\Music\1.mp3.
9. If English.nfo exists, construct the configuration from Darkages.cfg; otherwise use Legend.cfg.
10. Create the deferred-deletion queue, the 640 by 480 8-bit screen pane using Legend.pal, the internal event dispatcher, and the separate event_manager_instance. Both workers are resumed during this phase.
11. Register the screen pane with the dispatcher, establish the 640 by 480 screen rectangle, load Darkages.prf or Legend.prf according to configuration byte +0x8D, and create the first terminal pane.

Most constructors communicate failure through the process-wide app_error_code. app_initialize contains staged cleanup branches for partial construction. When it returns, app_win_main checks the error code again and returns 0 instead of entering the message loop if it is nonzero.

The missing-archive path is different. It deletes the two early rendering or media singletons, shows two error boxes, posts WM_QUIT, and calls _exit(0). The first box labels GetCommandLineA output as the current directory, even though it did not call GetCurrentDirectoryA. The direct _exit bypasses app_shutdown.

Command-line directory parsing

app_set_working_directory_from_command_line does not use the command_line argument supplied to app_win_main. It calls GetCommandLineA again and applies this parser:

• If any double quote exists, copy from the second command-line byte through the byte before the last quote.
• Otherwise, copy up to the first space.
• If there is no space, copy the complete command line.
• Find the last backslash in the copied path, terminate the string there, and pass the directory to SetCurrentDirectoryA.

The helper ignores the SetCurrentDirectoryA result. Its local path buffer is fixed at approximately 256 bytes and the copies have no length check. Because it uses the last quote anywhere in the raw command line and always starts the quoted case at byte 1, quoted arguments after the executable can confuse the result.

Message pump and activation

Immediately before the first GetMessageA, app_win_main marks the window active and calls ui_screen_pane_activate if the screen pane exists. The message loop is blocking and unfiltered. It does not render or advance timers directly:

for (;;) {
    int get_message_result;

    get_message_result = GetMessageA(&message, NULL, 0, 0);
    if (get_message_result == 0) {
        break;
    }

    if (message.message == WM_QUIT || app_shutdown_requested == 1) {
        app_shutdown_requested = 1;
        break;
    }

    TranslateMessage(&message);
    DispatchMessageA(&message);
}

The explicit WM_QUIT comparison is normally redundant because GetMessageA returns zero for WM_QUIT. The code tests only for zero, so a GetMessageA error return of -1 is treated as a message and passed to TranslateMessage and DispatchMessageA. The shutdown flag is examined only after GetMessageA returns, so changing the flag alone does not wake a blocked loop.

win_main_window_proc connects the pump to client behavior. Relevant lifecycle cases include:

• WM_DESTROY calls PostQuitMessage(0) and returns 0.
• An inactive WM_ACTIVATEAPP path minimizes the window, beeps, and clears app_window_active.
• The active WM_ACTIVATEAPP path repeats the Brothers Speeder window check. A match sets the shutdown flag and posts quit or close messages. Otherwise it restores the window, sets the active flag, and calls ui_screen_pane_activate.
• WM_USER + 2 routes asynchronous Winsock notifications, as described in Networking.
• Keyboard, mouse, palette, and client-specific messages are dispatched in the same procedure. The complete message table and both application-defined messages are documented in Input and Windows Events. Unknown messages go to DefWindowProcA.

Periodic timer processing is independent of this pump. The event worker waits with a 1 millisecond timeout and invokes the dispatcher tick. See Worker and timer lifecycle.

Normal and abnormal shutdown

Normal shutdown begins when GetMessageA returns zero or the loop observes app_shutdown_requested. app_win_main waits for a fixed 200 milliseconds, calls app_shutdown, closes and clears app_single_instance_mutex, and returns message.wParam. The CRT entry then passes that result to _exit.

For a normal WM_QUIT, message.wParam is the quit code. If the shutdown flag stops the loop while a different message is current, the function returns that message’s wParam instead.

app_shutdown is an ordered, null-safe deletion sweep. It closes the archive managers first, then destroys the constructed service singletons and global objects. Confirmed objects in the sweep include media and audio support, screen and UI state, configuration and preferences, the event dispatcher, the deferred-deletion queue, network-owned state, and the memory manager. Each owned global is set to null after deletion.

Deleting the event dispatcher releases its pane and timer containers, calls timeEndPeriod, and then invokes the worker base destructor. That base destructor uses TerminateThread, closes the worker and wait handles, and destroys queued synchronization state. It does not request a cooperative worker exit or join the thread. The full timing teardown is documented in Internal Event Routing.

Several exits do not run this sweep:

Code-level flow

CRT handoff

1. Darkages.exe:0x004C62A5 app_crt_entry installs the runtime exception frame and initializes the heap, thread runtime, standard I/O, arguments, environment, and C initializers. Heap initialization failure exits with code 0x1C; multithreading initialization failure exits with code 0x10.
2. It obtains the command tail from the CRT helper, derives show_command from STARTUPINFOA when STARTF_USESHOWWINDOW is present or uses SW_SHOWDEFAULT, and calls app_win_main(GetModuleHandleA(NULL), NULL, command_tail, show_command).
3. A normal return calls _exit(win_main_result). The exception branch calls __XcptFilter and then the CRT exception exit routine.

app_win_main

1. Clear app_main_window.
2. When previous_instance == NULL, assemble and register DAClass. A registration failure sets app_error_code = 1 and returns 0.
3. Save instance in app_instance.
4. Call app_check_runservices_entries. Return 0 from app_win_main if it returns 1.
5. Call app_check_conflicting_software. Return 0 if it returns 0.
6. Call win_top_level_window_exists("#32770", "Brothers Speeder"). Return 0 on a match.
7. Create Nexon.SingleInstance. Call _exit(0) when GetLastError() is ERROR_ALREADY_EXISTS.
8. Create and show the main window, set app_window_active = 1, and call app_initialize.
9. If app_error_code != 0, emit the diagnostic and return 0.
10. Activate the screen pane and enter the GetMessageA loop.
11. On loop exit, wait 200 milliseconds, call app_shutdown, close the mutex, and return the current MSG.wParam.

The command_line parameter is not read by this function. Directory setup re-reads the complete process command line.

Initialization and failure ownership

Darkages.exe:0x0045CCA0 app_initialize has no meaningful return value. Construction success is represented by nonnull globals and app_error_code == 0. Each major allocation is followed by an error check. Later failure labels delete the objects that were already created, proceeding backward through the partial dependency graph.

The successful path creates event_dispatcher with event_dispatcher_ctor, calls util_thread_queue_start to resume its suspended worker, then constructs event_manager_instance with event_manager_ctor and starts that worker. It registers ui_screen_pane with the dispatcher only after both exist.

The archive failure branch at Darkages.exe:0x0045CE6C does not join the common staged cleanup. It destroys the two early graphics or media objects, displays the archive errors, posts a quit message, and reaches _exit(0) at Darkages.exe:0x0045CF31.

Window messages and loop termination

Darkages.exe:0x0045BDC0 win_main_window_proc is the only window procedure installed for DAClass. DispatchMessageA reaches it for queued messages, while some client paths also post messages directly to app_main_window. Its WM_DESTROY case supplies the normal WM_QUIT. Other fatal paths set app_shutdown_requested and post a message so the blocking loop can observe the flag.

Darkages.exe:0x0049D790 ui_screen_pane_activate sets a screen-pane active field at +0x568, resets a presentation counter to 10, restores the pane’s render object through a virtual call, and invokes two screen update helpers. It is called once before the first GetMessageA and again after an active WM_ACTIVATEAPP transition.

Teardown

Darkages.exe:0x0045B8F0 app_shutdown checks each singleton or global before calling its deleting destructor. It then clears the corresponding global. The event dispatcher is deleted after the main screen, configuration, preference, and several UI service objects, but before the deferred-deletion queue and final media and memory singletons. No return code is propagated from teardown.

Function table

Rendering

The rendering subsystem covers graphics initialization, drawing primitives, surface ownership, sprite composition, palette and color handling, text, frame assembly, and final presentation.

High-level operation

This section will explain how a frame moves from game and user interface state to the displayed image. It will be divided into graphics initialization, resource and surface management, scene composition, user interface drawing, presentation, lost-surface recovery, and shutdown.

Rendering behavior has not been mapped yet.

Code-level flow

This section will trace the graphics entry points and their call trees. It will record DirectDraw interfaces, object ownership, function arguments, coordinate systems, clipping decisions, layer order, palette behavior, frame timing, presentation calls, and error recovery.

No rendering call tree is documented yet.

Function table

Audio

The audio subsystem covers sound initialization, music, sound effects, resource loading, playback, volume control, and shutdown.

High-level operation

This section will explain how audio resources enter the client, how music and sound effects are selected, what owns active playback, and which game or user interface events control sound.

Audio behavior has not been mapped yet.

Code-level flow

This section will trace audio initialization and playback call trees. It will record the Windows or DirectX interfaces in use, function arguments, resource lookup, caching, channel or buffer selection, volume calculations, stop behavior, failure handling, and cleanup.

No audio call tree is documented yet.

Function table

Input and Windows Events

The DAClass window procedure is the boundary between the Win32 message queue and the client’s asynchronous event system. It handles a fixed set of 15 message values. Keyboard and mouse messages update immediate window or screen state, then enter the EventMan worker queue. Activation, palette, socket, virus-check, and destruction messages remain on the window thread.

High-level operation

Message-pump boundary

app_win_main blocks in GetMessageA, calls TranslateMessage, and sends each retrieved message through DispatchMessageA. The registered DAClass procedure is win_main_window_proc. This is an event-driven pump, not the rendering or game-tick loop. Timer work runs on the event-dispatcher worker described in Internal Event Routing.

The window procedure returns 0 for every message it recognizes. All other messages go to DefWindowProcA. This includes WM_CLOSE, so the default procedure destroys the window and the resulting WM_DESTROY case posts WM_QUIT. It also includes WM_CHAR, WM_PAINT, WM_SETFOCUS, WM_KILLFOCUS, WM_TIMER, and WM_QUERYNEWPALETTE. TranslateMessage can therefore produce a WM_CHAR, but the client has no explicit text-message branch here.

Complete handled-message table

All handler locations below are inside Darkages.exe:0x0045BDC0 win_main_window_proc.

The last two rows are the only application-defined messages recognized by this window procedure.

Mouse input and message time

Every handled mouse message first performs the same software-cursor update under the critical section at screen-pane offset +0x534. The procedure restores the old cursor area with sub_49D850, calls ui_screen_pane_set_cursor_position, then draws or presents the new cursor area through the entry at sub_49D120. This occurs before EventMan input blocking is checked.

Coordinate handling has several exact quirks:

• The low word of lParam is zero-extended. Values at least 640 become 639. The apparent negative clamp cannot be reached after zero extension.
• The high word is obtained with a logical shift and is neither sign-extended nor clamped.
• WM_MOUSEWHEEL goes through the same coordinate path. Windows supplies wheel coordinates in screen space, but this procedure does not call ScreenToClient before treating them like the other mouse coordinates.

Each message then calls GetMessageTime and places that 32-bit timestamp in the EventMan work record. Mouse movement allocates and transfers ownership of an eight-byte pair stored internally as (y, x), matching the screen-pane cursor calls. Button messages use the most recently stored coordinates. The worker divides a signed wheel delta by 120 before dispatching its mouse Event.

EventMan field +0x4B0 bit 0 blocks movement, wheel, button-down, and key-down queueing. Releases are deliberately different: left-button up, right-button up, and key up still queue while input is blocked. Button state is held at +0x4B4, with bit 0 for left and bit 1 for right.

The worker recognizes double-clicks itself rather than relying on WM_LBUTTONDBLCLK or WM_RBUTTONDBLCLK, neither of which is handled. It compares the new down timestamp with its stored timestamp and requires total horizontal plus vertical movement of at most two pixels. It dispatches mouse subtypes 1 and 2 for left single and double down, 3 for left up, 4 and 5 for right single and double down, 6 for right up, and 7 for wheel. Mouse movement uses subtype 0.

Keyboard input

The client queues physical scan codes rather than the wParam virtual-key value. Bits 16 through 23 of lParam supply the scan byte. If KF_EXTENDED bit 24 is set, the procedure adds 0x80 and keeps the low byte. A resulting zero is ignored. Repeat count and previous-key-state fields do not suppress repeated key-down messages.

uint8_t input_scan_code(uint32_t key_data)
{
    uint8_t scan_code = (uint8_t)(key_data >> 16);

    if ((key_data & 0x01000000U) != 0) {
        scan_code = (uint8_t)(scan_code + 0x80U);
    }

    return scan_code;
}

WM_SYSKEYDOWN and WM_SYSKEYUP contain one special path. If wParam is VK_F4, the Alt-context bit 29 is set, and Darkages.exe:0x0043DE20 returns a nonnull UI object, the code rewrites the scan byte to 0x10, clears the extended and Alt-context bits, and preserves selected high transition bits. The down and up messages then continue through their ordinary paths. The code establishes the remap but does not establish its original design intent.

On the EventMan worker, event_dispatch_key_down marks the scan code pressed, applies the client’s scan-code mapping and modifier tables, and dispatches key subtype 8 when the mapped value is nonzero. event_update_key_up clears pressed and modifier state but does not dispatch a key-up Event to panes.

Activation, palette, and shutdown messages

The application-level activation message is WM_ACTIVATEAPP, not WM_ACTIVATE. A zero wParam invokes a render-object virtual method, minimizes the window with SW_MINIMIZE, emits a 2000 Hz beep for 100 ms, and clears app_window_active. A nonzero wParam repeats the Brothers Speeder top-level-window check. A match sets app_shutdown_requested, posts quit, and posts WM_CLOSE. Otherwise the client restores a 640 by 480, 8-bit presentation configuration, uses SW_RESTORE, sets app_window_active, and calls ui_screen_pane_activate.

WM_PALETTECHANGED is ignored when the sender in wParam is the main window or when no screen pane exists. Otherwise render_screen_pane_load_palette reads 256 RGB entries from legend.pal, preserves the system-reserved palette entries at both ends, applies the palette, and marks the screen palette dirty. The procedure then calls the small screen-pane apply entry at Darkages.exe:0x0049D0E0.

WM_DESTROY only posts WM_QUIT. It does not perform subsystem cleanup itself. The message loop returns to app_win_main, which calls app_shutdown as described in Startup and Shutdown.

Application-defined messages

WM_USER + 2 is registered by net_connect_configured_server through WSAAsyncSelect with FD_READ | FD_CLOSE. win_main_window_proc uses only LOWORD(lParam): FD_READ calls net_queue_receive, and FD_CLOSE calls net_handle_disconnect. Other network-event values are ignored. The procedure also ignores the socket in wParam and the WSAGETSELECTERROR value in the high word of lParam. The receive and framing path is documented in Networking.

WM_USER + 0x2046 belongs to the process/module virus-check worker. app_virus_check_module_callback copies the first reported module name into the 256-byte app_virus_report_module buffer and posts the message with that pointer in wParam. The window procedure formats it as a quoted name. A zero wParam instead inserts app_virus_check_failure_detail into a Korean format string whose meaning is, “Could not perform the virus scan. ( %s ) Would you like to continue?”

The report is sent to the first available target in this order: the object returned by sub_4AD130, dword_4F51AC, then receiver. The procedure allocates a 0x554-byte report object and initializes it with sub_498CE0. If no target exists, it calls MessageBoxA with caption LOD and type MB_OK. The subsequent IDCANCEL shutdown test is not reachable through an ordinary MB_OK message box, although the code contains it.

Code-level flow

Dispatch and default processing

app_win_main
  -> GetMessageA
  -> TranslateMessage
  -> DispatchMessageA
      -> win_main_window_proc
          -> explicit handler for one of 15 message values
          -> DefWindowProcA for every other value

Darkages.exe:0x0045BDC0 win_main_window_proc is a direct comparison chain rather than a jump table. Its four parameters have the normal WNDPROC contract. Every explicit branch returns zero.

Mouse queue and worker path

win_main_window_proc
  -> sub_49D850
  -> ui_screen_pane_set_cursor_position
  -> sub_49D120
  -> event_manager_get_instance
  -> GetMessageTime
  -> event_queue_mouse_*                  work code 4 through 9
      -> util_thread_queue posting path
          -> event_process_work_item
              -> event_dispatch_mouse_*   Event subtype 0 through 7
                  -> event dispatcher pane routing

Keyboard queue and worker path

WM_KEYDOWN or WM_SYSKEYDOWN
  -> scan-code normalization
  -> event_queue_key_down                 work code 0x0A
      -> event_process_work_item
          -> event_dispatch_key_down      key subtype 8 when mapping succeeds

WM_KEYUP or WM_SYSKEYUP
  -> scan-code normalization
  -> event_queue_key_up                   work code 0x0B
      -> event_process_work_item
          -> event_update_key_up          state update, no pane Event

event_dispatch_key_down stores pressed state in the per-scan-code table beginning at EventMan offset +0x390. It combines the active modifier byte at +0x490 with mapping tables at +0x90, +0x190, and +0x290. One internal mapped value, 0x88 with state bit 0 set, also sets app_shutdown_requested and posts WM_CLOSE before the key Event is dispatched.

Socket and virus-check messages

net_connect_configured_server
  -> WSAAsyncSelect(..., WM_USER + 2, FD_READ | FD_CLOSE)
      -> win_main_window_proc
          -> net_queue_receive
          -> net_handle_disconnect

app_virus_check_thread
  -> module scanner callback
      -> app_virus_check_module_callback
          -> PostMessageA(..., WM_USER + 0x2046,
                          app_virus_report_module, 0)
              -> win_main_window_proc
                  -> active UI report receiver
                  -> MessageBoxA fallback

The module callback posts only the first infected-module name because it first requires app_virus_report_module[0] == 0. It also clears the virus-check continuation flag after posting, which causes the worker’s loaded scanner callbacks to stop their traversal.

Function table

UI Panes and Registries

The client represents screens, dialogs, controls, and many temporary overlays as Pane-derived objects. A pane participates in two independent hierarchies. The Screen composition tree records placement and parent-child drawing relationships. The event-dispatch tree records which panes receive mouse, keyboard, socket-packet, and timer callbacks. A pane may appear in both trees, but the trees have different nodes, payloads, and ownership.

The executable does not expose usable Microsoft C++ class RTTI for these pane types. Enumeration instead starts from the common Pane virtual layout. Every confirmed pane-compatible virtual table contains ui_pane_register_events at slot +0x30 and ui_pane_unregister_events at +0x34. Cross-references to the registration slot identify 173 compatible tables. These include controls and construction-state tables as well as full visible screens, so the count is not a count of 173 independently visible windows. The complete address and handler inventory is in Pane Virtual Table Inventory.

High-level operation

Two pane hierarchies

The Screen composition tree answers where a pane is placed and which panes are below it. ui_screen_registry is a static pointer to its heap registry. The root node holds ui_screen_pane, the persistent 640 by 480 surface pane. Adding a pane supplies a rectangle, an optional pane to place it in front of, and an optional parent pane. Removing a node also removes its child hierarchy.

The event-dispatch tree answers which panes are eligible for input and internal events. It is reached through event_dispatcher + 0x68. Mouse events use virtual slot +0x38, keyboard events use +0x3C, socket-packet events use +0x40, and due pane timers use +0x44. Event traversal visits a node’s children before the node itself. Mouse coordinates are adjusted into pane-relative coordinates during traversal.

The two registrations are deliberately separate. ui_pane_add_to_screen does not register event handling, and ui_pane_register_events does not add anything to the drawing tree. Constructors and transitions normally perform both operations explicitly.

Pane lifecycle

app_initialize first creates the Screen registry, constructs ui_screen_pane, and makes that pane the Screen root. It then creates and starts the event dispatcher and registers the screen pane as the initial event receiver.

The first substantial screen is TerminalPane. Its constructor publishes ui_terminal_pane, adds the pane below ui_screen_pane, registers it in the event hierarchy, and adds its controls. A successful terminal bootstrap packet causes ui_terminal_handle_server_packet to remove the terminal child, unregister and remove the terminal pane, create MainMenuPane, add and register the main menu, send the bootstrap/version traffic, and delete the terminal object. The terminal destructor clears its static pointer.

MainMenuPane publishes ui_main_menu_pane. Its server handler can create ServerSelectDialogPane as a registered child dialog. The dialog destructor explicitly unregisters the pane and removes it from Screen before destroying its dialog state.

The transition into the game reaches ui_main_menu_create_game_panes. It creates the persistent in-game BackgroundPane and MapPane, publishes ui_background_pane and ui_map_pane, and builds the larger child-pane graph below them. The map pane becomes the principal socket-packet receiver for in-game server actions.

Temporary controls follow the same rule. The game-buttons owner stores each allocated skill or spell pane in an indexed heap-pointer array, adds it below the owner in Screen, and registers it below the owner in the event tree. Removal deletes the node from both trees, deletes the object, and clears the pointer slot. TextEdit Escape and Enter paths also remove both registrations before queueing deferred deletion. Enter calls the class-specific virtual slot +0x4C before removal.

Visibility is separate from both hierarchies. Common Pane vslot +0x14 sets the visible flag at +0xB0 and invalidates the pane, while +0x18 clears the flag and invalidates the exposed parent region. Persistent content panes can therefore remain present in both registries while hidden. The exact packet and input transitions for equipment, status, skills, spells, users, paper, messages, and bulletin or mail are in UI, Input, and Packet Flows.

The base ui_pane_dtor only cancels timers and destroys base members. It does not unregister the object from either tree. Every owning path must therefore remove both registrations before immediate or deferred deletion. The observed order varies by owner, but both removals precede destruction.

Named persistent panes and handlers

The following panes have established construction, virtual-table, and handler evidence. M, K, S, and T mean mouse, keyboard, socket packet, and timer.

Friendly class names and concrete event coverage

The executable has no usable Microsoft RTTI for this hierarchy, but it retains many class and method diagnostics. A friendly class name is treated as confirmed only when the same constructor, destructor, or virtual method also installs or is stored in the candidate vtable. This establishes names such as BulletinDialogPane, ArticleListDialog, MailListPane, LegendDialogPane, MonsterPane2, EffectObjectPane, OptionPane, and WeatherPane without relying on nearby text alone. The complete confirmed name-to-vtable map is in Pane Virtual Table Inventory.

A vtable identifies the broad Event families a pane can receive. The handler body supplies the narrower filter. For example, ServerSelectDialogPane has mouse, keyboard, socket, and timer slots, but its mouse override only adds behavior for a left double-click and its socket override only claims server action 0x56. The inherited Dialog handlers still process their ordinary mouse and keyboard cases. This distinction is important for runtime hooks because a non-default slot does not imply that every subtype is consumed.

The client dispatches key-down Events only. Key-up updates EventMan state but does not enter the pane hierarchy. Timer callbacks are also separate from the numbered Event types: the timer worker calls pane slot +0x44 with a class-local callback identifier and two payload values.

The socket handler is not a Winsock callback. Socket bytes are decoded and converted to internal Event type 9 before the dispatcher calls pane slot +0x40. The packet path is documented in Networking, while Win32 WM_* handling remains in Input and Windows Events.

Runtime observation roots

The documented virtual addresses use image base 0x00400000. A runtime tool that resolves a loaded module should use loaded_module_base + RVA rather than assuming the preferred base.

These roots are useful object discriminators as well as pointer chains. A live object begins with its current virtual-table pointer. Comparing that pointer against the vtable inventory identifies compatible panes without relying on absent RTTI.

The Runtime UI Memory Map turns these roots into concrete Screen and Event tree-walking recipes and records confirmed fields for GameButtonsPane, equipment and self-look state, skill and spell slots, BulletinSession, and Users Dialog Pane.

External readers can race Screen changes, event registration, and deferred deletion. The Screen add and remove paths do not acquire a visible lock around the packed list. A practical snapshot should read the list pointer, count, array pointer, and stride, copy the nodes, then re-read those four values and discard the snapshot if they changed. Each pane pointer should also be checked for readability and a known vtable before reading fields. Writes are more hazardous because pane fields, both registries, timers, and ownership must remain consistent.

Code-level flow

Common Pane layout and virtual slots

ui_pane_ctor constructs the common Pane base and installs ui_pane_vtable. The following fields and slots are directly established.

Event values and handler filters

The dispatcher reads the byte at Event offset +0x0C. Mouse subtype values and their Win32 production paths are established in Input and Windows Events.

The following filters are comparisons in the named handler bodies. A handler that delegates to ui_dialog_handle_mouse_event can still inherit the generic Dialog cases after its class-specific work.

Keyboard handlers receive Event type 8 and compare the mapped key byte at Event offset +0x10. Values below are recorded as the handler sees them. They are not assumed to be raw WM_* virtual-key values.

Socket Event handlers filter on the first decoded byte or, where noted, a second subtype byte. The Map action set is kept in the protocol index because each branch has its own parser and side effects.

Timer callback identifiers are local to the receiving class. BackPane uses IDs 0, 1, and 2; MapPane and ScreenPane each dispatch IDs 0 through 4. These values share no global enum with Event types 0 through 9.

Packed hierarchy representation

Both registries use ui_hierarchy_list_ctor, which adds an 11-byte hierarchy header to the requested payload size. The result is a packed, commonly unaligned node array.

Screen requests a 0x34-byte payload, producing stride 0x3F. The pane pointer is at node +0x08, its RECT is at +0x0C, and copied pane flags begin at +0x1C. The root pointer stored at [ui_screen_registry + 0x1C] addresses a node whose child-list pointer is at root +0x04 and whose pane at root +0x08 is ui_screen_pane.

The event dispatcher requests a four-byte payload, producing stride 0x0F. Each event node therefore contains only its hierarchy links and the pane pointer at +0x08.

The exact external pointer chains are:

screen_list = read_process_u32(module_base + 0x000f51cc);
screen_root = read_process_u32(screen_list + 0x1c);
screen_children = read_process_u32(screen_root + 0x04);

dispatcher_object = read_process_u32(module_base + 0x000f51d0);
event_list = read_process_u32(dispatcher_object + 0x68);

Walk screen_children for ordinary Screen descendants. The separately allocated Screen root itself can be observed directly at screen_root. Walk event_list for registered event receivers.

A raw external walk is equivalent to:

static void walk_pane_list(uintptr_t list_address)
{
    uint32_t node_stride;
    uint32_t node_count;
    uintptr_t node_array;
    uint32_t node_index;

    node_stride = read_process_u32(list_address + 0x0c);
    node_count = read_process_u32(list_address + 0x14);
    node_array = read_process_u32(list_address + 0x18);

    for (node_index = 0; node_index < node_count; ++node_index) {
        uintptr_t node_address;
        uintptr_t child_list;
        uintptr_t pane_address;

        node_address = node_array + node_index * node_stride;
        child_list = read_process_u32(node_address + 0x04);
        pane_address = read_process_u32(node_address + 0x08);
        observe_pane(pane_address);

        if (child_list != 0) {
            walk_pane_list(child_list);
        }
    }
}

The helper reads 32-bit values from arbitrary byte addresses because the strides 0x3F and 0x0F do not preserve four-byte alignment.

Creation and removal paths

The common add path is:

1. A constructor installs a concrete pane vtable after ui_pane_ctor initializes the base.
2. The owner calls vslot +0x28, reaching ui_pane_add_to_screen and then ui_screen_add_pane.
3. ui_screen_add_pane validates bounds, resolves optional parent and front panes with ui_screen_find_pane_node, copies the Screen payload, and inserts the packed node.
4. The owner calls vslot +0x30, reaching ui_pane_register_events and event_dispatcher_register_pane.

Removal reverses both memberships before destruction. ui_pane_remove_from_screen releases capture-related state when necessary and calls ui_screen_remove_pane. Event removal reaches event_dispatcher_unregister_pane. Representative dynamic paths are ui_skill_inventory_remove_slot_pane, ui_spell_inventory_remove_slot_pane, the server-select destructor, and ui_text_edit_handle_key_event.

ui_screen_find_pane_node recursively returns the containing list and node index. ui_screen_get_pane_origin walks parent links to accumulate screen coordinates. These functions make the Screen hierarchy useful for both rendering and runtime inspection.

Function table

Internal Event Routing

The internal event system owns two related paths. It routes typed events through registered panes, and it runs periodic timer callbacks on a worker thread independently of the blocking Windows message pump. Network packets enter the same pane hierarchy through a separate event-manager worker.

High-level operation

Dispatcher, event manager, and pane hierarchy

app_initialize creates the global event_dispatcher, starts its worker, then constructs and starts the separate event_manager_instance. The dispatcher owns the pane registry and the timer list. The event manager converts queued work records into Event objects, including socket-packet events, and submits those events to the dispatcher.

The established socket path is:

1. The Socket receive worker posts copied decoded bytes through event_post_socket_bytes.
2. event_process_work_item converts the queued record to Event type 9.
3. event_queue_socket_packet transfers the owned packet pointer and size into the Event queue.
4. event_dispatch and event_dispatch_hierarchy walk registered panes and invoke the socket-event virtual handler.

Packet ownership and the type 9 fields are documented in Networking. Pane registration and timer callbacks remain owned by this subsystem.

The dispatcher hierarchy is separate from the Screen composition hierarchy. The event tree stores packed 0x0F-byte nodes with a pane pointer at +0x08, while Screen stores placement and drawing relationships in 0x3F-byte nodes. Their raw layouts, pane virtual slots, creation and removal flows, and complete vtable inventory are documented in UI Panes and Registries.

Window input uses the same EventMan worker. The main window procedure posts work codes 4 through 0x0B for mouse movement, buttons, wheel, and physical scan codes. event_process_work_item converts those records into mouse and key state or Events before the normal pane hierarchy sees them. The complete mapping is documented in Input and Windows Events.

Event copying and queue ownership

event_dispatcher_queue_event_copy allocates and shallow-copies the complete 0x24-byte Event, then posts dispatcher work code 3. event_dispatcher_process_work_item calls event_dispatch for that code. After dispatch returns, it frees Event +0x14 when the object is a socket Event, then deletes the Event copy. This dispatcher-worker cleanup still runs when a hook or pane consumes the Event.

event_manager_queue_event_copy performs the same 0x24-byte shallow copy but posts EventMan work code 0x0F. event_process_work_item forwards that copy into the dispatcher queue. No native call site for the EventMan wrapper is present in this build, so its implementation and consumer are established but its original producer role is not.

Both wrappers ultimately call util_thread_queue_post_async, which appends the raw {code, data, value} record and releases the queue semaphore. The raw helper does not copy the data pointer. Ownership comes from the caller-specific wrapper, so proxy code should use a mapped wrapper instead of posting a stack pointer directly. See Event Proxy Hooks and Injection for the resulting interception and injection boundaries.

Bounded queue synchronization

The worker queue is safe for simultaneous producers. Its ring owns a monitor, a not-full condition, and a not-empty condition. util_ring_buffer_push_wait acquires the monitor, waits when element_count == capacity, copies one fixed-size record, signals not-empty, and releases the monitor. util_ring_buffer_pop_wait performs the symmetric operation and signals not-full after removing a record.

This establishes synchronization for the native client and an injected producer that calls a copied-input wrapper at the same time. It does not make admission nonblocking. util_thread_queue_post_async does not wait for worker completion, but its internal ring push can wait indefinitely for space. The Socket and EventMan rings each hold 128 records; the dispatcher ring holds 1,024.

That distinction matters during shutdown. EventMan destruction deletes its owned Socket, clears both static roots, and then tears down its worker base. The worker-base destructor uses TerminateThread and destroys the ring and its synchronization objects. A foreign thread must not still be waiting in that ring when teardown begins. The Event Proxy design therefore uses bounded proxy queues and worker-affine pumps, with app_shutdown entry as a drain barrier.

Worker and timer lifecycle

The Windows message loop is not a frame loop. The dispatcher derives from a cross-subsystem thread-queue base whose constructor creates a thread with _beginthreadex and CREATE_SUSPENDED. The same base is also used by the Socket and other worker-derived objects. The dispatcher configures that worker before util_thread_queue_start resumes it:

The dispatcher calls timeGetDevCaps but does not check its return. It calls timeBeginPeriod with the selected period, stores the first timeGetTime sample, creates the timer list, and raises the still-suspended worker’s priority. A 1 millisecond wait timeout is therefore a polling interval requested from the worker, not a promise that Windows will deliver callbacks every millisecond. The multimedia period is normally 5 milliseconds when the device range permits it.

util_thread_queue_start first calls virtual slot +0x08 so the derived object can add its wait object. It resumes the thread only when app_error_code remains zero.

The worker runs WaitForMultipleObjects(wait_count, wait_handles, FALSE, timeout_ms) forever. Wait handle index 0 is the queued-work notification. A work wake first checks the ring. It removes and handles one record when nonempty, but an empty ring is also valid and skips directly to the periodic virtual. Other registered handle indices call virtual slot +0x1C. After every handled wake, empty queue wake, secondary signal, or timeout, the loop calls virtual slot +0x10. In the dispatcher vtable, that periodic slot is event_dispatcher_tick; the Socket slot is net_poll_receive; the EventMan slot is event_manager_periodic_noop.

Timer records and scheduling

Timer insertion normally reaches event_dispatcher_process_work_item as work code 4. Code 5 cancels all timers for a pane. event_dispatcher_insert_timer converts the relative delay to an absolute 32-bit deadline by adding it to the dispatcher’s most recent timeGetTime sample.

Each sorted timer record has this layout:

The insertion scan uses an unsigned comparison and places the record before the first later deadline. Equal deadlines remain in insertion order. If the new record becomes element 0, its deadline is copied to the dispatcher’s cached next-deadline field.

event_dispatcher_remove_pane_timers scans the complete list and removes every record whose receiver pointer matches the pane. It then sets the cached deadline from the new first record, or to UINT32_MAX when the list is empty.

Periodic tick and deferred deletion

Each event_dispatcher_tick first drains event_deferred_delete_queue. The drain walks queued object pointers from the last element to the first, calls each object’s deleting destructor with flag 1, and removes the entry. This gives client code a deferred-destruction path tied to the dispatcher worker rather than the Windows message thread.

The tick then samples timeGetTime, stores the result, and compares it to the cached next deadline as unsigned 32-bit values. If the current tick is earlier, the tick returns. Otherwise it removes only the first timer record, refreshes the cached deadline, verifies that the receiver is still an active object, and calls receiver virtual slot +0x44 with the callback identifier and the two payload values.

At most one due timer is dispatched per worker iteration. When several timers are overdue, they are removed across successive worker wakes or timeouts.

The code uses plain unsigned addition, sorting, and current_tick < deadline comparisons. It does not use a signed modular difference or another visible timeGetTime wraparound correction. Implementations that need byte-for-byte behavioral compatibility should preserve that distinction; implementations seeking a robust long-running clock should account for 32-bit wrap separately.

Shutdown and ownership

app_shutdown first deletes EventMan, whose destructor deletes its owned Socket and clears both static roots. It later deletes the event dispatcher before it deletes the global deferred-deletion queue. The dispatcher destructor performs these operations in order:

1. Delete the pane registry.
2. Delete the timer list.
3. Call timeEndPeriod with the stored period.
4. Invoke the worker-base destructor.

The worker-base destructor calls TerminateThread(worker_handle, 0), closes the thread handle and every wait handle, and destroys the queued message and synchronization objects. There is no cooperative stop flag, worker acknowledgement, or thread join. The pane and timer containers are released before the worker is forcibly terminated, so shutdown relies on the fixed surrounding teardown sequence and timing rather than an explicit worker quiescence handshake.

Code-level flow

Construction and start

1. Darkages.exe:0x0045CCA0 app_initialize allocates the 128-byte dispatcher object and calls event_dispatcher_ctor.
2. Darkages.exe:0x00430FE0 calls util_thread_queue_ctor(this, 0x400). The base constructor creates queue state and a suspended _beginthreadex worker stored at object offset +0x60.
3. The dispatcher installs event_dispatcher_vtable, calls util_thread_queue_set_wait_timeout(this, 1), and allocates its pane registry at +0x68.
4. It reads TIMECAPS, clamps 5 milliseconds into the reported range, stores the result at +0x6C, and calls timeBeginPeriod.
5. It stores timeGetTime() at +0x70, sets cached next deadline +0x74 to UINT32_MAX, and creates a 256-element timer list at +0x78 with 20-byte elements.
6. It sets the suspended thread to THREAD_PRIORITY_TIME_CRITICAL.
7. app_initialize stores the object in event_dispatcher and calls util_thread_queue_start, which creates the derived wait object and resumes the worker.
8. After the screen pane exists, event_dispatcher_register_pane(screen_pane, 0, 0) inserts it into the pane registry.
9. app_initialize separately allocates the EventMan object, calls event_manager_ctor, and calls util_thread_queue_start. The constructor uses a work-queue capacity of 0x80, publishes event_manager_instance, and sets its worker timeout from the constructed event-manager state.

Allocation failure sets app_error_code to 2 and records the same error in the dispatcher base. The initializer then follows its staged failure cleanup.

Worker loop

Darkages.exe:0x004BF250 util_thread_queue_worker_loop has no normal exit branch. Its repeating path is equivalent to:

for (;;) {
    uint32_t wait_result;

    wait_result = WaitForMultipleObjects(
        worker->wait_count,
        worker->wait_handles,
        0,
        worker->timeout_ms
    );

    if (wait_result == WAIT_OBJECT_0) {
        if (!util_ring_buffer_is_empty(worker->work_queue)) {
            process_one_queued_record(worker);
        }
    } else if (wait_result > WAIT_OBJECT_0 &&
               wait_result < WAIT_OBJECT_0 + worker->wait_count) {
        process_secondary_wait_handle(worker, wait_result);
    }

    run_periodic_worker_method(worker);
}

The real queue path supports both asynchronous records and synchronous records whose producer waits on an event for a returned result. After processing a synchronous record, the worker writes the result to the matching waiter entry and signals its event.

Timer insertion and callback

For work code 4, event_dispatcher_process_work_item extracts the receiver, callback identifier, delay, and two payload values and calls event_dispatcher_insert_timer. The insertion function builds the 20-byte record, performs a linear scan of the sorted list, inserts it, and updates +0x74 only when inserted at index 0.

The periodic vtable call reaches event_dispatcher_tick:

event_deferred_delete_queue_drain(event_deferred_delete_queue);

current_tick = timeGetTime();
dispatcher->current_tick = current_tick;
if (current_tick < dispatcher->next_deadline) {
    return;
}

timer_record = remove_first_timer_record(dispatcher);
refresh_next_deadline(dispatcher);

if (receiver_is_active(timer_record.receiver)) {
    invoke_timer_callback(
        timer_record.receiver,
        timer_record.callback_id,
        timer_record.payload_0,
        timer_record.payload_1
    );
}

The implementation removes the timer before checking receiver activity. An inactive receiver therefore loses the due callback rather than retaining or rescheduling it.

Network event handoff

The separate event manager’s mapped packet route is documented in detail under receive and event routing. The important cross-thread ownership boundary is that event_post_socket_bytes copies the decoded packet into a work record. event_process_work_item later constructs the Event and queues it to the dispatcher. The dispatcher worker frees the owned packet and Event copy after pane dispatch.

Dispatcher object fields

Offsets below are from the event dispatcher object. The worker-base fields are shared with the event manager and other worker-derived objects.

Function table

File System

The file subsystem covers path construction, lookup order, file access, containers, caching, and the shared readers and writers used by format-specific code.

High-level operation

This section will explain where the client looks for data, how resources are identified, which content is loaded eagerly or on demand, and how file data reaches rendering, audio, user interface, and game systems.

File system behavior has not been mapped yet. Specific layouts will be linked from the Format Catalog.

Code-level flow

This section will trace path construction, open and close operations, archive or container access, allocation, common byte and string readers, bounds handling, caching, decoding, and cleanup. Format-specific flows will link back to their reader and writer functions.

No file system call tree is documented yet.

Function table

Networking

The networking subsystem owns the active transport, turns a byte stream into packet bodies, applies the protocol’s XOR transformations, and moves decoded server packets into the pane event hierarchy. Client packet builders use raw byte arrays and the same small big-endian field writers.

The directional action indexes are Client actions and Server actions. Each index links to one payload-relative page per action.

High-level operation

Connection and Windows notification

The normal game transport uses Winsock 1.1 and an IPv4 TCP stream. Connection setup creates an AF_INET, SOCK_STREAM socket, requests a 0x4000 byte Winsock receive buffer, resolves the configured host, and connects to the configured port. Once connected, WSAAsyncSelect associates the socket with the main window using message 0x0402 and event mask 0x21, which is FD_READ | FD_CLOSE.

The main window procedure handles the low word of lParam for message 0x0402:

The executable also retains serial and printable-text transports. They eventually feed the same logical packet event path, but the standard Stone server path is the binary TCP path described here.

Binary frame

Every binary TCP frame begins with 0xAA. The two-byte size is unsigned and big-endian. It counts the body beginning at the action byte, not the marker or the size itself.

The total frame length is therefore 3 + body_length. The receive code requires a positive body length and stores at most 0x10000 body bytes. Since the wire field is 16 bits, the largest representable wire value is 0xFFFF.

The application-facing logical packet is:

[uint8 action] [payload bytes...] [zero sentinel]

net_c_queue_send receives the action and payload length from a packet builder, copies those bytes, and appends the zero sentinel. The sentinel is an implementation guard, not a checksum. The decoder does not validate its transformed value. After decoding it writes another zero immediately after the returned logical bytes.

Direction defines the action

Action values are not globally unique. A client action and a server action with the same byte can have unrelated meanings. For example, both directions support 0x0D, but the send builders and receive handlers are separate code paths. Protocol implementations must key dispatch by (direction, action), never by action alone.

The executable contains 52 established client action values and 59 server action values. Fifty-one client values occur directly at net_c_queue_send call sites. Action 0x0F is built by the spell-slot path and reaches the queue through the spell-delay controller. Thirty-five values occur in both directions. A server 0x4B packet can also ask the client to forward an embedded logical client packet, so that path is not restricted to one statically embedded client action constant.

Receive and event routing

The TCP reader refills a 0x18000 byte cache with recv and then supplies one byte at a time to the framer. This preserves a partial header or body across Windows notifications and permits multiple complete frames to be drained from one receive cache.

After a frame is complete, the client decodes it when required and posts a copy as internal work code 0x0E. The EventMan worker converts that work item into an Event with type 9, packet pointer at offset +0x14, and packet size at offset +0x18. It queues a copied Event to the dispatcher worker, which recursively walks the pane hierarchy and calls virtual slot +0x40 on each eligible pane. That virtual method is the pane’s server-packet handler.

Dispatch is therefore distributed rather than centralized. MapPane owns the largest switch, while MainMenuPane, ServerSelectDialogPane, exchange panes, bulletin panes, and other UI objects handle actions relevant to their current state. The server action index combines those separate handlers.

Send path

Packet builders assemble a logical packet in a local byte array and call net_c_queue_send. The Socket object copies the bytes, appends the sentinel, and queues work code 5. The socket worker then applies the client transformation rule, allocates body_length + 3 bytes, writes the frame header, and calls Winsock send once.

The send path treats SOCKET_ERROR as failure. It does not retry when send succeeds with a byte count smaller than the requested frame length. A compatible implementation should use a full-write loop even though this client does not.

During a server transfer state, net_c_queue_send drops every client action except 0x10, the client transfer-server action.

Queue concurrency and Socket affinity

The Socket work queue has capacity 0x80. Its ring is protected by a monitor and paired not-full and not-empty conditions. net_c_queue_send can therefore run concurrently on a native client thread and an injected producer without racing the head, tail, count, or copied packet ownership.

The enqueue is not nonblocking. util_thread_queue_post_async calls util_ring_buffer_push_wait, which waits indefinitely when the ring is full, then signals the worker semaphore after admission. Calling it from an IPC read thread would make pipe liveness depend on Socket progress. Calling it from the Socket consumer itself can deadlock if other producers refill the ring before the self-enqueue.

Sequence, XOR state, framing buffers, and the transport call are mutated only by the Socket worker after it consumes code 5. A production Event Proxy should preserve that affinity. The documented design wakes the Socket worker with an empty native-queue signal and drains a bounded proxy queue from the worker’s net_poll_receive periodic callback. A simpler dedicated producer thread may call net_c_queue_send, but it must be drained before EventMan destroys its owned Socket during app_shutdown.

The active Socket is reachable through net_socket_instance at Darkages.exe:0x004F51BC. EventMan owns the Socket at object offset +0x68, publishes the static root during construction, and clears it during destruction. This is the established runtime root for logical packet injection, but callers must still validate the live net_socket_vtable before using a cached pointer. See Event Proxy Hooks and Injection for the injection contract and ownership boundaries.

Packet representation and C++ class evidence

The traced send and receive paths do not instantiate a class per packet or a common ClientPacket or ServerPacket object. Client builders write directly into byte arrays. The receiver copies decoded bytes into an Event, and pane handlers switch on packet[0] and call field readers on later offsets.

The code does establish these surrounding C++ types through constructors, virtual tables, source assertions, and diagnostics:

Names such as kServerRequestPortrait and kClientTransferServer are enum-style action names embedded in diagnostics, not evidence of packet classes. The safest compatible-client model for the mapped path is a direction-tagged byte buffer plus per-action serializers and handlers.

Big-endian serialization

The packet builders and handlers share small integer helpers:

The writers place a zero byte immediately after the value. Packet builders subsequently overwrite that byte when adding the next field, or leave it as the packet sentinel at the final logical offset.

Sequence and XOR transformation

Ordinary bodies carry a sequence byte and three XOR passes over the payload and trailing zero. The message indexes label this branch Encrypted: Yes, but the transformation does not provide authentication or cryptographic security.

The default repeating key is the nine ASCII bytes NexonInc., the default table is generated by function 0, and the client send sequence starts at zero. Clear server action 0x00, subtype 0x00, can replace the nine-byte key and select any table function from 0 through 9. Only encrypted client packets increment the client send sequence.

The decoder does not verify that the transformed trailing byte becomes zero. It retains that byte and writes a second local zero guard after the returned logical packet.

See Sequence and XOR Transformation for the exact wire placement, pass order, negotiation payload, all ten table formulas, and implementation addresses.

Failure and bounds behavior

The standard receive path has these established edge behaviors:

• Outside a frame, the next consumed byte is asserted to be 0xAA; the code does not scan ahead for a later marker.
• A body length of zero or greater than 0x10000 fails an internal assertion. The two-byte wire field cannot encode a value greater than 0xFFFF.
• recv == 0 closes the socket, sets it to INVALID_SOCKET, clears connection state, and stops reading.
• recv == SOCKET_ERROR clears the receive cache and returns no byte. This path does not distinguish individual WSAGetLastError values.
• Completed packet bytes are copied for the event worker. The Event owns the copy and frees it after pane dispatch.
• No checksum or message authentication value is validated by the mapped frame or XOR code.

Code-level flow

Startup and connection

1. Darkages.exe:0x004A32F0 net_socket_ctor installs the Socket virtual table, initializes the transport buffers and state, and installs NexonInc. as the default repeating key.
2. Darkages.exe:0x004A59F4 net_connect_configured_server starts Winsock 1.1, checks that version 1.1 was returned, resolves the configured host, creates and connects the TCP socket, and registers WM_USER + 2 with FD_READ | FD_CLOSE.
3. Darkages.exe:0x0045BDC0 win_main_window_proc receives message 0x0402. FD_READ calls net_queue_receive; FD_CLOSE calls net_handle_disconnect.

Receive, decode, and dispatch

win_main_window_proc
  -> net_queue_receive                         work code 4
  -> net_process_work_item
      -> net_s_receive_frames
          -> net_read_transport_byte
              -> recv                          refill up to 0x18000 bytes
          -> net_s_decode_packet_body          ordinary server actions
          -> event_post_socket_bytes           work code 0x0E
              -> event_process_work_item
                  -> event_queue_socket_packet Event type 9
                      -> event_dispatch
                          -> event_dispatch_hierarchy
                              -> pane vtable +0x40

net_s_receive_frames maintains three important pieces of persistent state: whether a frame is open, the number of header or body bytes collected, and the current body length. It combines the first two body-header bytes as (high << 8) | low. Completion occurs after exactly body_length bytes have been placed in the packet buffer.

event_dispatch_hierarchy tests Event type 9 with event_is_socket_packet before calling pane virtual slot +0x40. The return value indicates whether the event was consumed. After event_dispatch returns, event_dispatcher_process_work_item frees the packet pointer for a socket Event and deletes the copied Event.

Build, encode, and send

per-action packet builder
  -> net_write_u8 / net_write_u16_be / net_write_u32_be
  -> net_c_queue_send                          copy and append zero
      -> net_process_work_item                 work code 5
          -> net_c_send_packet_body
              -> net_c_encode_packet_body      ordinary client actions
              -> net_write_u8(0xAA)
              -> net_write_u16_be(body_length)
              -> send                          one call

net_c_encode_packet_body returns one byte more than its input size because it inserts the sequence after the action. net_s_decode_packet_body returns one byte less than its input size because it removes that sequence. Bypass actions keep their original body size.

Representative server dispatch

Darkages.exe:0x00468A90 ui_map_dispatch_server_packet is the largest action switch. It accepts 31 action values and rejects the other values in its 0x03 through 0x4B switch range. Important established branches include:

The complete accepted set and all other pane handlers are in the server action index. The separate exit-wait pane handles SReconnect, server action 0x4C. Its subtype-one branch completes an orderly-exit exchange and does not call the Socket reconnect path.

Function table

Event Proxy Architecture

An Event Proxy can run inside the client and expose logical input, internal Events, decoded server packets, logical client packets, and selected runtime state to an external controller. It can provide most of the useful behavior of a network proxy without redirecting the TCP connection and without asking the controller to reproduce sequence, XOR, framing, or socket state.

This section is a development design based on confirmed Dark Ages 4.21 client boundaries. The client functions, object roots, ownership rules, and worker paths are established by static analysis. The injected DLL, IPC protocol, rule engine, and version resolver described here are proposed components and have not yet been implemented or validated by a controlled runtime experiment.

High-level operation

Design goals

The injected module should satisfy these requirements:

“All events” means every event category the mapped client recognizes. Mouse Event types are 0 through 7, keyboard is type 8, and decoded server packets are type 9. Pane timers are a separate callback path and are not Event objects. Unknown Event type values reach an assertion path instead of a generic extension handler, so the public IPC API should reject unknown types.

Component layout

flowchart LR
    Controller["External controller"] <-->|"duplex named pipe"| IPC["IPC service thread"]

    subgraph Proxy["Injected Event Proxy DLL"]
        IPC --> Commands["Bounded proxy command queues"]
        Hooks["Hook adapters"] --> Rules["Local immutable rules"]
        Hooks --> Telemetry["Bounded telemetry ring"]
        Telemetry --> IPC
        Commands --> SocketPump["Socket worker pump"]
        Commands --> EventPump["EventMan worker pump"]
        Commands --> DispatchPump["Dispatcher worker pump"]
        Snapshot["Typed state snapshotter"] --> IPC
    end

    Win32["Win32 messages"] --> EventMan["EventMan worker"]
    Receive["Socket receive and decode"] --> Inbound["event_post_socket_bytes"]
    Inbound --> EventMan
    EventMan --> Dispatch["event_dispatch"]
    Dispatch --> Panes["Pane hierarchy"]
    Builders["Client packet builders"] --> Outbound["net_c_queue_send"]
    Outbound --> SocketWorker["Socket worker: sequence, XOR, frame, send"]

    Hooks -. "observe or block" .-> Inbound
    Hooks -. "observe or block" .-> Dispatch
    Hooks -. "observe or block" .-> Outbound
    SocketPump -. "worker-affine send" .-> SocketWorker
    EventPump -. "worker-affine inject" .-> EventMan
    DispatchPump -. "UI and snapshot commands" .-> Dispatch
    Snapshot -. "read validated roots" .-> Panes

The hooks remain synchronous only for the local decision. Telemetry is copied into a bounded ring and delivered later by the IPC thread. Commands travel in the other direction through bounded proxy-owned queues. The target client worker drains each queue so IPC code does not call a live client object from an unrelated thread.

Threading model and pump placement

The named-pipe pump should run on a proxy-owned thread, but that thread should stop at framing, validation, ruleset compilation, command admission, and response serialization. It should not call net_c_queue_send, event_post_socket_bytes, pane methods, or timer methods.

The strongest 4.21 design has one bounded command queue for each client ownership domain:

This wake mechanism is supported by the generic worker loop. A wait-handle-0 wake first checks whether the native ring is empty. If it is empty, the loop skips the native pop and still invokes virtual slot +0x10. A proxy can therefore enqueue into its own ring, release the existing work semaphore once, and let the correct client worker enter the class-specific pump without adding a fake native work record.

Command admission and the matching ReleaseSemaphore call must run inside a proxy lifecycle read guard. Admission rechecks the active state after acquiring the guard, validates the live root, vtable, and wait handle, copies the command, and checks the wake result before leaving. The shutdown hook changes the state to draining and waits for these guards before the original client can close any worker handle. This closes the race where an IPC thread captures Socket or EventMan +0x14 immediately before destruction.

Each pump should call the original periodic method and then process a small fixed number of commands. The Socket and EventMan pumps can normally process one packet per wake. The dispatcher pump needs both an item limit and a short elapsed-time budget because its thread runs at THREAD_PRIORITY_TIME_CRITICAL and also owns deferred deletion and timers. None of the pumps should wait for pipe I/O or a controller response.

The client native queues are synchronized, so a simpler first implementation can use a separate proxy command-executor thread that calls net_c_queue_send and event_post_socket_bytes. This does not race the native ring indices. It is not the preferred final design because both wrappers can wait indefinitely when their 128-record queues are full, and a blocked foreign producer complicates Socket and EventMan destruction. Never make those calls on the named-pipe accept or read thread.

Hook layers

Three primary hooks cover different semantics:

1. event_post_socket_bytes sees one decoded server packet before Event creation. It is the cleanest inbound packet filter because skipping the original call prevents allocation and pane delivery.
2. event_dispatch sees one logical Event before hierarchy fan-out. It covers input and packets at a common point and preserves the dispatcher’s normal cleanup when a hook reports the Event consumed.
3. net_c_queue_send sees one native logical client packet before the sequence byte, XOR transformation, frame header, and Winsock call. It is the outbound observation point and a synchronized fallback injection adapter. The preferred controller injection path runs on the Socket worker and enters net_c_send_packet_body directly.

Hooking event_dispatch_hierarchy alone is not a replacement for the central Event hook. It is recursive, visits children before parents, translates mouse coordinates during traversal, and may be called more than once for one Event. It is useful for pane-specific diagnostics, but it produces duplicate observations and is a poor global blocking boundary.

Injection lifecycle

The DLL entry point should do only loader-safe work. Windows holds the loader lock while it calls DllMain, so starting IPC, resolving imports, installing hooks, or waiting for client initialization there can deadlock with other module loads. A small entry point can disable thread notifications and arrange for initialization after LoadLibrary returns. Injector-assisted invocation of an exported proxy_start function is the cleanest option. A separately created bootstrap thread is a practical fallback.

The proxy lifecycle should be explicit:

Early injection does not require guessing how long initialization takes. The bootstrap can validate the image immediately, then wait until event_dispatcher, event_manager_instance, and net_socket_instance are nonnull and have their expected vtables. Late injection follows the same validation and can enter active as soon as those roots are stable.

app_shutdown is the critical detach boundary. It destroys EventMan, whose destructor destroys its owned Socket and clears net_socket_instance, before the final dispatcher destruction. The proxy should intercept shutdown entry, enter draining, stop accepting mutating commands, atomically select a pass-through ruleset, wait for in-flight hook calls to leave, and remove hooks in reverse order. It must not depend on a client worker shutdown notification because the shared worker destructor uses TerminateThread rather than a cooperative stop and join.

Failure isolation and pass-through

The injected module is part of the game process, so its failure policy must favor the unmodified client path:

• A missing or unknown build profile disables hooks that can mutate state.
• No controller connection means pass-through unless an explicitly persistent local ruleset is installed.
• A full telemetry ring drops telemetry, increments a loss counter, and continues the client call.
• A malformed IPC message is rejected before it reaches a client function.
• A controller timeout never blocks a client worker.
• A hook reentry guard prevents a rule-generated packet from recursively generating the same rule action without a limit.
• Shutdown invalidates all cached client pointers before closing the pipe.

Session rules should be removed automatically when their controller disconnects. Persistent rules should require an explicit flag and remain local to the DLL across reconnects. This distinction preserves seamless default pass-through while still allowing a block rule to operate without live IPC.

Code-level flow

Activation path

1. Fingerprint the loaded Darkages.exe image and select a version profile.
2. Resolve every required RVA to loaded_module_base + rva.
3. Decode and validate the expected instructions, call relationships, globals, and vtables before changing code.
4. Start the pipe accept loop and publish passive build and capability information.
5. Wait for event_dispatcher, event_manager_instance, and net_socket_instance to be live.
6. Install the inbound, Event, and outbound hooks. Install the Socket and EventMan worker pumps for packet mutation capabilities, and the dispatcher pump for pane, timer, write, or snapshot capabilities.
7. Atomically change the capability state to active.

Hook installation should use one transaction where the hooking library supports it. If any required hook fails, roll back the complete set and remain passive. A partial set can create misleading ordering, such as allowing injected packets without observing the resulting outbound queue.

Normal packet and Event flow

decoded server packet
  -> inbound local rules
      -> block: return without event posting
      -> pass or copy-on-write modify
          -> event_post_socket_bytes
              -> EventMan work code 0x0E
                  -> Event type 9
                      -> central Event rules
                          -> block: report consumed; dispatcher still frees payload
                          -> pass: event_dispatch hierarchy fan-out

native client builder
  -> outbound local rules
      -> block: return without queue allocation
      -> pass or copy-on-write modify
          -> net_c_queue_send
              -> Socket work code 5
                  -> sequence, XOR, frame, send

proxy client command
  -> bounded Socket command queue and worker wake
      -> Socket periodic pump
          -> outbound local rules and telemetry
              -> net_c_send_packet_body
                  -> sequence, XOR, frame, send

The inbound and Event hooks can both observe a server packet. Telemetry therefore includes a phase field. A default subscription should publish decoded ingress at the first hook and suppress the duplicate type 9 record at the central Event hook unless the controller explicitly requests both phases.

Worker-affine packet pumps

For a client packet, the Socket pump validates the live root and vtable, checks the same transfer gate used by net_c_queue_send, applies outbound rules, appends the zero sentinel in proxy-owned storage, and calls net_c_send_packet_body with logical_length + 1. Static analysis shows that this function reads the input synchronously, applies the normal sequence, XOR, framing, and send path, and neither retains nor frees the input pointer. The proxy pump must emit the controller or local_rule telemetry itself because this route intentionally does not re-enter the net_c_queue_send hook.

For a server packet, the EventMan pump allocates logical_length + 1 through util_memory_manager_alloc, copies the logical bytes, appends zero, and calls event_process_work_item(event_manager, 0x0E, owned_packet, logical_length) on the EventMan worker. Code 0x0E transfers the packet into Event type 9 and the dispatcher later releases it through util_memory_manager_free. A DLL-heap pointer must not be passed into this ownership path.

Input injection belongs on the same EventMan pump. It can invoke the established worker-side work-code behavior with the same normalized scan code, message time, coordinates, or wheel delta that the native wrappers would have queued. This avoids self-enqueueing into EventMan’s bounded ring from its own consumer thread.

Direct pane operations and timer-list operations remain dispatcher-only. event_dispatcher_insert_timer edits the timer list without a visible lock. A timer injection command must run through the dispatcher pump and should target only an established receiver and callback identifier. All commands carry a connection generation and cancellation token so a disconnected controller cannot leave stale work queued.

The Socket worker processes at most one native record and then calls its periodic method. A proxy send performed there is therefore serialized with sequence and transport state, but it is not in a single chronological FIFO with the remaining native Socket queue. If strict native-versus-controller admission order is required, use net_c_queue_send from one dedicated executor and accept its blocking full-queue behavior, or implement a separately validated unified admission hook.

Shutdown path

1. Enter draining at app_shutdown entry, before the original function deletes EventMan and its owned Socket.
2. Reject new mutations, stop worker wake signals, cancel queued commands, and atomically select pass-through rules.
3. Disconnect the current controller and stop the accept loop. Use overlapped pipe I/O or explicit cancellation so this step cannot wait indefinitely on a blocked pipe read or connect.
4. Wait for IPC admission and wake guards, the Socket, EventMan, and dispatcher pumps, and ordinary hook active-call counters to reach zero while all three client workers are still alive.
5. Restore worker vtable slots and remove the dispatcher, outbound, Event, and inbound hooks in reverse order.
6. Clear cached roots and call the original app_shutdown. The EventMan destructor then deletes the Socket, clears both roots, and tears down their workers.
7. Close proxy-owned handles and mark the module detached.

The proxy should normally remain loaded until process exit. Calling FreeLibrary while another client worker might still execute a trampoline or callback into the module is more dangerous than retaining a small inert DLL.

Function table

Event Proxy Hooks and Injection

The 4.21 client exposes logical boundaries on both sides of the internal Event system. Decoded server packets can be intercepted before Event creation, all pane-bound Events can be intercepted once before recursive delivery, and client packets can be intercepted before transport transformation. These are internal functions, so an injected module needs x86 inline detours or equivalent call-site instrumentation rather than Winsock import hooks.

This page distinguishes confirmed client behavior from recommended proxy behavior. Hook return values, copied-buffer ownership, queue codes, Event fields, and static roots are confirmed. Rule evaluation, telemetry, and IPC commands are proposed.

High-level operation

Primary hook matrix

The first and fourth hooks avoid the protocol transformation entirely. Inbound data has already been decoded. Outbound data has not yet received its sequence byte, XOR passes, frame marker, or big-endian frame length.

Packet blocking and mutation

Blocking is simplest at the copied-input boundaries:

• An inbound block skips event_post_socket_bytes. The receive framer has already consumed the frame, and no EventMan-owned copy exists yet.
• An outbound block skips net_c_queue_send. The producer retains its stack or object buffer, and the Socket queue has not allocated a copy.
• A central Event block skips the original event_dispatch, returns 1 as the consumed result, and does not free the Event or packet. event_dispatcher_process_work_item still performs normal socket-payload cleanup and deletes the queued Event after the hook returns.

Packet mutation should be copy-on-write. The proxy copies the logical packet into proxy-owned scratch storage, applies validated edits, and passes that copy to the original client function. Both packet-boundary functions make their own owned copy before returning, so the proxy scratch buffer can be released immediately afterward.

Do not replace Event +0x14 with memory allocated by the DLL’s C runtime. The dispatcher releases an owned socket packet through the client’s memory manager. Inbound packet replacement belongs at event_post_socket_bytes, where the client performs the allocation itself.

Client packet injection

A controller command for an arbitrary logical client packet should contain exactly:

[uint8 action] [payload bytes...]

It must not contain 0xAA, the two-byte frame length, a sequence byte, transformed bytes, or the trailing zero sentinel.

The recommended stable path queues the command in a bounded proxy-owned Socket queue, signals the Socket worker’s existing wait handle 0, and executes it from the Socket periodic callback. The worker-affine adapter checks the transfer gate, appends the sentinel, and calls:

net_c_send_packet_body(
    net_socket_instance,
    packet_with_sentinel,
    logical_length + 1
);

This is the same Socket-worker function reached by native work code 5. It updates sequence and transformation state and performs normal framing and transport output. It reads the supplied packet synchronously and does not retain or free it, so the pump can release its proxy-owned command after the call.

The native-queue alternative calls net_c_queue_send(net_socket_instance, logical_packet, logical_length) from a dedicated proxy executor. The confirmed wrapper contract has several consequences:

• logical_length includes the action byte and must be positive.
• The parameter is signed 16-bit. The function adds one for the sentinel before placing the value in another signed 16-bit work field, so the practical maximum input is 32,766 bytes.
• The function copies the packet and appends the sentinel before it returns.
• Socket work code 5 performs the later transformation and send.
• When Socket transfer_gate at +0x780D2 is 1, the function drops every action except 0x10.
• Its 128-record ring is protected by a monitor and not-full condition, so simultaneous native and proxy producers do not corrupt queue state.
• The push waits indefinitely when the ring is full. The wrapper is asynchronous with respect to completion, not nonblocking with respect to admission.
• The function returns no queue or transport success value. An IPC acknowledgement can mean “validated and admitted,” not “sent on TCP.” A later Socket-worker or send observation would be required for delivery-attempt telemetry.

Before either adapter runs, validate that net_socket_instance is nonnull and its first pointer is net_socket_vtable. A useful command response distinguishes not_ready, not_connected, blocked_by_rule, blocked_by_transfer_gate, admitted, executed, and invalid_length.

Server packet injection

To make a logical server packet enter the client as though it had just been decoded, queue the command for the EventMan worker. The pump allocates logical_length + 1 through the client’s util_memory_manager_alloc, copies the packet, appends zero, and invokes the established worker case:

void *memory_manager;
uint8_t *client_owned_packet;

memory_manager = util_memory_manager_get_instance();
client_owned_packet = util_memory_manager_alloc(
    memory_manager,
    logical_length + 1
);
memcpy(client_owned_packet, logical_packet, logical_length);
client_owned_packet[logical_length] = 0;

event_process_work_item(
    event_manager_instance,
    0x0e,
    client_owned_packet,
    logical_length
);

The input begins with the server action and excludes the sentinel. The pump must validate a live MemoryMan root before allocation and free the new buffer itself if command execution stops before work code 0x0E accepts it. Once called, work code 0x0E creates Event type 9, routes it through event_dispatch, and transfers the packet to dispatcher cleanup after pane delivery. Allocation through the executable is required because the dispatcher later calls util_memory_manager_free.

The native-queue alternative calls event_post_socket_bytes(event_manager_instance, logical_packet, logical_length) from a dedicated proxy executor. That wrapper performs the same client allocation and posts EventMan code 0x0E. Its 128-record ring is synchronized for multiple producers but can block for capacity, so it must not run on the named-pipe thread or on the EventMan consumer itself.

This path preserves normal pane filtering. A packet is acted on only if an active registered pane claims its action. For example, injecting an in-game action while only MainMenuPane is registered does not bypass the UI state machine.

Input injection

Two input modes are useful:

The complete handled WM_*, WM_USER + 2 Winsock notification, and application-defined WM_USER + 0x2046 behavior is indexed in Input and Windows Events. Window-faithful injection should be limited to messages whose parameter layout is established there.

For an internal mouse click at a new position, queue a mouse move first, then the button transition. Button work uses the current EventMan mouse coordinates. Queue order preserves the move-before-click relationship. Releases should normally be paired even when a press was blocked because the client deliberately allows button-up and key-up work while input blocking is active.

For the worker-affine architecture, the proxy command queue preserves the same move-before-click ordering and the EventMan pump invokes the corresponding event_process_work_item cases directly. Calling an input queue wrapper from the EventMan consumer can self-block if concurrent producers refill the native ring before the wrapper pushes.

Direct keyboard injection uses the client’s physical scan-code representation. Extended keys have 0x80 added to the base scan byte. Passing a virtual-key code instead produces the wrong mapping. The controller should either supply the normalized scan byte or request a window-faithful WM_KEYDOWN or WM_KEYUP with a correctly formed lParam.

Thread-affinity matrix

The proxy can keep a dedicated executor that calls native queue wrappers as a simpler implementation, but it is an admission adapter rather than the IPC pump. Use one executor, one in-flight client call, bounded proxy input, and an app_shutdown drain gate. The worker-affine pumps remove that foreign-thread lifetime edge and are the recommended production layout.

Generic Event injection

The Event object is 36 bytes and uses event_vtable. The mapped variants share these fields:

event_manager_queue_event_copy allocates and shallow-copies all 36 bytes, then posts EventMan work code 0x0F. The EventMan worker forwards another copy to the dispatcher and deletes its first copy. This function has no native call sites in the analyzed build, although its implementation and worker case are complete.

Use this generic path only for a fully mapped non-owning Event layout. Native input queue functions are safer for mouse and keyboard because they also update EventMan state. event_post_socket_bytes is safer for socket packets because it establishes correct packet allocation and ownership. An IPC INJECT_EVENT_RAW command should therefore be disabled by default and restricted to a version profile with explicit field validation.

Timers and pane-specific actions

Pane timers do not become Events. event_dispatcher_tick removes a timer record and calls receiver vtable slot +0x44 with a callback identifier and two payload values. event_dispatcher_insert_timer edits the dispatcher’s timer list directly and has no visible lock.

A proxy timer command must execute on the dispatcher worker, validate that the receiver is still registered, and use only a callback contract established for that pane class. An arbitrary receiver, callback identifier, or payload can violate pane state assumptions. Packet-driven UI should normally be exercised by injecting its server packet, and user-driven UI should normally be exercised by input injection, rather than calling class handlers directly.

Code-level flow

Inbound hook flow

hook_event_post_socket_bytes(event_manager, packet, length)
  -> validate length and read action packet[0]
  -> evaluate local ingress rules
  -> enqueue telemetry copy without waiting
  -> block: return
  -> modify: call original with scratch packet
  -> pass: call original with original packet
      -> copy length + 1
      -> append zero
      -> util_thread_queue_post_async(code 0x0E)

The hook must not retain the caller’s packet pointer. Normal TCP receive uses a persistent Socket decode buffer that is reused for later frames.

Central Event hook flow

event_dispatcher_process_work_item(code 3, event)
  -> hook_event_dispatch(dispatcher, event)
      -> classify event[0x0C]
      -> evaluate local Event rules
      -> enqueue bounded telemetry
      -> block: return consumed
      -> pass: call original event_dispatch
  -> if socket Event, free event[0x14]
  -> delete Event

Because cleanup belongs to the caller, the hook must never delete the Event. A telemetry record must copy all needed scalar fields and packet bytes before returning.

Outbound hook flow

native client packet builder
  -> hook_net_c_queue_send(socket, packet, length)
      -> validate action and signed length
      -> evaluate local egress rules
      -> enqueue telemetry copy without waiting
      -> block: return
      -> modify: call original with scratch packet
      -> pass: call original with original packet
          -> enforce transfer gate
          -> allocate and copy length + 1
          -> append zero
          -> util_thread_queue_post_async(code 5)
              -> net_process_work_item
                  -> net_c_send_packet_body

The hook should tag origin as client, controller, or local_rule. A thread-local reentry counter and a maximum rule-action depth prevent an injected or rule-generated packet from triggering an unbounded emission cycle. The packet should still be observable unless a subscription explicitly excludes non-client origins.

Worker-affine injected packets do not pass through net_c_queue_send. The Socket pump runs the same immutable outbound rules, publishes a logical-egress record with the command origin, appends the sentinel, and calls net_c_send_packet_body. This avoids recursive hook entry while retaining one telemetry model.

proxy Socket command
  -> wake Socket wait handle 0
  -> worker calls original net_poll_receive
  -> Socket pump validates root, vtable, generation, and transfer gate
  -> evaluate outbound rules and publish telemetry
  -> net_c_send_packet_body(packet_with_sentinel, logical_length + 1)

Detour ABI requirements

These functions are x86 __thiscall. The object pointer arrives in ECX, while the remaining arguments are on the stack. A detour wrapper must preserve the nonvolatile registers, stack cleanup convention, and original ECX. The trampoline must relocate complete overwritten instructions and any relative branches or calls.

Before patching a target, compare its bytes with the selected build profile and decode enough whole instructions for the jump stub. Do not install a detour from a raw address match alone. The Version Profiles page defines the required semantic validation.

Function table

Event Proxy IPC, Rules, and State

The Event Proxy should keep client hooks independent from the external controller. A duplex IPC service carries commands and telemetry, an in-process ruleset makes immediate decisions, and a typed snapshot service supplies current state after late attach or reconnect.

Everything on this page is a proposed proxy protocol built around confirmed 4.21 client roots and object layouts. It does not describe an IPC facility already present in the game.

High-level operation

Pipe ownership and reconnect

The injected DLL should be the named-pipe server. A practical per-process name is:

\\.\pipe\darkages-event-proxy-{process_id}

The pipe should reject remote-machine clients and grant access only to the current interactive user unless the operator explicitly configures a broader security descriptor. One connection owns mutation privileges. Additional read-only monitor connections can be added later, but they complicate rule ownership and backpressure and are not required for the first implementation.

The accept loop belongs to the DLL and survives client-controller failure:

1. Create a pipe instance and wait for a controller.
2. Complete a versioned handshake and allocate a new connection generation.
3. Apply subscriptions and session rules only after validation.
4. On clean close, broken pipe, or controller process death, remove session rules and cancel that generation’s pending commands.
5. Return immediately to the accept state. Do not unload the DLL or remove the pass-through hooks.

Persistent rules are separate from session rules. They survive pipe disconnect and must be installed with an explicit persistence flag. With no rules, no controller, or an IPC failure, the proxy passes client traffic unchanged.

Command execution and worker wakes

The pipe service and client command execution are separate concerns. The IPC thread parses and validates a command, copies it into a bounded proxy-owned queue, records the current connection generation, and signals the owning client worker. It never invokes a live client object directly.

The generic worker explicitly tolerates a work-semaphore wake while its native ring is empty and still calls virtual slot +0x10. This lets the DLL wake the correct worker without adding an unknown native work code. The Socket slot already calls net_poll_receive, the EventMan slot is a no-op, and the dispatcher slot calls event_dispatcher_tick.

Admission holds a proxy lifecycle read guard across the final state check, root and vtable validation, queue copy, and ReleaseSemaphore. A failed wake marks the command canceled and reports wake_failed; it must not be reported as admitted. At app_shutdown entry, the DLL changes to draining, rejects new guards, and waits for existing admission guards before the client closes worker handles.

All three proxy queues must be bounded. Admission fails immediately with proxy_queue_full; it must not wait for capacity while holding an IPC session lock. A successful command has two distinct milestones:

• admitted means the command was copied into the proxy queue and the worker was signaled.
• executed means the target pump validated the generation and live root and invoked the client-side action.

Neither status means that TCP delivered a client packet or that a pane accepted an injected server packet. Completion records should carry the original request identifier and may arrive asynchronously after the admission response.

The 4.21 native rings are also synchronized for multiple producers, so a dedicated fallback executor may call the copied-input wrappers safely. Their full-queue wait is infinite, however. This fallback must use one executor, never the pipe thread, and must stop before EventMan and Socket teardown. The worker-affine design avoids a foreign producer being asleep inside a native queue when app_shutdown destroys it.

IPC framing

A small fixed header lets either side skip unknown message types and correlate requests with replies. All proposed IPC integers are little-endian because this is a local Win32 protocol, not the game’s network byte order.

The DLL must reject an unsupported version, a header smaller than the required fields, integer overflow in header_size + payload_length, and payloads above a configured limit before allocating memory.

Message families

A packet command response reports local admission or execution only. The Socket and Winsock send paths do not provide delivery confirmation, so the IPC protocol must not describe either status as network delivery.

Nonblocking telemetry

Hooks must not write to a pipe, wait on a controller, perform name resolution, or take a lock that the IPC thread can hold. Each hook should create a compact record in a bounded multi-producer queue. The IPC thread drains records, applies subscription payload policy, and writes them to the pipe.

Every record should include:

• global sequence number;
• phase such as decoded_ingress, event_pre_dispatch, or logical_egress;
• origin such as client, controller, or local_rule;
• process and thread identifier;
• high-resolution proxy timestamp;
• client message timestamp when the Event contains one;
• Event type or directional packet action;
• rule generation and matched rule identifier;
• original and modified lengths where applicable;
• copied logical payload when subscribed.

When the queue is full, increment a loss counter and continue the original client call. The next successfully delivered record includes the accumulated loss count, and the IPC thread also emits GAP. Blocking the game to preserve telemetry defeats the pass-through requirement.

Local rules

The controller compiles policy in the DLL once and the hooks evaluate it without an IPC round trip. A useful rule model contains:

The hot representation should be immutable. Compile a replacement table on the IPC thread, validate every offset and action, then swap one pointer atomically. The old table is retired only after all hooks that acquired it have exited. This can use a small active-reader counter or an epoch scheme.

Rules must not allocate, parse regular expressions, or perform unbounded string work inside a hook. Payload predicates need a proven minimum length before every read. A patch must preserve the configured maximum length and should create a scratch copy rather than edit the client’s source buffer.

Rule-generated packets go to a proxy command queue rather than calling back into a client function while a hook is midway through its own decision. The generated command carries origin local_rule, a parent sequence, and a depth. A fixed maximum depth prevents recursive rules from emitting forever.

Late-connect state synchronization

The controller needs a baseline before it can interpret live deltas. A useful reconnect protocol is:

1. Establish the connection and begin retaining telemetry for the new generation.
2. Request a dispatcher-bound snapshot barrier.
3. At a bounded point between dispatcher work items, record last_applied_event_sequence and copy the small typed state roots.
4. Send the snapshot with its sequence and state epoch.
5. Send retained records newer than that sequence.
6. If the retention ring overflowed, send GAP and require a new snapshot.

The central Event hook can update last_applied_event_sequence after the original dispatch returns. Most pane state changes caused by input and server packets occur during that call. A compact snapshot taken from the dispatcher worker can therefore describe state after a known Event. The capture must still validate pointers and vtables because rendering, window processing, and teardown involve other threads.

Large or not-yet-mapped world state should not be copied without a time budget on the time-critical dispatcher worker. A later implementation can maintain a proxy-owned shadow model from decoded packets or divide large snapshots into stable chunks. The first version should favor small typed UI and character-pane state.

Runtime state and memory access

Static roots

All addresses below are for the analyzed image base 0x00400000. A profile and external controller must use loaded_module_base + rva.

The complete Screen and Event tree algorithms and current class fields are in Runtime UI Memory Map.

Current typed snapshot coverage

The proxy protocol should expose capability bits per snapshot family. It must not return guessed fields just because an object can be reached. A raw peek can still return bytes from a validated address, but the response should label them untyped.

Pointer-path reads

IPC requests should avoid controller-supplied absolute addresses where a stable descriptor is possible. A pointer path can contain:

1. a named profile root or module RVA;
2. whether to dereference it;
3. a bounded signed offset;
4. an expected vtable or readable region class;
5. another dereference step if required;
6. final byte count and scalar or string interpretation.

For example, a typed path can start at ui_equip_pane, dereference the root, validate ui_equip_pane_vtable, then read the item identifier expression for a checked slot. GameButtons is reached by scanning a stable Screen or Event tree snapshot for its vtable, then following the mapped content fields.

Before every dereference, validate the memory range and overflow, and confirm class vtables where available. After copying class-specific state, re-read both the root that led to it and its vtable. Discard and retry if either changed. Packed Screen nodes use stride 0x3F and Event nodes use 0x0F; they must be parsed with unaligned-safe reads rather than native structure casts.

Peek and poke policy

PEEK_REQUEST can support a named pointer path and an explicitly enabled raw-address mode. Bound each request, validate every page as readable, and return the resolved path, bytes, and profile identity. A raw address is meaningful only for the current process and build.

POKE_REQUEST should be disabled by default. A safe typed write includes:

• named field and exact width;
• expected root and vtable;
• expected old bytes for compare-before-write;
• allowed value range or bit mask;
• execution context, normally the dispatcher command pump for pane state;
• a response containing whether the compare and write succeeded.

Do not permit ordinary writes to vtables, function pointers, packed-list metadata, owned pointers, executable pages, or object lifetime fields. Writing a Pane visibility byte alone is not a valid show or hide operation because Screen composition, Event eligibility, capture, timers, and owner pointers must remain consistent. Prefer an established UI method, input event, or server packet for stateful changes. An explicit unsafe developer mode may offer raw writes, but it should be clearly separate from the typed API and never enabled by a controller handshake alone.

Code-level flow

Hot-hook rule evaluation

hook entry
  -> increment active hook count
  -> acquire immutable rule pointer
  -> classify fixed fields and validate payload bounds
  -> evaluate rules in priority order
  -> try to append telemetry record
  -> release rule pointer
  -> pass, block, or call original with a scratch copy
  -> decrement active hook count

The IPC thread performs ruleset parsing and compilation. It does not hold the active rules pointer while waiting on pipe I/O. A ruleset replacement response is sent only after the new table has been validated and published.

Stable typed snapshot

controller snapshot request
  -> proxy queues dispatcher barrier command
  -> signal dispatcher wait handle 0
  -> dispatcher tick pump drains bounded command
      -> record last applied Event sequence
      -> read roots and expected vtables
      -> copy packed registry metadata and nodes
      -> copy mapped class-specific fields
      -> re-read roots, metadata, and vtables
      -> retry or mark one family unstable
  -> IPC thread serializes snapshot
  -> replay retained telemetry newer than snapshot sequence

One unstable family should not invalidate unrelated stable families. The response can mark equipment stable while reporting that a bulletin child changed during capture.

Controller disconnect

pipe read or write reports disconnect
  -> invalidate connection generation
  -> cancel pending commands from that generation
  -> atomically remove session rules
  -> retain explicitly persistent rules
  -> release queued controller responses
  -> create the next pipe instance
  -> continue client pass-through

No hook waits for this cleanup. A command executor checks the generation again immediately before any mutation so a queued command cannot run after its owner disconnected.

Function table

Event Proxy Version Profiles

An Event Proxy should treat every executable build as a profile, even when later clients descend from the same source tree. Function signatures can relocate well-understood symbols across nearby builds, but they cannot by themselves prove object field offsets, allocation sizes, ownership, or calling conventions.

The recommended strategy for 5.x and 7.x is to reverse one representative executable from each build family, establish the same lifecycle, Event, Socket, pane, and state roots, and generate signatures from that ground truth. Signature remapping can then handle close patch revisions. It should not replace the first semantic analysis of a major client family.

High-level operation

Exact profiles first

The resolver should fingerprint the loaded image before it installs any hook. The strongest identity is a hash of the file or its mapped immutable sections. PE timestamp, image size, section sizes, and version resources are useful secondary properties but are not unique enough alone.

The analyzed sample has SHA-256 36093dc1572521ea8c4c5f25548068c971a3d41c7722ef9fe0c05c94e24d6979. Its project identification is 4.21 Stone, while its Windows version resource reports 360, 0, 0, 0; the mismatch is documented in Analyzed Binary.

For an exact match, the profile supplies RVAs, expected instructions, vtables, globals, calling conventions, object fields, and capability-specific validators. The runtime address is always:

loaded_module_base + profile_rva

Do not store a process-specific absolute address in controller configuration.

Dark Ages 4.21 core profile

This table is the core hook profile, not the complete memory profile. UI vtables, roots, and fields remain in Runtime UI Memory Map and Pane Virtual Table Inventory.

What a profile must contain

A useful profile contains more than symbol addresses:

A controller should receive the active profile identifier during HELLO_REPLY and repeat it in diagnostic logs and captured metadata. This prevents a memory path from one build being silently applied to another.

Signature scanning

A function signature is useful only when it survives relocations and still has enough structure to be unique. Generate signatures from decoded instructions, not by copying a long unexamined byte range.

The scanner should:

1. Restrict the search to the expected PE section and executable or read-only data class.
2. Wildcard absolute image addresses, import pointers, relative-call displacements, jump-table addresses, and other relocation-sensitive operands.
3. Preserve stable opcodes, constants, stack cleanup, field displacements, queue codes, and branch relationships when they are part of the established contract.
4. Require a unique candidate before semantic validation.
5. Decode the candidate and verify its control flow, callees, globals, object fields, and ownership behavior.
6. Resolve related symbols as a group and verify their cross-references.

A generic function prologue such as register saves and stack allocation is not a signature. A source filename or nearby assertion string is a useful anchor but is not proof. The final candidate must perform the mapped data flow.

Semantic validators for the core hooks

Validation should also confirm the expected vtable at each live root. A matching function body with a mismatched owner layout is not enough to enable mutation.

Capability gating

Resolve capabilities independently, then expose only the ones whose complete dependency set passed:

If a required mutation dependency fails, disable that capability. Do not fall back to an unvalidated nearest address. Passive build diagnostics can remain available without client hooks.

Porting to 5.x and 7.x

Why one-time reversing is still required

Shared source lineage is valuable because queue codes, class roles, packet actions, assertion text, vtable shapes, and ownership patterns may remain recognizable. It does not guarantee stable machine code or memory layouts. These changes can invalidate a 4.21 profile while leaving the game visibly similar:

• compiler or optimization changes;
• inserted class fields that shift every later offset;
• new virtual methods that shift vtable slots;
• inlining or outlining of queue wrappers;
• different static initialization and linker ordering;
• larger packet, map, UI, or transport buffers;
• changed ownership or thread-affinity rules;
• security additions around packet processing.

Function scanning also does not find heap fields automatically. Character statistics, inventory, and world-object walking require profile-specific owner roots, object discriminators, container layouts, and deletion rules. These should be established once for each family and then compared structurally with 4.21.

Recommended porting order

1. Identify the exact executable and record its hash without adding it to the repository.
2. Map WinMain, app_initialize, the message procedure, and app_shutdown.
3. Locate the generic worker queue and distinguish the dispatcher, EventMan, and Socket objects.
4. Trace decoded receive bytes into pane delivery and packet builders into the logical send queue.
5. Establish Event type layout, Event cleanup, pane handler vslots, and timer delivery.
6. Find EventMan, Socket, dispatcher, Screen, MapPane, and persistent character-pane roots.
7. Map state fields from packet handlers and multiple callers, not from string proximity.
8. Update IDA names, types, comments, and vtable slots.
9. Produce an exact profile and instruction-aware signatures from the established functions.
10. Run passive telemetry first. Enable blocking, injection, and writes only after runtime observations agree with the static model.

Start with one representative 5.x build and one representative 7.x build. If several patch revisions differ only slightly, signatures and semantic validators can likely cover them. If allocation sizes, vtable layouts, or packet ownership change, split them into separate profiles even when the major version is the same.

Comparing profiles

Use semantic identifiers across profiles while storing version-specific details beneath them. For example, all profiles can export logical_client_send, but each entry supplies its own RVA, ABI, transfer-gate offset, sentinel rule, and validators. The IPC command stays stable while the injected adapter changes by profile.

For memory, compare paths rather than absolute offsets alone:

semantic root -> owner relationship -> container kind -> element discriminator -> field

If EventMan -> owned Socket remains true but the owner offset changes, the profile records the new offset. If a later client moves the Socket to another singleton, the semantic path changes and must be re-established rather than forced into the old shape.

Code-level flow

Resolver flow

load image metadata
  -> exact immutable-section hash match
      -> load exact profile
  -> otherwise scan instruction-aware signatures
      -> collect unique candidates
      -> run per-symbol semantic validators
      -> validate roots, vtables, and cross-references
      -> build a temporary resolved profile
  -> evaluate capability dependency sets
  -> install only fully validated capabilities

The temporary resolved profile should be exportable as diagnostic data, but it should not be promoted to a maintained profile until the same addresses and layouts are confirmed in IDA and, where needed, by controlled runtime observation.

Normalized instruction matching

For matching purposes, represent each instruction by opcode class and stable operand properties. Relative targets can be expressed as “call to candidate with validator X” rather than a fixed displacement. Absolute globals can be expressed as “writable image address published by constructor Y.” This is more durable than a byte mask alone and permits cross-symbol validation.

A byte mask can remain the fast first stage. The instruction model is the proof stage before hook installation.

Field-offset recovery

Do not copy 4.21 offsets into an unknown profile. Recover offsets from established functions and require agreement across independent uses. Examples include:

• Event type reads in all three classifier functions;
• packet pointer and size writes in socket Event construction and reads in dispatcher cleanup;
• Socket transfer-gate reads in logical send queueing;
• Socket connection flag writes in connect, receive-zero, and disconnect paths;
• Pane visibility reads, show writes, and hide writes;
• parent slot-array reads in add, remove, destructor, and activation paths.

Only publish a field after its owner, width, signedness, and lifecycle agree across the relevant sites.

Function table

Format Catalog

This catalog will link to one page per understood file or container format.

Each format page must explain its purpose and loading flow, then record byte order, complete field layout, string rules, validation, reader and writer call paths, and relevant function addresses. Unknown fields must retain their exact offset and width.

Catalog

Protocol Catalog

The Stone client uses a direction-sensitive action byte inside an 0xAA binary frame. This catalog separates client actions from server actions because equal numeric values can have unrelated behavior.

Transport and framing

The standard network transport is an IPv4 TCP byte stream. Frames have this wire layout:

AA [uint16 body_length, big-endian] [body bytes...]

body_length includes the action and every remaining wire body byte. It excludes the marker and its own two bytes. Total frame length is body_length + 3.

Ordinary transformed bodies have this form:

[action] [sequence] [XOR-transformed payload and zero sentinel]

The logical packet delivered to or accepted from application code is:

[action] [payload] [zero sentinel]

The sequence byte and XOR passes are omitted for client actions 0x00, 0x10, and 0x48, and for server actions 0x00, 0x03, and 0x40. Only transformed client packets consume and increment the client send sequence. See Sequence and XOR Transformation for the exact pass order, negotiated key, and generated-table formulas.

Directional catalogs

Thirty-five action values occur in both lists. Direction is part of a packet’s identity.

The server action 0x4B contains a big-endian length followed by a logical client packet. The client forwards that embedded packet through its normal send queue. This permits a server-selected action in addition to the 51 constants present in client packet builders.

Current interpretation level

The indexes distinguish established action support from payload details that still require tracing:

• Direction-prefixed C... and S... class names identify messages in the 4.21 protocol catalog.
• Payload fields and behavioral meanings are documented only when instructions, data flow, diagnostics, or visible state changes establish them.
• Builder and handler addresses are included even when individual payload fields remain to be analyzed.

The indexes are exhaustive for fixed action constants accepted or emitted by the traced Stone packet path. They are not claims that every payload schema is already understood.

Direction-specific network-owned IDA names use net_c_... for client-to-server code and net_s_... for server-to-client code. Direction-neutral transport code retains net_.... Methods owned primarily by another subsystem retain that subsystem prefix, such as ui_... for pane packet dispatch.

Sequence and XOR Transformation

Most binary packets carry a sequence byte and use three XOR passes over the payload plus a trailing zero. The message indexes call this Encrypted: Yes for protocol familiarity. It is obfuscation rather than authenticated encryption: there is no integrity tag, message authentication code, or cryptographic security boundary.

Wire placement

The transformation applies inside the standard 0xAA frame:

Encrypted:     AA [uint16 body_length, big-endian] [action] [sequence] [XOR(payload || 00)]
Not encrypted: AA [uint16 body_length, big-endian] [action] [payload] [00]

body_length counts the action and every subsequent body byte. It excludes the marker and the two-byte length. The action remains visible in both forms. Only the payload and trailing zero enter the XOR passes.

These actions bypass the sequence and XOR code:

All other fixed actions in the current indexes use the encrypted branch.

Runtime state and defaults

Clear client packets do not consume the client send sequence. On receive, the decoder uses the sequence carried by the server packet. No independent receive counter or monotonic-sequence check appears in the decoded server path.

Server-controlled key and table

The server can replace both transformation inputs during the clear SVersionCheck action 0x00. Subtype 0x00 has this payload prefix:

ui_main_menu_handle_server_packet queues the table update through net_queue_xor_table_function and the key update through net_queue_xor_key. Socket work codes 11 and 10 apply them in net_process_work_item. The general setter accepts a key length no greater than nine, but this server-negotiation path asserts that the supplied length equals nine.

Because action 0x00 is not encrypted, these values can establish new state without depending on the previous key or table.

Client encoding

The encoder produces: