refactor: unify BitGrid to display::bitgrid, clean up naming

Move BitGrid from task::bit_grid to display::bitgrid as its canonical
home. Delete the old module. Rename fields to match known semantics:
_unused_04 → external_buffer, _unused_1c/20 → clip_left/clip_top,
width_dup/height_dup → clip_right/clip_bottom.

Convert bit_grid_init to BitGrid::init with *mut BitGrid parameter.
Replace magic vtable address with va::BIT_GRID_VTABLE constant.
Remove redundant double memset. Remove dead TaskStateMachine class.

Rename DDGame::display_gfx → display_bitgrid (it's a BitGrid, not
DisplayGfx). Rename Sprite::display_gfx → bitgrid_vtable. Clean up
tsm variable names and stale re-exports throughout.

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

crates/openwa-core/src/address.rs

@@ -182,10 +182,8 @@ pub mod va {
             fn/Usercall INPUT_CTRL_INIT = 0x0058_C0D0;
         }
 
-        class "TaskStateMachine" {
-            /// TaskStateMachine vtable
-            vtable TASK_STATE_MACHINE_VTABLE = 0x0066_4118;
-        }
+        // TaskStateMachine was our old name for BitGrid before we understood it.
+        // Vtable 0x664118 is now BIT_GRID_VARIANT_VTABLE in the BitGrid class block.
 
         class "OpenGLCPU" {
             /// OpenGLCPU vtable (0x48-byte object)
@@ -230,7 +228,7 @@ pub mod va {
         class "BitGrid" {
             /// BitGrid base vtable
             vtable BIT_GRID_VTABLE = 0x0066_40EC;
-            /// BitGrid variant vtable (TaskStateMachine-class)
+            /// BitGrid variant vtable (used for DDGame+0x380 collision grid)
             vtable BIT_GRID_VARIANT_VTABLE = 0x0066_4118;
             /// BitGrid init
             fn BIT_GRID_INIT = 0x004F_6370;

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

@@ -1,29 +1,108 @@
-//! BitGrid display layer vtable — pixel drawing primitives for rendering layers.
+//! BitGrid — 2D pixel/bit buffer used for rendering layers and spatial queries.
 //!
-//! The BitGrid struct lives in `crate::task::bit_grid`. This module adds the
-//! display-layer vtable (0x664144, 8 slots) used by the three rendering layers
-//! in DisplayGfx (+0x3D9C, +0x3DA0, +0x3DA4).
+//! Two vtables:
+//! - **Base** (0x6640EC): Bitfield grid for spatial queries (collision, visibility).
+//!   Initialized by `BitGrid::init` (0x4F6370). Size: 0x2C bytes.
+//! - **Display layer** (0x664144, 8 slots): Pixel buffer with drawing primitives.
+//!   Used as rendering layers in DisplayGfx (+0x3D9C/+0x3DA0/+0x3DA4).
+//!   Allocated at 0x4C bytes; first 0x2C bytes share the base layout.
 //!
-//! When used as display layers, the BitGrid is allocated at 0x4C bytes (vs the
-//! base 0x2C). The first 0x2C bytes share the same layout; the extra 0x20 bytes
-//! hold display-layer-specific state.
+//! ## Field reinterpretation (display-layer context)
 //!
-//! ## Field reinterpretation
-//!
-//! Some fields have different semantics in display-layer context:
+//! Some fields have different semantics when used as a display layer:
 //! - `cells_per_unit` (+0x0C) → bit depth (8 for 8bpp)
-//! - `width/height` (+0x14/+0x18) → unused in display context
-//! - `_unused_1c/20` (+0x1C/+0x20) → clip_left / clip_top
+//! - `width/height` (+0x14/+0x18) → unused
+//! - `_unused_1c/_unused_20` (+0x1C/+0x20) → clip_left / clip_top
 //! - `width_dup/height_dup` (+0x24/+0x28) → clip_right / clip_bottom
 
-pub use crate::task::bit_grid::BitGrid;
+use crate::address::va;
+use crate::rebase::rb;
+use crate::wa_alloc::wa_malloc;
+use crate::FieldRegistry;
+
+/// BitGrid — 2D pixel/bit buffer.
+///
+/// Base vtable at 0x6640EC (bitfield spatial grid).
+/// Display-layer vtable at 0x664144 (pixel drawing).
+/// Size: 0x2C bytes (base), 0x4C bytes (display layer).
+#[derive(FieldRegistry)]
+#[repr(C)]
+pub struct BitGrid {
+    pub vtable: u32,
+    /// 0x04: External buffer flag. 0 = BitGrid owns data (frees on destroy),
+    /// nonzero = external ownership.
+    pub external_buffer: u32,
+    /// 0x08: Pixel/bit data pointer
+    pub data: *mut u8,
+    /// 0x0C: Cells per unit (spatial) / bit depth (display, typically 8)
+    pub cells_per_unit: u32,
+    /// 0x10: Row stride in bytes
+    pub row_stride: u32,
+    /// 0x14: Width in pixels/cells
+    pub width: u32,
+    /// 0x18: Height in pixels/cells
+    pub height: u32,
+    /// 0x1C: Clip left / x minimum (display), init 0 (spatial)
+    pub clip_left: u32,
+    /// 0x20: Clip top / y minimum (display), init 0 (spatial)
+    pub clip_top: u32,
+    /// 0x24: Clip right / x maximum (display), init = width (spatial)
+    pub clip_right: u32,
+    /// 0x28: Clip bottom / y maximum (display), init = height (spatial)
+    pub clip_bottom: u32,
+}
+
+const _: () = assert!(core::mem::size_of::<BitGrid>() == 0x2C);
+
+impl BitGrid {
+    /// Pure Rust implementation of BitGrid__Init (0x4F6370).
+    ///
+    /// 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
+    /// `this` must point to a zero-filled allocation of at least 0x2C bytes.
+    pub unsafe fn init(this: *mut BitGrid, 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;
+
+        let alloc_size = ((total_size + 3) & !3) + 0x20;
+        let buffer = wa_malloc(alloc_size);
+
+        if buffer.is_null() {
+            return;
+        }
+        if total_size as usize > alloc_size as usize {
+            return;
+        }
+
+        // Note: the original calls memset twice on the same buffer (possibly a
+        // debug/paranoia pattern from MSVC 2005). We only do it once since the
+        // second write is a no-op that modern compilers would eliminate anyway.
+        core::ptr::write_bytes(buffer, 0, total_size as usize);
+
+        (*this).vtable = rb(va::BIT_GRID_VTABLE);
+        (*this).external_buffer = 0;
+        (*this).data = buffer;
+        (*this).cells_per_unit = cells_per_unit;
+        (*this).row_stride = row_stride as u32;
+        (*this).width = width;
+        (*this).height = height;
+        (*this).clip_left = 0;
+        (*this).clip_top = 0;
+        (*this).clip_right = width;
+        (*this).clip_bottom = height;
+    }
+}
 
 /// BitGrid display-layer vtable (0x664144, 8 slots).
 ///
 /// Pixel buffer operations for 8-bit paletted rendering layers.
 /// All pixel addressing uses: `data[y * row_stride + x]`
 ///
-/// The DDDisplay creates 3 layer objects in DDDisplay__Init:
+/// DDDisplay creates 3 layer objects in DDDisplay__Init:
 /// - Layer 0 at DisplayGfx+0x3D9C
 /// - Layer 1 at DisplayGfx+0x3DA0
 /// - Layer 2 at DisplayGfx+0x3DA4 (uses BitGrid__Init for extended setup)
@@ -42,8 +121,6 @@ pub struct BitGridDisplayVtable {
     #[slot(3)]
     pub destructor: fn(this: *mut BitGrid, flags: u8) -> *mut BitGrid,
     /// get pixel (clipped) — returns 0 if (x, y) is outside clip rect (0x4F9140, RET 0x8)
-    ///
-    /// Clip rect: `_unused_1c`..`width_dup` (x), `_unused_20`..`height_dup` (y)
     #[slot(4)]
     pub get_pixel_clipped: fn(this: *mut BitGrid, x: i32, y: i32) -> u8,
     /// put pixel (clipped) — no-op if (x, y) is outside clip rect (0x4F9180, RET 0xC)

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

@@ -1,5 +1,5 @@
 use super::base::DisplayBase;
-use crate::task::bit_grid::BitGrid;
+use super::bitgrid::BitGrid;
 use core::ffi::c_void;
 
 /// DisplayGfx — full display/graphics subsystem (derived from DisplayBase).

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

@@ -6,10 +6,10 @@
 //! may have subtle color differences due to the tangled decompiler output.
 
 use crate::address::va;
+use crate::display::bitgrid::BitGrid;
 use crate::engine::ddgame::DDGame;
 use crate::rebase::rb;
 use crate::render::gfx_dir::call_gfx_find_and_load;
-use crate::task::bit_grid::BitGrid;
 use crate::wa_alloc::{wa_free, wa_malloc};
 
 /// Palette context for gradient color mapping.

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

@@ -4,7 +4,11 @@ use crate::audio::music::Music;
 use crate::audio::speech::SpeechSlotTable;
 use crate::display::dd_display::DDDisplay;
 use crate::display::palette::Palette;
+use crate::display::BitGrid;
 use crate::engine::game_info::GameInfo;
+use crate::engine::{
+    CoordEntry, CoordList, RenderEntry, SoundQueueEntry, TeamArenaState, TeamIndexMap,
+};
 use crate::fixed::Fixed;
 use crate::game::weapon::WeaponTable;
 use crate::input::keyboard::DDKeyboard;
@@ -13,22 +17,6 @@ use crate::render::queue::RenderQueue;
 use crate::render::turn_order::TurnOrderWidget;
 use crate::FieldRegistry;
 
-// Re-export constructor items so existing `engine::ddgame::*` imports keep working.
-pub use super::ddgame_constructor::{
-    bit_grid_init, create_ddgame, ddgame_init_fields, ddgame_init_render_indices,
-    display_layer_color_init, gfx_dir_find_entry, gfx_resource_create, init_constructor_addrs,
-    ON_DDGAME_ALLOC,
-};
-// Re-export public GfxHandler functions so existing `engine::ddgame::*` imports keep working.
-pub use crate::render::gfx_dir::gfx_dir_load_dir;
-
-// Re-export all team_arena types so existing `engine::ddgame::*` imports keep working.
-pub use crate::engine::team_arena::{
-    worm, CoordEntry, CoordList, CoordListEntry, RenderEntry, SoundQueueEntry, TeamArenaRef,
-    TeamArenaState, TeamBlock, TeamHeader, TeamIndexMap, TeamSlot0, TeamWeaponSlots, WeaponSlots,
-    WormEntry, GAME_PHASE_NORMAL_MIN, GAME_PHASE_SUDDEN_DEATH,
-};
-
 /// DDGame — the main game engine object.
 ///
 /// This is a massive ~39KB struct (0x98D8 bytes) that owns all major subsystems:
@@ -81,15 +69,16 @@ pub struct DDGame {
     pub arrow_sprites: [*mut u8; 32],
     /// 0x0B8-0x134: Arrow GfxDir pointers (32 entries, conditional)
     pub arrow_gfxdirs: [*mut u8; 32],
-    /// 0x138: DisplayGfx object pointer (vtable 0x664144)
-    pub display_gfx: *mut u8,
-    /// 0x13C-0x37F: Sprite/image object cache (145 pointer slots).
-    /// All populated entries have vtable 0x664144 (same class as `display_gfx`).
+    /// 0x138: Primary display BitGrid (vtable 0x664144, 8bpp pixel buffer).
+    /// Allocated as 0x4C bytes, initialized with BitGrid::init(8, 0x100, 0x1E0).
+    pub display_bitgrid: *mut BitGrid,
+    /// 0x13C-0x37F: Sprite/image BitGrid cache (145 pointer slots).
+    /// All populated entries have vtable 0x664144 (same class as `display_bitgrid`).
     /// Not initialized in DDGame__Constructor — filled during gameplay with
     /// weapon sprites, effect images, cursor graphics, etc.
     pub sprite_cache: [*mut u8; 145],
     /// 0x380: BitGrid pointer (vtable 0x664118, 0x2C bytes)
-    pub bit_grid: *mut u8,
+    pub bit_grid: *mut BitGrid,
     /// 0x384-0x467: Additional sprite/image object slots.
     /// Same vtable 0x664144 as sprite_cache. ~20 entries populated at runtime.
     pub sprite_cache_2: [*mut u8; 57],
@@ -590,7 +579,7 @@ impl DDGame {
 // DDGame constructor code (create_ddgame, init helpers, usercall bridges)
 // has been moved to ddgame_constructor.rs.
 
-// BitGrid__Init moved to crate::task::bit_grid
+// BitGrid__Init lives in crate::display::bitgrid
 // Re-exported via ddgame_constructor.rs
 /// Well-known byte offsets into DDGame, for use with raw pointer access.
 ///

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

@@ -12,6 +12,7 @@ use crate::address::va;
 use crate::audio::active_sound::ActiveSoundTable;
 use crate::audio::dssound::DSSound;
 use crate::audio::music::Music;
+use crate::display::bitgrid::BitGrid;
 use crate::display::dd_display::DDDisplay;
 use crate::display::gradient::compute_complex_gradient;
 use crate::display::palette::Palette;
@@ -26,12 +27,8 @@ use crate::render::gfx_dir::{
 };
 pub use crate::render::gfx_dir::{gfx_dir_find_entry, gfx_resource_create};
 use crate::render::landscape::PCLandscape;
-use crate::task::bit_grid::BitGrid;
 use crate::wa_alloc::{wa_malloc, wa_malloc_zeroed};
 
-// Re-export bit_grid_init so existing `engine::ddgame::bit_grid_init` paths keep working.
-pub use crate::task::bit_grid::bit_grid_init;
-
 // ============================================================
 // Pure Rust implementations of DDGame sub-functions
 // ============================================================
@@ -708,16 +705,16 @@ unsafe fn init_graphics_and_resources(
         }
     };
 
-    // ── BitGrid at DDGame+0x380 (alloc 0x4C, memset 0x2C) ──
-    // Pure Rust: allocate object, call bit_grid_init, override vtable.
+    // ── BitGrid at DDGame+0x380 ──
     {
-        let bit_grid = wa_malloc(0x4C);
-        core::ptr::write_bytes(bit_grid, 0, 0x2C);
+        use crate::wa_alloc::wa_malloc_struct_zeroed;
+
+        let bit_grid = wa_malloc_struct_zeroed::<BitGrid>();
         if !bit_grid.is_null() {
             let width = (*ddgame).level_width;
             let height = (*ddgame).level_height;
-            bit_grid_init(bit_grid, 1, width, height);
-            *(bit_grid as *mut u32) = rb(va::BIT_GRID_VARIANT_VTABLE);
+            BitGrid::init(bit_grid as *mut BitGrid, 1, width, height);
+            (*bit_grid).vtable = rb(va::BIT_GRID_VARIANT_VTABLE);
         }
         (*ddgame).bit_grid = bit_grid;
     }
@@ -803,9 +800,9 @@ unsafe fn init_graphics_and_resources(
             //   right/bottom = dim - margin
             // Result: this[5]=this[6]=10 for sprites >20px (the 10px inset).
             if !sprite.is_null() {
-                let tsm = &*(sprite as *const BitGrid);
-                let sprite_w = tsm.width as i32;
-                let sprite_h = tsm.height as i32;
+                let grid = &*(sprite as *const BitGrid);
+                let sprite_w = grid.width as i32;
+                let sprite_h = grid.height as i32;
                 let margin_w = (sprite_w / 2 - 10).max(0);
                 let margin_h = (sprite_h / 2 - 10).max(0);
 
@@ -846,15 +843,16 @@ unsafe fn init_graphics_and_resources(
         release(gfx_resource, 1);
     }
 
-    // ── DisplayGfx at DDGame+0x138 ──
+    // ── Display BitGrid at DDGame+0x138 ──
     {
-        let tsm = wa_malloc(0x4C);
-        core::ptr::write_bytes(tsm, 0, 0x2C);
-        if !tsm.is_null() {
-            bit_grid_init(tsm, 8, 0x100, 0x1E0);
-            *(tsm as *mut u32) = rb(va::BIT_GRID_DISPLAY_VTABLE);
+        use crate::wa_alloc::wa_malloc_struct_zeroed;
+
+        let grid = wa_malloc_struct_zeroed::<BitGrid>();
+        if !grid.is_null() {
+            BitGrid::init(grid, 8, 0x100, 0x1E0);
+            *(grid as *mut u32) = rb(va::BIT_GRID_DISPLAY_VTABLE);
         }
-        (*ddgame).display_gfx = tsm;
+        (*ddgame).display_bitgrid = grid as *mut BitGrid;
     }
 
     // ── CoordList at DDGame+0x50C (capacity 600, 0x12C0 buffer) ──

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

@@ -143,6 +143,7 @@ pub struct WormEntry {
     /// 0x00: Worm state machine state.
     /// Values: 0x65=idle, 0x67=active/selected, 0x68=active variant.
     /// Special states {0x80..0x85, 0x89} = dying/drowning/special animation.
+    /// TODO: Update this to use WormState enum
     pub state: u32,
     /// 0x04: Unknown counter. Incremented by Freeze (+10).
     pub effect_counter_04_Maybe: i32,
@@ -310,6 +311,7 @@ pub struct TeamArenaState {
     /// 0x2C10: Unknown padding
     pub _pad_2c10: [u8; 0x18],
     /// 0x2C28: Game phase counter (>=484 = sudden death, >=-2 = normal game)
+    /// TODO: Convert this to GamePhase enum
     pub game_phase: i32,
 
     // === Alliance tracking (set by CountTeamsByAlliance + SetActiveWorm_Maybe) ===
@@ -332,6 +334,7 @@ pub struct TeamArenaState {
 const _: () = assert!(core::mem::size_of::<TeamArenaState>() == 0x2C48);
 
 /// Worm state constants and helpers.
+/// TODO: Replace this module with the WormState enum
 pub mod worm {
     // --- Known state values (runtime-validated via validator dumps) ---
 

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

@@ -13,7 +13,9 @@
 //! - CheckAnyWormState0x8b (0x522970)
 //! - SetActiveWorm_Maybe (0x522500)
 
-use super::ddgame::{self, TeamArenaRef};
+use crate::engine::team_arena::worm;
+
+use super::team_arena::TeamArenaRef;
 
 /// Count teams by alliance membership — port of 0x522030.
 ///
@@ -67,7 +69,7 @@ pub unsafe fn is_worm_in_special_state(
     worm_index: u32,
     arena: TeamArenaRef,
 ) -> u32 {
-    if ddgame::worm::is_special_state(
+    if worm::is_special_state(
         arena
             .team_worm(team_index as usize, worm_index as usize)
             .state,

crates/openwa-core/src/game/weapon_fire.rs

@@ -11,7 +11,7 @@
 
 use crate::address::va;
 use crate::audio::{KnownSoundId, SoundId};
-use crate::engine::ddgame::{self, TeamArenaRef};
+use crate::engine::{TeamArenaRef, GAME_PHASE_NORMAL_MIN, GAME_PHASE_SUDDEN_DEATH};
 use crate::fixed::Fixed;
 use crate::game::weapon::{WeaponEntry, WeaponFireParams, WeaponSpawnData};
 use crate::game::Weapon;
@@ -93,15 +93,13 @@ pub unsafe fn get_ammo(team_index: u32, arena: TeamArenaRef, weapon_id: u32) ->
         }
         // In sudden death (phase >= 484), delayed weapons return 0
         // unless it's Teleport (weapon 0x28)
-        if state.game_phase >= ddgame::GAME_PHASE_SUDDEN_DEATH
-            && weapon_id != Weapon::Teleport as u32
-        {
+        if state.game_phase >= GAME_PHASE_SUDDEN_DEATH && weapon_id != Weapon::Teleport as u32 {
             return 0;
         }
     }
 
     // SelectWorm (0x3B) requires >1 alive worm on the team
-    if state.game_phase >= ddgame::GAME_PHASE_NORMAL_MIN
+    if state.game_phase >= GAME_PHASE_NORMAL_MIN
         && weapon_id == Weapon::SelectWorm as u32
         && count_alive_worms(team_index, arena) == 0
     {
@@ -465,7 +463,6 @@ unsafe fn fire_select_worm(worm: *mut CTaskWorm) {
 /// Bit position comes from weapon entry's fire_params.
 /// In game_version > 0x1C: toggles (set/clear). Otherwise: always sets.
 unsafe fn fire_skip_go(worm: *const CTaskWorm, entry: *const WeaponEntry) {
-    use crate::engine::ddgame::TeamArenaRef;
     let ddgame = CTask::ddgame_raw(worm as *const CTask);
     let game_version = (*(*ddgame).game_info).game_version;
     let team_index = (*worm).team_index as usize;
@@ -489,8 +486,6 @@ unsafe fn fire_skip_go(worm: *const CTaskWorm, entry: *const WeaponEntry) {
 /// Sends message 0x29 (TaskMessage::Freeze) to CTaskTurnGame, then increments
 /// WormEntry.turn_action_counter_Maybe by 14 (0x0E).
 unsafe fn fire_freeze(worm: *mut CTaskWorm) {
-    use crate::engine::ddgame::TeamArenaRef;
-
     fire_send_team_message(worm, 0x29);
 
     let ddgame = CTask::ddgame_raw(worm as *const CTask);
@@ -514,7 +509,6 @@ unsafe fn fire_freeze(worm: *mut CTaskWorm) {
 /// - version >= 5 && worm state == 0x78 && version < 8: call vtable
 /// - otherwise: skip
 unsafe fn fire_mail_mine_mole(worm: *mut CTaskWorm) {
-    use crate::engine::ddgame::TeamArenaRef;
     let ddgame = CTask::ddgame_raw(worm as *const CTask);
     let version = (*ddgame).version_flag_4;
     let worm_state = (*worm).state();
@@ -989,7 +983,7 @@ unsafe fn fire_girder(worm: *mut CTaskWorm) {
         girder_visual(landscape, girder_x >> 16, girder_y >> 16, sprite1, sprite2);
 
         // Increment WormEntry counters
-        let arena = crate::engine::ddgame::TeamArenaRef::from_ptr(&raw mut (*ddgame).team_arena);
+        let arena = TeamArenaRef::from_ptr(&raw mut (*ddgame).team_arena);
         let team_index = (*worm).team_index as usize;
         let worm_index = (*worm).worm_index as usize;
         let entry = arena.team_worm_mut(team_index, worm_index);

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

@@ -795,8 +795,9 @@ pub struct Sprite {
     pub secondary_frame_count: u16,
     /// 0x32: Padding
     pub _pad_32: u16,
-    /// 0x34: DisplayGfx bitmap handle (vtable 0x664144 set by ConstructSprite)
-    pub display_gfx: *mut u8,
+    /// 0x34: Embedded BitGrid vtable pointer (0x664144, set by ConstructSprite).
+    /// Part of a BitGrid sub-object within the Sprite.
+    pub bitgrid_vtable: *mut u8,
     /// 0x38-0x5F: Unknown fields
     pub _unknown_38: [u8; 0x28],
     /// 0x60: Pointer to raw frame header data

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

@@ -1,67 +0,0 @@
-//! BitGrid initialization — bitfield grid buffer for spatial queries.
-
-use crate::rebase::rb;
-use crate::wa_alloc::wa_malloc;
-use crate::FieldRegistry;
-
-/// Bitfield grid buffer used for spatial collision/visibility queries.
-/// Vtable at 0x6640EC (shared with DisplayGfx base).
-/// Size: 0x2C bytes (11 u32 fields).
-#[derive(FieldRegistry)]
-#[repr(C)]
-pub struct BitGrid {
-    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::<BitGrid>() == 0x2C);
-
-/// Pure Rust implementation of BitGrid__Init (0x4F6370).
-///
-/// 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 bit_grid_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;
-
-    let alloc_size = ((total_size + 3) & !3) + 0x20;
-    let buffer = wa_malloc(alloc_size);
-
-    if buffer.is_null() {
-        return;
-    }
-    if total_size as usize > alloc_size as usize {
-        return;
-    }
-
-    // Memset twice (matches original — likely redundant but exact match)
-    core::ptr::write_bytes(buffer, 0, total_size as usize);
-    core::ptr::write_bytes(buffer, 0, total_size as usize);
-
-    let tsm = &mut *(object as *mut BitGrid);
-    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;
-}

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

@@ -1,6 +1,5 @@
 pub mod arrow;
 pub mod base;
-pub mod bit_grid;
 pub mod cloud;
 pub mod filter;
 pub mod fire;

crates/openwa-core/src/wa_alloc.rs

@@ -13,6 +13,25 @@ pub unsafe fn wa_malloc(size: u32) -> *mut u8 {
     f(size)
 }
 
+/// Allocate space for a `T` on WA's heap and return a pointer to it.
+///
+/// Equivalent to `wa_malloc(size_of::<T>())` with a cast. The allocation is uninitialized.
+///
+/// # Safety
+/// Must only be called from within the WA.exe process (game or injected DLL).
+pub unsafe fn wa_malloc_struct<T>() -> *mut T {
+    wa_malloc(core::mem::size_of::<T>() as u32) as *mut T
+}
+
+/// Allocate space for a `T` on WA's heap, zero-initialize it, and return a pointer to it.
+/// Equivalent to `wa_malloc_zeroed(size_of::<T>())` with a cast. The allocation is zero-initialized.
+///
+/// # Safety
+/// Must only be called from within the WA.exe process (game or injected DLL).
+pub unsafe fn wa_malloc_struct_zeroed<T>() -> *mut T {
+    wa_malloc_zeroed(core::mem::size_of::<T>() as u32) as *mut T
+}
+
 /// Allocate `size` bytes from WA's CRT heap and zero-initialize them.
 ///
 /// Equivalent to `wa_malloc(size)` followed by `write_bytes(ptr, 0, size)`.

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

@@ -14,15 +14,15 @@
 use crate::hook;
 use core::ffi::c_char;
 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_dir_load_dir, gfx_resource_create, DDGame,
-};
+use openwa_core::display::BitGrid;
 use openwa_core::engine::game_state_init::{
     check_weapon_avail, init_alliance_data, init_landscape_flags, init_team_scoring,
     init_turn_state, is_super_weapon, ring_buffer_init, sprite_gfx_table_init,
 };
-use openwa_core::engine::DDGameWrapper;
+use openwa_core::engine::{
+    ddgame_init_fields, ddgame_init_render_indices, display_layer_color_init, DDGame, DDGameWrapper,
+};
+use openwa_core::render::gfx_dir::{gfx_dir_find_entry, gfx_dir_load_dir, gfx_resource_create};
 
 // ─── DDGame__InitFields (0x526120) ──────────────────────────────────────────
 
@@ -54,13 +54,18 @@ extern "cdecl" fn impl_init_render_indices(base: u32) -> u32 {
 
 // ─── BitGrid__Init (0x4F6370) ──────────────────────────────────────
 
-extern "cdecl" fn impl_tsm_init(object: u32, param1: u32, height: u32, width: u32) -> u32 {
-    unsafe { bit_grid_init(object as *mut u8, param1, width, height) }
-    object // Original: MOV EAX, ESI; RET 0x4
+extern "cdecl" fn impl_bitgrid_init(
+    bit_grid: *mut BitGrid,
+    cells_per_unit: u32,
+    height: u32,
+    width: u32,
+) -> *mut BitGrid {
+    unsafe { BitGrid::init(bit_grid, cells_per_unit, width, height) }
+    bit_grid // Original: MOV EAX, ESI; RET 0x4
 }
 
 #[unsafe(naked)]
-unsafe extern "C" fn tsm_init_trampoline() {
+unsafe extern "C" fn bitgrid_init_trampoline() {
     core::arch::naked_asm!(
         "push edx",
         "push [esp+8]",       // width (stack param)
@@ -71,7 +76,7 @@ unsafe extern "C" fn tsm_init_trampoline() {
         "add esp, 16",
         "pop edx",
         "ret 0x4",
-        impl_fn = sym impl_tsm_init,
+        impl_fn = sym impl_bitgrid_init,
     );
 }
 
@@ -180,7 +185,7 @@ pub fn install() -> Result<(), String> {
         hook::install(
             "BitGrid__Init",
             va::BIT_GRID_INIT,
-            tsm_init_trampoline as *const (),
+            bitgrid_init_trampoline as *const (),
         )?;
 
         hook::install(

crates/openwa-dll/src/replacements/game_session.rs

@@ -17,7 +17,8 @@ use crate::log_line;
 use openwa_core::address::va;
 use openwa_core::audio::DSSound;
 use openwa_core::display::{DDDisplay, Palette};
-use openwa_core::engine::ddgame::{create_ddgame, init_constructor_addrs};
+use openwa_core::engine::create_ddgame;
+use openwa_core::engine::init_constructor_addrs;
 use openwa_core::engine::{DDGameWrapper, GameInfo, GameSession};
 use openwa_core::rebase::rb;
 

crates/openwa-dll/src/replacements/replay_test.rs

@@ -13,9 +13,10 @@
 use std::sync::atomic::{AtomicBool, AtomicI32, AtomicU32, Ordering};
 
 use crate::log_line;
-use openwa_core::engine::ddgame::{offsets, TeamArenaRef};
+use openwa_core::engine::ddgame::offsets;
 use openwa_core::engine::game_session;
 use openwa_core::engine::DDGame;
+use openwa_core::engine::TeamArenaRef;
 
 // ---------------------------------------------------------------------------
 // Fast-forward

crates/openwa-dll/src/replacements/sprite.rs

@@ -24,9 +24,9 @@ unsafe extern "cdecl" fn construct_sprite_impl(sprite: *mut Sprite, context: *mu
 
     (*sprite).vtable = rb(va::SPRITE_VTABLE) as *mut u8;
     (*sprite).context_ptr = context;
-    (*sprite).display_gfx = rb(va::BIT_GRID_DISPLAY_VTABLE) as *mut u8;
+    (*sprite).bitgrid_vtable = rb(va::BIT_GRID_DISPLAY_VTABLE) as *mut u8;
 
-    // DisplayGfx sub-object fields (within _unknown_38)
+    // BitGrid sub-object fields (within _unknown_38)
     let p = sprite as *mut u8;
     *(p.add(0x38) as *mut u32) = 1;
     *(p.add(0x40) as *mut u32) = 8;

crates/openwa-dll/src/replacements/team.rs

@@ -3,9 +3,8 @@
 //! Thin hook shim — all game logic lives in `openwa_core::engine::team_ops`.
 //! This file contains only usercall trampolines and hook installation.
 
-use openwa_core::address::va;
-use openwa_core::engine::ddgame::TeamArenaRef;
 use openwa_core::engine::team_ops;
+use openwa_core::{address::va, engine::TeamArenaRef};
 
 use crate::hook::{self, usercall_trampoline};
 

crates/openwa-dll/src/replacements/weapon.rs

@@ -12,12 +12,11 @@
 
 use core::sync::atomic::{AtomicU32, Ordering};
 
-use openwa_core::address::va;
-use openwa_core::engine::ddgame::TeamArenaRef;
 use openwa_core::game::weapon::WeaponFireParams;
 use openwa_core::game::weapon_fire;
 use openwa_core::log::log_line;
 use openwa_core::task::worm::CTaskWorm;
+use openwa_core::{address::va, engine::TeamArenaRef};
 
 use crate::hook::{self, usercall_trampoline};
 

crates/openwa-dll/src/snapshot.rs

@@ -19,6 +19,8 @@ use openwa_core::task::{CTask, CTaskBfsIter, CTaskMissile, CTaskWorm};
 /// Must be called from the DLL while the game is paused (frame breakpoint).
 #[cfg(target_arch = "x86")]
 pub unsafe fn capture() -> String {
+    use openwa_core::engine::TeamArenaRef;
+
     let mut out = String::with_capacity(128 * 1024);
 
     let session_ptr = rb(va::G_GAME_SESSION) as *const *mut GameSession;
@@ -60,7 +62,7 @@ pub unsafe fn capture() -> String {
     // ── Team blocks + worm entries ──
     let team_count = (*ddgame).team_arena.team_count as usize;
     let _ = writeln!(out, "[Teams] count={}", team_count);
-    let arena = openwa_core::engine::ddgame::TeamArenaRef::from_ptr(&raw mut (*ddgame).team_arena);
+    let arena = TeamArenaRef::from_ptr(&raw mut (*ddgame).team_arena);
     let blocks = arena.blocks();
     for t in 0..team_count {
         let header = arena.team_header(t);