Files
Neutron/docs/reference-testing.md
T

102 lines
6.4 KiB
Markdown

# Original reference testing
Originals are never executed in place. `tools/recon/reference_capture.py` copies
Original to ignored `artifacts/reference/game`, then launches official Wine 11.0
in bubblewrap with all namespaces unshared, no network, a minimal read-only host
filesystem, and writable generated work/prefix only. Original paths and home are
not mounted. Xvfb runs inside the namespace; ImageMagick captures its root window.
Return key injection is optional. The new port has no Wine dependency.
Local WineHQ Ubuntu noble stable amd64/i386 packages were downloaded separately,
verified against official index SHA-256 and extracted under `.tools/wine`. The
wrapper also needs `.tools/native/usr/bin/Xvfb`, bubblewrap, xkbcomp, ImageMagick,
32-bit Wine runtime libraries and an appropriate Wine graphics backend. Mesa
software-driver dependencies are kept project-local. Network namespace creation
needs scoped tool escalation in this environment; no host installation is used.
Reproduce (Linux host with those tools):
```sh
python3 tools/recon/reference_capture.py --seconds 24 --enter --debug
```
The supplied NeutronNoCD.exe was launched in the isolated copy and created its
1024x768 'Jimmy Neutron' window. Initial captures were uniform white. Debug logs
show Wine DirectDraw/Direct3D initialization failing to find a suitable GL pixel
format, then failing to allocate a 3D-capable surface (0x8876086a). These captures
are **not usable gameplay references**. Original timing, startup, cutscene,
lighting, camera, collision and audio have therefore not yet been compared.
The wrapper records screenshots, Wine/Xvfb logs, window tree and isolated process
list, all locally under artifacts/reference. An alternate Wine Vulkan backend is
also tested with `--wine-renderer vulkan --output artifacts/reference-vulkan`.
It created a Vulkan device/window but logged unsupported fixed-function states
and a requested swapchain image count1 outside the driver's supported3..16 range.
Those frames are also unusable. Failures must not be treated as original behavior.
No native Windows installation/VM or Windows 98 image was available in the initial
environment/tool inventory. A local reference machine remains necessary if Wine
cannot render correctly. Native Windows port execution remains separately untested.
2026-11-06 follow-up: a fresh generated prefix initially lacked Wine builtin
modules; missing files were copied only from the already-installed local Wine
tree. Missing32-bit EGL/GBM/Wayland libraries were downloaded into the local cache
and extracted under `.tools/native`, without a system installation. The supplied
HDnoCD variant then creates its window without the earlier GL-context failure,
but frames remain black. The normal Return/focus check and optional
`--managed-desktop` (isolated `dbus-run-session`/xfwm4) do not establish playable
startup. This is a different observed failure boundary, not a usable reference.
Canonical Neutron/HD also encounter a CD prompt; no executable patch is applied.
[Read-only state observer](gameplay/original-state-observer.md) now supports a
verified copied-original launch or attach. Its Wine32 attach smoke passes928
samples and leaves the original running. Only MAIN, no Jimmy, was observed;
native Windows Carl skip/return remains unverified. Variant identities, mappings,
probe build/log hashes and setup details stay local in
artifacts/original-state-observer/ and artifacts/jimmy-skip-original-sw/.
`--probe-arg=VALUE` forwards repeatable generated-probe arguments, including
option-shaped arguments, and `probe-identity.json` binds the executable hash and
arguments before capture; a changed probe hash invalidates the observation.
## Preliminary Windows-port smoke under Wine64
`python3 tools/recon/reference_capture.py --port-smoke --seconds 24 --debug`
mounts only the self-contained Windows package in a fresh filesystem/network
namespace, with its own win64 prefix. The runtime, assets, shaders and scene data
all come from that package; the source, SDK and Original directory are not mounted.
The new port calls Vulkan directly and does not use Wine's legacy D3D backend.
The Windows x64 .NET10.0.13 executable decoded LV1B, loaded original lab/character
resources and rendered two offscreen frames through lavapipe, exiting0. This test
disabled Vulkan validation and **does not** establish Windows-driver validation,
SDL window/audio/input functionality or native Windows compatibility.
At checkpoint670adb4 and fixed morph time0.05, its PPM GPU readback was byte-identical to the native Linux
package readback (SHA-256 `c30bcbc95d00ce104b146cc46c84e9a9d50849bf0b0bf33c027a402bb46e47c4`).
Both use the same software Vulkan driver. This establishes consistency between
those two package executions, not fidelity to the original game.
An initial harness configuration disabled mscoree for the legacy game and thereby
prevented Wine from loading the port's IL-only System.Runtime.dll. Port mode now
uses Wine's built-in mscoree, correcting the test environment; no app workaround
or Mono runtime is required. Logs/readback are in artifacts/windows-smoke/.
After the user-reported floor/idle issue, the rebuilt Windows package also passed
`python3 tools/recon/reference_capture.py --port-window --seconds 12`: six windowed
frames, preview correction+38.503Y, injected key2 switched to Run cycle, and
960x720->800x600 resize succeeded, exit0. This Wine test disabled validation; Linux
tests separately enabled Khronos validation and reported zero errors. The latest
artifacts/windows-smoke contains that updated window test, superseding the earlier
headless capture. Native Windows retesting is still pending.
The controllable lab checkpoint supersedes that capture with
`python3 tools/recon/reference_capture.py --port-walk --seconds 60`.
The rebuilt self-contained Windows package rendered240 windowed frames under
isolated Wine64, received SDL arrow/Shift events, jumped/landed, resized800x600,
and exited0. Travel1250.12, maxrise137.62, one jump, two landing transitions and
final grounded feet `(4524.3555,0.62445164,-280.2899)` match Linux replay statistics.
The extra landing transition is stepping off/recontacting source geometry; it is
not a second jump. Validation was disabled in Wine. Logs/readback now live in
`artifacts/windows-smoke/`, with harness summary `artifacts/walk-wine-test.log`.
This validates preliminary port compatibility only; native Windows movement and
original-game movement/collision/camera comparison remain outstanding.