feat: add WormState enum — typed worm state machine values

Add repr(u8) WormState enum with all known states from CTaskWorm::HandleMessage
(0x510B40) decompilation and weapon fire dispatch analysis:
- Idle/Active states (0x64-0x68)
- Weapon fire states (0x6C-0x75: Blowtorch, Bat, Kamikaze, etc.)
- Aiming/charging states (0x77-0x7E)
- Dying/dead states (0x7F-0x8B)

Update CTaskWormVTable::set_state to take WormState parameter.
Replace all hex literals in weapon.rs with enum variants.

Source: Ghidra decompilation of HandleMessage switch cases +
SetState call sites across weapon fire dispatch.

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

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

@@ -25,7 +25,7 @@ pub use overlays::{BungeeTrailTask, WeaponAimTask};
 pub use supply_crate::{CTaskCrate, CTaskCrateVTable};
 pub use team::{CTaskTeam, CTaskTeamVTable};
 pub use turn_game::{CTaskTurnGame, CTaskTurnGameVTable, TurnGameCtx};
-pub use worm::{CTaskWorm, CTaskWormVTable};
+pub use worm::{CTaskWorm, CTaskWormVTable, WormState};
 
 // Task trait impls — safe access to CTask base regardless of inheritance depth.
 // CTask<V> impl is in base.rs (blanket impl).

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

@@ -3,6 +3,98 @@ use super::game_task::CGameTask;
 use crate::game::weapon::WeaponEntry;
 use crate::FieldRegistry;
 
+/// Worm state machine states.
+///
+/// CTaskWorm's `SetState` (vtable slot 14) transitions between these.
+/// The state byte lives at CTaskWorm+0x44 (inside `base.subclass_data`).
+/// Also stored in WormEntry.state in the TeamArenaState.
+///
+/// States 0x68..=0x8A are the "weapon/action active" range — checked by
+/// `(state - 0x68) < 0x23` in HandleMessage. States 0x80+ are dying/dead.
+/// Names are best guesses from behavioral observation and disassembly.
+///
+/// Source: CTaskWorm::HandleMessage (0x510B40) decompilation + weapon fire dispatch.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+#[repr(u8)]
+#[allow(non_camel_case_types)]
+pub enum WormState {
+    /// Transitional state checked by CheckWormState0x64 (0x5228D0).
+    /// Appears briefly during turn transitions.
+    Transitional = 0x64,
+    /// Idle — not this worm's turn. Also used by MailMineMole to re-enter idle.
+    Idle = 0x65,
+    /// Idle variant — grouped with 0x65/0x67 in HandleMessage switch cases.
+    IdleVariant_Maybe = 0x66,
+    /// Active turn — this worm is currently being controlled.
+    Active = 0x67,
+    /// Active variant — observed in WormEntry. Start of weapon/action range.
+    ActiveVariant_Maybe = 0x68,
+    // 0x69–0x6B: unknown (within weapon/action range)
+    /// Blowtorch — using the blowtorch weapon.
+    Blowtorch = 0x6C,
+    /// Baseball Bat — swinging the baseball bat. Frequently checked in HandleMessage.
+    BaseballBat = 0x6D,
+    /// Kamikaze — performing kamikaze attack.
+    Kamikaze = 0x6E,
+    // 0x6F: unknown
+    /// Dragon Ball — performing dragon ball attack.
+    DragonBall = 0x70,
+    /// Scales of Justice — using scales of justice.
+    ScalesOfJustice = 0x71,
+    /// Suicide Bomber — performing suicide bomber attack.
+    SuicideBomber = 0x72,
+    /// Weapon charging — entered from aiming states (0x7B, 0x7C) before release.
+    /// Also set by CheckPendingAction when field +0xBC is nonzero.
+    WeaponCharging_Maybe = 0x73,
+    /// Teleport cancelled — teleport failed or was denied.
+    TeleportCancelled_Maybe = 0x74,
+    /// Fire Punch — performing fire punch attack.
+    FirePunch = 0x75,
+    // 0x76: unknown
+    /// Weapon selected — entered via SelectCursor (msg 0x24) from idle/active states.
+    /// HandleMessage sets param[0xa7]=-1 when already in this state.
+    WeaponSelected_Maybe = 0x77,
+    /// Weapon aimed — post-select state. Teleport check accepts this.
+    /// Also used for Magic Bullet weapon fire.
+    WeaponAimed_Maybe = 0x78,
+    // 0x79–0x7A: unknown
+    /// Aiming with angle — entered for aimed weapons. Sets angle params.
+    /// Teleport check accepts this. Transitions to 0x73 on fire.
+    AimingAngle_Maybe = 0x7B,
+    /// Rope swinging — IsNotOnRope checks `state != 0x7C`.
+    /// Transitions to 0x73 on fire.
+    RopeSwinging = 0x7C,
+    /// Pre-fire variant — MailMineMole version check uses this.
+    /// Transitions to 0x7E or 0x65 depending on FUN_004fb580.
+    PreFire_Maybe = 0x7D,
+    /// Post-fire / special movement — entered from 0x78 and 0x7D
+    /// when FUN_004fb580 returns nonzero.
+    PostFire_Maybe = 0x7E,
+    /// Drowning — worm fell in water.
+    Drowning = 0x7F,
+    /// Hurt — worm took damage.
+    Hurt = 0x80,
+    /// Dead variant 1.
+    Dead1 = 0x81,
+    /// Dying variant 1 — checked alongside 0x83 in HandleMessage.
+    Dying1_Maybe = 0x82,
+    /// Dying variant 2 — checked alongside 0x82 in HandleMessage.
+    Dying2_Maybe = 0x83,
+    // 0x84–0x85: unknown
+    /// Dead — set by Surrender (msg 0x29). Frequently checked in HandleMessage.
+    Dead = 0x86,
+    /// Dead variant 3.
+    Dead3 = 0x87,
+    /// Unknown — grouped with idle states (0x65/0x66/0x67/0x8B) in HandleMessage.
+    Unknown_0x88 = 0x88,
+    /// Dying/special animation (from WormEntry state documentation).
+    DyingAnimation_Maybe = 0x89,
+    // 0x8A: end of weapon/action range
+    /// Unknown state checked in CTaskTeam handlers.
+    /// Grouped with idle states in HandleMessage switch cases.
+    Unknown_0x8B = 0x8B,
+}
+
 crate::define_addresses! {
     class "CTaskWorm" {
         /// CTaskWorm vtable
@@ -61,7 +153,7 @@ pub struct CTaskWormVTable {
     pub on_killed: fn(this: *mut CTaskWorm),
     /// SetState — worm state machine; handles all state transitions
     #[slot(14)]
-    pub set_state: fn(this: *mut CTaskWorm, state: u32),
+    pub set_state: fn(this: *mut CTaskWorm, state: WormState),
     /// CheckPendingAction — if field +0xBC is set, calls SetState(0x73)
     #[slot(15)]
     pub check_pending_action: fn(this: *mut CTaskWorm),
@@ -194,10 +286,7 @@ bind_CTaskWormVTable!(CTaskWorm, base.base.vtable);
 
 impl CTaskWorm {
     /// Returns the worm's current state code (lives at offset +0x44, inside
-    /// `base.subclass_data`).
-    ///
-    /// Known states: `0x65`=idle, `0x67`=active turn, `0x7F`=drowning,
-    /// `0x80`=hurt, `0x81`/`0x86`=dead, `0x87`=dead variant, `0x8B`=unknown.
+    /// `base.subclass_data`). See [`WormState`] for known values.
     pub fn state(&self) -> u32 {
         unsafe { *((self as *const CTaskWorm as *const u8).add(0x44) as *const u32) }
     }

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

@@ -22,7 +22,7 @@ use openwa_core::game::weapon::{WeaponEntry, WeaponFireParams, WeaponSpawnData};
 use openwa_core::game::Weapon;
 use openwa_core::log::log_line;
 use openwa_core::task::Task;
-use openwa_core::task::worm::CTaskWorm;
+use openwa_core::task::worm::{CTaskWorm, WormState};
 
 use crate::hook::{self, usercall_trampoline};
 
@@ -358,25 +358,25 @@ unsafe fn fire_weapon_special(
 
     match subtype {
         // Blowtorch
-        1 => (*worm).set_state(0x6C),
+        1 => (*worm).set_state(WormState::Blowtorch),
         // Pneumatic Drill (pure Rust)
         2 => fire_drill(worm, local_struct),
         // Girder
         3 => call_fire_stdcall3(worm, params_38_ptr, local_struct, rb(0x51E350)),
         // Baseball Bat
-        4 => (*worm).set_state(0x6D),
+        4 => (*worm).set_state(WormState::BaseballBat),
         // Fire Punch
-        5 => (*worm).set_state(0x75),
+        5 => (*worm).set_state(WormState::FirePunch),
         // Dragon Ball
-        6 => (*worm).set_state(0x70),
+        6 => (*worm).set_state(WormState::DragonBall),
         // Kamikaze
-        8 => (*worm).set_state(0x6E),
+        8 => (*worm).set_state(WormState::Kamikaze),
         // Prod (pure Rust)
         9 => fire_prod(worm, local_struct),
         // Air Strike (EAX=worm)
         10 => call_fire_usercall(worm as *const (), worm, rb(0x51E710)),
         // Scales of Justice
-        11 => (*worm).set_state(0x71),
+        11 => (*worm).set_state(WormState::ScalesOfJustice),
         // Napalm Strike
         13 => fire_send_team_message(worm, 0x2B),
         // Mail/Mine/Mole (pure Rust)
@@ -387,13 +387,14 @@ unsafe fn fire_weapon_special(
             if can_teleport(worm_state) {
                 call_fire_usercall(worm_state as *const (), worm, rb(0x51EB00));
             } else {
-                (*worm).set_state(0x74);
+                // Teleport denied — return to cancelled state
+                (*worm).set_state(WormState::TeleportCancelled_Maybe);
             }
         }
         // Freeze (EAX=worm)
         17 => call_fire_usercall(worm as *const (), worm, rb(0x51E920)),
         // Suicide Bomber
-        18 => (*worm).set_state(0x72),
+        18 => (*worm).set_state(WormState::SuicideBomber),
         // Skip Go (pure Rust)
         19 => fire_skip_go(worm, entry),
         // Surrender (pure Rust)
@@ -403,7 +404,7 @@ unsafe fn fire_weapon_special(
         // Jet Pack (EAX=entry)
         22 => call_fire_usercall(entry as *const (), worm, rb(0x51EC30)),
         // Magic Bullet
-        23 => (*worm).set_state(0x78),
+        23 => (*worm).set_state(WormState::WeaponAimed_Maybe),
         // Low Gravity (EAX=entry)
         24 => call_fire_usercall(entry as *const (), worm, rb(0x51EA60)),
         _ => {}
@@ -412,9 +413,9 @@ unsafe fn fire_weapon_special(
 
 /// Teleport validity check — pure Rust port of 0x516930.
 /// Returns true if the worm's current state allows teleportation.
-/// Valid states: 0x78 (idle-aim), 0x7B-0x7D (pre-fire range).
 fn can_teleport(state: u32) -> bool {
-    state == 0x78 || (0x7B..=0x7D).contains(&state)
+    state == WormState::WeaponAimed_Maybe as u32
+        || (WormState::AimingAngle_Maybe as u32..=WormState::PreFire_Maybe as u32).contains(&state)
 }
 
 // ── Pure Rust fire handlers (no bridge needed) ──────────────
@@ -538,10 +539,11 @@ unsafe fn fire_mail_mine_mole(worm: *mut CTaskWorm) {
 
     let should_call_vtable = version < 2
         || (version >= 5
-            && (worm_state == 0x7D || (worm_state == 0x78 && version < 8)));
+            && (worm_state == WormState::PreFire_Maybe as u32
+                || (worm_state == WormState::WeaponAimed_Maybe as u32 && version < 8)));
 
     if should_call_vtable {
-        (*worm).set_state(0x65);
+        (*worm).set_state(WormState::Idle);
     }
 
     fire_send_team_message(worm, 0x28);