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