refactor: create GfxDir struct, rename GfxHandler → GfxDir throughout

New GfxDir struct (0x19C bytes, #[repr(C)]):
- Typed fields: vtable, bucket_array, fallback_alloc, cache_slots,
index_table, slot_count, loaded, file_handle
- GfxDir::alloc(vtable) constructor replaces wa_malloc+memset+vtable pattern
- Size assertion: size_of::<GfxDir>() == 0x19C

Renamed across entire codebase:
- GfxHandler → GfxDir (struct, module, constants)
- gfx_handler.rs → gfx_dir.rs (module file)
- GFX_HANDLER_VTABLE → GFX_DIR_VTABLE
- GFX_HANDLER_LOAD_DIR → GFX_DIR_LOAD_DIR
- GFX_HANDLER_LOAD_SPRITES → GFX_DIR_LOAD_SPRITES
- DDGameWrapper._field_4c0 → primary_gfx_dir
- DDGameWrapper._field_4c4 → secondary_gfx_dir
- Ghidra: GfxHandler__LoadDir → GfxDir__LoadDir, vtable label updated

Eliminated pointer arithmetic:
- gfx_dir_reset: handler.add(0x04/0x08/0x194/etc.) → gfx.field
- gfx_dir_load_dir: handler.add(4/8/0x194) → gfx.field
- gfx_dir_find_entry: handler.add(4) → gfx.bucket_array
- ddgame.rs: gfx.add(0x198) → (*gfx).file_handle

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

crates/openwa-core/src/address.rs

@@ -345,7 +345,7 @@ pub mod va {
     pub const DDGAME_WRAPPER_LOADING_PROGRESS_TICK: u32 = 0x0057_17A0;
     /// DDGame__LoadHudAndWeaponSprites (0x53D0E0): loads weapon icons, wind indicators,
     /// girder sprites, and creates DDGame+0x37C DisplayGfx object.
-    /// thiscall(ECX=gfx_handler_4c0) + 2 stack(ddgame, wrapper_4c4), RET 0x8.
+    /// thiscall(ECX=gfx_dir_4c0) + 2 stack(ddgame, wrapper_4c4), RET 0x8.
     pub const DDGAME_LOAD_HUD_AND_WEAPON_SPRITES: u32 = 0x0053_D0E0;
     /// PaletteContext__Init (0x5411A0): initialize palette context free-list.
     /// usercall(EAX=context), plain RET.
@@ -359,12 +359,12 @@ pub mod va {
     /// g_GameInfo global — set to current GameInfo* during DDGame construction.
     pub const G_GAME_INFO: u32 = 0x0077_49A0;
     /// GfxHandler__LoadSprites_Maybe (0x570B50): loads sprites from GfxHandler.
-    pub const GFX_HANDLER_LOAD_SPRITES: u32 = 0x0057_0B50;
+    pub const GFX_DIR_LOAD_SPRITES: u32 = 0x0057_0B50;
     /// FUN_00570A90: called before display palette setup (non-headless only).
     pub const FUN_570A90: u32 = 0x0057_0A90;
     /// FUN_00570E20: called after GfxHandler initialization.
     pub const FUN_570E20: u32 = 0x0057_0E20;
-    pub const GFX_HANDLER_LOAD_DIR: u32 = 0x0056_63E0;
+    pub const GFX_DIR_LOAD_DIR: u32 = 0x0056_63E0;
     pub const GFX_DIR_FIND_ENTRY: u32 = 0x0056_6520;
     pub const GFX_DIR_LOAD_IMAGE: u32 = 0x0056_66D0;
     /// DisplayGfx__Constructor_Maybe (0x4F5E80): stdcall(raw_image) -> DisplayGfx*, RET 0x4.
@@ -377,7 +377,7 @@ pub mod va {
     // === Vtables ===
 
     /// GfxHandler vtable (0x66B280).
-    pub const GFX_HANDLER_VTABLE: u32 = 0x0066_B280;
+    pub const GFX_DIR_VTABLE: u32 = 0x0066_B280;
     /// BitGrid base vtable (0x6640EC): shared by BitGrid, DisplayGfx base, gradient stubs.
     pub const BIT_GRID_VTABLE: u32 = 0x0066_40EC;
     /// BitGrid variant vtable (0x664118): used by TaskStateMachine-class objects.

crates/openwa-core/src/display/gradient.rs

@@ -8,7 +8,7 @@
 use crate::address::va;
 use crate::engine::ddgame::DDGame;
 use crate::rebase::rb;
-use crate::render::gfx_handler::call_gfx_find_and_load;
+use crate::render::gfx_dir::call_gfx_find_and_load;
 use crate::task::bit_grid::BitGrid;
 use crate::wa_alloc::{wa_free, wa_malloc};
 

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

@@ -11,12 +11,10 @@ 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::gfx_dir::{
+    call_gfx_find_and_load, call_gfx_load_and_wrap, call_gfx_load_dir, GfxDir,
 };
+pub use crate::render::gfx_dir::{gfx_dir_find_entry, gfx_dir_load_dir, gfx_resource_create};
 use crate::render::landscape::PCLandscape;
 use crate::render::queue::RenderQueue;
 use crate::render::turn_order::TurnOrderWidget;
@@ -200,7 +198,7 @@ pub struct DDGame {
     pub rng_state_2: u32,
     /// 0x72F4-0x7307: Unknown
     pub _unknown_72f4: [u8; 0x7308 - 0x72F4],
-    /// 0x7308: Sprite/gfx dimension data (passed to GFX_HANDLER_LOAD_SPRITES).
+    /// 0x7308: Sprite/gfx dimension data (passed to GFX_DIR_LOAD_SPRITES).
     pub gfx_sprite_data: [u8; 0x730C - 0x7308],
     /// 0x730C-0x731C: 5 GfxDir color entries
     pub _gfx_color_entries: [u8; 0x7324 - 0x730C],
@@ -542,7 +540,7 @@ pub fn init_constructor_addrs() {
         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();
+    crate::render::gfx_dir::init_addrs();
 }
 
 // ── Typed wrappers for WA stdcall functions ────────────────────────────────
@@ -566,7 +564,7 @@ unsafe fn wa_load_sprites(
     param4: u32,
 ) {
     let f: unsafe extern "stdcall" fn(*mut DDGameWrapper, *mut u8, u32, u32) =
-        core::mem::transmute(rb(va::GFX_HANDLER_LOAD_SPRITES) as usize);
+        core::mem::transmute(rb(va::GFX_DIR_LOAD_SPRITES) as usize);
     f(wrapper, sprite_data, display_flags, param4);
 }
 
@@ -638,12 +636,12 @@ unsafe fn wa_init_display_final(display: *mut DDDisplay) {
 }
 
 /// DDGame__LoadHudAndWeaponSprites (0x53D0E0): load weapon icons and HUD sprites.
-/// thiscall(ECX=gfx_handler) + 2 stack(ddgame, secondary_gfx_handler), RET 0x8.
+/// thiscall(ECX=gfx_dir) + 2 stack(ddgame, secondary_gfx_dir), RET 0x8.
 #[cfg(target_arch = "x86")]
-unsafe fn wa_load_hud_sprites(gfx_handler: *mut u8, ddgame: *mut DDGame, secondary: *mut u8) {
+unsafe fn wa_load_hud_sprites(gfx_dir: *mut u8, ddgame: *mut DDGame, secondary: *mut u8) {
     let f: unsafe extern "thiscall" fn(*mut u8, *mut DDGame, *mut u8) =
         core::mem::transmute(rb(va::DDGAME_LOAD_HUD_AND_WEAPON_SPRITES) as usize);
-    f(gfx_handler, ddgame, secondary);
+    f(gfx_dir, ddgame, secondary);
 }
 
 /// Create and initialize DDGame, matching DDGame__Constructor (0x56E220).
@@ -744,14 +742,12 @@ unsafe fn init_graphics_and_resources(
     let ddgame = (*wrapper).ddgame;
     let fopen: unsafe extern "cdecl" fn(*const u8, *const u8) -> *mut u8 =
         core::mem::transmute(rb(va::WA_FOPEN) as usize);
-    let gfx_handler_vtable = rb(va::GFX_HANDLER_VTABLE) as u32;
+    let gfx_dir_vtable = rb(va::GFX_DIR_VTABLE) as u32;
 
-    // ── GfxHandler #1 (primary) ──
-    let gfx1 = wa_malloc(0x19C);
-    core::ptr::write_bytes(gfx1, 0, 0x19C);
-    *(gfx1 as *mut u32) = gfx_handler_vtable;
-    (*wrapper)._field_4c0 = gfx1;
-    (*wrapper)._field_4c4 = core::ptr::null_mut();
+    // ── GfxDir #1 (primary) ──
+    let gfx1 = GfxDir::alloc(gfx_dir_vtable);
+    (*wrapper).primary_gfx_dir = gfx1 as *mut u8;
+    (*wrapper).secondary_gfx_dir = core::ptr::null_mut();
 
     // Build path list (order depends on headless + display_flags)
     let headless = (*game_info).headless_mode as i32;
@@ -787,9 +783,9 @@ unsafe fn init_graphics_and_resources(
     let mut gfx_loaded_idx = 0u32;
     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;
+        (*gfx1).file_handle = fp;
         if !fp.is_null()
-            && call_gfx_load_dir(gfx1, crate::render::gfx_handler::gfx_load_dir_addr()) != 0
+            && call_gfx_load_dir(gfx1 as *mut u8, crate::render::gfx_dir::gfx_load_dir_addr()) != 0
         {
             gfx_loaded_idx = i as u32;
             break;
@@ -806,7 +802,7 @@ unsafe fn init_graphics_and_resources(
         0
     };
 
-    // ── GfxHandler #2 (conditional) ──
+    // ── GfxDir #2 (conditional — supplemental sprites for certain game versions) ──
     let game_version = (*game_info).game_version;
     let threshold = if (*wrapper).gfx_mode != 0 { 33 } else { -2i32 };
     if game_version < threshold {
@@ -814,21 +810,16 @@ unsafe fn init_graphics_and_resources(
         let mut gfx_c_path = *b"data\\Gfx\\GfxC_3_0.dir\0";
         gfx_c_path[14] = c_digit;
 
-        let gfx2 = wa_malloc(0x19C);
-        core::ptr::write_bytes(gfx2, 0, 0x19C);
-        *(gfx2 as *mut u32) = gfx_handler_vtable;
-        (*wrapper)._field_4c4 = gfx2;
+        let gfx2 = GfxDir::alloc(gfx_dir_vtable);
+        (*wrapper).secondary_gfx_dir = gfx2 as *mut u8;
 
         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, crate::render::gfx_handler::gfx_load_dir_addr()) == 0
-        {
+        (*gfx2).file_handle = fp;
+        let load_addr = crate::render::gfx_dir::gfx_load_dir_addr();
+        if fp.is_null() || call_gfx_load_dir(gfx2 as *mut u8, load_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, crate::render::gfx_handler::gfx_load_dir_addr()) == 0
-            {
+            (*gfx2).file_handle = fp2;
+            if fp2.is_null() || call_gfx_load_dir(gfx2 as *mut u8, load_addr) == 0 {
                 panic!("DDGame: couldn't open secondary Gfx.dir");
             }
         }
@@ -840,16 +831,9 @@ unsafe fn init_graphics_and_resources(
             call_usercall_eax(wrapper, FUN_570A90_ADDR);
         }
         let disp = (*wrapper).display;
-        let gfx_handler = (*wrapper)._field_4c0;
+        let gfx_dir = (*wrapper).primary_gfx_dir;
         DDDisplay::set_layer_color(disp, 1, 0xFE);
-        DDDisplay::load_sprite(
-            disp,
-            1,
-            1,
-            0,
-            gfx_handler,
-            rb(va::STR_CDROM_SPR) as *const u8,
-        );
+        DDDisplay::load_sprite(disp, 1, 1, 0, gfx_dir, rb(va::STR_CDROM_SPR) as *const u8);
         DDDisplay::set_layer_visibility(disp, 1, -100);
 
         // Palette slot range init
@@ -880,7 +864,7 @@ unsafe fn init_graphics_and_resources(
     if (*wrapper).gfx_mode != 0 {
         // The layer_ctx is used as the output buffer, not a plain stack alloc.
         let res = gfx_resource_create(
-            (*wrapper)._field_4c0,
+            (*wrapper).primary_gfx_dir,
             rb(va::STR_COLOURS_IMG) as *const u8,
             layer_ctx,
         );
@@ -906,7 +890,7 @@ unsafe fn init_graphics_and_resources(
     }
 
     // ── Secondary GfxDir object (DDGame+0x2C, conditional) ──
-    if !(*wrapper)._field_4c4.is_null() {
+    if !(*wrapper).secondary_gfx_dir.is_null() {
         let gfxdir2 = wa_malloc(0x70C);
         core::ptr::write_bytes(gfxdir2, 0, 0x70C);
         *(gfxdir2 as *mut u16) = 1;
@@ -952,14 +936,13 @@ unsafe fn init_graphics_and_resources(
         }
     }
 
-    // ── GfxResource: thiscall(ECX=gfx_handler) + EAX=name + 1 stack(output), RET 0x4 ──
+    // ── GfxResource: thiscall(ECX=gfx_dir) + EAX=name + 1 stack(output), RET 0x4 ──
     let gfx_resource: *mut u8;
     {
-        let gfx_handler = (*wrapper)._field_4c0;
+        let gfx_dir = (*wrapper).primary_gfx_dir;
         let out_buf = wa_malloc(0x900);
         core::ptr::write_bytes(out_buf, 0, 0x900);
-        gfx_resource =
-            gfx_resource_create(gfx_handler, rb(va::STR_MASKS_IMG) as *const u8, out_buf);
+        gfx_resource = gfx_resource_create(gfx_dir, rb(va::STR_MASKS_IMG) as *const u8, out_buf);
     }
 
     // ── PCLandscape (alloc 0xB44, stdcall 11 params) ──
@@ -1054,7 +1037,7 @@ unsafe fn init_graphics_and_resources(
 
     // ── Arrow sprites + collision regions (32 iterations) ──
     {
-        let gfx_handler = (*wrapper)._field_4c0;
+        let gfx_dir = (*wrapper).primary_gfx_dir;
 
         for i in 0u32..32 {
             // Format "arrow%02u.img\0" into stack buffer
@@ -1064,25 +1047,25 @@ unsafe fn init_graphics_and_resources(
 
             let layer_ctx = DDDisplay::set_active_layer((*ddgame).display, 1);
 
-            let entry = gfx_dir_find_entry(name_buf.as_ptr(), gfx_handler);
+            let entry = gfx_dir_find_entry(name_buf.as_ptr(), gfx_dir);
 
             let sprite: *mut u8;
             if !entry.is_null() {
-                // Try gfx_handler->vtable[2](entry->field_4)
-                let gfx_vt = *(gfx_handler as *const *const u32);
+                // Try gfx_dir->vtable[2](entry->field_4)
+                let gfx_vt = *(gfx_dir as *const *const u32);
                 let load_cached: unsafe extern "thiscall" fn(*mut u8, u32) -> *mut u8 =
                     core::mem::transmute(*gfx_vt.add(2));
                 let entry_val = *(entry.add(4) as *const u32);
-                let cached = load_cached(gfx_handler, entry_val);
+                let cached = load_cached(gfx_dir, entry_val);
                 if !cached.is_null() {
                     sprite = wa_displaygfx_ctor(cached);
                 } else {
                     // Fallback: load from file via GfxDir__LoadImage + IMG_Decode
-                    sprite = call_gfx_load_and_wrap(gfx_handler, name_buf.as_ptr(), layer_ctx);
+                    sprite = call_gfx_load_and_wrap(gfx_dir, name_buf.as_ptr(), layer_ctx);
                 }
             } else {
                 // Entry not found — try direct file load
-                sprite = call_gfx_load_and_wrap(gfx_handler, name_buf.as_ptr(), layer_ctx);
+                sprite = call_gfx_load_and_wrap(gfx_dir, name_buf.as_ptr(), layer_ctx);
             }
 
             // Store arrow sprite at DDGame+0x38+i*4
@@ -1124,7 +1107,7 @@ unsafe fn init_graphics_and_resources(
                 let gfx_resource_create: unsafe extern "thiscall" fn(*mut u8, *mut u8) -> *mut u8 =
                     core::mem::transmute(rb(va::GFX_RESOURCE_CREATE) as usize);
                 (*ddgame).arrow_gfxdirs[i as usize] =
-                    gfx_resource_create(gfx_handler, core::ptr::null_mut());
+                    gfx_resource_create(gfx_dir, core::ptr::null_mut());
             }
         }
     }
@@ -1200,12 +1183,12 @@ unsafe fn init_graphics_and_resources(
 
     // ── Sprite resource loading via DDGameWrapper vtable[0] ──
     // DDNetGameWrapper__LoadResourceList: thiscall(ECX=wrapper) +
-    // 5 stack params (layer, gfx_handler, base_path, data_table, table_size)
+    // 5 stack params (layer, gfx_dir, base_path, data_table, table_size)
     {
         let landscape_ptr = (*wrapper).landscape;
-        let water_layer = (*landscape_ptr).water_gfx_handler;
-        let land_layer = (*landscape_ptr).level_gfx_handler;
-        let gfx_handler = (*wrapper)._field_4c0;
+        let water_layer = (*landscape_ptr).water_gfx_dir;
+        let land_layer = (*landscape_ptr).level_gfx_dir;
+        let gfx_dir = (*wrapper).primary_gfx_dir;
 
         let wrapper_vt = *(wrapper as *const *const u32);
         let load_resource_list: unsafe extern "thiscall" fn(
@@ -1220,7 +1203,7 @@ unsafe fn init_graphics_and_resources(
         load_resource_list(
             wrapper,
             1,
-            gfx_handler,
+            gfx_dir,
             rb(va::SPRITE_RESOURCE_BASE_PATH) as *const u8, // base path
             rb(va::SPRITE_RESOURCE_TABLE_1) as *const u8,
             0x1D88, // table size
@@ -1233,7 +1216,7 @@ unsafe fn init_graphics_and_resources(
         load_resource_list(
             wrapper,
             1,
-            gfx_handler,
+            gfx_dir,
             rb(va::SPRITE_RESOURCE_BASE_PATH) as *const u8,
             rb(va::SPRITE_RESOURCE_TABLE_2) as *const u8,
             0x18,
@@ -1302,7 +1285,7 @@ unsafe fn init_graphics_and_resources(
         }
 
         // ── DDGame__LoadHudAndWeaponSprites (0x53D0E0) ──
-        wa_load_hud_sprites(gfx_handler, ddgame, (*wrapper)._field_4c4);
+        wa_load_hud_sprites(gfx_dir, ddgame, (*wrapper).secondary_gfx_dir);
 
         // ── Loading progress ticks (2 of 4 — after LoadHudAndWeaponSprites) ──
         call_usercall_ecx(wrapper, LOADING_PROGRESS_TICK_ADDR);
@@ -1321,12 +1304,12 @@ unsafe fn init_graphics_and_resources(
     }
 
     // ── Release primary GfxHandler (vtable[3] = release, param 1 = free) ──
-    let gfx_handler_4c0 = (*wrapper)._field_4c0;
-    if !gfx_handler_4c0.is_null() {
-        let gfx_vt = *(gfx_handler_4c0 as *const *const u32);
+    let gfx_dir_4c0 = (*wrapper).primary_gfx_dir;
+    if !gfx_dir_4c0.is_null() {
+        let gfx_vt = *(gfx_dir_4c0 as *const *const u32);
         let release: unsafe extern "thiscall" fn(*mut u8, u32) =
             core::mem::transmute(*gfx_vt.add(3));
-        release(gfx_handler_4c0, 1);
+        release(gfx_dir_4c0, 1);
     }
 
     if !is_headless {

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

@@ -31,10 +31,10 @@ pub struct DDGameWrapper {
     pub ddgame_secondary: *mut u8,
     /// 0x490-0x4BF: Unknown
     pub _unknown_490: [u8; 0x30],
-    /// 0x4C0: Unknown object pointer (not GfxHandler — vtable reads as 0)
-    pub _field_4c0: *mut u8,
-    /// 0x4C4: Unknown pointer
-    pub _field_4c4: *mut u8,
+    /// 0x4C0: Primary GfxDir — main sprite archive (Gfx.dir / Gfx0.dir / Gfx1.dir).
+    pub primary_gfx_dir: *mut u8,
+    /// 0x4C4: Secondary GfxDir — supplemental sprites (GfxC_3_0.dir), conditional on game version.
+    pub secondary_gfx_dir: *mut u8,
     /// 0x4C8: Graphics mode flag (DWORD index 0x132)
     pub gfx_mode: u32,
     /// 0x4CC: PCLandscape object pointer (DWORD index 0x133)

crates/openwa-core/src/render/{gfx_handler.rs → gfx_dir.rs}

@@ -1,15 +1,61 @@
-//! GfxHandler/GfxDir resource loading subsystem.
+//! GfxDir — .dir sprite archive reader.
+//!
+//! A GfxDir manages a hash table loaded from `.dir` files (e.g. `Gfx.dir`,
+//! `Gfx0.dir`). It provides name→resource lookup via a 1024-bucket hash table
+//! and delegates file I/O and caching to vtable methods.
 
 use crate::address::va;
 use crate::rebase::rb;
 use crate::wa_alloc::wa_malloc;
 
+/// .dir archive reader (0x19C bytes, vtable 0x66B280).
+///
+/// Loaded from `.dir` files via `gfx_dir_load`. Contains a 1024-bucket
+/// hash table for name→resource lookups, plus a 16-slot cache.
+#[repr(C)]
+pub struct GfxDir {
+    /// 0x000: Vtable pointer (0x66B280).
+    pub vtable: u32,
+    /// 0x004: Bucket array — 1024 pointers to GfxDirEntry linked lists.
+    pub bucket_array: *mut u8,
+    /// 0x008: 1 if bucket_array was allocated via malloc fallback (needs free).
+    pub fallback_alloc: u32,
+    /// 0x00C-0x10B: 16 cache slots (0x10 bytes each, first u32 zeroed on reset).
+    pub cache_slots: [u8; 0x100],
+    /// 0x10C-0x14B: Index table (16 u32 entries, identity permutation on reset).
+    pub index_table: [u32; 16],
+    /// 0x14C-0x18B: Unknown padding.
+    pub _unknown_14c: [u8; 0x40],
+    /// 0x18C: Number of cache slots (always 0x10).
+    pub slot_count: u32,
+    /// 0x190: Unknown (zeroed on reset).
+    pub _unknown_190: u32,
+    /// 0x194: Loaded flag (1 after successful gfx_dir_load).
+    pub loaded: u32,
+    /// 0x198: FILE* handle to the open .dir file.
+    pub file_handle: *mut u8,
+}
+
+const _: () = assert!(core::mem::size_of::<GfxDir>() == 0x19C);
+
+impl GfxDir {
+    /// Allocate and initialize a new GfxDir with the given vtable.
+    pub unsafe fn alloc(vtable: u32) -> *mut Self {
+        let ptr = wa_malloc(core::mem::size_of::<Self>() as u32) as *mut Self;
+        if !ptr.is_null() {
+            core::ptr::write_bytes(ptr as *mut u8, 0, core::mem::size_of::<Self>());
+            (*ptr).vtable = vtable;
+        }
+        ptr
+    }
+}
+
 /// Entry in a GfxDir hash bucket linked list.
 /// Each entry maps a name string to a cached resource value.
 #[repr(C)]
 pub struct GfxDirEntry {
     pub next: *mut GfxDirEntry,
-    /// Passed to GfxHandler vtable[2] for cached resource lookup.
+    /// Passed to GfxDir vtable[2] for cached resource lookup.
     pub value: u32,
     pub _unknown_08: u32,
     // +0x0C: null-terminated name (variable-length, not in struct)
@@ -43,7 +89,7 @@ unsafe fn gfx_dir_hash(name: *const u8) -> u32 {
 
 /// Pure Rust implementation of GfxDir__FindEntry (0x566520).
 ///
-/// Convention: usercall(EAX=name) + 1 stack(gfx_handler), RET 0x4.
+/// Convention: usercall(EAX=name) + 1 stack(gfx_dir), 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").
@@ -55,10 +101,10 @@ unsafe fn gfx_dir_hash(name: *const u8) -> u32 {
 /// - entry+0x0C: name string (null-terminated, lowercase)
 ///
 /// # Safety
-/// `gfx_handler` must be a valid GfxHandler with initialized hash table at +0x04.
+/// `gfx_dir` 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 {
+pub unsafe fn gfx_dir_find_entry(name: *const u8, gfx_dir: *mut u8) -> *mut u8 {
     let mut current_name = name;
 
     loop {
@@ -106,8 +152,8 @@ pub unsafe fn gfx_dir_find_entry(name: *const u8, gfx_handler: *mut u8) -> *mut
         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 gfx = &*(gfx_dir as *const GfxDir);
+        let bucket_array = gfx.bucket_array as *const u32;
         let mut entry = *bucket_array.add(bucket as usize) as *mut GfxDirEntry;
 
         while !entry.is_null() {
@@ -145,20 +191,20 @@ pub unsafe fn gfx_dir_find_entry(name: *const u8, gfx_handler: *mut u8) -> *mut
 /// 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;
+unsafe fn gfx_dir_reset(handler: *mut u8) {
+    let gfx = &mut *(handler as *mut GfxDir);
+    gfx.bucket_array = core::ptr::null_mut();
+    gfx.fallback_alloc = 0;
+    gfx.loaded = 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;
+        // Zero first u32 of each cache slot (stride 0x10)
+        *(gfx.cache_slots.as_mut_ptr().add(i as usize * 0x10) as *mut u32) = 0;
+        gfx.index_table[i as usize] = i;
     }
 
-    *(handler.add(400) as *mut u32) = 0; // 0x190
-    *(handler.add(0x18C) as *mut u32) = 0x10;
+    gfx._unknown_190 = 0;
+    gfx.slot_count = 0x10;
 }
 
 /// Pure Rust implementation of GfxHandler__LoadDir (0x5663E0).
@@ -180,8 +226,9 @@ unsafe fn gfx_handler_reset(handler: *mut u8) {
 /// # 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);
+pub unsafe fn gfx_dir_load_dir(handler: *mut u8) -> i32 {
+    gfx_dir_reset(handler);
+    let gfx = &mut *(handler as *mut GfxDir);
 
     let vt = *(handler as *const *const u32);
     // vtable[0] = read: thiscall(handler, buf, size) -> bytes_read
@@ -217,12 +264,10 @@ pub unsafe fn gfx_handler_load_dir(handler: *mut u8) -> i32 {
 
     // 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;
+    gfx.bucket_array = 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.
+        // Fallback: seek past header, then malloc + read entire data block
         vt_seek(handler, alloc_size);
 
         let read_size = total_file_size - data_size - 4;
@@ -232,7 +277,7 @@ pub unsafe fn gfx_handler_load_dir(handler: *mut u8) -> i32 {
             return 0;
         }
         core::ptr::write_bytes(buf, 0, read_size as usize);
-        *(handler.add(4) as *mut *mut u8) = buf;
+        gfx.bucket_array = buf;
 
         let bytes_read = vt_read(handler, buf, read_size);
         if bytes_read != read_size {
@@ -240,13 +285,12 @@ pub unsafe fn gfx_handler_load_dir(handler: *mut u8) -> i32 {
             return 0;
         }
 
-        // Mark as "loaded from fallback" at handler+8
-        *(handler.add(8) as *mut u32) = 1;
+        gfx.fallback_alloc = 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 data = gfx.bucket_array;
     let base = data as u32;
 
     for bucket in 0..1024u32 {
@@ -276,14 +320,14 @@ pub unsafe fn gfx_handler_load_dir(handler: *mut u8) -> i32 {
         }
     }
 
-    *(handler.add(0x194) as *mut u32) = 1;
+    gfx.loaded = 1;
 
     1 // success
 }
 
 /// Pure Rust implementation of GfxResource__Create_Maybe (0x4F6300).
 ///
-/// Convention: usercall(ECX=gfx_handler, EAX=name) + 1 stack(output), RET 0x4.
+/// Convention: usercall(ECX=gfx_dir, 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.
@@ -291,20 +335,16 @@ pub unsafe fn gfx_handler_load_dir(handler: *mut u8) -> i32 {
 /// # 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 {
+pub unsafe fn gfx_resource_create(gfx_dir: *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);
+    let entry = gfx_dir_find_entry(name, gfx_dir);
     if !entry.is_null() {
-        // gfx_handler->vtable[2](entry->field_4) — cached load
-        let vt = *(gfx_handler as *const *const u32);
+        // gfx_dir->vtable[2](entry->field_4) — cached load
+        let vt = *(gfx_dir 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 as *const GfxDirEntry)).value;
-        let cached = load_cached(gfx_handler, entry_val);
+        let cached = load_cached(gfx_dir, entry_val);
         if !cached.is_null() {
             // DisplayGfx__Constructor_Maybe: stdcall(raw_image), RET 0x4
             let ctor: unsafe extern "stdcall" fn(*mut u8) -> *mut u8 =
@@ -314,7 +354,7 @@ pub unsafe fn gfx_resource_create(
     }
 
     // 2. Fallback: LoadImage → IMG_Decode
-    let raw_image = call_gfx_load_image(gfx_handler, name);
+    let raw_image = call_gfx_load_image(gfx_dir, name);
     if raw_image.is_null() {
         return core::ptr::null_mut();
     }
@@ -366,11 +406,11 @@ pub(crate) unsafe fn call_gfx_find_and_load(
 /// 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,
+    gfx_dir: *mut u8,
     name: *const u8,
     display_ctx: *mut u8,
 ) -> *mut u8 {
-    let image = call_gfx_load_image(gfx_handler, name);
+    let image = call_gfx_load_image(gfx_dir, name);
     if image.is_null() {
         return core::ptr::null_mut();
     }
@@ -387,7 +427,7 @@ pub(crate) unsafe fn call_gfx_load_and_wrap(
 
 static mut GFX_LOAD_DIR_ADDR: u32 = 0;
 
-// GfxDir__LoadImage is usercall(ESI=gfx_handler) + 1 stack(name), RET 0x4.
+// GfxDir__LoadImage is usercall(ESI=gfx_dir) + 1 stack(name), RET 0x4.
 // Returns raw image pointer or null.
 static mut GFX_LOAD_IMAGE_ADDR: u32 = 0;
 
@@ -409,10 +449,10 @@ pub(crate) unsafe fn call_gfx_load_dir(handler: *mut u8, addr: u32) -> i32 {
 
 #[cfg(target_arch = "x86")]
 #[unsafe(naked)]
-unsafe extern "C" fn call_gfx_load_image(_gfx_handler: *mut u8, _name: *const u8) -> *mut u8 {
+unsafe extern "C" fn call_gfx_load_image(_gfx_dir: *mut u8, _name: *const u8) -> *mut u8 {
     core::arch::naked_asm!(
         "pushl %esi",
-        "movl 8(%esp), %esi",     // ESI = gfx_handler
+        "movl 8(%esp), %esi",     // ESI = gfx_dir
         "pushl 12(%esp)",         // push name (callee cleans via RET 0x4)
         "calll *({addr})",
         "popl %esi",
@@ -427,7 +467,7 @@ unsafe extern "C" fn call_gfx_load_image(_gfx_handler: *mut u8, _name: *const u8
 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);
+        GFX_LOAD_DIR_ADDR = rb(va::GFX_DIR_LOAD_DIR);
     }
 }
 

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

@@ -86,9 +86,9 @@ pub struct PCLandscape {
     pub visible_right: u32,
     pub visible_bottom: u32,
     /// 0xB34: GfxHandler for Level.dir (param_1[0x2CD])
-    pub level_gfx_handler: *mut u8,
+    pub level_gfx_dir: *mut u8,
     /// 0xB38: GfxHandler for Water.dir (param_1[0x2CE])
-    pub water_gfx_handler: *mut u8,
+    pub water_gfx_dir: *mut u8,
     /// 0xB3C: Remaining control flag
     pub _unknown_b3c: u32,
 }

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

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

crates/openwa-harness/src/lib.rs

@@ -301,7 +301,7 @@ mod tests {
             ("CGameTask", va::CGAMETASK_VTABLE),
             ("CGameTask2", va::CGAMETASK_VTABLE2),
             ("DDGameWrapper", va::DDGAME_WRAPPER_VTABLE),
-            ("GfxHandler", va::GFX_HANDLER_VTABLE),
+            ("GfxHandler", va::GFX_DIR_VTABLE),
             ("DisplayGfx", va::DISPLAY_GFX_VTABLE),
             ("PCLandscape", va::PC_LANDSCAPE_VTABLE),
             ("LandscapeShader", va::LANDSCAPE_SHADER_VTABLE),
@@ -326,7 +326,7 @@ mod tests {
             ("CTask", va::CTASK_VTABLE),
             ("CGameTask", va::CGAMETASK_VTABLE),
             ("DDGameWrapper", va::DDGAME_WRAPPER_VTABLE),
-            ("GfxHandler", va::GFX_HANDLER_VTABLE),
+            ("GfxHandler", va::GFX_DIR_VTABLE),
             ("DisplayGfx", va::DISPLAY_GFX_VTABLE),
             ("PCLandscape", va::PC_LANDSCAPE_VTABLE),
             ("LandscapeShader", va::LANDSCAPE_SHADER_VTABLE),

crates/openwa-wormkit/src/replacements/ddgame_init.rs

@@ -15,7 +15,7 @@ use crate::hook;
 use openwa_core::address::va;
 use openwa_core::engine::ddgame::{
     bit_grid_init, ddgame_init_fields, ddgame_init_render_indices, display_layer_color_init,
-    gfx_dir_find_entry, gfx_handler_load_dir, gfx_resource_create, DDGame,
+    gfx_dir_find_entry, gfx_dir_load_dir, gfx_resource_create, DDGame,
 };
 use openwa_core::engine::DDGameWrapper;
 
@@ -83,10 +83,9 @@ extern "cdecl" fn impl_display_layer_init(wrapper: u32) -> u32 {
 
 // ─── GfxResource__Create_Maybe (0x4F6300) ───────────────────────────────────
 
-extern "cdecl" fn impl_gfx_resource_create(gfx_handler: u32, name: u32, output: u32) -> u32 {
-    let result = unsafe {
-        gfx_resource_create(gfx_handler as *mut u8, name as *const u8, output as *mut u8)
-    };
+extern "cdecl" fn impl_gfx_resource_create(gfx_dir: u32, name: u32, output: u32) -> u32 {
+    let result =
+        unsafe { gfx_resource_create(gfx_dir as *mut u8, name as *const u8, output as *mut u8) };
     result as u32
 }
 
@@ -96,7 +95,7 @@ unsafe extern "C" fn gfx_resource_create_trampoline() {
         "push edx",
         "push [esp+8]",       // output (stack param)
         "push eax",           // name
-        "push ecx",           // gfx_handler
+        "push ecx",           // gfx_dir
         "call {impl_fn}",
         "add esp, 12",
         "pop edx",
@@ -107,7 +106,7 @@ unsafe extern "C" fn gfx_resource_create_trampoline() {
 
 // ─── GfxDir__FindEntry (0x566520) ────────────────────────────────────────────
 //
-// Convention: usercall(EAX=name) + 1 stack(gfx_handler), RET 0x4.
+// Convention: usercall(EAX=name) + 1 stack(gfx_dir), RET 0x4.
 
 hook::usercall_trampoline!(
     fn find_entry_trampoline;
@@ -118,8 +117,8 @@ hook::usercall_trampoline!(
 
 static FIND_ENTRY_LOG_COUNT: core::sync::atomic::AtomicU32 = core::sync::atomic::AtomicU32::new(0);
 
-extern "cdecl" fn impl_find_entry(name: u32, gfx_handler: u32) -> u32 {
-    let result = unsafe { gfx_dir_find_entry(name as *const u8, gfx_handler as *mut u8) };
+extern "cdecl" fn impl_find_entry(name: u32, gfx_dir: u32) -> u32 {
+    let result = unsafe { gfx_dir_find_entry(name as *const u8, gfx_dir as *mut u8) };
 
     // Log first 20 lookups for debugging
     let count = FIND_ENTRY_LOG_COUNT.fetch_add(1, core::sync::atomic::Ordering::Relaxed);
@@ -151,7 +150,7 @@ hook::usercall_trampoline!(
 );
 
 extern "cdecl" fn impl_load_dir(handler: u32) -> u32 {
-    unsafe { gfx_handler_load_dir(handler as *mut u8) as u32 }
+    unsafe { gfx_dir_load_dir(handler as *mut u8) as u32 }
 }
 
 // ─── Hook installation ──────────────────────────────────────────────────────
@@ -196,7 +195,7 @@ pub fn install() -> Result<(), String> {
 
         hook::install(
             "GfxHandler__LoadDir",
-            va::GFX_HANDLER_LOAD_DIR,
+            va::GFX_DIR_LOAD_DIR,
             load_dir_trampoline as *const (),
         )?;
     }

crates/openwa-wormkit/src/validation/mod.rs

@@ -116,7 +116,7 @@ fn validate_addresses(result: &mut ValidationResult) {
             va::CGAMETASK_SOUND_EMITTER_VT,
         ),
         ("DDGameWrapper vtable", va::DDGAME_WRAPPER_VTABLE),
-        ("GfxHandler vtable", va::GFX_HANDLER_VTABLE),
+        ("GfxHandler vtable", va::GFX_DIR_VTABLE),
         ("DisplayGfx vtable", va::DISPLAY_GFX_VTABLE),
         ("PCLandscape vtable", va::PC_LANDSCAPE_VTABLE),
         ("LandscapeShader vtable", va::LANDSCAPE_SHADER_VTABLE),
@@ -316,7 +316,7 @@ fn validate_struct_offsets(result: &mut ValidationResult) {
     let _ = log_validation("  DDGameWrapper:");
     check_offset!(result, DDGameWrapper, vtable, 0x00);
     check_offset!(result, DDGameWrapper, ddgame, 0x488);
-    check_offset!(result, DDGameWrapper, _field_4c0, 0x4C0);
+    check_offset!(result, DDGameWrapper, primary_gfx_dir, 0x4C0);
     check_offset!(result, DDGameWrapper, landscape, 0x4CC);
     check_offset!(result, DDGameWrapper, display, 0x4D0);
 
@@ -825,12 +825,12 @@ fn dump_landscape() {
             land.resource_handle as u32
         ));
         let _ = log_validation(&format!(
-            "  level_gfx_handler: 0x{:08X}",
-            land.level_gfx_handler as u32
+            "  level_gfx_dir: 0x{:08X}",
+            land.level_gfx_dir as u32
         ));
         let _ = log_validation(&format!(
-            "  water_gfx_handler: 0x{:08X}",
-            land.water_gfx_handler as u32
+            "  water_gfx_dir: 0x{:08X}",
+            land.water_gfx_dir as u32
         ));
         let _ = log_validation(&format!(
             "  visible_bounds: left={} top={} right={} bottom={}",