Files
Neutron/README.md
T

173 lines
9.5 KiB
Markdown

# Jimmy Neutron reconstruction
Local reconstruction of the supplied **Jimmy Neutron: Boy Genius** installation
using C#/.NET 10, Silk.NET.Vulkan (Vulkan 1.3), and SDL3. Original files remain
untouched in `../Original`. Work is local; no remote operations or runtime online
services are used.
**Current direction: architecture recovery; feature expansion paused.** The
[checkpoint review](docs/checkpoint/review.md), [coverage map](docs/checkpoint/coverage.md)
and [implementation plan](docs/checkpoint/implementation-plan.md) compare source
owners, update order and lifecycles with the port. Clean69d0187 and its packages
are preserved locally as the playable baseline. Corrections now include task/Carl
callbacks, controlled player phase ordering, source static camera queries for the
first route and gadget availability through tutorial/return. Full scene scheduling,
collision and shared camera state remain incomplete.
**Current milestone: original lab story, interactions and jet pack practice flow.**
The runtime includes recovered camera/speech triggers, moving props, Carl/Goddard
patrol logic, pickups, objectives, the practice prompt, VR04 powered jumping and
checkpoint transitions. Collision response, timing and visual fidelity remain
provisional. The full game is incomplete; see [progress](docs/progress.md) and
[compatibility](docs/compatibility.md) for tested scope and remaining work.
## Build and run locally
From `GamePort/`, using an installed .NET 10 SDK or the already provisioned local SDK:
```bash
source scripts/env.sh
dotnet build
python3 tools/extractors/prepare.py --audio sounds musicsecretlab
dotnet run
```
The default starts the original secret lab (LV1B), including the recovered intro
camera/speech sequence. **Escape or Space** skips the current sequence and restores
control. **Arrows** walk/backpedal/turn; **Shift, Insert, numpad 0 or right mouse**
jump, and holding jump uses the jet pack after obtaining it. **O** opens/closes
the objective panel; new objectives slide in and disappear automatically. **R** resets the scene placement with current progression;
**C** pauses into inspection, **F11** toggles fullscreen, **Escape** quits during
ordinary play. Use `--skip-intro` to begin with control or `--mute` for silent play.
The lab camera sequence stops background music and DEFAULT restarts it when
control returns, including after skipping.
**F1** opens the debug menu and pauses gameplay and audio. Use Up/Down to select,
Left/Right to change values, Enter to apply, and F1/Escape to close. It includes
live diagnostics, camera switching, cutscene skip, energy refill, jet-pack grant,
SCENE task editing, all 33 prepared levels and their original startpoints, and
reset. Page Up/Down changes the staged SCENE value by 10.
The Force Control toggle keeps Jimmy controllable during scripted control locks. See
[debug menu controls](docs/debug-menu.md).
**F2** toggles a compact live debug overlay without pausing play. It shows frame
timing, position/velocity, movement, control/force state, tasks, camera/clipping
and error counters. F1 also has a Live Overlay toggle. Visibility stays selected
across scene changes during the session; `--debug-overlay` enables it at startup.
Level changes keep the same window and Vulkan renderer, preserving window bounds,
focus and fullscreen state. UI scales uniformly on widescreen: prompts/F1 stay
centered, objectives stay bottom-right and F2 stays top-left. Use
`--width 1920 --height 1080` for an initial window/offscreen size; resizing and F11
update UI placement and clicks.
The original lab pickup is internally tagged `shrinkray`; the original objective
art identifies it as the **jet pack**. Its practice prompt accepts **Y** or a click
on Yes to enter VR04, and **N** or a click on No to resume. Enter selects the
hovered Yes region, otherwise No. Practice RETURN restores Jimmy and Goddard to
the saved departure position, retains the lab start's yaw and suppresses its intro.
In the air, Up accelerates, Left/Right turn, and Down brakes horizontal motion. Source patrol/door logic is integrated, while
sensing, full collision response, alpha/lighting and audio effects remain incomplete.
`--load-save PATH` reads original TSK task/items/score/checkpoint state;
`--write-save PATH` writes that state outside the asset directory. This resumes the
saved STRT checkpoint; arbitrary current-position/complete game-state saving is
not implemented. `--start TAG` selects an original checkpoint for investigation.
Prepare all available scenes for other save files with
`python3 tools/extractors/prepare.py --all-scenes --audio sounds musicsecretlab`.
All35 GAM entity files are supplied;33 have matching OMT geometry archives.
Level3B.gam and Level3E.gam each contain the same four entities apart from their
level identifier. Their registered OMT archives are absent, but no incoming GAM
transition or supplied save selects them. Their use in normal gameplay remains
unverified; this is not an established blocker. The manifest records the absent
geometry without substitution. See [level resource evidence](docs/analysis/level-resource-mapping.md).
Use `--inspect` for the previous inspector: arrows/WASD orbit, plus/minus zoom;
1 idle, 2 run, 3 jump, 4 scratch preview. With no simulation, C toggles stored/orbit
camera. Idle is a still original pose. Exact actor pivot and animation state timing
remain under investigation; GAM/ASE source data is unchanged. Without a prepared
scene the app previews the Jimmy base model.
Headless verification on a machine with Vulkan 1.3 (Mesa lavapipe works):
```bash
dotnet run -- --headless --with-player --time 0.05 --screenshot artifacts/lab.ppm
dotnet run -- --headless --smoke-walk --screenshot artifacts/walk.ppm
dotnet run -- --headless --story --story-time 12 --screenshot artifacts/story.ppm
dotnet run -- --headless --skip-intro --write-save artifacts/checkpoint.tsk
dotnet run -- --headless --model ASE/jimstop.ase --texture png/jimycarl.png
dotnet run -- --audio artifacts/extracted/musicsecretlab/Wave_00000000_HuntingBuildupVar2_11k.wav --loop-audio
dotnet run -- --help
```
Explicit original paths can be supplied with `--assets /path/to/Original`.
`--scene` accepts generated scene JSON; `--level` accepts an original GAM relative
to the original root. Use `--walk` for an explicitly selected scene/GAM pair.
`--original-camera` uses its matching startpoint in inspection mode. Player
preview uses `--with-player` or `--animation path/to/animation.json`. Morph sample
interpolation is recovered; loop closure and playback speed remain preview policies.
If tooling is missing on Linux, `scripts/bootstrap.sh` downloads pinned official
SDK/SDL dependencies and obtains build tools using the existing Ubuntu apt index,
all under `.tools`. It needs network access for dependencies, Python 3.12+, CMake,
a C compiler and ordinary native runtime libraries. It does not install host packages.
Restore uses NuGet; subsequent builds/tests use local caches. The runtime needs
a Vulkan 1.3 driver/loader, plus X11/Wayland on Linux for visible windows.
## Test and package
```bash
scripts/test.sh
scripts/build-linux.sh
scripts/build-windows.sh
scripts/package.sh
```
After building, `scripts/test-window-transitions.sh` runs a local Linux fullscreen/
ultrawide regression using installed Xvfb, Xfwm, D-Bus and xprop.
The publish scripts perform equivalent self-contained publishes:
```bash
dotnet publish -c Release -r linux-x64 --self-contained true
dotnet publish -c Release -r win-x64 --self-contained true
```
Packages are local directories `dist/linux-x64` and `dist/win-x64`. Run
`launch-scene.sh` or `launch-scene.cmd`; append `--headless --frames 1` for a
render smoke test. They include the .NET runtime, SDL3 native library, SPIR-V,
original asset copies, all33 available prepared scenes, actor/UI resources, audio
and limitations.
Windows cross-publishing and preliminary headless Wine64 rendering are verified.
A user confirmed native Windows loading/rendering of the earlier checkpoint;
this story/tutorial update still needs native Windows input/physics testing. Full native Windows functionality is unverified.
These are investigation packages, not a finished game release.
`scripts/test.sh` runs Python regressions, native C# data/collision/movement checks,
all PNG/ASE decoders, source-backed interaction/AI/support/jetpack/UI checks,
actual Vulkan GPU readback, dummy-device SDL3 audio, and
original SHA-256 verification. Set `NEUTRON_WINDOW_TEST=1` with a working DISPLAY
to include injected keyboard and swapchain-resize verification. Full OMT audit:
```bash
python3 tools/extractors/audit.py ../Original --report artifacts/extracted/audit.json
python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json
```
## Investigation and continuity
Start with [AGENTS.md](AGENTS.md), [tasks](docs/tasks.md),
[reverse-engineering index](docs/reverse-engineering.md), and
[architecture](docs/architecture.md). Detailed binary/graphics/asset/gameplay
reports are under `docs/analysis`. `tools/extractors` contains bounded OMT/ASE/PNG
decoders; `tools/levels/gam.py` round-trips all original level records.
Original reference capture uses `tools/recon/reference_capture.py` with local
Wine/Xvfb, bubblewrap and ImageMagick. It executes a separate copy with no network
and no original-directory mount. Wine is for investigation only; the port does not
use Wine, DirectX or OpenGL. See `docs/reference-testing.md` for actual results.
All generated extraction output, local SDK/native dependencies, captures and
packages are ignored by the nested local Git repository. Never configure a remote,
upload assets, or overwrite the original installation.