refactor: add TaskStateMachine and GfxDirEntry structs, eliminate pointer arithmetic

New structs:
- TaskStateMachine (#[repr(C)], 0x2C bytes): replaces raw u32 offset
writes in task_state_machine_init and gradient stub creation
- GfxDirEntry: typed linked-list entry with .next, .value, .name_ptr()
replaces .add(0x00), .add(0x04), .add(0x0C) in gfx_dir_find_entry

Updated files:
- task/state_machine.rs: struct definition + typed init
- render/gfx_handler.rs: GfxDirEntry struct, typed entry traversal
- display/gradient.rs: use TaskStateMachine for gradient image wrapper
and sprite height read
- engine/ddgame.rs: use TaskStateMachine for gradient stub

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

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

@@ -8,6 +8,7 @@
 use crate::engine::ddgame::DDGame;
 use crate::rebase::rb;
 use crate::render::gfx_handler::call_gfx_find_and_load;
+use crate::task::state_machine::TaskStateMachine;
 use crate::wa_alloc::{wa_free, wa_malloc};
 
 /// Palette context for gradient color mapping.
@@ -117,8 +118,8 @@ pub(crate) unsafe fn compute_complex_gradient(
         return;
     }
 
-    // Sprite height at offset +0x18
-    let gradient_height = *(gradient_sprite.add(0x18) as *const i32);
+    // Sprite height from TaskStateMachine layout (shared vtable 0x6640EC)
+    let gradient_height = (*(gradient_sprite as *const TaskStateMachine)).height as i32;
     if gradient_height <= 0 {
         return;
     }
@@ -239,18 +240,23 @@ pub(crate) unsafe fn compute_complex_gradient(
         }
     }
 
-    // Step 8: Wrap pixel data in a DisplayGfx-compatible object
-    let gfx_obj = wa_malloc(0x2C);
+    // Step 8: Wrap pixel data in a TaskStateMachine-compatible object
+    // (shares vtable 0x6640EC; CTaskLand reads .height to decide whether to render)
+    let gfx_obj =
+        wa_malloc(core::mem::size_of::<TaskStateMachine>() as u32) as *mut TaskStateMachine;
     if gfx_obj.is_null() {
         wa_free(data);
         return;
     }
-    core::ptr::write_bytes(gfx_obj, 0, 0x2C);
-    let g = gfx_obj as *mut u32;
-    *g = rb(0x6640EC); // vtable
-    *g.add(2) = data as u32; // pixel data
-    *g.add(4) = stride; // bytes per row
-    *g.add(5) = 0; // x offset
-    *g.add(6) = total_height as u32; // height (CTaskLand checks `if (0 < [6])`)
-    (*ddgame).gradient_image = gfx_obj;
+    core::ptr::write_bytes(
+        gfx_obj as *mut u8,
+        0,
+        core::mem::size_of::<TaskStateMachine>(),
+    );
+    (*gfx_obj).vtable = rb(0x6640EC);
+    (*gfx_obj).data = data;
+    (*gfx_obj).row_stride = stride;
+    (*gfx_obj).width = 0;
+    (*gfx_obj).height = total_height as u32;
+    (*ddgame).gradient_image = gfx_obj as *mut u8;
 }

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

@@ -20,6 +20,7 @@ pub use crate::render::gfx_handler::{
 use crate::render::landscape::PCLandscape;
 use crate::render::queue::RenderQueue;
 use crate::render::turn_order::TurnOrderWidget;
+use crate::task::state_machine::TaskStateMachine;
 use crate::wa_alloc::wa_malloc;
 
 /// DDGame — the main game engine object.
@@ -1279,12 +1280,13 @@ unsafe fn init_graphics_and_resources(
     // ── Gradient image stub (DDGame+0x30) ──
     // Minimal stub: [6]=0 (zero-width) so CTaskLand skips the gradient column loop.
     if (*ddgame).gradient_image.is_null() {
-        let obj = wa_malloc(0x2C);
-        core::ptr::write_bytes(obj, 0, 0x2C);
+        let obj =
+            wa_malloc(core::mem::size_of::<TaskStateMachine>() as u32) as *mut TaskStateMachine;
         if !obj.is_null() {
-            *(obj as *mut u32) = rb(0x6640EC); // vtable (DisplayGfx vtable, vtable[4]=ProcessFrame_stub)
-                                               // [6] = height/width = 0 → CTaskLand loop: `if (0 < 0)` → skip
-            (*ddgame).gradient_image = obj;
+            core::ptr::write_bytes(obj as *mut u8, 0, core::mem::size_of::<TaskStateMachine>());
+            (*obj).vtable = rb(0x6640EC);
+            // height = 0 → CTaskLand skips the gradient column loop
+            (*ddgame).gradient_image = obj as *mut u8;
         }
     }
 

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

@@ -4,6 +4,24 @@ use crate::address::va;
 use crate::rebase::rb;
 use crate::wa_alloc::wa_malloc;
 
+/// 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.
+    pub value: u32,
+    pub _unknown_08: u32,
+    // +0x0C: null-terminated name (variable-length, not in struct)
+}
+
+impl GfxDirEntry {
+    /// Name string at +0x0C (immediately after the fixed fields).
+    pub unsafe fn name_ptr(&self) -> *const u8 {
+        (self as *const Self as *const u8).add(0x0C)
+    }
+}
+
 /// Hash function for GfxDir entry lookup (FUN_566390).
 ///
 /// 10-bit CRC-like hash over the global name buffer at 0x8ACF58.
@@ -90,11 +108,10 @@ pub unsafe fn gfx_dir_find_entry(name: *const u8, gfx_handler: *mut u8) -> *mut
         // 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;
+        let mut entry = *bucket_array.add(bucket as usize) as *mut GfxDirEntry;
 
         while !entry.is_null() {
-            // Compare entry name at entry+0x0C with our buffer
-            let entry_name = entry.add(0x0C);
+            let entry_name = (*entry).name_ptr();
             let mut match_found = true;
             let mut k = 0usize;
             loop {
@@ -111,11 +128,10 @@ pub unsafe fn gfx_dir_find_entry(name: *const u8, gfx_handler: *mut u8) -> *mut
             }
 
             if match_found {
-                return entry;
+                return entry as *mut u8;
             }
 
-            // Next in linked list: entry+0x00
-            entry = *(entry as *const *mut u8);
+            entry = (*entry).next;
         }
 
         // Not found — try fallback name after '|'
@@ -287,7 +303,7 @@ pub unsafe fn gfx_resource_create(
         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 entry_val = (*(entry as *const GfxDirEntry)).value;
         let cached = load_cached(gfx_handler, entry_val);
         if !cached.is_null() {
             // DisplayGfx__Constructor_Maybe: stdcall(raw_image), RET 0x4
@@ -332,7 +348,7 @@ pub(crate) unsafe fn call_gfx_find_and_load(
         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));
+        let cached = load_cached(gfx_dir, (*(entry as *const GfxDirEntry)).value);
         if !cached.is_null() {
             // Wrap with DisplayGfx__Constructor_Maybe (0x4F5E80)
             // This is stdcall(1 param), RET 0x4

crates/openwa-core/src/task/state_machine.rs

@@ -3,30 +3,50 @@
 use crate::rebase::rb;
 use crate::wa_alloc::wa_malloc;
 
+/// Bitfield grid buffer used for spatial collision/visibility queries.
+/// Vtable at 0x6640EC (shared with DisplayGfx base).
+/// Size: 0x2C bytes (11 u32 fields).
+#[repr(C)]
+pub struct TaskStateMachine {
+    pub vtable: u32,
+    pub _unused_04: u32,
+    pub data: *mut u8,
+    pub cells_per_unit: u32,
+    pub row_stride: u32,
+    pub width: u32,
+    pub height: u32,
+    pub _unused_1c: u32,
+    pub _unused_20: u32,
+    pub width_dup: u32,
+    pub height_dup: u32,
+}
+
+const _: () = assert!(core::mem::size_of::<TaskStateMachine>() == 0x2C);
+
 /// Pure Rust implementation of TaskStateMachine__Init (0x4F6370).
 ///
-/// Convention: usercall(ESI=object, ECX=param1, EDI=height) + 1 stack(width), RET 0x4.
-///
-/// Allocates a bit-per-cell grid buffer. `param1` is typically 1 (cells per unit).
-/// `width` and `height` are pixel dimensions. The buffer is a row-major bitfield
-/// with rows aligned to 4 bytes.
+/// Allocates a bit-per-cell grid buffer. `cells_per_unit` is typically 1.
+/// `width` and `height` are pixel dimensions. The buffer is a row-major
+/// bitfield with rows aligned to 4 bytes.
 ///
 /// # Safety
 /// `object` must point to a zero-filled allocation of at least 0x2C bytes.
-pub unsafe fn task_state_machine_init(object: *mut u8, param1: u32, width: u32, height: u32) {
-    // Row stride: bits-to-bytes rounded up, then aligned to 4
-    let bits = param1.wrapping_mul(width).wrapping_add(7) as i32;
+pub unsafe fn task_state_machine_init(
+    object: *mut u8,
+    cells_per_unit: u32,
+    width: u32,
+    height: u32,
+) {
+    let bits = cells_per_unit.wrapping_mul(width).wrapping_add(7) as i32;
     let row_stride = ((bits >> 3) + 3) & !3;
     let total_size = row_stride as u32 * height;
 
-    // Allocate data buffer with 0x20-byte header
     let alloc_size = ((total_size + 3) & !3) + 0x20;
     let buffer = wa_malloc(alloc_size);
 
     if buffer.is_null() {
         return;
     }
-    // Guard against integer overflow producing tiny alloc_size with huge total_size
     if total_size as usize > alloc_size as usize {
         return;
     }
@@ -35,16 +55,16 @@ pub unsafe fn task_state_machine_init(object: *mut u8, param1: u32, width: u32,
     core::ptr::write_bytes(buffer, 0, total_size as usize);
     core::ptr::write_bytes(buffer, 0, total_size as usize);
 
-    let obj = object as *mut u32;
-    *obj.add(0) = rb(0x6640EC); // vtable
-    *obj.add(1) = 0;
-    *obj.add(2) = buffer as u32; // data pointer
-    *obj.add(3) = param1;
-    *obj.add(4) = row_stride as u32;
-    *obj.add(5) = width;
-    *obj.add(6) = height;
-    *obj.add(7) = 0;
-    *obj.add(8) = 0;
-    *obj.add(9) = width; // duplicate
-    *obj.add(10) = height; // duplicate
+    let tsm = &mut *(object as *mut TaskStateMachine);
+    tsm.vtable = rb(0x6640EC);
+    tsm._unused_04 = 0;
+    tsm.data = buffer;
+    tsm.cells_per_unit = cells_per_unit;
+    tsm.row_stride = row_stride as u32;
+    tsm.width = width;
+    tsm.height = height;
+    tsm._unused_1c = 0;
+    tsm._unused_20 = 0;
+    tsm.width_dup = width;
+    tsm.height_dup = height;
 }