aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--crates/fparkan-assets/src/lib.rs332
-rw-r--r--crates/fparkan-runtime/tests/behavior_distributor_tick_native_oracle.cs96
-rw-r--r--docs/appendices/knowledge-boundaries.md56
-rw-r--r--docs/tomes/03-resources.md29
-rw-r--r--docs/tomes/06-behavior.md153
5 files changed, 642 insertions, 24 deletions
diff --git a/crates/fparkan-assets/src/lib.rs b/crates/fparkan-assets/src/lib.rs
index d34effb..da3411e 100644
--- a/crates/fparkan-assets/src/lib.rs
+++ b/crates/fparkan-assets/src/lib.rs
@@ -1180,6 +1180,19 @@ impl Default for ControlTag21InstanceState {
/// Input or metadata prevented a safe native control sample.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum ControlSamplingError {
+ /// This resource-device helper only implements typed-record tag 26.
+ UnsupportedResourceDeviceTag { actual: u32 },
+ /// The record's raw provider key has no resolved NDP table.
+ MissingResourceDeviceNodeData { key: u32 },
+ /// The record's raw provider key is not a row in its NDP table.
+ ResourceDeviceNodeDataKeyOutOfRange { key: u32, row_count: usize },
+ /// The caller did not supply the provider's current type-1 value.
+ MissingResourceDeviceProviderValue { key: u32 },
+ /// A coefficient is outside the helper's finite normal-or-zero contract.
+ InvalidResourceDeviceOperand { operand: &'static str },
+ /// The native x87 intermediate is outside the range represented by normal
+ /// f32 values, so the Rust result could differ from the original.
+ UnsupportedResourceDeviceFloatRange { stage: &'static str },
/// A state object was reused with a different model node count.
StateNodeCountMismatch { expected: usize, actual: usize },
/// A state object was reused with a different number of tag-21 records.
@@ -1216,6 +1229,74 @@ pub enum ControlSamplingError {
NonFiniteSample { record_index: usize },
}
+/// Samples Control's tag-26 typed-record query `0x300` for one current state.
+///
+/// The key in fixed word 1 must select an existing NDP row. The caller supplies
+/// that provider's current type-1 value and the object's current multiplier;
+/// this function does not invent their runtime state. Fixed word 11 is the
+/// coefficient loaded by selector `0x300`. Native code multiplies in the order
+/// `provider_now * coefficient * multiplier_now`.
+///
+/// The source x87 code returns a value with an extended exponent range even
+/// though it uses 24-bit precision. This f32 helper therefore accepts only
+/// finite normal-or-zero operands and normal-or-exact-zero intermediate and
+/// final products. It rejects subnormal or out-of-f32-range products rather
+/// than silently underflowing or overflowing differently from x87.
+pub fn sample_control_resource_device_selector_300(
+ record: &PreparedControlTypedRecord,
+ node_data: Option<&PreparedControlNodeDataTable>,
+ provider_now: Option<f32>,
+ multiplier_now: f32,
+) -> Result<f32, ControlSamplingError> {
+ if record.tag != 26 {
+ return Err(ControlSamplingError::UnsupportedResourceDeviceTag { actual: record.tag });
+ }
+
+ let key = record.fixed_words[1];
+ let Some(node_data) = node_data else {
+ return Err(ControlSamplingError::MissingResourceDeviceNodeData { key });
+ };
+ if !usize::try_from(key).is_ok_and(|key| key < node_data.rows.len()) {
+ return Err(ControlSamplingError::ResourceDeviceNodeDataKeyOutOfRange {
+ key,
+ row_count: node_data.rows.len(),
+ });
+ }
+ let provider_now =
+ provider_now.ok_or(ControlSamplingError::MissingResourceDeviceProviderValue { key })?;
+ let base = f32::from_bits(record.fixed_words[11]);
+
+ for (operand, value) in [
+ ("provider", provider_now),
+ ("base coefficient", base),
+ ("multiplier", multiplier_now),
+ ] {
+ if !value.is_finite() || (value != 0.0 && !value.is_normal()) {
+ return Err(ControlSamplingError::InvalidResourceDeviceOperand { operand });
+ }
+ }
+
+ let provider_times_base =
+ native_range_compatible_product(provider_now, base, "provider times base")?;
+ native_range_compatible_product(provider_times_base, multiplier_now, "then multiplier")
+}
+
+fn native_range_compatible_product(
+ lhs: f32,
+ rhs: f32,
+ stage: &'static str,
+) -> Result<f32, ControlSamplingError> {
+ let exact = f64::from(lhs) * f64::from(rhs);
+ let absolute = exact.abs();
+ let minimum_normal = f64::from(f32::MIN_POSITIVE);
+ let maximum = f64::from(f32::MAX);
+ if exact != 0.0 && (absolute < minimum_normal || absolute > maximum) {
+ return Err(ControlSamplingError::UnsupportedResourceDeviceFloatRange { stage });
+ }
+
+ Ok(lhs * rhs)
+}
+
/// Samples per-node animation times using the decoded Control timeline.
///
/// `native_clock_ms` is the absolute u32 millisecond clock passed to native
@@ -4141,6 +4222,203 @@ mod tests {
// Preserve the authored CTLD fixture bits; this is not the `f32` value of tau.
const AUTHORED_TAG21_RAW_PARAMETER_3: f32 = f32::from_bits(0x40C8_F5C3);
+ fn resource_device_record(tag: u32, key: u32, base_bits: u32) -> PreparedControlTypedRecord {
+ let mut fixed_words = [0; 44];
+ fixed_words[1] = key;
+ fixed_words[11] = base_bits;
+ PreparedControlTypedRecord {
+ tag,
+ fixed_words,
+ values: Vec::new(),
+ string_bytes: Vec::new(),
+ gate_provider: PreparedControlGateProvider::NotApplicable,
+ }
+ }
+
+ fn resource_device_node_data_table(row_count: usize) -> PreparedControlNodeDataTable {
+ PreparedControlNodeDataTable {
+ source: ResourceKey {
+ archive: parse_path("parts.rlb").expect("NDP archive"),
+ name: resource_name(b"resource-device.ndp"),
+ type_id: None,
+ },
+ rows: vec![
+ PreparedControlNodeDataRow {
+ raw_flags: 0,
+ max_volume: 0.0,
+ mobility_per_volume: 0.0,
+ effect: PreparedControlResourcePair {
+ archive: [0; 32],
+ name: [0; 32],
+ },
+ };
+ row_count
+ ],
+ }
+ }
+
+ #[test]
+ fn tag26_selector_300_multiplies_provider_then_fixed_base_then_multiplier() {
+ let record = resource_device_record(26, 1, 0x3D25_AE4A);
+ let node_data = resource_device_node_data_table(2);
+ let provider_now = f32::from_bits(0x3FE6_982F);
+ let multiplier_now = f32::from_bits(0x4071_5539);
+
+ let sampled = sample_control_resource_device_selector_300(
+ &record,
+ Some(&node_data),
+ Some(provider_now),
+ multiplier_now,
+ )
+ .expect("valid tag-26 resource-device sample");
+
+ assert_eq!(sampled.to_bits(), 0x3E8C_B02E);
+ assert_ne!(
+ sampled.to_bits(),
+ ((provider_now * multiplier_now) * f32::from_bits(record.fixed_words[11])).to_bits(),
+ "the original selector multiplies the provider by the record base first"
+ );
+ }
+
+ #[test]
+ fn tag26_selector_300_requires_its_ndp_row_and_explicit_provider() {
+ let record = resource_device_record(26, 1, 2.0_f32.to_bits());
+ let one_row = resource_device_node_data_table(1);
+ assert_eq!(
+ sample_control_resource_device_selector_300(&record, Some(&one_row), Some(3.0), 4.0,),
+ Err(ControlSamplingError::ResourceDeviceNodeDataKeyOutOfRange {
+ key: 1,
+ row_count: 1,
+ })
+ );
+
+ let two_rows = resource_device_node_data_table(2);
+ assert_eq!(
+ sample_control_resource_device_selector_300(&record, Some(&two_rows), None, 4.0),
+ Err(ControlSamplingError::MissingResourceDeviceProviderValue { key: 1 })
+ );
+ assert_eq!(
+ sample_control_resource_device_selector_300(&record, None, Some(3.0), 4.0),
+ Err(ControlSamplingError::MissingResourceDeviceNodeData { key: 1 })
+ );
+ }
+
+ #[test]
+ fn tag26_selector_300_rejects_other_tags_and_extended_x87_ranges() {
+ let node_data = resource_device_node_data_table(1);
+ let tag21 = resource_device_record(21, 0, 1.0_f32.to_bits());
+ assert_eq!(
+ sample_control_resource_device_selector_300(&tag21, Some(&node_data), Some(1.0), 1.0),
+ Err(ControlSamplingError::UnsupportedResourceDeviceTag { actual: 21 })
+ );
+
+ let tag26 = resource_device_record(26, 0, f32::MIN_POSITIVE.to_bits());
+ assert_eq!(
+ sample_control_resource_device_selector_300(
+ &tag26,
+ Some(&node_data),
+ Some(f32::MIN_POSITIVE),
+ 1.0,
+ ),
+ Err(ControlSamplingError::UnsupportedResourceDeviceFloatRange {
+ stage: "provider times base",
+ })
+ );
+ }
+
+ #[test]
+ fn tag26_selector_300_preserves_negative_and_signed_zero_values() {
+ let node_data = resource_device_node_data_table(1);
+ let record = resource_device_record(26, 0, 0.5_f32.to_bits());
+ let negative =
+ sample_control_resource_device_selector_300(&record, Some(&node_data), Some(-2.0), 4.0)
+ .expect("negative factors are not clamped");
+ assert_eq!(negative, -4.0);
+
+ let negative_zero = sample_control_resource_device_selector_300(
+ &resource_device_record(26, 0, 2.0_f32.to_bits()),
+ Some(&node_data),
+ Some(-0.0),
+ 3.0,
+ )
+ .expect("signed zero is an exact native input");
+ assert_eq!(negative_zero.to_bits(), (-0.0_f32).to_bits());
+
+ let positive_zero = sample_control_resource_device_selector_300(
+ &resource_device_record(26, 0, 2.0_f32.to_bits()),
+ Some(&node_data),
+ Some(0.0),
+ 3.0,
+ )
+ .expect("positive zero is an exact native input");
+ assert_eq!(positive_zero.to_bits(), 0.0_f32.to_bits());
+ }
+
+ #[test]
+ fn tag26_selector_300_rejects_nonfinite_and_subnormal_operands() {
+ let node_data = resource_device_node_data_table(1);
+ for (operand, provider_now, multiplier_now, base_bits) in [
+ ("provider", f32::NAN, 1.0, 1.0_f32.to_bits()),
+ ("multiplier", 1.0, f32::INFINITY, 1.0_f32.to_bits()),
+ ("base coefficient", 1.0, 1.0, 1),
+ ] {
+ let record = resource_device_record(26, 0, base_bits);
+ assert_eq!(
+ sample_control_resource_device_selector_300(
+ &record,
+ Some(&node_data),
+ Some(provider_now),
+ multiplier_now,
+ ),
+ Err(ControlSamplingError::InvalidResourceDeviceOperand { operand })
+ );
+ }
+ }
+
+ #[test]
+ fn tag26_selector_300_rejects_extended_intermediate_and_final_ranges() {
+ let node_data = resource_device_node_data_table(1);
+ let provider = f32::MAX;
+ let overflowing_intermediate = resource_device_record(26, 0, 2.0_f32.to_bits());
+ assert_eq!(
+ sample_control_resource_device_selector_300(
+ &overflowing_intermediate,
+ Some(&node_data),
+ Some(provider),
+ 0.25,
+ ),
+ Err(ControlSamplingError::UnsupportedResourceDeviceFloatRange {
+ stage: "provider times base",
+ })
+ );
+
+ let underflowing_intermediate = resource_device_record(26, 0, f32::MIN_POSITIVE.to_bits());
+ assert_eq!(
+ sample_control_resource_device_selector_300(
+ &underflowing_intermediate,
+ Some(&node_data),
+ Some(f32::MIN_POSITIVE),
+ f32::MAX,
+ ),
+ Err(ControlSamplingError::UnsupportedResourceDeviceFloatRange {
+ stage: "provider times base",
+ })
+ );
+
+ let subnormal_final = resource_device_record(26, 0, 1.0_f32.to_bits());
+ assert_eq!(
+ sample_control_resource_device_selector_300(
+ &subnormal_final,
+ Some(&node_data),
+ Some(f32::MIN_POSITIVE),
+ 0.5,
+ ),
+ Err(ControlSamplingError::UnsupportedResourceDeviceFloatRange {
+ stage: "then multiplier",
+ })
+ );
+ }
+
fn tag21_fullcycle_control() -> PreparedComponentControl {
let source = ResourceKey {
archive: parse_path("parts.rlb").expect("archive"),
@@ -6166,6 +6444,60 @@ mod tests {
#[test]
#[ignore = "requires licensed corpus"]
+ fn tag26_selector_300_uses_a_real_control_record_and_ndp_key() {
+ let root = fixture_root("IS");
+ let vfs: Arc<dyn Vfs> = Arc::new(DirectoryVfs::new(&root));
+ let repository = CachedResourceRepository::new(Arc::clone(&vfs));
+ let roots = [resource_name(b"UNITS/BUILDS/MINE/min_l_n1.dat")];
+ let (_graph, prototypes) =
+ build_prototype_graph(&repository, vfs.as_ref(), &roots).expect("prototype graph");
+ let assets = prepare_mission_assets_with_repository(
+ &repository,
+ &[0..prototypes.len()],
+ &prototypes,
+ )
+ .expect("prepared licensed unit controls");
+
+ let mut sampled_records = 0;
+ for control in assets.object_component_controls.iter().flatten().flatten() {
+ for record in control
+ .typed_records
+ .iter()
+ .filter(|record| record.tag == 26)
+ {
+ let node_data = control
+ .node_data
+ .as_ref()
+ .expect("tag-26 control has its explicit NDP table");
+ assert_eq!(control.source.name.0, b"fr_l_mine.ctl");
+ assert_eq!(node_data.source.name.0, b"fr_l_mine.ndp");
+ assert_eq!(node_data.rows.len(), 22);
+ assert_eq!(record.fixed_words[1], 2);
+ assert_eq!(record.fixed_words[11], 0x3F80_0000);
+ let sample = sample_control_resource_device_selector_300(
+ record,
+ Some(node_data),
+ Some(1.0),
+ 1.0,
+ )
+ .expect("real tag-26 key selects an NDP row");
+ assert_eq!(sample.to_bits(), record.fixed_words[11]);
+ println!(
+ "control={}: ndp={}: key={} rows={} coefficient=0x{:08x}",
+ String::from_utf8_lossy(&control.source.name.0),
+ String::from_utf8_lossy(&node_data.source.name.0),
+ record.fixed_words[1],
+ node_data.rows.len(),
+ record.fixed_words[11],
+ );
+ sampled_records += 1;
+ }
+ }
+ assert_eq!(sampled_records, 1);
+ }
+
+ #[test]
+ #[ignore = "requires licensed corpus"]
fn repository_plan_deduplicates_duplicate_visuals_but_graph_preserves_requests() {
let root = fixture_root("IS");
let vfs: Arc<dyn Vfs> = Arc::new(DirectoryVfs::new(&root));
diff --git a/crates/fparkan-runtime/tests/behavior_distributor_tick_native_oracle.cs b/crates/fparkan-runtime/tests/behavior_distributor_tick_native_oracle.cs
index 8532d1a..d2e5bb9 100644
--- a/crates/fparkan-runtime/tests/behavior_distributor_tick_native_oracle.cs
+++ b/crates/fparkan-runtime/tests/behavior_distributor_tick_native_oracle.cs
@@ -16,6 +16,7 @@ internal static class BehaviorDistributorTickOracle {
private const uint MemRelease = 0x00008000;
private const uint PageReadWrite = 0x04;
private const string ExpectedBehaviorSha256 = "ddfbdbde07832358fe6e35e01c8dba9b58e7313789498b6049ed51d4ed9baf99";
+ private const string ExpectedControlSha256 = "bcb86318089028548a178b03a21accdce15df0cc85ddd91674cf3c2f55012c6e";
private const int TickRva = 0x19e80;
private const int AddObjectRva = 0x1aac0;
private const int NormalizeRva = 0x1ac90;
@@ -23,6 +24,9 @@ internal static class BehaviorDistributorTickOracle {
private const int IndexedPropertyGetRva = 0x0b5b0;
private const int OreInitializationRva = 0x08790;
private const int GetSystemArealMapIatRva = 0x59008;
+ private const int ControlResourceDeviceGetterRva = 0x21d00;
+ private const int ControlProviderInterfaceVtableRva = 0x3d254;
+ private const int ControlProviderType1GetterRva = 0x0dc40;
private const uint ResourceProperty = 0x02000100;
private static Fixture active;
@@ -52,6 +56,7 @@ internal static class BehaviorDistributorTickOracle {
[UnmanagedFunctionPointer(CallingConvention.StdCall)] private delegate void IndexedPropertySet(IntPtr self, uint index, uint valueBits);
[UnmanagedFunctionPointer(CallingConvention.StdCall)] private delegate int IndexedPropertyGet(IntPtr self, uint index, IntPtr resultBits);
[UnmanagedFunctionPointer(CallingConvention.ThisCall)] private delegate void NativeOreInitialization(IntPtr self);
+ [UnmanagedFunctionPointer(CallingConvention.ThisCall)] private delegate float NativeControlResourceDeviceGet(IntPtr self, uint selector);
private static readonly AreaMapGetter AreaMapGetterCallback = GetAreaMap;
private static readonly VectorInsert VectorInsertCallback = InsertVector;
@@ -306,13 +311,20 @@ internal static class BehaviorDistributorTickOracle {
private static int Main() {
if (IntPtr.Size != 4) { Console.Error.WriteLine("Build with /platform:x86."); return 2; }
+ string controlPath = Environment.GetEnvironmentVariable("FPARKAN_ORIGINAL_CONTROL_DLL");
+ if (String.IsNullOrEmpty(controlPath)) controlPath = @"C:\GOG Games\Parkan - Iron Strategy\Control.dll";
+ if (!File.Exists(controlPath)) { Console.Error.WriteLine("Set FPARKAN_ORIGINAL_CONTROL_DLL to the installed Control.dll."); return 7; }
+ string controlHash = Hash(controlPath);
+ if (controlHash != ExpectedControlSha256) { Console.Error.WriteLine("Unexpected Control.dll SHA-256: " + controlHash); return 8; }
+ IntPtr controlModule = LoadLibraryEx(controlPath, IntPtr.Zero, LoadWithAlteredSearchPath);
+ if (controlModule == IntPtr.Zero) { Console.Error.WriteLine("LoadLibraryEx(Control.dll) failed: " + Marshal.GetLastWin32Error()); return 9; }
string path = Environment.GetEnvironmentVariable("FPARKAN_ORIGINAL_BEHAVIOR_DLL");
if (String.IsNullOrEmpty(path)) path = @"C:\GOG Games\Parkan - Iron Strategy\Behavior.dll";
- if (!File.Exists(path)) { Console.Error.WriteLine("Set FPARKAN_ORIGINAL_BEHAVIOR_DLL to the installed Behavior.dll."); return 3; }
+ if (!File.Exists(path)) { Console.Error.WriteLine("Set FPARKAN_ORIGINAL_BEHAVIOR_DLL to the installed Behavior.dll."); FreeLibrary(controlModule); return 3; }
string hash = Hash(path);
- if (hash != ExpectedBehaviorSha256) { Console.Error.WriteLine("Unexpected Behavior.dll SHA-256: " + hash); return 4; }
+ if (hash != ExpectedBehaviorSha256) { Console.Error.WriteLine("Unexpected Behavior.dll SHA-256: " + hash); FreeLibrary(controlModule); return 4; }
IntPtr module = LoadLibraryEx(path, IntPtr.Zero, LoadWithAlteredSearchPath);
- if (module == IntPtr.Zero) { Console.Error.WriteLine("LoadLibraryEx(Behavior.dll) failed: " + Marshal.GetLastWin32Error()); return 5; }
+ if (module == IntPtr.Zero) { Console.Error.WriteLine("LoadLibraryEx(Behavior.dll) failed: " + Marshal.GetLastWin32Error()); FreeLibrary(controlModule); return 5; }
IntPtr import = IntPtr.Add(module, GetSystemArealMapIatRva);
IntPtr originalImport = Marshal.ReadIntPtr(import);
uint oldProtection = 0;
@@ -334,7 +346,7 @@ internal static class BehaviorDistributorTickOracle {
throw new InvalidOperationException("VirtualProtect(GetSystemArealMap IAT) failed: " + Marshal.GetLastWin32Error());
protectionChanged = true;
Marshal.WriteIntPtr(import, Marshal.GetFunctionPointerForDelegate(AreaMapGetterCallback));
- RunSmokeCases(module);
+ RunSmokeCases(module, controlModule);
Console.WriteLine("original Behavior.dll distributor oracle passed (native Add 0x1aac0, normalize 0x1ac90, tick 0x19e80; only GetSystemArealMap IAT and bounded vector insertion are substituted; this does not compare Rust parity).");
return 0;
}
@@ -357,10 +369,11 @@ internal static class BehaviorDistributorTickOracle {
throw new InvalidOperationException("VirtualFree(fastcall callback thunks) failed: " + Marshal.GetLastWin32Error());
if (x87ControlWordCell != IntPtr.Zero) { Marshal.FreeHGlobal(x87ControlWordCell); x87ControlWordCell = IntPtr.Zero; }
FreeLibrary(module);
+ FreeLibrary(controlModule);
}
}
- private static void RunSmokeCases(IntPtr module) {
+ private static void RunSmokeCases(IntPtr module, IntPtr controlModule) {
ushort savedControlWord = CurrentX87ControlWord();
Console.WriteLine("x87-control-word-before=0x" + savedControlWord.ToString("x4") + " (x86 oracle process)");
try {
@@ -368,6 +381,7 @@ internal static class BehaviorDistributorTickOracle {
Console.WriteLine("native-add-normalize-x87-control-word=0x" + CurrentX87ControlWord().ToString("x4"));
RunNativeAddCases(module);
RunNativeNormalizeCases(module);
+ RunNativeControlResourceDeviceCase(controlModule);
} finally {
SetX87ControlWord(savedControlWord);
Console.WriteLine("x87-control-word-restored=0x" + CurrentX87ControlWord().ToString("x4"));
@@ -396,6 +410,76 @@ internal static class BehaviorDistributorTickOracle {
RunSkippedCase(tick);
}
+ private static void RunNativeControlResourceDeviceCase(IntPtr module) {
+ Expect(CurrentX87ControlWord() == 0x007f, "Control selector 0x300 uses x87 control word 0x007f");
+ const uint key = 2;
+ const int rowCount = 22;
+ const int providerRow = (int)key * 0x2c;
+ IntPtr providerOwner = Marshal.AllocHGlobal(0x560);
+ IntPtr providerRows = Marshal.AllocHGlobal(rowCount * 0x2c);
+ IntPtr device = IntPtr.Zero;
+ try {
+ Zero(providerOwner, 0x560);
+ Zero(providerRows, rowCount * 0x2c);
+ IntPtr providerInterface = IntPtr.Add(providerOwner, 4);
+ IntPtr providerVtable = IntPtr.Add(module, ControlProviderInterfaceVtableRva);
+ Marshal.WriteIntPtr(providerInterface, providerVtable);
+ Expect(
+ Marshal.ReadIntPtr(providerVtable, 0x0c) == IntPtr.Add(module, ControlProviderType1GetterRva),
+ "Control provider interface vtable uses the native type-1 getter");
+ Marshal.WriteIntPtr(providerOwner, 0x55c, providerRows);
+
+ device = Marshal.AllocHGlobal(0x94);
+ Zero(device, 0x94);
+ Marshal.WriteInt32(device, 0x04, unchecked((int)key));
+ Marshal.WriteIntPtr(device, 0x44, providerInterface);
+
+ NativeControlResourceDeviceGet getter = (NativeControlResourceDeviceGet)
+ Marshal.GetDelegateForFunctionPointer(
+ IntPtr.Add(module, ControlResourceDeviceGetterRva),
+ typeof(NativeControlResourceDeviceGet));
+ ExpectControlResourceDeviceResult(getter, device, providerRows, providerRow,
+ 0x3fe6982f, 0x3d25ae4a, 0x40715539, 0x3e8cb02e, "order-sensitive normal");
+ ExpectControlResourceDeviceResult(getter, device, providerRows, providerRow,
+ 0x7f7fffff, 0x40000000, 0x3e800000, 0x7effffff, "extended intermediate overflow then finite");
+ ExpectControlResourceDeviceResult(getter, device, providerRows, providerRow,
+ 0x00800000, 0x00800000, 0x7f7fffff, 0x017fffff, "extended intermediate underflow then finite");
+ ExpectControlResourceDeviceResult(getter, device, providerRows, providerRow,
+ 0x00800000, 0x3f800000, 0x3f000000, 0x00400000, "subnormal final result");
+ ExpectControlResourceDeviceResult(getter, device, providerRows, providerRow,
+ 0xc0000000, 0x3f000000, 0x40800000, 0xc0800000, "negative factors");
+ ExpectControlResourceDeviceResult(getter, device, providerRows, providerRow,
+ 0x80000000, 0x40000000, 0x40400000, 0x80000000, "negative zero");
+ Expect(CurrentX87ControlWord() == 0x007f, "Control selector 0x300 retains x87 control word 0x007f");
+ Console.WriteLine("native-control-tag26-selector-300: controlHash=" + ExpectedControlSha256 +
+ " cw=0x" + CurrentX87ControlWord().ToString("x4") + " key=2 rows=22");
+ GC.KeepAlive(getter);
+ } finally {
+ if (device != IntPtr.Zero) Marshal.FreeHGlobal(device);
+ Marshal.FreeHGlobal(providerRows);
+ Marshal.FreeHGlobal(providerOwner);
+ }
+ }
+
+ private static void ExpectControlResourceDeviceResult(
+ NativeControlResourceDeviceGet getter,
+ IntPtr device,
+ IntPtr providerRows,
+ int providerRow,
+ uint providerBits,
+ uint baseBits,
+ uint multiplierBits,
+ uint expectedBits,
+ string label) {
+ Marshal.WriteInt32(providerRows, providerRow + 0x14, unchecked((int)providerBits));
+ Marshal.WriteInt32(device, 0x54, unchecked((int)baseBits));
+ Marshal.WriteInt32(device, 0x4c, unchecked((int)multiplierBits));
+ uint actualBits = unchecked((uint)FloatBits(getter(device, 0x300)));
+ Expect(actualBits == expectedBits,
+ "Control selector 0x300 " + label + " expected " + Hex(expectedBits) + " but got " + Hex(actualBits));
+ Console.WriteLine("native-control-tag26-selector-300-" + label + ": result=" + Hex(actualBits));
+ }
+
private static void RunNativeIndexedPropertyCases(IntPtr module) {
IndexedPropertySet set = (IndexedPropertySet)Marshal.GetDelegateForFunctionPointer(
IntPtr.Add(module, IndexedPropertySetRva), typeof(IndexedPropertySet));
@@ -911,7 +995,7 @@ internal static class BehaviorDistributorTickOracle {
foreach (byte value in digest) hex.Append(value.ToString("x2")); return hex.ToString();
}
}
- private static void Expect(bool value, string message) { if (!value) throw new InvalidOperationException("original Behavior oracle failed: " + message); }
+ private static void Expect(bool value, string message) { if (!value) throw new InvalidOperationException("original native oracle failed: " + message); }
private static void ExpectLookupOrder(Fixture fixture, params string[] keys) {
List<string> actual = new List<string>();
foreach (string item in fixture.Trace) if (item.StartsWith("lookup:", StringComparison.Ordinal)) actual.Add(item.Substring(7));
diff --git a/docs/appendices/knowledge-boundaries.md b/docs/appendices/knowledge-boundaries.md
index c1993ca..5791836 100644
--- a/docs/appendices/knowledge-boundaries.md
+++ b/docs/appendices/knowledge-boundaries.md
@@ -130,7 +130,7 @@ host construction phases. Не проверена другая лицензир
непустым `Init`. Вызов `Behavior.dll!FUN_10019e80` (RVA `0x19e80`, SHA-256
`ddfbdbde07832358fe6e35e01c8dba9b58e7313789498b6049ed51d4ed9baf99`) исполнялся
на синтетических интерфейсах. Путь членства в реальных distributor-списках
-теперь связан с полями TMA и Unit DAT: `World3D!CreateObject` передаёт selector
+связан с полями TMA и Unit DAT: `World3D!CreateObject` передаёт selector
и class word через дескриптор в Behavior (RVA `0x7e55`, `0x7e62`), а
`Behavior.dll!FUN_10005e60` (RVA `0x5e60`) проверяет высокий бит registration
key, AI и distributor. Selector из первого DWORD после имени ресурса выбирает
@@ -203,7 +203,15 @@ prototype roots без Unit DAT и отложенные spawn после исх
этой модели. Путь в `ArealMap.dll` (SHA-256
`a25f9254ebb339d70e2e07c8121950191e9584ca0858d8e9c2e2b6c671edf6ea`) к
`CreateObject` по RVA `0x14fd0`/`0x15290` показывает выбор World3D class 3 или 4
-по старшему биту, но не всю цепочку их Behavior attachment.
+по старшему биту. Для ветки GOG `AniMesh.dll` (SHA-256
+`65659bf67f20e5be77d67a5b2f59968f61b94293143807fa59ca451c560c4f7e`) RVA
+`0x2ff0` показывает одну ветку создания: после QueryInterface для IID `0x204`
+выполняется отдельный импорт `GetQueue()`, а на возвращённом объекте вызывается
+метод через vtable slot `+0x30`. `CreateBehaviour` вызывается только при
+ненулевом результате этого метода и host class `3` или `4`; class `4` получает
+адреса полей prototype `+0x140` и `+0x160`. Семантика метода slot `+0x30` не
+установлена. Другие factory paths, нулевой результат и spawn после исходной
+загрузки остаются за границами подтверждённой ветки.
Для `Handler(30)` отдельно подтверждены обратный вызов `iron3d.dll` RVA
`0x611d0` (SHA-256 `d1dc4ea8535e2069b0a05c9e8be2724dd438ba44cca7a83007d8b2e50f9e35fa`),
@@ -239,6 +247,50 @@ CTLD и связанные resources структурно читаются, coun
известны. Не названы все секции, shape types, coefficients и точный contact
solver. То же относится к редким MSH auxiliary streams и части CTPT/NDPR flags.
+Одна цепочка Unit DAT → AniMesh descriptor → Control теперь восстановлена
+статически в [главе о Behavior и Control](../tomes/06-behavior.md): raw
+`parent_or_link` копируется в descriptor. В non-`EXTO` registry path parent ID
+разрешается в индекс устройства и сдвигает локальный индекс только когда parent
+ID не равен `-1` и IID `0x202` доступен; иначе используется raw локальный индекс.
+В этом потоке нулевой raw kind пропускает узел вместе с потомками, поэтому общий
+assigned ID нельзя получать из preorder-позиции записи. Это закрывает только
+передачу полей в native loader-е; Rust ещё должен строить такую же проекцию.
+
+Control loader также различает добавление устройств и применение одной записи
+к уже выбранному устройству. Для tag `19` найденные поля и ветви описаны в
+главе, но эффективное слияние пока не реализовано. В Rust parser-е
+`Unsupported { typed_record_index: Some(_) }` означает, что разбор остановился
+внутри списка typed records; без индекса остановки unsupported может относиться
+к effect-tail после уже разобранного списка. Эти случаи нужно различать.
+Ветка default native-фабрики вызывает конструктор по RVA `0x20800`, поэтому
+неизвестный Rust parser-у tag не доказывает отказ оригинального loader-а. Подготовка assets
+сейчас пропускает Control refs у non-geometric prototype, поэтому отсутствие
+подготовленного CTL должно оставаться явным unavailable result, а не
+трактоваться как пустой список.
+
+Глобальные Control selectors `1/2` и setter selector `1` по tag `19` описаны
+там же только по статическому разбору `Control.dll`; execution oracle для этих
+глобальных вызовов нет. Остаются открытыми проверка effective merge на живых
+объектах, полный охват registry types и host factory paths, а также runtime
+жизненный цикл множителя `+0x4c`.
+
+Для `Control.dll` (SHA-256
+`bcb86318089028548a178b03a21accdce15df0cc85ddd91674cf3c2f55012c6e`) tag-26
+getter selector `0x300` восстановлен локально: RVA `0x21d00` читает provider по
+ключу `fixed_words[1]`, затем умножает provider, CTLD coefficient `fixed_words[11]`
+и поле объекта `+0x4c` именно в таком порядке. Rust helper принимает текущие
+provider и multiplier извне; он не восстанавливает их жизненный цикл или весь
+Control tick. В x86 oracle при x87 control word `0x007f` проверены порядок,
+signed zero, отрицательные входы, расширенный промежуточный диапазон и
+subnormal return. Helper ограничивает себя normal-or-zero значениями, поэтому
+явно отклоняет промежуточные случаи, где результат выходит за поддерживаемый
+диапазон f32, даже если позднее умножение вернуло бы его в диапазон. Это
+ограничение поддержки Rust helper-а, а не неверный native-результат.
+
+В Unit DAT fixture `UNITS/BUILDS/MINE/min_l_n1.dat` проверена реальная связка
+`fr_l_mine.ctl` + `fr_l_mine.ndp`: tag `26`, ключ `2` в таблице из `22` строк,
+коэффициент `1.0`. Это не запись живого resource-device значения в миссии.
+
Закрывающий эксперимент: трассировать `LoadControlSystem`,
`LoadPhysicalModel`, `CreateCollManager` и создание collision objects; связать
каждый изменяемый field с созданным shape, contact или реакцией на движение.
diff --git a/docs/tomes/03-resources.md b/docs/tomes/03-resources.md
index 29fef77..a11ad55 100644
--- a/docs/tomes/03-resources.md
+++ b/docs/tomes/03-resources.md
@@ -448,21 +448,28 @@ struct UnitDatRecord112 {
char archive_name[32]; // +0x00
char resource_name[32]; // +0x20
uint32_t kind; // +0x40, в корпусе всегда 1
- int32_t parent_or_link; // +0x44
+ int32_t parent_or_link; // +0x44, context-dependent local index
char description[32]; // +0x48
uint32_t tail0; // +0x68, opaque
- uint32_t tail1; // +0x6C, opaque
+ uint32_t tail1; // +0x6C, immediate_child_count
};
#pragma pack(pop)
```
Во всех проверенных records `archive_name == "objects.rlb"` и `kind == 1`.
-Поле `parent_or_link` встречается как `-1`, `0`, `1` и другие небольшие индексы
-и связывает компоненты составного unit; точная предметная классификация ссылки
-ещё не закрыта. `description` -- человекочитаемое описание компонента. В Части 2
-есть поля `description[32]`, полностью заполненные без NUL; это валидная bounded
-string длиной 32 байта. Требование обязательного terminator применяется только
-к полям, где оно доказано форматом. `tail0` и `tail1` нельзя нормализовать.
+`tail1` задаёт `immediate_child_count` — число непосредственных дочерних
+записей при построении дерева Unit DAT; оно не opaque. Поле `parent_or_link`
+встречается как `-1`, `0`, `1` и другие небольшие индексы. В подтверждённой
+цепочке Unit DAT → AniMesh → Control оно становится локальным индексом. Для
+`INTO` индекс задаёт устройство Control относительно первого устройства
+родительского компонента, а `EXTO` обрабатывается отдельной ветвью. Поэтому
+поле нельзя трактовать как универсальный parent ID или одинаковую ссылку для
+всех registry types. Детали передачи описаны в [главе о Behavior и Control](06-behavior.md).
+`tail0` сохраняется как raw DWORD без установленной семантики. `description` --
+человекочитаемое описание компонента. В Части 2 есть поля `description[32]`,
+полностью заполненные без NUL; это валидная bounded string длиной 32 байта.
+Требование обязательного terminator применяется только к полям, где оно доказано
+форматом.
Проверено 425 файлов / 5 219 records Части 1 и 676 файлов / 8 145 records
Части 2. Все соответствуют формуле размера, `kind == 1` и
@@ -470,10 +477,8 @@ string длиной 32 байта. Требование обязательног
При построении mission prototype graph FParkan сохраняет для каждого root
упорядоченный список этих raw records. Список передаётся в
-`MissionObjectDraft` без преобразования `kind`, `parent_or_link`, description
-или tails в предполагаемые роли. Так runtime уже располагает исходными данными
-составного unit для будущих Control/physics/AniMesh consumers, но не выдаёт
-структурное сходство за доказанную семантику.
+`MissionObjectDraft` с исходными `kind`, `parent_or_link`, description и tails;
+эти данные пока не объединяются в таблицу эффективных устройств Control.
Каждый graph edge от `UnitDatRoot` к effective component и далее к его MSH
dependency также несёт `unit_component_index`. Это индекс исходной записи в
diff --git a/docs/tomes/06-behavior.md b/docs/tomes/06-behavior.md
index 16ea21a..9d7b01e 100644
--- a/docs/tomes/06-behavior.md
+++ b/docs/tomes/06-behavior.md
@@ -542,10 +542,155 @@ component как ordered raw-string/resource provenance, но не для при
этим строкам смысловых имён до трассировки private update methods.
Runtime сохраняет ordered raw Unit DAT records рядом с каждым mission object
-draft. Это создаёт проверяемую границу передачи данных от loader-а к будущему
-Control consumer-у: никакой компонент пока не получает имя `Control` только
-по `kind`, `parent_or_link` или description; semantic binding появится лишь
-после trace private update/load methods.
+draft. Теперь подтверждена связь Unit DAT с descriptor-ом AniMesh, который
+передаётся в Control: порядок узлов задаётся деревом immediate-child counts,
+а `parent_or_link` попадает в descriptor как локальное поле. Его смысл зависит
+от registry type и состояния Control manager-а; в частности, для `INTO` это
+локальный индекс устройства, а `EXTO` проходит отдельную ветвь.
+
+### От Unit DAT к Control descriptor
+
+В GOG `ArealMap.dll` (SHA-256
+`a25f9254ebb339d70e2e07c8121950191e9584ca0858d8e9c2e2b6c671edf6ea`)
+`FUN_10016a10` (RVA `0x16a10`) читает запись Unit DAT в дерево узлов по
+`0x78` байт: перед сырыми полями узла находятся указатель и количество детей,
+а байты файла копируются начиная с node `+0x0c`. `FUN_10015290` (RVA
+`0x15290`) передаёт каждый непосредственный узел корня в `FUN_10014b90`
+(RVA `0x14b90`) с начальным parent ID `0`.
+
+Для узла с ненулевым raw kind `FUN_10014b90` формирует descriptor размером
+`0x4c`: две строки ресурса копируются из node `+0x0c` и `+0x2c`, поле
+descriptor `+0x40` получает parent ID, `+0x44` — DWORD node `+0x50`, а
+`+0x48` начинается со значения `-1`. Из-за смещения raw-полей на `0x0c`
+node `+0x50` — это ровно `parent_or_link` по смещению `0x44` в записи Unit
+DAT. Затем `ArealMap` посылает owner-у событие `6 / 0x80000020` через vtable
+slot `+0x34`.
+
+В `AniMesh.dll` (SHA-256
+`65659bf67f20e5be77d67a5b2f59968f61b94293143807fa59ca451c560c4f7e`)
+dispatcher `FUN_10001370` (RVA `0x1370`) передаёт это событие в
+`FUN_10003760` (RVA `0x3760`). Тот выбирает следующий свободный ID, записывает
+его в descriptor `+0x48` и сохраняет descriptor в списке компонентов.
+Вернувшись после virtual call, `FUN_10014b90` передаёт этот ID как parent ID
+рекурсивного обхода детей. Поэтому родительская связь Control descriptor-а
+строится по фактически назначенному ID в обходе дерева, а локальный индекс
+устройства приходит из `parent_or_link`.
+
+У этого обхода есть ранний выход: если raw kind в node `+0x4c` равен нулю,
+узел и его дети пропускаются. AniMesh начинает со служебного root ID `0`, но
+из-за пропусков и других записей назначенный ID нельзя в общем случае считать
+равным индексу узла или номеру его записи в Unit DAT.
+
+Для registry type `INTO` и других не-`EXTO` значений `FUN_10003760` разрешает
+parent ID через Control IID `0x202`, virtual slot `+0x44`, только если parent ID
+не равен `-1` и интерфейс IID `0x202` доступен. `Control.dll`
+`FUN_1002ecc0` (RVA `0x2ecc0`) возвращает индекс первого устройства, чьё поле
+`+0x08` равно этому ID, или `-1`, если совпадения нет; AniMesh прибавляет
+возвращённое значение к локальному индексу `+0x44` без отдельной проверки
+`-1`. Если parent ID равен `-1` или IID `0x202` недоступен, используется сам
+локальный индекс без смещения. Отсутствие устройства с parent ID — отдельный
+случай: native path даёт индекс на единицу меньше локального, и Rust-проекции
+нужно проверить это поведение явно. `EXTO` проходит отдельную ветвь, поэтому
+это правило нельзя распространять на все registry types.
+
+### Как Control добавляет и переопределяет устройства
+
+В `Control.dll` (SHA-256
+`bcb86318089028548a178b03a21accdce15df0cc85ddd91674cf3c2f55012c6e`)
+`FUN_10008b10` (RVA `0x8b10`) выбирает путь по полю descriptor `+0xc8`.
+Значение `-1` запускает цикл по typed records; фабрика `FUN_1002d4b0` (RVA
+`0x2d4b0`) создаёт по устройству на запись и сохраняет их порядок. Иное
+значение вызывает `FUN_1002d890` (RVA `0x2d890`) только один раз; цикл по
+typed-record count в этой ветви отсутствует. Следовательно, подтверждённый
+override path применяет первую typed record и не добавляет новый объект.
+Так модуль меняет характеристики уже существующего слота, не увеличивая число
+устройств. Неизвестный tag в Rust CTLD parser приводит к `Unsupported` и может
+оставить typed-record list неполным. Native factory имеет отдельный default
+путь `0x20800`, поэтому такой результат парсера сам по себе не доказывает отказ
+оригинального loader-а и не позволяет объявить Rust merge полным.
+
+Для tag `19` фабрика создаёт объект с его исходными классом и vtable. Базовый
+конструктор `FUN_100218b0` задаёт multiplier `+0x4c = 1.0`. Override через
+`FUN_1002d890` вызывает у выбранного объекта vtable slot `+0x1c`, то есть
+`FUN_10021d50` с флагом инициализации `0`. Этот вызов не создаёт объект и не
+заменяет класс или vtable. Он сохраняет уже существующий ключ `+0x04`; сохраняет
+текущее значение multiplier `+0x4c` (которое могло измениться после
+конструктора); и копирует коэффициенты из CTLD в блок `+0x54`. Поле `+0x50`
+обновляется лишь когда слово записи `+0x18` не равно `-1`. Сопоставленные
+записи значений прибавляются к текущим полям объекта `+0x1c/+0x20`, а не
+сбрасывают их. Поэтому «переопределение» здесь означает обновить часть данных
+того же устройства, с ограничениями конкретного метода.
+
+Статический разбор глобального Control interface показывает aggregate getters
+`1/2` (`FUN_1002b410`, RVA `0x2b410`) и setter `1` (`FUN_1002ba30`, RVA
+`0x2ba30`) для устройств tag `19`. Для конечных значений getter `1` вычисляет
+`sum(base * multiplier) / sum(base)`, а getter `2` — `sum(base)`. При встрече
+отрицательного base selector `1` сразу возвращает `1.0`, а selector
+`2` — этот base. Если подходящих записей нет или сумма base неположительна,
+getter возвращает неуспех без записи результата. Setter пишет multiplier `+0x4c`
+только устройствам tag `19` с положительным selector-0 значением; пустой набор
+возвращает успех. Это вывод статического анализа для конечных входных значений,
+без отдельного native execution oracle для глобальных selectors.
+
+Отдельная ветка того же GOG `AniMesh.dll` показывает, когда создаётся Behavior
+для host object. В `FUN_10002ff0` (RVA `0x2ff0`, SHA-256
+`65659bf67f20e5be77d67a5b2f59968f61b94293143807fa59ca451c560c4f7e`) вызывающая
+сторона запрашивает IID `0x204` и сохраняет интерфейс в поле `+0x168`. Затем
+отдельный импорт `GetQueue()` возвращает объект очереди; вызов метода через его
+vtable slot `+0x30` даёт результат, который проверяется на ненулевое значение.
+Только при ненулевом результате host class `3` вызывает
+`CreateBehaviour(0, 0, self)` (RVA `0x34bd`); class `4` передаёт в
+`CreateBehaviour` адреса полей prototype `+0x140` и `+0x160` (RVA `0x3426`).
+Семантика метода slot `+0x30` здесь не установлена. Это подтверждает только
+такую ветку и эти два класса; другие фабрики, нулевой результат и отложенные
+spawn сюда не входят.
+
+### Один запрос Control для ресурсного устройства
+
+В CTLD запись tag `26` задаёт ресурсный множитель, но текущее значение
+поставщика живёт в runtime state Control. GOG `Control.dll` (SHA-256
+`bcb86318089028548a178b03a21accdce15df0cc85ddd91674cf3c2f55012c6e`)
+`FUN_10021d00` (RVA `0x21d00`) реализует getter selector `0x300`. Его фиксированное
+слово `+0x2c` становится `fixed_words[11]` при копировании записи RVA `0x21d50`;
+`fixed_words[1]` — ключ строки NDP. В объекте Control getter использует ключ
+`+0x04`, provider interface `+0x44`, множитель `+0x4c` и коэффициент `+0x54`.
+Provider interface направляет selector `1` и ключ в Control RVA `0xdc40`, где
+читается текущее type-1 значение выбранной строки. Затем selector умножает
+сначала provider на коэффициент, после чего на множитель: `provider * base *
+multiplier`. Коэффициент приходит из CTLD; NDP связывает ключ с описанной
+строкой, а текущее значение provider нельзя заменить предположением о состоянии
+мира.
+
+Так этот селектор включён в цепочку добычи руды оригинала. В той же сборке
+`Behavior.dll` (SHA-256
+`ddfbdbde07832358fe6e35e01c8dba9b58e7313789498b6049ed51d4ed9baf99`)
+`FUN_100186b0` (RVA `0x186b0`) перечисляет устройства типа `0x1a`, а
+`FUN_100198e0` (RVA `0x198e0`) суммирует успешные запросы IID `0x204` с selector
+`0xe00`. В парной `Control.dll` выше `FUN_1002bb40` (RVA `0x2bb40`) для типа
+`0x1a` вызывает selector `0x300`, описанный в этом разделе. Затем Behavior query
+`0x1002` (RVA `0xa490`) умножает полученную сумму на текущее значение block
+`+0x820`, поле `+0x58` `Transfer_Ore_OffBoard` (имя — RVA `0x22e20`, default
+5.0 — RVA `0x22d90`; config selector 2 загружает блок через RVA `0x0a1a0`).
+Отдельный query `0x1005` (RVA `0xa490`) возвращает поле `+0x60`
+`Transfer_Power_Out` (имя — RVA `0x22e20`, default 100.0 — RVA `0x22d90`;
+setter — RVA `0xaa40`). Rust helper пока описывает один Control selector `0x300`
+при явно переданных входах; он не реализует эту сумму, Behavior-умножение или
+подключение к игровому циклу.
+
+На x87 control word `0x007f` каждое умножение округляет мантиссу до 24 бит,
+но промежуточная степень может выйти за диапазон `f32` и вернуться в него при
+следующем умножении. Rust helper поэтому принимает явные текущие значения
+provider и multiplier, проверяет tag, ключ и строку NDP, сохраняет порядок
+операций, но поддерживает только конечные нормализованные значения или ноль на
+входе, промежуточном и конечном этапах. Остальные случаи за этим численным
+диапазоном он отклоняет; полный x87 accumulator здесь не эмулируется.
+
+Лицензированный тест на Unit DAT `UNITS/BUILDS/MINE/min_l_n1.dat` проходит через
+компонент `fr_l_mine.ctl` и sidecar `fr_l_mine.ndp`: у найденного tag-26
+дескриптора ключ равен `2` из `22` строк, а raw коэффициент — `0x3f800000`.
+Тест передаёт helper-у искусственные текущие значения `1.0` только для проверки
+записи и привязки ключа; этот Unit DAT не является наблюдением живого Control
+tick-а.
### Control system и physical model
Copyright © 2026 Valentin A. Popov. All Rights Reverse Engineered.