Files
Neutron/docs/analysis/binary.md
T

182 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Executable investigation
Static analysis, 2026-10-23. No original code was executed or modified. Addresses
below are preferred-base virtual addresses of **Neutron.exe** or **OMT2.dll**;
patch variants must be checked independently. No Ghidra/Rizin/Wine was available
on PATH initially; the initial investigation uses Python, strings and objdump.
## Verified identity and toolchain
| File | Format | Preferred base | Entry | Header timestamp |
|---|---|---|---|---|
| Neutron.exe | PE32 GUI, native Intel 80386 | 0x00400000 | 0x004802F2 | 2001-09-29 21:07:40 UTC |
| OMT2.dll | PE32 DLL, native Intel 80386 | 0x10000000 | 0x10105753 | 2001-08-27 10:27:41 UTC |
Both have linker 6.0, MSVC decorated C++ exports/imports, C++ RTTI, x87 code and
MSVC exception handling. Together these strongly identify Microsoft Visual C++ 6
era C++; the linker header alone does not prove the exact compiler build. CLR
directories are zero. The normal `.text`, `.rdata`, `.data` sections, extensive
readable symbols and direct instructions support an unpacked build. No packer
was detected; absence is a static inference, not an exhaustive packer test.
The runtime is **Open Media Toolkit 2.0 DR4**. DLL assertion paths literally name
`C:\Open Media Toolkit 2.0 DR4\Sources\OMTClasses\...`, including graphics,
database, compression and DirectX implementations. `OMT2Old.dll` is byte-identical
to `OMT2.dll` (SHA-256
`3ec41ead011adf56387a6dbd4580e5b5a9721b5f8020c8a56420f42824354943`).
Neutron SHA-256:
`f5281076e1a2492f2d61f87aae3f4544b6d0f535ebe33f9fbb6f78710fe1aea8`.
Five EXE variants have distinct hashes; filenames imply software/HD/no-CD behavior
but no behavior should be assigned solely from filenames.
## Dependencies and system boundaries
Neutron imports the OMT DLL and Win32 USER32/KERNEL32/ADVAPI32; consult the
generated PE inventory for full lists. The DLL imports DirectDrawCreateEx and
DirectDrawEnumerateA from DDRAW, DirectInput8Create from DINPUT8, DSOUND ordinal1,
WINMM PlaySoundA, USER32, GDI32, COMDLG32, KERNEL32. Direct3D is obtained through
COM rather than a D3D8 import; see [graphics.md](graphics.md).
The engine has named exports for database objects, shape and morph animation,
collision caches, sphere/triangle picking, light/material state, world updates,
sound channels, event manager and periodical dispatch. These exports are useful
evidence and stable starting points, not complete recovered game logic.
## Initialization and loop map
| Module/address | Identified behavior | Evidence |
|---|---|---|
| EXE 0x4802F2 | CRT entry | PE header, MSVC CRT setup |
| EXE 0x4789B0 | WinMain wrapper | CRT calls it with four WinMain args at 0x4803BB; stores OMT start info, sets current directory, calls 0x46A4A0 |
| EXE 0x46A4A0 | Application bootstrap | Calls window existence/dialog code, creates CAweReal and CGfx objects |
| DLL 0x100218A0 | OMediaApplication::start | Repeatedly invokes OMediaPeriodical::devote_time until application byte +0x18 is true |
| DLL 0x10060720 | OMediaPeriodical::devote_time | Named export; dispatch list must be analyzed further |
| DLL 0x100215C0 | OMediaAnimPeriodical::spend_time | Sends messages -604 for logic, -605 for animation/render dispatch |
| DLL 0x100F9B10 | OMediaWorld::update_logic | Uses timer at world+0x48, pause/max/min-period controls, dispatches update_elements with float elapsed |
| DLL 0x100F9C80 | OMediaWorld::update_elements | Named export, recursively dispatches element logic |
| EXE 0x47E470 | Reset game performance timer | QueryPerformanceCounter into 0x696018 |
| EXE 0x47E490 | Elapsed time in seconds | (counter-lastCounter)/frequency, updates lastCounter when nonzero |
| EXE 0x47E4F0 | Game frame callback | Calls timer via virtual slot 0xD4, stores seconds at 0x696030; only processes `0 < dt < 1` |
QueryPerformanceFrequency IAT is EXE 0x48D0BC, frequency global 0x696020.
QueryPerformanceCounter IAT is 0x48D0B8. Engine GetTickCount exists separately.
The frame callback forwards seconds to 0x479BC0, 0x462A20, 0x4693A0, 0x47D8F0
and 0x477DB0. Their exact roles require further call graph analysis. Timing is
mixed: time-based motion plus per-call speed increments, so a proposed fixed
simulation rate is a compatibility choice until the original cadence is observed.
## Player class and recovered movement evidence
MSVC RTTI identifies C3DJimmy, derived C3DPlayer/C3DAnimated/C3DObject and OMT
classes. C3DJimmy type descriptor: **0x4EEFF8**; main game interface vtable:
**0x4A373C**, object displacement **0xC0**; OMT element vtable at **0x4A3BDC**.
The unusual multiple inheritance means offsets below explicitly distinguish
complete object pointers from game-interface pointers.
| Address | Behavior |
|---|---|
| 0x422AC0 | C3DJimmy::InitObject (embedded exact debug label) |
| 0x422D30 | Jimmy object event/message handler; identified from vtable but exact name unverified |
| 0x424600 | Jimmy per-frame update, game-interface virtual slot 0x3C4 |
| 0x426030 | Jimmy input/movement handler, game-interface slot 0x3CC; calls base 0x438A60 |
| 0x438A60 | Player movement-mode dispatcher; mode0 invokes walking, mode1 no action, mode2 flying, mode3 seated |
| 0x438BC0 | Walking handler; receives complete object pointer, `float dt` |
| 0x437C40 | Applies player speed/turn to world velocity; receives complete object pointer |
| 0x437740 | Sets default follow-camera offsets/scales (complete object pointer) |
| 0x472980 | Rotates local point by object Euler rotation then adds object position |
Complete-object fields from C3DPlayer constructor and walking usage:
| Offset | Initial value | Confirmed use |
|---|---|---|
| +0x6BC | 30.0f | Speed increment per input invocation |
| +0x6C0 | 35.0f | Speed decay per invocation with no movement input |
| +0x6C4 | 600.0f | Speed cap |
| +0x6C8 | 0.0f | Current speed |
| +0x6D4 | 0.0f | Current turn rate, later multiplied by dt |
| +0x7C8,+0x7CC,+0x7D0 | 0,200,-350 | Camera local follow offset |
| +0x7D8,+0x7DC,+0x7E0 | 0,80,0 | Camera local look target offset |
| +0x854,+0x858,+0x85C | 1.6,1,1.6 | Camera interpolation coefficients |
**Correction to a preliminary investigation hypothesis:** -350 at +0x7D0 is
camera offset, not gravity. Do not use it as a physics constant.
Walking input uses global booleans 0x50985D/0x50985F for left/right and
0x50985E/0x509860 for forward/backward, plus analog axes. The precise mapping
is inferred from signed +/- turn behavior and must be checked against input
assignment code. Left/right branches set turn contribution +/-1000, adjust a
local angle by +/-20 and increase speed by30 capped600. Forward also adds30.
No movement input decays speed by35 toward0. These changes omit dt deliberately
in the original. Forward plus turn can increment twice; don't simplify silently.
The application uses 16384 angular units per revolution (mask0x3FFF); conversion
from degrees multiplies by float45.5111122 at EXE 0x48E5E8, followed by x87-to-int
conversion0x47F940. Original trigonometry uses OMediaCosSinTable, 16384 floats per
sin/cos array with cosine base offset0x10004. Position is X/Y/Z with Y vertical,
matching follow-camera local offset and level placement data.
Walking follow-camera logic is in 0x4395CF–0x4398E4. It rotates local offsets,
subtracts prior target positions, applies dt-dependent interpolation, adds to
global viewport position at `[0x509A50]+0x44`, and computes viewport angles. This
is richer than a rigid chase camera; a simple chase camera is an approximation.
Random behavior at0x438D52 uses wrapping uint32 LCG
`seed = seed * 1664525 + 32767; value = seed >> 16`. Verified from instruction
sequence; seed object pointer is global0x509A40. This differs from MSVC rand().
## Reproducible tooling and next work
From GamePort:
```sh
python3 tools/binary/pe_inspect.py ../Original/Neutron.exe
python3 tools/binary/pe_inspect.py ../Original/OMT2.dll --symbols 'render|update_logic'
python3 tools/binary/rtti_map.py ../Original/Neutron.exe C3DJimmy
objdump -d -M intel --start-address=0x438bc0 --stop-address=0x4398f2 ../Original/Neutron.exe
```
Generated complete PE inventories/disassemblies are cached under ignored
`artifacts/binary/`; regenerate with the commands above rather than versioning
the full dumps. Read-only parser output was cross-checked against objdump header,
import and named-export results. Full physics/collision, jump impulse, cadence,
AI, save/load and dynamic initialization remain unresolved. Next investigate the
game-object dispatch0x479BC0, shared physics collision function via game slot0x130
in0x462520, input assignment and compare a copied original in isolated Wine.
## Follow-up evidence preserved by primary integration
The last agent updates below refine earlier unresolved fields. General physics
arithmetic is implemented/tested separately; the full controller is not recovered.
- Generic gravity initially (0,-5000,0) at `0x478D50`; CJimmyGame initialization
`0x44D414` overrides it to **(0,-800,0)**. World physics dispatch `0x479BC0`
calls per-object `0x479D20`. At `0x479EBB..0x479EF2`, queued impulse is added
to velocity and cleared; then object acceleration*dt and gravity*dt are added,
and updated velocity*dt becomes displacement at `0x479F8D` onward.
- Jump branch `0x438397` selects JUMP; `0x4383B3` queues impulse (0,550,0) via
interface slot0x28C. **Gravity -800 alone is not the full player jump model.**
Air handler `0x437F90`, branch `0x438148`, sets extra accelerationY to
`gravityY*1.33f-gravityY` when jump state<3, producing approximately -1064
total acceleration. Constant `0x4AFCE4` is float1.33000004. Other air states
use 0.1/0.3 factors and require further tracing before implementation.
- Jump-held predicate `0x42A730` includes right mouse/Insert/Shift/numpad0 and
controller/gadget gates. Mode dispatch `0x437A8C`: state0 requires grounded;
jump queues impulse and state1; release state1->2; holding0.4s can enter
state3 with jetpack gating. Exact landing/retrigger table is still unresolved.
- Walking +/-20 affects destination yaw through `0x472660`; `0x43A430` smooths
wrapped Y-angle difference by `dt*3.7`. Forward vector at `0x472B10` for
zero pitch/roll is **(-sin(yaw)*speed,0,cos(yaw)*speed)**. Ground motion
`0x437C40` preserves vertical velocity. A right vector (cosYaw,0,sinYaw) is
scaled by `(turnRate*(1-friction)*speed/45 + keyboardStrafe)*dt`, with strafe
+1000 left / -1000 right (`0x4391B1` / `0x439226`). Friction source and full
state gates still require recovery; a simple tank controller would differ.
- Key state array `0x509838` is indexed by Windows key code; handlers `0x46A360`
and `0x46A380` set/clear it; consuming function `0x46A3E0` clears on read.
- C3DJimmy::InitObject `0x422C96..0x422CB0`: texture slot0 uses **jimycarl.png**
(stringVA `0x4EEAC4`), slot1 uses **jimyshock.png**. Inferring normal texture
from neighboring strings alone was incorrect and has been corrected.
Original execution was subsequently attempted in an isolated Wine copy; see
`../reference-testing.md`. No usable original gameplay frames are verified yet.