paavohtl Claude Opus 4.6 (1M context) commited on
Commit
123d0d1
·
1 Parent(s): 1b0dae9

feat: add #[derive(FieldRegistry)] proc macro for auto-generated field maps

Browse files

New openwa-derive crate with FieldRegistry proc macro that generates
HasFieldRegistry impls for #[repr(C)] structs. Uses offset_of!() and
size_of() for compiler-verified offsets. Fields prefixed _unknown/_pad
are automatically excluded.

Applied to 5 key structs: DDGame, DDGameWrapper, GameSession, CTask,
CTaskWorm. Each now has a field_registry() -> &'static StructFields
method for runtime offset-to-name lookups.

This lays groundwork for typed vtable derive macros using the same
proc macro infrastructure.

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

Cargo.lock CHANGED
@@ -1477,6 +1477,7 @@ dependencies = [
1477
  "hound",
1478
  "inventory",
1479
  "openwa-debug-proto",
 
1480
  "windows",
1481
  "windows-sys 0.59.0",
1482
  ]
@@ -1505,6 +1506,15 @@ dependencies = [
1505
  "winit",
1506
  ]
1507
 
 
 
 
 
 
 
 
 
 
1508
  [[package]]
1509
  name = "openwa-harness"
1510
  version = "0.1.0"
 
1477
  "hound",
1478
  "inventory",
1479
  "openwa-debug-proto",
1480
+ "openwa-derive",
1481
  "windows",
1482
  "windows-sys 0.59.0",
1483
  ]
 
1506
  "winit",
1507
  ]
1508
 
1509
+ [[package]]
1510
+ name = "openwa-derive"
1511
+ version = "0.1.0"
1512
+ dependencies = [
1513
+ "proc-macro2",
1514
+ "quote",
1515
+ "syn",
1516
+ ]
1517
+
1518
  [[package]]
1519
  name = "openwa-harness"
1520
  version = "0.1.0"
crates/openwa-core/Cargo.toml CHANGED
@@ -8,6 +8,7 @@ description = "Core library for Worms Armageddon reverse engineering — types,
8
  heapless = "0.9"
9
  hound = "3"
10
  inventory = "0.3.22"
 
11
  openwa-debug-proto = { path = "../openwa-debug-proto" }
12
 
13
  [target.'cfg(target_os = "windows")'.dependencies]
 
8
  heapless = "0.9"
9
  hound = "3"
10
  inventory = "0.3.22"
11
+ openwa-derive = { path = "../openwa-derive" }
12
  openwa-debug-proto = { path = "../openwa-debug-proto" }
13
 
14
  [target.'cfg(target_os = "windows")'.dependencies]
crates/openwa-core/src/engine/ddgame.rs CHANGED
@@ -1,5 +1,6 @@
1
  use crate::address::va;
2
  use crate::audio::active_sound::ActiveSoundTable;
 
3
  use crate::audio::dssound::DSSound;
4
  use crate::audio::music::Music;
5
  use crate::audio::speech::SpeechSlotTable;
@@ -37,6 +38,7 @@ use crate::wa_alloc::{wa_malloc, wa_malloc_zeroed};
37
  /// Note on offsets: The constructor accesses DDGame fields via
38
  /// `*(param_2[0x122] + byte_offset)` — these are byte offsets, NOT DWORD-indexed.
39
  /// DWORD indexing only applies to param_2 (DDGameWrapper) itself.
 
40
  #[repr(C)]
41
  pub struct DDGame {
42
  /// 0x000: DDKeyboard pointer (vtable 0x66AEC8). Constructor param "keyboard".
 
1
  use crate::address::va;
2
  use crate::audio::active_sound::ActiveSoundTable;
3
+ use crate::FieldRegistry;
4
  use crate::audio::dssound::DSSound;
5
  use crate::audio::music::Music;
6
  use crate::audio::speech::SpeechSlotTable;
 
38
  /// Note on offsets: The constructor accesses DDGame fields via
39
  /// `*(param_2[0x122] + byte_offset)` — these are byte offsets, NOT DWORD-indexed.
40
  /// DWORD indexing only applies to param_2 (DDGameWrapper) itself.
41
+ #[derive(FieldRegistry)]
42
  #[repr(C)]
43
  pub struct DDGame {
44
  /// 0x000: DDKeyboard pointer (vtable 0x66AEC8). Constructor param "keyboard".
crates/openwa-core/src/engine/ddgame_wrapper.rs CHANGED
@@ -3,6 +3,7 @@ use crate::display::dd_display::DDDisplay;
3
  use crate::engine::ddgame::DDGame;
4
  use crate::engine::net_bridge::NetBridge;
5
  use crate::render::landscape::PCLandscape;
 
6
 
7
  /// Speech name table entry size (0x40 = 64 bytes, null-terminated C string).
8
  pub const SPEECH_NAME_ENTRY_SIZE: usize = 0x40;
@@ -20,6 +21,7 @@ pub const SPEECH_NAME_TABLE_LEN: usize = 360;
20
  /// Byte offset = dword_index * 4.
21
  ///
22
  /// PARTIAL: Only confirmed fields are defined.
 
23
  #[repr(C)]
24
  pub struct DDGameWrapper {
25
  /// 0x000: Vtable pointer (0x66A30C)
 
3
  use crate::engine::ddgame::DDGame;
4
  use crate::engine::net_bridge::NetBridge;
5
  use crate::render::landscape::PCLandscape;
6
+ use crate::FieldRegistry;
7
 
8
  /// Speech name table entry size (0x40 = 64 bytes, null-terminated C string).
9
  pub const SPEECH_NAME_ENTRY_SIZE: usize = 0x40;
 
21
  /// Byte offset = dword_index * 4.
22
  ///
23
  /// PARTIAL: Only confirmed fields are defined.
24
+ #[derive(FieldRegistry)]
25
  #[repr(C)]
26
  pub struct DDGameWrapper {
27
  /// 0x000: Vtable pointer (0x66A30C)
crates/openwa-core/src/engine/game_session.rs CHANGED
@@ -2,6 +2,7 @@ use crate::audio::dssound::DSSound;
2
  use crate::display::palette::Palette;
3
  use crate::engine::ddgame_wrapper::DDGameWrapper;
4
  use crate::input::keyboard::DDKeyboard;
 
5
 
6
  /// Top-level game session context, allocated once per game run.
7
  ///
@@ -22,6 +23,7 @@ use crate::input::keyboard::DDKeyboard;
22
  ///
23
  /// In headless/stats mode (`GameInfo+0xF914 != 0`), `display_gfx` holds a
24
  /// `GameStats` object with a DDInput vtable instead of a real `DisplayGfx`.
 
25
  #[repr(C)]
26
  pub struct GameSession {
27
  /// 0x000: vtable pointer (class `GameSession`, `PTR_FUN_0066b3f8`)
 
2
  use crate::display::palette::Palette;
3
  use crate::engine::ddgame_wrapper::DDGameWrapper;
4
  use crate::input::keyboard::DDKeyboard;
5
+ use crate::FieldRegistry;
6
 
7
  /// Top-level game session context, allocated once per game run.
8
  ///
 
23
  ///
24
  /// In headless/stats mode (`GameInfo+0xF914 != 0`), `display_gfx` holds a
25
  /// `GameStats` object with a DDInput vtable instead of a real `DisplayGfx`.
26
+ #[derive(FieldRegistry)]
27
  #[repr(C)]
28
  pub struct GameSession {
29
  /// 0x000: vtable pointer (class `GameSession`, `PTR_FUN_0066b3f8`)
crates/openwa-core/src/lib.rs CHANGED
@@ -13,10 +13,17 @@
13
  #![allow(clippy::empty_line_after_doc_comments)]
14
  #![allow(clippy::doc_lazy_continuation)]
15
 
 
 
 
 
16
  // Re-export inventory so the define_addresses! macro can reference it
17
  // from any crate that depends on openwa-core.
18
  pub use inventory;
19
 
 
 
 
20
  #[macro_use]
21
  pub mod macros;
22
 
 
13
  #![allow(clippy::empty_line_after_doc_comments)]
14
  #![allow(clippy::doc_lazy_continuation)]
15
 
16
+ // Allow proc macros to reference `openwa_core::registry` even when
17
+ // invoked from within openwa-core itself (where the crate name is `crate`).
18
+ extern crate self as openwa_core;
19
+
20
  // Re-export inventory so the define_addresses! macro can reference it
21
  // from any crate that depends on openwa-core.
22
  pub use inventory;
23
 
24
+ // Re-export derive macros so users write `use openwa_core::FieldRegistry;`
25
+ pub use openwa_derive::FieldRegistry;
26
+
27
  #[macro_use]
28
  pub mod macros;
29
 
crates/openwa-core/src/registry.rs CHANGED
@@ -338,4 +338,77 @@ mod tests {
338
 
339
  assert!(FIELDS.field_containing(0x30).is_none());
340
  }
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
341
  }
 
338
 
339
  assert!(FIELDS.field_containing(0x30).is_none());
340
  }
341
+
342
+ #[test]
343
+ fn derive_field_registry_ctask() {
344
+ use crate::task::CTask;
345
+
346
+ let reg = CTask::field_registry();
347
+ assert_eq!(reg.struct_name, "CTask");
348
+
349
+ // CTask has known fields at known offsets
350
+ let vtable = reg.field_at(0x00).expect("vtable field at 0x00");
351
+ assert_eq!(vtable.name, "vtable");
352
+ assert_eq!(vtable.size, 4);
353
+
354
+ let ddgame = reg.field_at(0x2C).expect("ddgame field at 0x2C");
355
+ assert_eq!(ddgame.name, "ddgame");
356
+
357
+ // _unknown_1c should be skipped
358
+ assert!(
359
+ reg.fields.iter().all(|f| !f.name.starts_with("_unknown")),
360
+ "unknown fields should be excluded"
361
+ );
362
+ }
363
+
364
+ #[test]
365
+ fn derive_field_registry_ddgame() {
366
+ use crate::engine::DDGame;
367
+
368
+ let reg = DDGame::field_registry();
369
+ assert_eq!(reg.struct_name, "DDGame");
370
+
371
+ // DDGame has keyboard at 0x00
372
+ let keyboard = reg.field_at(0x00).expect("keyboard at 0x00");
373
+ assert_eq!(keyboard.name, "keyboard");
374
+
375
+ // game_info at 0x24
376
+ let gi = reg.field_at(0x24).expect("game_info at 0x24");
377
+ assert_eq!(gi.name, "game_info");
378
+
379
+ // Should have many fields (DDGame is huge)
380
+ assert!(
381
+ reg.fields.len() > 20,
382
+ "DDGame should have >20 named fields, got {}",
383
+ reg.fields.len()
384
+ );
385
+
386
+ // No unknown fields
387
+ assert!(
388
+ reg.fields.iter().all(|f| !f.name.starts_with("_unknown")),
389
+ "unknown fields should be excluded"
390
+ );
391
+ }
392
+
393
+ #[test]
394
+ fn derive_field_registry_game_session() {
395
+ use crate::engine::GameSession;
396
+
397
+ let reg = GameSession::field_registry();
398
+ assert_eq!(reg.struct_name, "GameSession");
399
+
400
+ // ddgame_wrapper at 0xA0
401
+ let wrapper = reg.field_at(0xA0).expect("ddgame_wrapper at 0xA0");
402
+ assert_eq!(wrapper.name, "ddgame_wrapper");
403
+ }
404
+
405
+ #[test]
406
+ fn derive_preserves_doc_comments() {
407
+ use crate::task::CTask;
408
+
409
+ let reg = CTask::field_registry();
410
+ let vtable = reg.field_at(0x00).unwrap();
411
+ // Doc comment should be non-empty (we have "0x00: Pointer to virtual method table")
412
+ assert!(!vtable.doc.is_empty(), "doc should be extracted: {:?}", vtable.doc);
413
+ }
414
  }
crates/openwa-core/src/task/base.rs CHANGED
@@ -1,5 +1,6 @@
1
  use crate::engine::ddgame::DDGame;
2
  use crate::game::class_type::ClassType;
 
3
 
4
  /// Base task class in WA's entity hierarchy.
5
  ///
@@ -17,6 +18,7 @@ use crate::game::class_type::ClassType;
17
  /// 0x14: 0x562FA0 unknown
18
  /// 0x18: 0x563000 unknown
19
  /// 0x1C: 0x563210 ProcessFrame
 
20
  #[repr(C)]
21
  pub struct CTask {
22
  /// 0x00: Pointer to virtual method table
 
1
  use crate::engine::ddgame::DDGame;
2
  use crate::game::class_type::ClassType;
3
+ use crate::FieldRegistry;
4
 
5
  /// Base task class in WA's entity hierarchy.
6
  ///
 
18
  /// 0x14: 0x562FA0 unknown
19
  /// 0x18: 0x563000 unknown
20
  /// 0x1C: 0x563210 ProcessFrame
21
+ #[derive(FieldRegistry)]
22
  #[repr(C)]
23
  pub struct CTask {
24
  /// 0x00: Pointer to virtual method table
crates/openwa-core/src/task/worm.rs CHANGED
@@ -1,6 +1,7 @@
1
  use super::base::CTask;
2
  use super::game_task::CGameTask;
3
  use crate::game::weapon::WeaponEntry;
 
4
 
5
  /// Virtual method table for CTaskWorm (vtable at 0x6644C8, 20 slots).
6
  ///
@@ -81,6 +82,7 @@ const _: () = assert!(core::mem::size_of::<CTaskWormVTable>() == 20 * 4);
81
  ///
82
  /// Source: Ghidra decompilation of 0x50BFB0, vtable analysis of 0x6644C8,
83
  /// wkJellyWorm CTaskWorm.h
 
84
  #[repr(C)]
85
  pub struct CTaskWorm {
86
  /// 0x00–0xFB: CGameTask base (position, velocity, sound emitter, etc.)
 
1
  use super::base::CTask;
2
  use super::game_task::CGameTask;
3
  use crate::game::weapon::WeaponEntry;
4
+ use crate::FieldRegistry;
5
 
6
  /// Virtual method table for CTaskWorm (vtable at 0x6644C8, 20 slots).
7
  ///
 
82
  ///
83
  /// Source: Ghidra decompilation of 0x50BFB0, vtable analysis of 0x6644C8,
84
  /// wkJellyWorm CTaskWorm.h
85
+ #[derive(FieldRegistry)]
86
  #[repr(C)]
87
  pub struct CTaskWorm {
88
  /// 0x00–0xFB: CGameTask base (position, velocity, sound emitter, etc.)
crates/openwa-derive/Cargo.toml ADDED
@@ -0,0 +1,13 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ [package]
2
+ name = "openwa-derive"
3
+ version = "0.1.0"
4
+ edition = "2021"
5
+ description = "Proc macros for OpenWA reverse engineering — FieldRegistry, typed vtables"
6
+
7
+ [lib]
8
+ proc-macro = true
9
+
10
+ [dependencies]
11
+ proc-macro2 = "1"
12
+ quote = "1"
13
+ syn = { version = "2", features = ["full", "extra-traits"] }
crates/openwa-derive/src/lib.rs ADDED
@@ -0,0 +1,129 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ //! Proc macros for OpenWA reverse engineering.
2
+ //!
3
+ //! ## `#[derive(FieldRegistry)]`
4
+ //!
5
+ //! Generates a `HasFieldRegistry` impl for `#[repr(C)]` structs, producing
6
+ //! a sorted `StructFields` table from the struct's field names, offsets,
7
+ //! sizes, and doc comments. Fields prefixed with `_unknown` or `_pad` are
8
+ //! excluded (they represent unmapped regions).
9
+ //!
10
+ //! ```ignore
11
+ //! #[derive(FieldRegistry)]
12
+ //! #[repr(C)]
13
+ //! pub struct DDGame {
14
+ //! /// DDKeyboard pointer
15
+ //! pub keyboard: *mut DDKeyboard,
16
+ //! pub _unknown_04: [u8; 4],
17
+ //! /// Game PRNG state
18
+ //! pub rng_state: u32,
19
+ //! }
20
+ //! // Generates: DDGame::field_registry() -> &'static StructFields
21
+ //! // with entries for "keyboard" and "rng_state" (skips _unknown_04)
22
+ //! ```
23
+
24
+ use proc_macro::TokenStream;
25
+ use quote::quote;
26
+ use syn::{parse_macro_input, Data, DeriveInput, Fields, Lit, Meta};
27
+
28
+ /// Derive `HasFieldRegistry` for a `#[repr(C)]` struct.
29
+ ///
30
+ /// Generates a static `StructFields` table with one `FieldEntry` per named
31
+ /// field (excluding `_unknown*` and `_pad*` prefixes). Offsets and sizes
32
+ /// are computed at compile time via `core::mem::offset_of!()` and
33
+ /// `core::mem::size_of::<Type>()`.
34
+ #[proc_macro_derive(FieldRegistry)]
35
+ pub fn derive_field_registry(input: TokenStream) -> TokenStream {
36
+ let input = parse_macro_input!(input as DeriveInput);
37
+ let struct_name = &input.ident;
38
+ let struct_name_str = struct_name.to_string();
39
+
40
+ let fields = match &input.data {
41
+ Data::Struct(data) => match &data.fields {
42
+ Fields::Named(named) => &named.named,
43
+ _ => {
44
+ return syn::Error::new_spanned(struct_name, "FieldRegistry requires named fields")
45
+ .to_compile_error()
46
+ .into();
47
+ }
48
+ },
49
+ _ => {
50
+ return syn::Error::new_spanned(struct_name, "FieldRegistry can only be used on structs")
51
+ .to_compile_error()
52
+ .into();
53
+ }
54
+ };
55
+
56
+ // Collect field entries, skipping _unknown* and _pad* fields
57
+ let mut entries = Vec::new();
58
+ for field in fields {
59
+ let field_ident = match &field.ident {
60
+ Some(id) => id,
61
+ None => continue,
62
+ };
63
+ let field_name = field_ident.to_string();
64
+
65
+ // Skip unknown/padding fields
66
+ if field_name.starts_with("_unknown") || field_name.starts_with("_pad") {
67
+ continue;
68
+ }
69
+
70
+ // Extract doc comment from attributes
71
+ let doc = extract_doc_comment(&field.attrs);
72
+ let field_ty = &field.ty;
73
+
74
+ entries.push(quote! {
75
+ openwa_core::registry::FieldEntry {
76
+ offset: core::mem::offset_of!(#struct_name, #field_ident) as u32,
77
+ name: #field_name,
78
+ size: core::mem::size_of::<#field_ty>() as u32,
79
+ doc: #doc,
80
+ }
81
+ });
82
+ }
83
+
84
+ let entry_count = entries.len();
85
+
86
+ let expanded = quote! {
87
+ impl openwa_core::registry::HasFieldRegistry for #struct_name {
88
+ fn field_registry() -> &'static openwa_core::registry::StructFields {
89
+ // Sort entries by offset at runtime on first access.
90
+ // We can't sort a const array, but the fields are defined in
91
+ // declaration order which matches memory order for #[repr(C)].
92
+ static FIELDS: openwa_core::registry::StructFields = openwa_core::registry::StructFields {
93
+ struct_name: #struct_name_str,
94
+ fields: {
95
+ const ENTRIES: [openwa_core::registry::FieldEntry; #entry_count] = [
96
+ #(#entries),*
97
+ ];
98
+ &ENTRIES
99
+ },
100
+ };
101
+ &FIELDS
102
+ }
103
+ }
104
+ };
105
+
106
+ expanded.into()
107
+ }
108
+
109
+ /// Extract the concatenated doc comment from a field's attributes.
110
+ fn extract_doc_comment(attrs: &[syn::Attribute]) -> String {
111
+ let mut doc = String::new();
112
+ for attr in attrs {
113
+ if let Meta::NameValue(nv) = &attr.meta {
114
+ if nv.path.is_ident("doc") {
115
+ if let syn::Expr::Lit(expr_lit) = &nv.value {
116
+ if let Lit::Str(s) = &expr_lit.lit {
117
+ let text = s.value();
118
+ let trimmed = text.trim();
119
+ if !doc.is_empty() && !trimmed.is_empty() {
120
+ doc.push(' ');
121
+ }
122
+ doc.push_str(trimmed);
123
+ }
124
+ }
125
+ }
126
+ }
127
+ }
128
+ doc
129
+ }