234 lines
14 KiB
Markdown
234 lines
14 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: gameplay gadgets; collision recovery is parked.** 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.
|
|
The user requested this change after milestone35a2a66/0272f7b. Gadget work uses
|
|
original controls, state and assets; the collision checkpoint remains available
|
|
to resume after this gameplay work.
|
|
VR04 and the bounded VR01/VR07 tutorials use recovered static body response/support/friction with original-code
|
|
numeric references. Lab/outside retain the capsule until special contacts and
|
|
dynamic collision are recovered; see [body implementation](docs/checkpoint/collision-body-implementation.md).
|
|
|
|
**Current milestone: Baseball, Bubble, Invisible, shrink ray and their gadget screen.**
|
|
Tab/Space selects owned gadgets and their practice levels; the default device
|
|
fires on Enter/Ctrl/left mouse and supports actual VR04 soldier shrink/restore
|
|
with original morphs and score effects. Invisible uses the recovered recharge,
|
|
activation, blend flash, meter and cleanup rules; full enemy sensing/combat and
|
|
other gadget effects remain incomplete.
|
|
See [gadget implementation](docs/gameplay/gadgets-implementation.md) for recovered
|
|
rules, modern policies and the verification boundary.
|
|
The [Invisible continuation](docs/gameplay/invisible-implementation.md) records
|
|
the later implementation and shared energy-warning sounds.
|
|
The [Bubble continuation](docs/gameplay/bubble-implementation.md) adds its source
|
|
controller, original sprite, automatic/high bounces and VR01 floor behavior.
|
|
The [Baseball continuation](docs/gameplay/baseball-implementation.md) adds hold/
|
|
release aiming, original ball/TIME art and VR07's moving targets and trophy gate.
|
|
|
|
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, Tab to switch General/Player/Systems
|
|
pages, 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). Player/System pages add movement and
|
|
jetpack state controls, camera obstruction, audio category mutes, objective/practice
|
|
controls and checkpoint save/load. **F3** toggles noclip: WASD moves/strafe, arrows
|
|
move/turn, Space/E rises, Ctrl/Q descends and Shift triples flight speed. Noclip
|
|
bypasses collision and contact triggers; reset or a new level disables it.
|
|
F1→Player also grants/selects Invisible, unequips it, and shows its timers and
|
|
targetability state. After selecting Invisible, allow7 seconds to recharge, then
|
|
fire without jump to activate for7 seconds at a fixed2-energy cost (tutorials
|
|
are exempt). Its last3 seconds flash before normal rendering returns.
|
|
F1→Player can also Give/Select Bubble. **Up or primary fire** accelerates, arrows
|
|
steer, and holding jump makes higher bounces. Tab/Space first unequips it; the
|
|
original sprite fades afterward. VR01 uses source body/floor rules; lab/outside
|
|
collision remains provisional.
|
|
F1→Player also has **Give/Select Baseball**. Hold **Enter/Ctrl/left mouse** to
|
|
aim, use **Up/Down** to change elevation and **Left/Right** to turn, then release
|
|
fire to throw. Practice on its owned tile opens VR07. The twenty-ball pool,
|
|
target respawn and original aim display are implemented; full enemy combat and
|
|
original dynamic contact scheduling remain incomplete.
|
|
|
|
**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 lab pickup is the combined **shrink ray and jetpack** (inventory item3).
|
|
Hold **Enter, Ctrl or left mouse** to fire the continuous ray; release to stop.
|
|
Grounded firing stops forward motion. Eligible original Yokian soldiers can be
|
|
shrunk for30 seconds, awarding10 points. Their authored shrink animation holds
|
|
its small endpoint; complete enemy AI/combat remains unimplemented.
|
|
|
|
**Tab or Space** opens the original gadget screen; with another special gadget
|
|
equipped, the first press unequips it. Use the mouse or arrows to point, then
|
|
Enter/Ctrl or a mouse button to select. Escape or Return closes the screen.
|
|
Practice Mode followed by an owned gadget enters its original tutorial directly.
|
|
The screen scales uniformly on widescreen and pauses port gameplay while music
|
|
continues. Other gadget selection art is present; the remaining special behaviors stay
|
|
future work. F1's jetpack availability control also controls shrink-ray ownership.
|
|
|
|
The pickup's original objective calls its jump action 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.
|
|
|
|
Native reverse engineering uses the local REA/Ghidra launcher separately from
|
|
runtime builds; see [local analysis setup](docs/rea.md). Current source-backed
|
|
cutscene control/body phase findings are in
|
|
[control-phase implementation](docs/checkpoint/control-phase-implementation.md).
|
|
The collision continuation adds a probed
|
|
[source sphere kernel](docs/checkpoint/collision-response.md) and integrates the
|
|
[overhead response](docs/checkpoint/ceiling-wrapper.md); full capsule replacement
|
|
and [shared camera handoff](docs/checkpoint/camera-handoff.md) remain open.
|