refactor: extract GfxHandler subsystem to render/gfx_handler.rs

Move GfxDir/GfxHandler resource loading functions out of ddgame.rs:
- gfx_dir_hash, gfx_dir_find_entry, gfx_handler_reset
- gfx_handler_load_dir, gfx_resource_create
- call_gfx_find_and_load, call_gfx_load_and_wrap
- call_gfx_load_image, call_gfx_load_dir (asm bridges)
- GFX_LOAD_IMAGE_ADDR, GFX_LOAD_DIR_ADDR statics

ddgame.rs: 2640 → 2250 lines (-390)
New: render/gfx_handler.rs (422 lines)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

crates/openwa-core/src/engine/ddgame.rs

@@ -9,6 +9,13 @@ use crate::engine::ddgame_wrapper::DDGameWrapper;
 use crate::engine::game_info::GameInfo;
 use crate::input::keyboard::DDKeyboard;
 use crate::rebase::rb;
+// Re-export public GfxHandler functions so existing `engine::ddgame::*` imports keep working.
+use crate::render::gfx_handler::{
+    call_gfx_find_and_load, call_gfx_load_and_wrap, call_gfx_load_dir,
+};
+pub use crate::render::gfx_handler::{
+    gfx_dir_find_entry, gfx_handler_load_dir, gfx_resource_create,
+};
 use crate::render::landscape::PCLandscape;
 use crate::render::queue::RenderQueue;
 use crate::render::turn_order::TurnOrderWidget;
@@ -563,333 +570,17 @@ pub unsafe fn display_layer_color_init(wrapper: *mut DDGameWrapper) {
     set_color(display, 3, 0x70);
 }
 
-/// Hash function for GfxDir entry lookup (FUN_566390).
-///
-/// 10-bit CRC-like hash over the global name buffer at 0x8ACF58.
-/// Operates on the already-lowercased name.
-///
-/// # Safety
-/// `name` must be a valid null-terminated C string pointer.
-unsafe fn gfx_dir_hash(name: *const u8) -> u32 {
-    let mut hash: u32 = 0;
-    let mut p = name;
-    while *p != 0 {
-        let bit9 = (hash >> 9) & 1;
-        hash = ((hash << 1) | bit9) & 0x3FF;
-        hash = hash.wrapping_add(*p as u32) & 0x3FF;
-        p = p.add(1);
-    }
-    hash
-}
-
-/// Pure Rust implementation of GfxDir__FindEntry (0x566520).
-///
-/// Convention: usercall(EAX=name) + 1 stack(gfx_handler), RET 0x4.
-///
-/// Looks up a name in the GfxHandler's hash table. Names are case-insensitive.
-/// Supports `|`-separated fallback names (e.g. "path\\file.img|fallback.img").
-///
-/// Returns entry pointer or null. Entry layout:
-/// - entry+0x00: next pointer (linked list)
-/// - entry+0x04: value (passed to vtable[2] for cached load)
-/// - entry+0x08: unknown
-/// - entry+0x0C: name string (null-terminated, lowercase)
-///
-/// # Safety
-/// `gfx_handler` must be a valid GfxHandler with initialized hash table at +0x04.
-/// `name` must be a valid null-terminated C string.
-#[cfg(target_arch = "x86")]
-pub unsafe fn gfx_dir_find_entry(name: *const u8, gfx_handler: *mut u8) -> *mut u8 {
-    let mut current_name = name;
-
-    loop {
-        // Copy name to stack buffer (max 0xFF chars + null)
-        let mut buf = [0u8; 0x100];
-        let mut i = 0usize;
-        let mut src = current_name;
-        while *src != 0 && i < 0xFF {
-            buf[i] = *src;
-            src = src.add(1);
-            i += 1;
-        }
-        buf[i] = 0;
-
-        // Find '|' separator in buffer
-        let mut pipe_pos: Option<usize> = None;
-        for j in 0..i {
-            if buf[j] == b'|' {
-                buf[j] = 0; // truncate at pipe
-                pipe_pos = Some(j);
-                break;
-            }
-        }
-
-        // Compute next_name: pointer into original string after '|'
-        let next_name: *const u8 = if let Some(pos) = pipe_pos {
-            // Offset of '|' in buffer = pos
-            // Same offset in original string → current_name + pos + 1
-            current_name.add(pos + 1)
-        } else {
-            core::ptr::null()
-        };
-
-        // Lowercase A-Z in buffer
-        for j in 0..buf.len() {
-            if buf[j] == 0 {
-                break;
-            }
-            if buf[j] >= b'A' && buf[j] <= b'Z' {
-                buf[j] += 0x20;
-            }
-        }
-
-        // Hash the lowercased name
-        let bucket = gfx_dir_hash(buf.as_ptr());
-
-        // Walk linked list in hash bucket
-        // gfx_handler+4 = pointer to bucket array (1024 entries)
-        let bucket_array = *(gfx_handler.add(4) as *const *const u32);
-        let mut entry = *bucket_array.add(bucket as usize) as *mut u8;
-
-        while !entry.is_null() {
-            // Compare entry name at entry+0x0C with our buffer
-            let entry_name = entry.add(0x0C);
-            let mut match_found = true;
-            let mut k = 0usize;
-            loop {
-                let a = *entry_name.add(k);
-                let b = buf[k];
-                if a != b {
-                    match_found = false;
-                    break;
-                }
-                if a == 0 {
-                    break;
-                }
-                k += 1;
-            }
-
-            if match_found {
-                return entry;
-            }
-
-            // Next in linked list: entry+0x00
-            entry = *(entry as *const *mut u8);
-        }
-
-        // Not found — try fallback name after '|'
-        if next_name.is_null() {
-            return core::ptr::null_mut();
-        }
-        current_name = next_name;
-    }
-}
-
-/// Pure Rust implementation of FUN_5665F0 (GfxHandler reset).
-///
-/// Convention: usercall(ESI=handler), plain RET. Called at start of LoadDir.
-unsafe fn gfx_handler_reset(handler: *mut u8) {
-    *(handler.add(0x04) as *mut u32) = 0;
-    *(handler.add(0x08) as *mut u32) = 0;
-    *(handler.add(0x194) as *mut u32) = 0;
-
-    for i in 0..16u32 {
-        // handler+0x0C + i*0x10 = 0 (16 entries at stride 0x10)
-        *(handler.add(0x0C + i as usize * 0x10) as *mut u32) = 0;
-        // handler+0x10C + i*4 = i (index array)
-        *(handler.add(0x10C + i as usize * 4) as *mut u32) = i;
-    }
-
-    *(handler.add(400) as *mut u32) = 0; // 0x190
-    *(handler.add(0x18C) as *mut u32) = 0x10;
-}
-
-/// Pure Rust implementation of GfxHandler__LoadDir (0x5663E0).
-///
-/// Convention: usercall(EAX=handler), plain RET. Returns 1 on success, 0 on failure.
-///
-/// Reads a .dir file through the handler's vtable I/O methods:
-/// - vtable[0]: read(buf, size) → thiscall, returns bytes read
-/// - vtable[1]: seek/reposition(size) → thiscall
-/// - vtable[2]: allocate(size) → thiscall, returns buffer or null
-///
-/// .dir file format:
-/// - 4 bytes: magic "DIR\x1A" (0x1A524944)
-/// - 4 bytes: total_file_size
-/// - 4 bytes: data_size (hash table + entries)
-/// - data: 1024-bucket hash table followed by linked list nodes
-///   All pointers are relative offsets from (data_start + 4)
-///
-/// # Safety
-/// `handler` must be a valid GfxHandler with file handle at +0x198.
-#[cfg(target_arch = "x86")]
-pub unsafe fn gfx_handler_load_dir(handler: *mut u8) -> i32 {
-    gfx_handler_reset(handler);
-
-    let vt = *(handler as *const *const u32);
-    // vtable[0] = read: thiscall(handler, buf, size) -> bytes_read
-    let vt_read: unsafe extern "thiscall" fn(*mut u8, *mut u8, u32) -> u32 =
-        core::mem::transmute(*vt);
-    // vtable[1] = seek: thiscall(handler, size)
-    let vt_seek: unsafe extern "thiscall" fn(*mut u8, u32) = core::mem::transmute(*vt.add(1));
-    // vtable[2] = allocate: thiscall(handler, size) -> *mut u8
-    let vt_alloc: unsafe extern "thiscall" fn(*mut u8, u32) -> *mut u8 =
-        core::mem::transmute(*vt.add(2));
-
-    // Read and validate magic
-    let mut magic: u32 = 0;
-    if vt_read(handler, &mut magic as *mut u32 as *mut u8, 4) != 4 {
-        return 0;
-    }
-    if magic != 0x1A524944 {
-        // "DIR\x1A"
-        return 0;
-    }
-
-    // Read total_file_size and data_size
-    let mut total_file_size: u32 = 0;
-    if vt_read(handler, &mut total_file_size as *mut u32 as *mut u8, 4) != 4 {
-        return 0;
-    }
-    let mut data_size: u32 = 0;
-    if vt_read(handler, &mut data_size as *mut u32 as *mut u8, 4) != 4 {
-        return 0;
-    }
-
-    let alloc_size = data_size + 4;
-
-    // Try fast path: vtable[2] allocate (memory-maps the data)
-    let data = vt_alloc(handler, alloc_size);
-    *(handler.add(4) as *mut *mut u8) = data;
-
-    if data.is_null() {
-        // Fallback: seek past header, then malloc + read entire data block.
-        // Original calls vt_seek(alloc_size) then WA_MallocMemset(EDI=read_size).
-        // WA_MallocMemset allocates (size+3)&~3 + 0x20 and memsets size bytes.
-        vt_seek(handler, alloc_size);
-
-        let read_size = total_file_size - data_size - 4;
-        let malloc_size = ((read_size + 3) & !3) + 0x20;
-        let buf = wa_malloc(malloc_size);
-        if buf.is_null() {
-            return 0;
-        }
-        core::ptr::write_bytes(buf, 0, read_size as usize);
-        *(handler.add(4) as *mut *mut u8) = buf;
-
-        let bytes_read = vt_read(handler, buf, read_size);
-        if bytes_read != read_size {
-            crate::wa_alloc::wa_free(buf);
-            return 0;
-        }
-
-        // Mark as "loaded from fallback" at handler+8
-        *(handler.add(8) as *mut u32) = 1;
-    }
-
-    // Fix up relative pointers in the hash table
-    // 1024 buckets at data[0..0x1000], each is a pointer to a linked list node
-    let data = *(handler.add(4) as *const *mut u8);
-    let base = data as u32;
-
-    for bucket in 0..1024u32 {
-        let bucket_ptr = data.add(bucket as usize * 4) as *mut u32;
-        let entry_offset = *bucket_ptr;
-        if entry_offset == 0 {
-            continue;
-        }
-
-        // Convert relative offset to absolute: offset + base - 4
-        let entry_addr = entry_offset.wrapping_add(base).wrapping_sub(4);
-        *bucket_ptr = entry_addr;
-
-        // Walk linked list, fix up each next pointer
-        let mut node = entry_addr as *mut u32;
-        loop {
-            if node.is_null() {
-                break;
-            }
-            let next_offset = *node;
-            if next_offset == 0 {
-                break;
-            }
-            let next_addr = next_offset.wrapping_add(base).wrapping_sub(4);
-            *node = next_addr;
-            node = next_addr as *mut u32;
-        }
-    }
-
-    *(handler.add(0x194) as *mut u32) = 1;
-
-    1 // success
-}
-
-/// Pure Rust implementation of GfxResource__Create_Maybe (0x4F6300).
-///
-/// Convention: usercall(ECX=gfx_handler, EAX=name) + 1 stack(output), RET 0x4.
-///
-/// Looks up `name` in the GfxHandler's directory, tries cached load, wraps
-/// as DisplayGfx. Falls back to loading the raw image and decoding it.
-///
-/// # Safety
-/// All pointers must be valid WA objects.
-#[cfg(target_arch = "x86")]
-pub unsafe fn gfx_resource_create(
-    gfx_handler: *mut u8,
-    name: *const u8,
-    output: *mut u8,
-) -> *mut u8 {
-    // 1. Try FindEntry → cached load → DisplayGfx wrap
-    let entry = gfx_dir_find_entry(name, gfx_handler);
-    if !entry.is_null() {
-        // gfx_handler->vtable[2](entry->field_4) — cached load
-        let vt = *(gfx_handler as *const *const u32);
-        let load_cached: unsafe extern "thiscall" fn(*mut u8, u32) -> *mut u8 =
-            core::mem::transmute(*vt.add(2));
-        let entry_val = *(entry.add(4) as *const u32);
-        let cached = load_cached(gfx_handler, entry_val);
-        if !cached.is_null() {
-            // DisplayGfx__Constructor_Maybe: stdcall(raw_image), RET 0x4
-            let ctor: unsafe extern "stdcall" fn(*mut u8) -> *mut u8 =
-                core::mem::transmute(rb(va::DISPLAYGFX_CONSTRUCTOR) as usize);
-            return ctor(cached);
-        }
-    }
-
-    // 2. Fallback: LoadImage → IMG_Decode
-    let raw_image = call_gfx_load_image(gfx_handler, name);
-    if raw_image.is_null() {
-        return core::ptr::null_mut();
-    }
-
-    // IMG_Decode: stdcall(output, raw_image, 1), RET 0xC
-    let decode: unsafe extern "stdcall" fn(*mut u8, *mut u8, i32) -> *mut u8 =
-        core::mem::transmute(rb(va::IMG_DECODE) as usize);
-    let result = decode(output, raw_image, 1);
-
-    // Release raw image: raw_image->vtable[0](1)
-    let img_vt = *(raw_image as *const *const u32);
-    let fn_ptr = *img_vt;
-    let release: unsafe extern "thiscall" fn(*mut u8, i32) = core::mem::transmute(fn_ptr);
-    release(raw_image, 1);
-
-    result
-}
-
-static mut GFX_LOAD_DIR_ADDR: u32 = 0;
-
 /// Initialize runtime addresses for the constructor bridges.
 /// Must be called once at DLL startup (from lib.rs or similar).
 pub fn init_constructor_addrs() {
     unsafe {
         SPRITE_REGION_CTOR_ADDR = rb(va::SPRITE_REGION_CONSTRUCTOR);
         FUN_570A90_ADDR = rb(va::FUN_570A90);
-        GFX_LOAD_IMAGE_ADDR = rb(va::GFX_DIR_LOAD_IMAGE);
-        GFX_LOAD_DIR_ADDR = rb(va::GFX_HANDLER_LOAD_DIR);
         FUN_570F30_ADDR = rb(va::DDGAME_INIT_SOUND_PATHS);
         LOAD_SPEECH_BANKS_ADDR = rb(va::DSSOUND_LOAD_ALL_SPEECH_BANKS);
         LOADING_PROGRESS_TICK_ADDR = rb(va::DDGAME_WRAPPER_LOADING_PROGRESS_TICK);
     }
+    crate::render::gfx_handler::init_addrs();
 }
 
 /// Bridge to DDGame__InitVersionFlags (0x525BE0).
@@ -1043,7 +734,9 @@ unsafe fn init_graphics_and_resources(
     for (i, path) in paths.iter().enumerate() {
         let fp = fopen(path.as_ptr(), b"rb\0".as_ptr());
         *(gfx1.add(0x198) as *mut *mut u8) = fp;
-        if !fp.is_null() && call_gfx_load_dir(gfx1, GFX_LOAD_DIR_ADDR) != 0 {
+        if !fp.is_null()
+            && call_gfx_load_dir(gfx1, crate::render::gfx_handler::gfx_load_dir_addr()) != 0
+        {
             gfx_loaded_idx = i as u32;
             break;
         }
@@ -1074,10 +767,14 @@ unsafe fn init_graphics_and_resources(
 
         let fp = fopen(gfx_c_path.as_ptr(), b"rb\0".as_ptr());
         *(gfx2.add(0x198) as *mut *mut u8) = fp;
-        if fp.is_null() || call_gfx_load_dir(gfx2, GFX_LOAD_DIR_ADDR) == 0 {
+        if fp.is_null()
+            || call_gfx_load_dir(gfx2, crate::render::gfx_handler::gfx_load_dir_addr()) == 0
+        {
             let fp2 = fopen(b"data\\Gfx\\Gfx.dir\0".as_ptr(), b"rb\0".as_ptr());
             *(gfx2.add(0x198) as *mut *mut u8) = fp2;
-            if fp2.is_null() || call_gfx_load_dir(gfx2, GFX_LOAD_DIR_ADDR) == 0 {
+            if fp2.is_null()
+                || call_gfx_load_dir(gfx2, crate::render::gfx_handler::gfx_load_dir_addr()) == 0
+            {
                 panic!("DDGame: couldn't open secondary Gfx.dir");
             }
         }
@@ -1668,35 +1365,6 @@ unsafe fn init_graphics_and_resources(
     let _ = crate::log::log_line("[DDGame] init_graphics_and_resources DONE");
 }
 
-/// Helper: find entry in GfxDir and load image, or load directly.
-/// Returns a DisplayGfx/sprite pointer or null.
-#[cfg(target_arch = "x86")]
-unsafe fn call_gfx_find_and_load(
-    gfx_dir: *mut u8,
-    name: *const u8,
-    display_ctx: *mut u8,
-) -> *mut u8 {
-    let entry = gfx_dir_find_entry(name, gfx_dir);
-
-    if !entry.is_null() {
-        // Try cached load: gfx_dir->vtable[2](entry->field_4)
-        let dir_vt = *(gfx_dir as *const *const u32);
-        let load_cached: unsafe extern "thiscall" fn(*mut u8, u32) -> *mut u8 =
-            core::mem::transmute(*dir_vt.add(2));
-        let cached = load_cached(gfx_dir, *(entry.add(4) as *const u32));
-        if !cached.is_null() {
-            // Wrap with DisplayGfx__Constructor_Maybe (0x4F5E80)
-            // This is stdcall(1 param), RET 0x4
-            let ctor: unsafe extern "stdcall" fn(*mut u8) -> *mut u8 =
-                core::mem::transmute(rb(0x4F5E80) as usize);
-            return ctor(cached);
-        }
-    }
-
-    // Fallback: load image directly
-    call_gfx_load_and_wrap(gfx_dir, name, display_ctx)
-}
-
 // ── Complex gradient computation ──────────────────────────────────────────────
 
 /// Palette context for gradient color mapping.
@@ -2024,64 +1692,6 @@ unsafe fn call_usercall_ecx(wrapper: *mut DDGameWrapper, addr: u32) {
     f(wrapper);
 }
 
-/// Bridge to GfxHandler__LoadDir (0x5663E0).
-/// Convention: usercall(EAX=handler), plain RET. Returns nonzero on success.
-#[cfg(target_arch = "x86")]
-unsafe fn call_gfx_load_dir(handler: *mut u8, addr: u32) -> i32 {
-    let result: i32;
-    core::arch::asm!(
-        "call {addr}",
-        addr = in(reg) addr,
-        inlateout("eax") handler => result,
-        out("ecx") _,
-        out("edx") _,
-        clobber_abi("C"),
-    );
-    result
-}
-
-// GfxDir__LoadImage is usercall(ESI=gfx_handler) + 1 stack(name), RET 0x4.
-// Returns raw image pointer or null.
-static mut GFX_LOAD_IMAGE_ADDR: u32 = 0;
-
-#[cfg(target_arch = "x86")]
-#[unsafe(naked)]
-unsafe extern "C" fn call_gfx_load_image(_gfx_handler: *mut u8, _name: *const u8) -> *mut u8 {
-    core::arch::naked_asm!(
-        "pushl %esi",
-        "movl 8(%esp), %esi",     // ESI = gfx_handler
-        "pushl 12(%esp)",         // push name (callee cleans via RET 0x4)
-        "calll *({addr})",
-        "popl %esi",
-        "retl",
-        addr = sym GFX_LOAD_IMAGE_ADDR,
-        options(att_syntax),
-    );
-}
-
-/// Helper: load image via GfxDir__LoadImage + wrap as DisplayGfx.
-/// Used by arrow sprite loop when GfxDir__FindEntry returns null.
-#[cfg(target_arch = "x86")]
-unsafe fn call_gfx_load_and_wrap(
-    gfx_handler: *mut u8,
-    name: *const u8,
-    display_ctx: *mut u8,
-) -> *mut u8 {
-    let image = call_gfx_load_image(gfx_handler, name);
-    if image.is_null() {
-        return core::ptr::null_mut();
-    }
-    // FUN_004F5F80(display_ctx, image, 1) — stdcall, RET 0xC (3 params)
-    let f: unsafe extern "stdcall" fn(*mut u8, *mut u8, u32) -> *mut u8 =
-        core::mem::transmute(rb(0x4F5F80) as usize);
-    let result = f(display_ctx, image, 1);
-    // Release the raw image
-    let image_vt = *(image as *const *const u32);
-    let destroy: unsafe extern "thiscall" fn(*mut u8, u32) = core::mem::transmute(*image_vt);
-    destroy(image, 1);
-    result
-}
-
 /// Bridge to SpriteRegion__Constructor (0x57DB20).
 /// Convention: fastcall(ECX, EDX) + 6 stack params, RET 0x18.
 #[cfg(target_arch = "x86")]

crates/openwa-core/src/render/gfx_handler.rs

@@ -0,0 +1,422 @@
+//! GfxHandler/GfxDir resource loading subsystem.
+
+use crate::address::va;
+use crate::rebase::rb;
+use crate::wa_alloc::wa_malloc;
+
+/// Hash function for GfxDir entry lookup (FUN_566390).
+///
+/// 10-bit CRC-like hash over the global name buffer at 0x8ACF58.
+/// Operates on the already-lowercased name.
+///
+/// # Safety
+/// `name` must be a valid null-terminated C string pointer.
+unsafe fn gfx_dir_hash(name: *const u8) -> u32 {
+    let mut hash: u32 = 0;
+    let mut p = name;
+    while *p != 0 {
+        let bit9 = (hash >> 9) & 1;
+        hash = ((hash << 1) | bit9) & 0x3FF;
+        hash = hash.wrapping_add(*p as u32) & 0x3FF;
+        p = p.add(1);
+    }
+    hash
+}
+
+/// Pure Rust implementation of GfxDir__FindEntry (0x566520).
+///
+/// Convention: usercall(EAX=name) + 1 stack(gfx_handler), RET 0x4.
+///
+/// Looks up a name in the GfxHandler's hash table. Names are case-insensitive.
+/// Supports `|`-separated fallback names (e.g. "path\\file.img|fallback.img").
+///
+/// Returns entry pointer or null. Entry layout:
+/// - entry+0x00: next pointer (linked list)
+/// - entry+0x04: value (passed to vtable[2] for cached load)
+/// - entry+0x08: unknown
+/// - entry+0x0C: name string (null-terminated, lowercase)
+///
+/// # Safety
+/// `gfx_handler` must be a valid GfxHandler with initialized hash table at +0x04.
+/// `name` must be a valid null-terminated C string.
+#[cfg(target_arch = "x86")]
+pub unsafe fn gfx_dir_find_entry(name: *const u8, gfx_handler: *mut u8) -> *mut u8 {
+    let mut current_name = name;
+
+    loop {
+        // Copy name to stack buffer (max 0xFF chars + null)
+        let mut buf = [0u8; 0x100];
+        let mut i = 0usize;
+        let mut src = current_name;
+        while *src != 0 && i < 0xFF {
+            buf[i] = *src;
+            src = src.add(1);
+            i += 1;
+        }
+        buf[i] = 0;
+
+        // Find '|' separator in buffer
+        let mut pipe_pos: Option<usize> = None;
+        for j in 0..i {
+            if buf[j] == b'|' {
+                buf[j] = 0; // truncate at pipe
+                pipe_pos = Some(j);
+                break;
+            }
+        }
+
+        // Compute next_name: pointer into original string after '|'
+        let next_name: *const u8 = if let Some(pos) = pipe_pos {
+            // Offset of '|' in buffer = pos
+            // Same offset in original string → current_name + pos + 1
+            current_name.add(pos + 1)
+        } else {
+            core::ptr::null()
+        };
+
+        // Lowercase A-Z in buffer
+        for j in 0..buf.len() {
+            if buf[j] == 0 {
+                break;
+            }
+            if buf[j] >= b'A' && buf[j] <= b'Z' {
+                buf[j] += 0x20;
+            }
+        }
+
+        // Hash the lowercased name
+        let bucket = gfx_dir_hash(buf.as_ptr());
+
+        // Walk linked list in hash bucket
+        // gfx_handler+4 = pointer to bucket array (1024 entries)
+        let bucket_array = *(gfx_handler.add(4) as *const *const u32);
+        let mut entry = *bucket_array.add(bucket as usize) as *mut u8;
+
+        while !entry.is_null() {
+            // Compare entry name at entry+0x0C with our buffer
+            let entry_name = entry.add(0x0C);
+            let mut match_found = true;
+            let mut k = 0usize;
+            loop {
+                let a = *entry_name.add(k);
+                let b = buf[k];
+                if a != b {
+                    match_found = false;
+                    break;
+                }
+                if a == 0 {
+                    break;
+                }
+                k += 1;
+            }
+
+            if match_found {
+                return entry;
+            }
+
+            // Next in linked list: entry+0x00
+            entry = *(entry as *const *mut u8);
+        }
+
+        // Not found — try fallback name after '|'
+        if next_name.is_null() {
+            return core::ptr::null_mut();
+        }
+        current_name = next_name;
+    }
+}
+
+/// Pure Rust implementation of FUN_5665F0 (GfxHandler reset).
+///
+/// Convention: usercall(ESI=handler), plain RET. Called at start of LoadDir.
+unsafe fn gfx_handler_reset(handler: *mut u8) {
+    *(handler.add(0x04) as *mut u32) = 0;
+    *(handler.add(0x08) as *mut u32) = 0;
+    *(handler.add(0x194) as *mut u32) = 0;
+
+    for i in 0..16u32 {
+        // handler+0x0C + i*0x10 = 0 (16 entries at stride 0x10)
+        *(handler.add(0x0C + i as usize * 0x10) as *mut u32) = 0;
+        // handler+0x10C + i*4 = i (index array)
+        *(handler.add(0x10C + i as usize * 4) as *mut u32) = i;
+    }
+
+    *(handler.add(400) as *mut u32) = 0; // 0x190
+    *(handler.add(0x18C) as *mut u32) = 0x10;
+}
+
+/// Pure Rust implementation of GfxHandler__LoadDir (0x5663E0).
+///
+/// Convention: usercall(EAX=handler), plain RET. Returns 1 on success, 0 on failure.
+///
+/// Reads a .dir file through the handler's vtable I/O methods:
+/// - vtable[0]: read(buf, size) → thiscall, returns bytes read
+/// - vtable[1]: seek/reposition(size) → thiscall
+/// - vtable[2]: allocate(size) → thiscall, returns buffer or null
+///
+/// .dir file format:
+/// - 4 bytes: magic "DIR\x1A" (0x1A524944)
+/// - 4 bytes: total_file_size
+/// - 4 bytes: data_size (hash table + entries)
+/// - data: 1024-bucket hash table followed by linked list nodes
+///   All pointers are relative offsets from (data_start + 4)
+///
+/// # Safety
+/// `handler` must be a valid GfxHandler with file handle at +0x198.
+#[cfg(target_arch = "x86")]
+pub unsafe fn gfx_handler_load_dir(handler: *mut u8) -> i32 {
+    gfx_handler_reset(handler);
+
+    let vt = *(handler as *const *const u32);
+    // vtable[0] = read: thiscall(handler, buf, size) -> bytes_read
+    let vt_read: unsafe extern "thiscall" fn(*mut u8, *mut u8, u32) -> u32 =
+        core::mem::transmute(*vt);
+    // vtable[1] = seek: thiscall(handler, size)
+    let vt_seek: unsafe extern "thiscall" fn(*mut u8, u32) = core::mem::transmute(*vt.add(1));
+    // vtable[2] = allocate: thiscall(handler, size) -> *mut u8
+    let vt_alloc: unsafe extern "thiscall" fn(*mut u8, u32) -> *mut u8 =
+        core::mem::transmute(*vt.add(2));
+
+    // Read and validate magic
+    let mut magic: u32 = 0;
+    if vt_read(handler, &mut magic as *mut u32 as *mut u8, 4) != 4 {
+        return 0;
+    }
+    if magic != 0x1A524944 {
+        // "DIR\x1A"
+        return 0;
+    }
+
+    // Read total_file_size and data_size
+    let mut total_file_size: u32 = 0;
+    if vt_read(handler, &mut total_file_size as *mut u32 as *mut u8, 4) != 4 {
+        return 0;
+    }
+    let mut data_size: u32 = 0;
+    if vt_read(handler, &mut data_size as *mut u32 as *mut u8, 4) != 4 {
+        return 0;
+    }
+
+    let alloc_size = data_size + 4;
+
+    // Try fast path: vtable[2] allocate (memory-maps the data)
+    let data = vt_alloc(handler, alloc_size);
+    *(handler.add(4) as *mut *mut u8) = data;
+
+    if data.is_null() {
+        // Fallback: seek past header, then malloc + read entire data block.
+        // Original calls vt_seek(alloc_size) then WA_MallocMemset(EDI=read_size).
+        // WA_MallocMemset allocates (size+3)&~3 + 0x20 and memsets size bytes.
+        vt_seek(handler, alloc_size);
+
+        let read_size = total_file_size - data_size - 4;
+        let malloc_size = ((read_size + 3) & !3) + 0x20;
+        let buf = wa_malloc(malloc_size);
+        if buf.is_null() {
+            return 0;
+        }
+        core::ptr::write_bytes(buf, 0, read_size as usize);
+        *(handler.add(4) as *mut *mut u8) = buf;
+
+        let bytes_read = vt_read(handler, buf, read_size);
+        if bytes_read != read_size {
+            crate::wa_alloc::wa_free(buf);
+            return 0;
+        }
+
+        // Mark as "loaded from fallback" at handler+8
+        *(handler.add(8) as *mut u32) = 1;
+    }
+
+    // Fix up relative pointers in the hash table
+    // 1024 buckets at data[0..0x1000], each is a pointer to a linked list node
+    let data = *(handler.add(4) as *const *mut u8);
+    let base = data as u32;
+
+    for bucket in 0..1024u32 {
+        let bucket_ptr = data.add(bucket as usize * 4) as *mut u32;
+        let entry_offset = *bucket_ptr;
+        if entry_offset == 0 {
+            continue;
+        }
+
+        // Convert relative offset to absolute: offset + base - 4
+        let entry_addr = entry_offset.wrapping_add(base).wrapping_sub(4);
+        *bucket_ptr = entry_addr;
+
+        // Walk linked list, fix up each next pointer
+        let mut node = entry_addr as *mut u32;
+        loop {
+            if node.is_null() {
+                break;
+            }
+            let next_offset = *node;
+            if next_offset == 0 {
+                break;
+            }
+            let next_addr = next_offset.wrapping_add(base).wrapping_sub(4);
+            *node = next_addr;
+            node = next_addr as *mut u32;
+        }
+    }
+
+    *(handler.add(0x194) as *mut u32) = 1;
+
+    1 // success
+}
+
+/// Pure Rust implementation of GfxResource__Create_Maybe (0x4F6300).
+///
+/// Convention: usercall(ECX=gfx_handler, EAX=name) + 1 stack(output), RET 0x4.
+///
+/// Looks up `name` in the GfxHandler's directory, tries cached load, wraps
+/// as DisplayGfx. Falls back to loading the raw image and decoding it.
+///
+/// # Safety
+/// All pointers must be valid WA objects.
+#[cfg(target_arch = "x86")]
+pub unsafe fn gfx_resource_create(
+    gfx_handler: *mut u8,
+    name: *const u8,
+    output: *mut u8,
+) -> *mut u8 {
+    // 1. Try FindEntry → cached load → DisplayGfx wrap
+    let entry = gfx_dir_find_entry(name, gfx_handler);
+    if !entry.is_null() {
+        // gfx_handler->vtable[2](entry->field_4) — cached load
+        let vt = *(gfx_handler as *const *const u32);
+        let load_cached: unsafe extern "thiscall" fn(*mut u8, u32) -> *mut u8 =
+            core::mem::transmute(*vt.add(2));
+        let entry_val = *(entry.add(4) as *const u32);
+        let cached = load_cached(gfx_handler, entry_val);
+        if !cached.is_null() {
+            // DisplayGfx__Constructor_Maybe: stdcall(raw_image), RET 0x4
+            let ctor: unsafe extern "stdcall" fn(*mut u8) -> *mut u8 =
+                core::mem::transmute(rb(va::DISPLAYGFX_CONSTRUCTOR) as usize);
+            return ctor(cached);
+        }
+    }
+
+    // 2. Fallback: LoadImage → IMG_Decode
+    let raw_image = call_gfx_load_image(gfx_handler, name);
+    if raw_image.is_null() {
+        return core::ptr::null_mut();
+    }
+
+    // IMG_Decode: stdcall(output, raw_image, 1), RET 0xC
+    let decode: unsafe extern "stdcall" fn(*mut u8, *mut u8, i32) -> *mut u8 =
+        core::mem::transmute(rb(va::IMG_DECODE) as usize);
+    let result = decode(output, raw_image, 1);
+
+    // Release raw image: raw_image->vtable[0](1)
+    let img_vt = *(raw_image as *const *const u32);
+    let fn_ptr = *img_vt;
+    let release: unsafe extern "thiscall" fn(*mut u8, i32) = core::mem::transmute(fn_ptr);
+    release(raw_image, 1);
+
+    result
+}
+
+/// Helper: find entry in GfxDir and load image, or load directly.
+/// Returns a DisplayGfx/sprite pointer or null.
+#[cfg(target_arch = "x86")]
+pub(crate) unsafe fn call_gfx_find_and_load(
+    gfx_dir: *mut u8,
+    name: *const u8,
+    display_ctx: *mut u8,
+) -> *mut u8 {
+    let entry = gfx_dir_find_entry(name, gfx_dir);
+
+    if !entry.is_null() {
+        // Try cached load: gfx_dir->vtable[2](entry->field_4)
+        let dir_vt = *(gfx_dir as *const *const u32);
+        let load_cached: unsafe extern "thiscall" fn(*mut u8, u32) -> *mut u8 =
+            core::mem::transmute(*dir_vt.add(2));
+        let cached = load_cached(gfx_dir, *(entry.add(4) as *const u32));
+        if !cached.is_null() {
+            // Wrap with DisplayGfx__Constructor_Maybe (0x4F5E80)
+            // This is stdcall(1 param), RET 0x4
+            let ctor: unsafe extern "stdcall" fn(*mut u8) -> *mut u8 =
+                core::mem::transmute(rb(0x4F5E80) as usize);
+            return ctor(cached);
+        }
+    }
+
+    // Fallback: load image directly
+    call_gfx_load_and_wrap(gfx_dir, name, display_ctx)
+}
+
+/// Helper: load image via GfxDir__LoadImage + wrap as DisplayGfx.
+/// Used by arrow sprite loop when GfxDir__FindEntry returns null.
+#[cfg(target_arch = "x86")]
+pub(crate) unsafe fn call_gfx_load_and_wrap(
+    gfx_handler: *mut u8,
+    name: *const u8,
+    display_ctx: *mut u8,
+) -> *mut u8 {
+    let image = call_gfx_load_image(gfx_handler, name);
+    if image.is_null() {
+        return core::ptr::null_mut();
+    }
+    // FUN_004F5F80(display_ctx, image, 1) — stdcall, RET 0xC (3 params)
+    let f: unsafe extern "stdcall" fn(*mut u8, *mut u8, u32) -> *mut u8 =
+        core::mem::transmute(rb(0x4F5F80) as usize);
+    let result = f(display_ctx, image, 1);
+    // Release the raw image
+    let image_vt = *(image as *const *const u32);
+    let destroy: unsafe extern "thiscall" fn(*mut u8, u32) = core::mem::transmute(*image_vt);
+    destroy(image, 1);
+    result
+}
+
+static mut GFX_LOAD_DIR_ADDR: u32 = 0;
+
+// GfxDir__LoadImage is usercall(ESI=gfx_handler) + 1 stack(name), RET 0x4.
+// Returns raw image pointer or null.
+static mut GFX_LOAD_IMAGE_ADDR: u32 = 0;
+
+/// Bridge to GfxHandler__LoadDir (0x5663E0).
+/// Convention: usercall(EAX=handler), plain RET. Returns nonzero on success.
+#[cfg(target_arch = "x86")]
+pub(crate) unsafe fn call_gfx_load_dir(handler: *mut u8, addr: u32) -> i32 {
+    let result: i32;
+    core::arch::asm!(
+        "call {addr}",
+        addr = in(reg) addr,
+        inlateout("eax") handler => result,
+        out("ecx") _,
+        out("edx") _,
+        clobber_abi("C"),
+    );
+    result
+}
+
+#[cfg(target_arch = "x86")]
+#[unsafe(naked)]
+unsafe extern "C" fn call_gfx_load_image(_gfx_handler: *mut u8, _name: *const u8) -> *mut u8 {
+    core::arch::naked_asm!(
+        "pushl %esi",
+        "movl 8(%esp), %esi",     // ESI = gfx_handler
+        "pushl 12(%esp)",         // push name (callee cleans via RET 0x4)
+        "calll *({addr})",
+        "popl %esi",
+        "retl",
+        addr = sym GFX_LOAD_IMAGE_ADDR,
+        options(att_syntax),
+    );
+}
+
+/// Initialize runtime addresses for GfxHandler bridges.
+/// Must be called once at DLL startup.
+pub fn init_addrs() {
+    unsafe {
+        GFX_LOAD_IMAGE_ADDR = rb(va::GFX_DIR_LOAD_IMAGE);
+        GFX_LOAD_DIR_ADDR = rb(va::GFX_HANDLER_LOAD_DIR);
+    }
+}
+
+/// Returns the rebased runtime address for GfxHandler__LoadDir.
+/// Used by callers that pass the address to `call_gfx_load_dir`.
+pub fn gfx_load_dir_addr() -> u32 {
+    unsafe { GFX_LOAD_DIR_ADDR }
+}

crates/openwa-core/src/render/mod.rs

@@ -1,3 +1,4 @@
+pub mod gfx_handler;
 pub mod landscape;
 pub mod queue;
 pub mod sprite;