feat: add .wsc scheme file parser + Scheme__ReadFile hook

Add SchemeFile type to openwa-types with from_bytes/to_bytes for the
SCHM container format (v1: 0xD8 payload, v2: 0x124 payload). Tested
against all 18 bundled scheme files with round-trip verification.

RE discoveries: Scheme__Load (0x4D4CD0) is actually just a file-exists
check, Scheme__ParseFile (0x4D44F0) is a save function. The real reader
is Scheme__ReadFile (0x4D3890), stdcall with 4 params. Hook confirms it
fires when selecting schemes in the multiplayer setup dialog.

8 new Ghidra labels: scheme functions + CFile Read/Write/Open/Close.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

crates/openwa-types/src/address.rs

@@ -218,6 +218,22 @@ pub mod va {
     pub const FRONTEND_LOBBY_HOST_CTOR: u32 = 0x004B_0160;
     pub const FRONTEND_LOBBY_GAME_START_CTOR: u32 = 0x004B_DBE0;
 
+    // === Scheme file operations ===
+
+    /// Reads .wsc file into scheme struct: stdcall(dest, path, flag, out_ptr), RET 0x10
+    /// Opens modeRead|typeBinary, reads header + version-dependent payload to dest+0x14
+    pub const SCHEME_READ_FILE: u32 = 0x004D_3890;
+    /// Checks if scheme file exists: stdcall(name) → 0=not found, 1=found, RET 0x4
+    pub const SCHEME_FILE_EXISTS: u32 = 0x004D_4CD0;
+    /// Saves scheme struct to .wsc file: thiscall(this, name, flag), RET 0x8
+    pub const SCHEME_SAVE_FILE: u32 = 0x004D_44F0;
+    /// Variant file-exists check for numbered schemes ({%02d} Name.wsc)
+    pub const SCHEME_FILE_EXISTS_NUMBERED: u32 = 0x004D_4E00;
+    /// Version detection: compares patterns to determine v1/v2/v3
+    pub const SCHEME_DETECT_VERSION: u32 = 0x004D_4480;
+    /// Extracts built-in schemes from PE resources to User\Schemes\ directory
+    pub const SCHEME_EXTRACT_BUILTINS: u32 = 0x004D_5720;
+
     // === Lobby / network ===
 
     pub const LOBBY_HOST_COMMANDS: u32 = 0x004B_9B00;

crates/openwa-types/src/lib.rs

@@ -11,4 +11,5 @@ pub mod landscape;
 pub mod dssound;
 pub mod opengl;
 pub mod frontend;
+pub mod scheme;
 pub mod address;

crates/openwa-types/src/scheme.rs

@@ -0,0 +1,270 @@
+/// Scheme file (.wsc) parser for Worms Armageddon.
+///
+/// .wsc files store game settings (turn time, wind, per-weapon ammo/delay, etc.).
+/// Located in `User\Schemes\*.wsc`.
+///
+/// Binary format:
+///   Bytes 0-3: Magic "SCHM" (0x5343484D)
+///   Byte 4:    Version byte
+///   Bytes 5+:  Payload (size depends on version)
+///
+/// Version → payload size:
+///   0x01 → 0xD8 bytes (216)
+///   0x02 → 0x124 bytes (292)
+///   other → version_byte as usize + 0x124 bytes
+///
+/// Source: Ghidra decompilation of Scheme__Load (0x4D4CD0),
+///         Scheme__ParseFile (0x4D44F0), hex analysis of bundled .wsc files.
+
+/// Magic header bytes for .wsc files.
+pub const SCHEME_MAGIC: [u8; 4] = *b"SCHM";
+
+/// Size of the file header (magic + version byte).
+pub const SCHEME_HEADER_SIZE: usize = 5;
+
+/// Payload size for version 1 schemes.
+pub const SCHEME_PAYLOAD_V1: usize = 0xD8;
+
+/// Payload size for version 2 schemes.
+pub const SCHEME_PAYLOAD_V2: usize = 0x124;
+
+/// Scheme file version.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SchemeVersion {
+    /// Version 1: 0xD8 byte payload (total file: 221 bytes)
+    V1,
+    /// Version 2: 0x124 byte payload (total file: 297 bytes)
+    V2,
+    /// Extended: payload = version_byte + 0x124 bytes
+    Extended(u8),
+}
+
+impl SchemeVersion {
+    /// Raw version byte as stored in the file.
+    pub fn to_byte(self) -> u8 {
+        match self {
+            SchemeVersion::V1 => 1,
+            SchemeVersion::V2 => 2,
+            SchemeVersion::Extended(v) => v,
+        }
+    }
+
+    /// Parse version from the raw byte.
+    pub fn from_byte(b: u8) -> Self {
+        match b {
+            1 => SchemeVersion::V1,
+            2 => SchemeVersion::V2,
+            v => SchemeVersion::Extended(v),
+        }
+    }
+
+    /// Expected payload size for this version.
+    pub fn payload_size(self) -> usize {
+        match self {
+            SchemeVersion::V1 => SCHEME_PAYLOAD_V1,
+            SchemeVersion::V2 => SCHEME_PAYLOAD_V2,
+            SchemeVersion::Extended(v) => v as usize + SCHEME_PAYLOAD_V2,
+        }
+    }
+}
+
+/// Errors from parsing a .wsc scheme file.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum SchemeError {
+    /// File is too short to contain the header.
+    TooShort { len: usize },
+    /// Magic bytes don't match "SCHM".
+    BadMagic([u8; 4]),
+    /// Payload size doesn't match what the version byte expects.
+    PayloadMismatch { expected: usize, got: usize },
+}
+
+impl core::fmt::Display for SchemeError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            SchemeError::TooShort { len } => {
+                write!(f, "file too short ({len} bytes, need at least {SCHEME_HEADER_SIZE})")
+            }
+            SchemeError::BadMagic(m) => {
+                write!(f, "bad magic: {:02X} {:02X} {:02X} {:02X} (expected SCHM)", m[0], m[1], m[2], m[3])
+            }
+            SchemeError::PayloadMismatch { expected, got } => {
+                write!(f, "payload size mismatch: expected {expected}, got {got}")
+            }
+        }
+    }
+}
+
+/// A parsed .wsc scheme file.
+///
+/// The payload bytes are initially opaque. Typed field accessors will be
+/// added incrementally as we map individual byte offsets through RE.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SchemeFile {
+    pub version: SchemeVersion,
+    /// Raw payload bytes (game options + per-weapon settings).
+    /// Length matches `version.payload_size()`.
+    pub payload: Vec<u8>,
+}
+
+impl SchemeFile {
+    /// Parse a scheme file from raw bytes (entire file contents).
+    pub fn from_bytes(data: &[u8]) -> Result<Self, SchemeError> {
+        if data.len() < SCHEME_HEADER_SIZE {
+            return Err(SchemeError::TooShort { len: data.len() });
+        }
+
+        let magic: [u8; 4] = data[0..4].try_into().unwrap();
+        if magic != SCHEME_MAGIC {
+            return Err(SchemeError::BadMagic(magic));
+        }
+
+        let version = SchemeVersion::from_byte(data[4]);
+        let expected_payload = version.payload_size();
+        let actual_payload = data.len() - SCHEME_HEADER_SIZE;
+
+        if actual_payload != expected_payload {
+            return Err(SchemeError::PayloadMismatch {
+                expected: expected_payload,
+                got: actual_payload,
+            });
+        }
+
+        Ok(SchemeFile {
+            version,
+            payload: data[SCHEME_HEADER_SIZE..].to_vec(),
+        })
+    }
+
+    /// Serialize back to .wsc format.
+    pub fn to_bytes(&self) -> Vec<u8> {
+        let mut buf = Vec::with_capacity(SCHEME_HEADER_SIZE + self.payload.len());
+        buf.extend_from_slice(&SCHEME_MAGIC);
+        buf.push(self.version.to_byte());
+        buf.extend_from_slice(&self.payload);
+        buf
+    }
+
+    /// Total file size (header + payload).
+    pub fn file_size(&self) -> usize {
+        SCHEME_HEADER_SIZE + self.payload.len()
+    }
+}
+
+impl SchemeFile {
+    /// Load a scheme file from disk.
+    pub fn from_file(path: &std::path::Path) -> Result<Self, SchemeFileError> {
+        let data = std::fs::read(path).map_err(SchemeFileError::Io)?;
+        Self::from_bytes(&data).map_err(SchemeFileError::Parse)
+    }
+
+    /// Save a scheme file to disk.
+    pub fn to_file(&self, path: &std::path::Path) -> Result<(), std::io::Error> {
+        std::fs::write(path, self.to_bytes())
+    }
+}
+
+/// Error type for file-based scheme operations.
+#[derive(Debug)]
+pub enum SchemeFileError {
+    Io(std::io::Error),
+    Parse(SchemeError),
+}
+
+impl core::fmt::Display for SchemeFileError {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            SchemeFileError::Io(e) => write!(f, "I/O error: {e}"),
+            SchemeFileError::Parse(e) => write!(f, "parse error: {e}"),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn version_roundtrip() {
+        for v in [SchemeVersion::V1, SchemeVersion::V2, SchemeVersion::Extended(5)] {
+            assert_eq!(SchemeVersion::from_byte(v.to_byte()), v);
+        }
+    }
+
+    #[test]
+    fn payload_sizes() {
+        assert_eq!(SchemeVersion::V1.payload_size(), 0xD8);
+        assert_eq!(SchemeVersion::V2.payload_size(), 0x124);
+        assert_eq!(SchemeVersion::Extended(3).payload_size(), 3 + 0x124);
+    }
+
+    #[test]
+    fn parse_v1_synthetic() {
+        let mut data = Vec::new();
+        data.extend_from_slice(b"SCHM");
+        data.push(0x01);
+        data.extend_from_slice(&[0xAA; SCHEME_PAYLOAD_V1]);
+        assert_eq!(data.len(), 221);
+
+        let scheme = SchemeFile::from_bytes(&data).unwrap();
+        assert_eq!(scheme.version, SchemeVersion::V1);
+        assert_eq!(scheme.payload.len(), SCHEME_PAYLOAD_V1);
+        assert!(scheme.payload.iter().all(|&b| b == 0xAA));
+    }
+
+    #[test]
+    fn parse_v2_synthetic() {
+        let mut data = Vec::new();
+        data.extend_from_slice(b"SCHM");
+        data.push(0x02);
+        data.extend_from_slice(&[0xBB; SCHEME_PAYLOAD_V2]);
+        assert_eq!(data.len(), 297);
+
+        let scheme = SchemeFile::from_bytes(&data).unwrap();
+        assert_eq!(scheme.version, SchemeVersion::V2);
+        assert_eq!(scheme.payload.len(), SCHEME_PAYLOAD_V2);
+    }
+
+    #[test]
+    fn roundtrip_synthetic() {
+        let mut data = Vec::new();
+        data.extend_from_slice(b"SCHM");
+        data.push(0x01);
+        data.extend_from_slice(&[0x42; SCHEME_PAYLOAD_V1]);
+
+        let scheme = SchemeFile::from_bytes(&data).unwrap();
+        assert_eq!(scheme.to_bytes(), data);
+    }
+
+    #[test]
+    fn error_too_short() {
+        assert_eq!(
+            SchemeFile::from_bytes(b"SCH"),
+            Err(SchemeError::TooShort { len: 3 })
+        );
+    }
+
+    #[test]
+    fn error_bad_magic() {
+        let mut data = vec![b'N', b'O', b'P', b'E', 0x01];
+        data.extend_from_slice(&[0; SCHEME_PAYLOAD_V1]);
+        assert!(matches!(
+            SchemeFile::from_bytes(&data),
+            Err(SchemeError::BadMagic([b'N', b'O', b'P', b'E']))
+        ));
+    }
+
+    #[test]
+    fn error_payload_mismatch() {
+        // v1 header but only 10 bytes of payload
+        let mut data = Vec::new();
+        data.extend_from_slice(b"SCHM");
+        data.push(0x01);
+        data.extend_from_slice(&[0; 10]);
+
+        assert!(matches!(
+            SchemeFile::from_bytes(&data),
+            Err(SchemeError::PayloadMismatch { expected: 0xD8, got: 10 })
+        ));
+    }
+}

crates/openwa-types/tests/fixtures/beginner.wsc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:632057e77927f0a3fd506963015795de622244aabea78d70bd3e28bab888a10f
+size 297

crates/openwa-types/tests/fixtures/classic.wsc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:12980f196d85c7acc0284d34935c998a01296ca4b28439de83d5cf2d5820f6cb
+size 221

crates/openwa-types/tests/fixtures/shopping.wsc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ea83352929ad768d506238f32ea58da4ab6ac210a751db99b404002fb3617fd0
+size 221

crates/openwa-types/tests/scheme_parse.rs

@@ -0,0 +1,86 @@
+use std::path::Path;
+
+use openwa_types::scheme::{SchemeFile, SchemeVersion, SCHEME_PAYLOAD_V1, SCHEME_PAYLOAD_V2};
+
+const FIXTURES: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/fixtures");
+
+#[test]
+fn parse_beginner_v2() {
+    let path = Path::new(FIXTURES).join("beginner.wsc");
+    let scheme = SchemeFile::from_file(&path).expect("failed to parse beginner.wsc");
+    assert_eq!(scheme.version, SchemeVersion::V2);
+    assert_eq!(scheme.payload.len(), SCHEME_PAYLOAD_V2);
+    assert_eq!(scheme.file_size(), 297);
+}
+
+#[test]
+fn parse_classic_v1() {
+    let path = Path::new(FIXTURES).join("classic.wsc");
+    let scheme = SchemeFile::from_file(&path).expect("failed to parse classic.wsc");
+    assert_eq!(scheme.version, SchemeVersion::V1);
+    assert_eq!(scheme.payload.len(), SCHEME_PAYLOAD_V1);
+    assert_eq!(scheme.file_size(), 221);
+}
+
+#[test]
+fn parse_shopping_v1() {
+    let path = Path::new(FIXTURES).join("shopping.wsc");
+    let scheme = SchemeFile::from_file(&path).expect("failed to parse shopping.wsc");
+    assert_eq!(scheme.version, SchemeVersion::V1);
+    assert_eq!(scheme.payload.len(), SCHEME_PAYLOAD_V1);
+}
+
+#[test]
+fn roundtrip_beginner() {
+    let path = Path::new(FIXTURES).join("beginner.wsc");
+    let original = std::fs::read(&path).unwrap();
+    let scheme = SchemeFile::from_bytes(&original).unwrap();
+    assert_eq!(scheme.to_bytes(), original);
+}
+
+#[test]
+fn roundtrip_classic() {
+    let path = Path::new(FIXTURES).join("classic.wsc");
+    let original = std::fs::read(&path).unwrap();
+    let scheme = SchemeFile::from_bytes(&original).unwrap();
+    assert_eq!(scheme.to_bytes(), original);
+}
+
+#[test]
+fn roundtrip_shopping() {
+    let path = Path::new(FIXTURES).join("shopping.wsc");
+    let original = std::fs::read(&path).unwrap();
+    let scheme = SchemeFile::from_bytes(&original).unwrap();
+    assert_eq!(scheme.to_bytes(), original);
+}
+
+/// Parse all .wsc files from the game directory if available.
+#[test]
+fn parse_all_game_schemes() {
+    let schemes_dir = Path::new("I:/games/SteamLibrary/steamapps/common/Worms Armageddon/User/Schemes");
+    if !schemes_dir.exists() {
+        eprintln!("Skipping: game schemes directory not found");
+        return;
+    }
+
+    let mut count = 0;
+    for entry in std::fs::read_dir(schemes_dir).unwrap() {
+        let entry = entry.unwrap();
+        let path = entry.path();
+        if path.extension().map_or(false, |e| e == "wsc") {
+            let scheme = SchemeFile::from_file(&path)
+                .unwrap_or_else(|e| panic!("failed to parse {}: {e}", path.display()));
+
+            // Roundtrip check
+            let original = std::fs::read(&path).unwrap();
+            assert_eq!(
+                scheme.to_bytes(),
+                original,
+                "roundtrip failed for {}",
+                path.display()
+            );
+            count += 1;
+        }
+    }
+    eprintln!("Successfully parsed and round-tripped {count} scheme files");
+}

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

@@ -1,6 +1,8 @@
 mod frontend;
+mod scheme;
 
 pub fn install_all() -> Result<(), String> {
     frontend::install()?;
+    scheme::install()?;
     Ok(())
 }

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

@@ -0,0 +1,82 @@
+//! Scheme file (.wsc) hook.
+//!
+//! Hooks Scheme__ReadFile (0x4D3890) to log when schemes are loaded.
+//! Currently a passthrough — calls the original and logs the result.
+//! Future: replace the file I/O with our Rust SchemeFile parser.
+
+use std::ffi::c_void;
+use std::sync::atomic::{AtomicU32, Ordering};
+
+use minhook::MinHook;
+
+use crate::log_line;
+use crate::rebase::rb;
+use openwa_types::address::va;
+
+/// Trampoline to original Scheme__ReadFile.
+static ORIG_SCHEME_READ_FILE: AtomicU32 = AtomicU32::new(0);
+
+/// Hook for Scheme__ReadFile (0x4D3890).
+/// stdcall(dest_struct, file_path, flag, out_ptr) -> u32, RET 0x10
+///
+/// - dest_struct: pointer to destination scheme struct (payload written to +0x14)
+/// - file_path: scheme file path string
+/// - flag: boolean flag (passed to error display)
+/// - out_ptr: optional output byte pointer
+/// - returns: 0 on success, 0xFFFFFFFF on failure
+unsafe extern "stdcall" fn hook_scheme_read_file(
+    dest_struct: u32,
+    file_path: u32,
+    flag: u32,
+    out_ptr: u32,
+) -> u32 {
+    // Read the scheme name from the file_path pointer
+    let name = if file_path != 0 {
+        let cstr = std::ffi::CStr::from_ptr(file_path as *const i8);
+        cstr.to_string_lossy().into_owned()
+    } else {
+        "<null>".to_string()
+    };
+
+    // Call original
+    let orig: unsafe extern "stdcall" fn(u32, u32, u32, u32) -> u32 =
+        core::mem::transmute(ORIG_SCHEME_READ_FILE.load(Ordering::Relaxed));
+    let result = orig(dest_struct, file_path, flag, out_ptr);
+
+    // Log the result
+    if result == 0 {
+        // Read the version byte from dest_struct+0x14 (first 5 bytes are the header)
+        // Actually the header is consumed during read; the payload starts at +0x14
+        let _ = log_line(&format!(
+            "[Scheme] Loaded: {name} -> dest=0x{dest_struct:08X}"
+        ));
+    } else {
+        let _ = log_line(&format!(
+            "[Scheme] FAILED to load: {name} (result=0x{result:08X})"
+        ));
+    }
+
+    result
+}
+
+pub fn install() -> Result<(), String> {
+    unsafe {
+        let target = rb(va::SCHEME_READ_FILE) as *mut c_void;
+        let detour = hook_scheme_read_file as *const () as *mut c_void;
+
+        let trampoline = MinHook::create_hook(target, detour)
+            .map_err(|e| format!("MinHook create_hook failed for Scheme__ReadFile: {e}"))?;
+
+        MinHook::enable_hook(target)
+            .map_err(|e| format!("MinHook enable_hook failed for Scheme__ReadFile: {e}"))?;
+
+        ORIG_SCHEME_READ_FILE.store(trampoline as u32, Ordering::Relaxed);
+
+        let _ = log_line(&format!(
+            "  [HOOK] Scheme__ReadFile: target 0x{:08X}, trampoline 0x{:08X}",
+            target as u32, trampoline as u32
+        ));
+    }
+
+    Ok(())
+}