diff options
| -rw-r--r-- | crates/fparkan-script/src/lib.rs | 213 | ||||
| -rw-r--r-- | docs/appendices/script-vm.md | 32 | ||||
| -rw-r--r-- | tools/capture-ai-init.ps1 | 91 | ||||
| -rw-r--r-- | tools/ghidra/ExportAiGetSuperAi.java | 23 | ||||
| -rw-r--r-- | tools/ghidra/ExportAiVmHandler19.java | 23 | ||||
| -rw-r--r-- | tools/ghidra/ExportAiVmHandler19Setter.java | 23 | ||||
| -rw-r--r-- | tools/ghidra/ExportAiVmHandler19SetterCallee.java | 23 |
7 files changed, 425 insertions, 3 deletions
diff --git a/crates/fparkan-script/src/lib.rs b/crates/fparkan-script/src/lib.rs index 2f8b703..9acbcb7 100644 --- a/crates/fparkan-script/src/lib.rs +++ b/crates/fparkan-script/src/lib.rs @@ -143,6 +143,77 @@ pub struct Handler8StateChange { pub reset: Handler8Reset, } +/// One raw DWORD write made by the corpus-proven `Handler(19)` Init path. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub struct Handler19DwordWrite { + /// Compiled varset record index selected by the instruction reference. + pub index: u32, + /// Exact 32-bit payload passed to the original common varset setter. + pub value: u32, +} + +/// Inputs already expressed at the original `Handler(19)` setter ABI boundary. +/// +/// The first two words are results of original x87 `__ftol` calls. Keeping +/// them as words prevents this package from silently substituting Rust's float +/// conversion policy before captured x87 vectors are available. +#[derive(Clone, Copy, Debug, Eq, PartialEq)] +pub struct Handler19InitInput { + /// x87-converted value from VM field `+0x80`. + pub first_x87_word: u32, + /// x87-converted value from VM field `+0x84`. + pub second_x87_word: u32, + /// Raw word from VM field `+0x7c`. + pub third_word: u32, +} + +/// Error resolving the three-target `Handler(19)` Init contract. +#[derive(Clone, Debug, Eq, PartialEq)] +pub enum Handler19ResolveError { + /// One of the three required references was absent. + MissingReference { + /// Zero-based required target position. + position: usize, + }, + /// A compiled reference indexed outside the loaded varset. + VarSetIndexOutOfBounds { + /// Referenced compiled-varset index. + index: u32, + /// Available declaration count. + declarations: usize, + }, + /// The `AutoDemo` Init target was not a `DWORD` declaration. + UnexpectedType { + /// Zero-based target position. + position: usize, + /// Observed declaration type. + found: VarSetType, + }, +} + +impl std::fmt::Display for Handler19ResolveError { + fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Self::MissingReference { position } => { + write!(formatter, "Handler(19) is missing reference {position}") + } + Self::VarSetIndexOutOfBounds { + index, + declarations, + } => write!( + formatter, + "Handler(19) reference {index} is outside {declarations} varset declarations" + ), + Self::UnexpectedType { position, found } => write!( + formatter, + "Handler(19) reference {position} has {found:?}, expected Dword" + ), + } + } +} + +impl std::error::Error for Handler19ResolveError {} + /// Error resolving the one-operand `Handler(8)` contract. #[derive(Clone, Debug, Eq, PartialEq)] pub enum Handler8ResolveError { @@ -391,6 +462,68 @@ impl VarSet { }) } + /// Resolves the three DWORD targets written by GOG `Handler(19)`. + /// + /// The caller supplies values at the original setter ABI boundary: the + /// first two are already x87-converted `__ftol` results and the third is + /// the raw VM word. This preserves the exact default-script Init path + /// without claiming an unrecovered portable x87 policy. + /// + /// # Errors + /// + /// Returns a typed failure for missing/out-of-range targets or a target + /// type that differs from the observed `AutoDemo` `DWORD` contract. + pub fn resolve_handler19( + &self, + instruction: &ScriptInstruction, + input: Handler19InitInput, + ) -> Result<[Handler19DwordWrite; 3], Handler19ResolveError> { + let targets = [ + self.resolve_handler19_target(instruction, 0)?, + self.resolve_handler19_target(instruction, 1)?, + self.resolve_handler19_target(instruction, 2)?, + ]; + Ok([ + Handler19DwordWrite { + index: targets[0], + value: input.first_x87_word, + }, + Handler19DwordWrite { + index: targets[1], + value: input.second_x87_word, + }, + Handler19DwordWrite { + index: targets[2], + value: input.third_word, + }, + ]) + } + + fn resolve_handler19_target( + &self, + instruction: &ScriptInstruction, + position: usize, + ) -> Result<u32, Handler19ResolveError> { + let index = *instruction + .references + .get(position) + .ok_or(Handler19ResolveError::MissingReference { position })?; + match self.declarations.get(index as usize) { + Some(VarSetDeclaration { + type_name: VarSetType::Dword, + .. + }) => Ok(index), + Some(declaration) => Err(Handler19ResolveError::UnexpectedType { + position, + found: declaration.type_name, + }), + None => Err(Handler19ResolveError::VarSetIndexOutOfBounds { + index, + declarations: self.declarations.len(), + }), + } + } + /// Resolves the fixed-width, corpus-proven operands of GOG `Handler(15)`. /// /// Static analysis of `ai.dll` at `0x10008054` shows four DWORD slots, @@ -1033,9 +1166,10 @@ fn read_instruction( mod tests { use super::{ decode, decode_with_limits, parse_varset, Handler15ResolveError, Handler15TargetPayload, - Handler2RecordInput, Handler2RecordScheduler, Handler30ResolveError, Handler8Reset, - Handler8ResolveError, ScriptDispatchSelector, ScriptInstruction, VarSetDefault, - VarSetError, VarSetType, VmHostCallbackCommand, GOG_HANDLER_COUNT, INSTRUCTION_WORDS, + Handler19DwordWrite, Handler19InitInput, Handler19ResolveError, Handler2RecordInput, + Handler2RecordScheduler, Handler30ResolveError, Handler8Reset, Handler8ResolveError, + ScriptDispatchSelector, ScriptInstruction, VarSetDefault, VarSetError, VarSetType, + VmHostCallbackCommand, GOG_HANDLER_COUNT, INSTRUCTION_WORDS, }; use fparkan_binary::{DecodeError, Limits}; @@ -1290,6 +1424,79 @@ STRING( 8, ignored, ignored, ignored)\r\n"; } #[test] + fn handler_nineteen_writes_exact_default_init_dwords_without_float_coercion() { + let varset = parse_varset( + b"VAR( DWORD, ClanBaseX, 950)\nVAR( DWORD, ClanBaseY, 1000)\nVAR( DWORD, ClanID, 0)\n", + ) + .expect("default Init targets"); + let writes = varset + .resolve_handler19( + &ScriptInstruction { + header_words: [19, 0, 0, 0, 0, 3, 0], + references: vec![0, 1, 2], + }, + Handler19InitInput { + first_x87_word: 500, + second_x87_word: 752, + third_word: 0, + }, + ) + .expect("resolved Init writes"); + assert_eq!( + writes, + [ + Handler19DwordWrite { + index: 0, + value: 500 + }, + Handler19DwordWrite { + index: 1, + value: 752 + }, + Handler19DwordWrite { index: 2, value: 0 }, + ] + ); + } + + #[test] + fn handler_nineteen_keeps_target_errors_explicit() { + let float = parse_varset(b"VAR( float, f0, 1.0)\n").expect("float target"); + let instruction = ScriptInstruction { + header_words: [19, 0, 0, 0, 0, 1, 0], + references: vec![0], + }; + assert_eq!( + float.resolve_handler19( + &instruction, + Handler19InitInput { + first_x87_word: 0, + second_x87_word: 0, + third_word: 0, + }, + ), + Err(Handler19ResolveError::UnexpectedType { + position: 0, + found: VarSetType::Float, + }) + ); + let empty = parse_varset(b"").expect("empty varset"); + assert_eq!( + empty.resolve_handler19( + &ScriptInstruction { + header_words: [19, 0, 0, 0, 0, 0, 0], + references: Vec::new(), + }, + Handler19InitInput { + first_x87_word: 0, + second_x87_word: 0, + third_word: 0, + }, + ), + Err(Handler19ResolveError::MissingReference { position: 0 }) + ); + } + + #[test] fn handler_fifteen_resolves_exact_typed_target_by_place_operands() { let varset = parse_varset( b"VAR( DWORD, d0, 1)\nVAR( DWORD, d1, 2)\nVAR( DWORD, d2, 3)\nVAR( DWORD, d3, 4)\nVAR( float, f4, 1.5)\nVAR( float, f5, 2.5)\nVAR( float, f6, 3.5)\nVAR( float, f7, 4.5)\nVAR( DWORD, mode, 0x0202)\nVAR( DWORD, place0, 12)\nVAR( DWORD, place1, 13)\n", diff --git a/docs/appendices/script-vm.md b/docs/appendices/script-vm.md index 54d4e9f..3902dfe 100644 --- a/docs/appendices/script-vm.md +++ b/docs/appendices/script-vm.md @@ -173,6 +173,38 @@ layout prerequisites/modifiers/unlocks. Formula evaluator требует strict grammar/version, typed operands, deterministic numeric policy, bounded stack и явных errors; x87-compatible rounding нужен там, где оно выбирает ветку. +### Handler(19): AutoDemo Init varset initialization + +`Handler(19)` is the twentieth VM-table entry at GOG `ai.dll` VA `0x1000aa38`. +It is the only instruction in the `Init` event of the two `default.scr` bundles +referenced by `MISSIONS\\Autodemo.00\\data.tma`; together those bundles account for +the observed 18 named script events. Each instruction references varset records +`224`, `225`, and `226`: `ClanBaseX`, `ClanBaseY`, and `ClanID` respectively. + +The original writes three raw DWORD values in order. It converts the VM fields +at `+0x80` and `+0x84` through the x87 `__ftol` helper and stores the resulting +words into references 0 and 1. It copies the raw word from `+0x7c` into reference +2, then clears VM field `+0x50`. The default targets are `DWORD` records; the +shared setter preserves the incoming word for that type. Therefore this is not +a license to replace the first two conversions with Rust float casts: their +rounding behavior remains an x87 compatibility boundary until it has captured +test vectors. + +`GetSuperAI` returns element `n` of the 64-pointer global table at preferred +`ai.dll + 0x55398` for `n <= 63`. The read-only +`tools/capture-ai-init.ps1` probe observed the running GOG AutoDemo values +`(500, 752, 0)` for entry 0 and `(728, 449, 1)` for entry 1 at fields +`(+0x80, +0x84, +0x7c)`. These values are integral samples, not a rounding +profile. + +The Rust reader exposes `VarSet::resolve_handler19`. It accepts the already +converted first two words and the third raw word, produces three typed writes, +and rejects missing, out-of-range, or non-`DWORD` targets. It deliberately does +not guess how the mission creates the three source fields or execute a script +event yet. The associated Ghidra scripts are +`ExportAiVmHandler19.java`, `ExportAiVmHandler19Setter.java`, +`ExportAiVmHandler19SetterCallee.java`, and `ExportAiGetSuperAi.java`. + ### Handler(8): problem-record state write `Handler(8)` is the ninth VM-table entry at GOG `ai.dll` VA `0x10009b0d`. diff --git a/tools/capture-ai-init.ps1 b/tools/capture-ai-init.ps1 new file mode 100644 index 0000000..0c39b5e --- /dev/null +++ b/tools/capture-ai-init.ps1 @@ -0,0 +1,91 @@ +[CmdletBinding()] +param([Parameter(Mandatory = $true)][int]$ProcessId) + +Set-StrictMode -Version Latest +$ErrorActionPreference = 'Stop' + +# Read-only observer for ai.dll's `GetSuperAI` singleton array. It never sends +# input, writes memory, suspends, injects, or calls into the original process. +Add-Type -TypeDefinition @' +using System; +using System.Runtime.InteropServices; +public static class FparkanAiInitCapture { + public const uint TH32CS_SNAPMODULE = 0x00000008; + public const uint TH32CS_SNAPMODULE32 = 0x00000010; + public const uint PROCESS_QUERY_INFORMATION = 0x00000400; + public const uint PROCESS_VM_READ = 0x00000010; + [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)] + public struct MODULEENTRY32 { + public uint dwSize, th32ModuleID, th32ProcessID, GlblcntUsage, ProccntUsage; + public IntPtr modBaseAddr; + public uint modBaseSize; + public IntPtr hModule; + [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)] public string szModule; + [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 260)] public string szExePath; + } + [DllImport("kernel32.dll", SetLastError = true)] + public static extern IntPtr CreateToolhelp32Snapshot(uint flags, uint processId); + [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)] + public static extern bool Module32First(IntPtr snapshot, ref MODULEENTRY32 entry); + [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)] + public static extern bool Module32Next(IntPtr snapshot, ref MODULEENTRY32 entry); + [DllImport("kernel32.dll", SetLastError = true)] + public static extern IntPtr OpenProcess(uint access, bool inheritHandle, uint processId); + [DllImport("kernel32.dll", SetLastError = true)] + public static extern bool ReadProcessMemory(IntPtr process, IntPtr address, + [Out] byte[] buffer, IntPtr size, out IntPtr bytesRead); + [DllImport("kernel32.dll", SetLastError = true)] + public static extern bool CloseHandle(IntPtr handle); +} +'@ + +function Read-Bytes([IntPtr]$Process, [Int64]$Address, [int]$Length) { + $bytes = [byte[]]::new($Length); $read = [IntPtr]::Zero + if (-not [FparkanAiInitCapture]::ReadProcessMemory($Process, [IntPtr]$Address, + $bytes, [IntPtr]$Length, [ref]$read) -or $read.ToInt64() -ne $Length) { + throw "ReadProcessMemory failed at 0x$('{0:X8}' -f $Address)" + } + $bytes +} + +$snapshot = [FparkanAiInitCapture]::CreateToolhelp32Snapshot( + [FparkanAiInitCapture]::TH32CS_SNAPMODULE -bor [FparkanAiInitCapture]::TH32CS_SNAPMODULE32, + [uint32]$ProcessId) +$aiBase = $null +try { + $entry = [FparkanAiInitCapture+MODULEENTRY32]::new() + $entry.dwSize = [Runtime.InteropServices.Marshal]::SizeOf([type][FparkanAiInitCapture+MODULEENTRY32]) + if ([FparkanAiInitCapture]::Module32First($snapshot, [ref]$entry)) { + do { + if ($entry.szModule -ieq 'ai.dll') { $aiBase = $entry.modBaseAddr.ToInt64(); break } + $entry = [FparkanAiInitCapture+MODULEENTRY32]::new() + $entry.dwSize = [Runtime.InteropServices.Marshal]::SizeOf([type][FparkanAiInitCapture+MODULEENTRY32]) + } while ([FparkanAiInitCapture]::Module32Next($snapshot, [ref]$entry)) + } +} finally { [void][FparkanAiInitCapture]::CloseHandle($snapshot) } +if ($null -eq $aiBase) { throw "ai.dll is not loaded by process $ProcessId" } + +$process = [FparkanAiInitCapture]::OpenProcess( + [FparkanAiInitCapture]::PROCESS_QUERY_INFORMATION -bor [FparkanAiInitCapture]::PROCESS_VM_READ, + $false, [uint32]$ProcessId) +if ($process -eq [IntPtr]::Zero) { throw "OpenProcess read-only failed" } +try { + # GetSuperAI(i) returns (&DAT_10055398)[i], with ai.dll preferred base 0x10000000. + $entries = Read-Bytes $process ($aiBase + 0x55398) (64 * 4) + $samples = for ($index = 0; $index -lt 64; $index++) { + $pointer = [BitConverter]::ToUInt32($entries, $index * 4) + if ($pointer -le 0x10000) { continue } + try { + $fields = Read-Bytes $process ([int64]$pointer) 0x88 + [ordered]@{ + index = $index + super_ai = ('0x{0:X8}' -f $pointer) + word_7c = [BitConverter]::ToUInt32($fields, 0x7c) + float_80 = [BitConverter]::ToSingle($fields, 0x80) + float_84 = [BitConverter]::ToSingle($fields, 0x84) + } + } catch { } + } + [ordered]@{ schema = 'fparkan-ai-init-v1'; process_id = $ProcessId; ai_module_base = ('0x{0:X8}' -f $aiBase); entries = @($samples) } | + ConvertTo-Json -Depth 4 -Compress +} finally { [void][FparkanAiInitCapture]::CloseHandle($process) } diff --git a/tools/ghidra/ExportAiGetSuperAi.java b/tools/ghidra/ExportAiGetSuperAi.java new file mode 100644 index 0000000..27ea107 --- /dev/null +++ b/tools/ghidra/ExportAiGetSuperAi.java @@ -0,0 +1,23 @@ +// Emits the GOG ai.dll GetSuperAI export to recover the live singleton +// boundary for read-only handler-input capture. +import ghidra.app.decompiler.DecompInterface; +import ghidra.app.script.GhidraScript; +import ghidra.program.model.address.Address; +import ghidra.program.model.listing.Function; + +public class ExportAiGetSuperAi extends GhidraScript { + private static final long ADDRESS = 0x1000f780L; + + @Override + public void run() throws Exception { + Address address = currentProgram.getAddressFactory().getDefaultAddressSpace() + .getAddress(ADDRESS); + Function function = currentProgram.getFunctionManager().getFunctionAt(address); + println("===== AI GetSuperAI ====="); + if (function == null) { println("missing"); return; } + DecompInterface decompiler = new DecompInterface(); + decompiler.openProgram(currentProgram); + println(decompiler.decompileFunction(function, 60, monitor).getDecompiledFunction().getC()); + decompiler.dispose(); + } +} diff --git a/tools/ghidra/ExportAiVmHandler19.java b/tools/ghidra/ExportAiVmHandler19.java new file mode 100644 index 0000000..8729999 --- /dev/null +++ b/tools/ghidra/ExportAiVmHandler19.java @@ -0,0 +1,23 @@ +// Emits Handler(19), the first instruction in both AutoDemo default-script +// Init events. Run headless; the original PE remains read only. +import ghidra.app.decompiler.DecompInterface; +import ghidra.app.script.GhidraScript; +import ghidra.program.model.address.Address; +import ghidra.program.model.listing.Function; + +public class ExportAiVmHandler19 extends GhidraScript { + private static final long ADDRESS = 0x1000aa38L; + + @Override + public void run() throws Exception { + Address address = currentProgram.getAddressFactory().getDefaultAddressSpace() + .getAddress(ADDRESS); + Function function = currentProgram.getFunctionManager().getFunctionAt(address); + println("===== AI VM Handler(19) ====="); + if (function == null) { println("missing"); return; } + DecompInterface decompiler = new DecompInterface(); + decompiler.openProgram(currentProgram); + println(decompiler.decompileFunction(function, 60, monitor).getDecompiledFunction().getC()); + decompiler.dispose(); + } +} diff --git a/tools/ghidra/ExportAiVmHandler19Setter.java b/tools/ghidra/ExportAiVmHandler19Setter.java new file mode 100644 index 0000000..2aa1ce0 --- /dev/null +++ b/tools/ghidra/ExportAiVmHandler19Setter.java @@ -0,0 +1,23 @@ +// Emits Handler(19)'s common x87 varset setter. Run headless; the original PE +// remains read only. +import ghidra.app.decompiler.DecompInterface; +import ghidra.app.script.GhidraScript; +import ghidra.program.model.address.Address; +import ghidra.program.model.listing.Function; + +public class ExportAiVmHandler19Setter extends GhidraScript { + private static final long ADDRESS = 0x10013770L; + + @Override + public void run() throws Exception { + Address address = currentProgram.getAddressFactory().getDefaultAddressSpace() + .getAddress(ADDRESS); + Function function = currentProgram.getFunctionManager().getFunctionAt(address); + println("===== AI VM Handler(19) setter ====="); + if (function == null) { println("missing"); return; } + DecompInterface decompiler = new DecompInterface(); + decompiler.openProgram(currentProgram); + println(decompiler.decompileFunction(function, 60, monitor).getDecompiledFunction().getC()); + decompiler.dispose(); + } +} diff --git a/tools/ghidra/ExportAiVmHandler19SetterCallee.java b/tools/ghidra/ExportAiVmHandler19SetterCallee.java new file mode 100644 index 0000000..92cf7d5 --- /dev/null +++ b/tools/ghidra/ExportAiVmHandler19SetterCallee.java @@ -0,0 +1,23 @@ +// Emits the common varset storage helper reached by Handler(19)'s setter. +// Run headless; the original PE remains read only. +import ghidra.app.decompiler.DecompInterface; +import ghidra.app.script.GhidraScript; +import ghidra.program.model.address.Address; +import ghidra.program.model.listing.Function; + +public class ExportAiVmHandler19SetterCallee extends GhidraScript { + private static final long ADDRESS = 0x10012fe0L; + + @Override + public void run() throws Exception { + Address address = currentProgram.getAddressFactory().getDefaultAddressSpace() + .getAddress(ADDRESS); + Function function = currentProgram.getFunctionManager().getFunctionAt(address); + println("===== AI VM Handler(19) setter storage helper ====="); + if (function == null) { println("missing"); return; } + DecompInterface decompiler = new DecompInterface(); + decompiler.openProgram(currentProgram); + println(decompiler.decompileFunction(function, 60, monitor).getDecompiledFunction().getC()); + decompiler.dispose(); + } +} |