# NBA Live 97 Recomp

A playable Windows recompilation project for **NBA Live 97 (USA), SLUS-00267**, using [PSXRecomp](https://github.com/mstan/psxrecomp). Build it locally from your own game disc image, play exhibition basketball, and explore optional graphics, loading, and animation improvements.

## Status

- **Working and playable on Windows.** Menus, starting lineups, tip-off, exhibition gameplay, shooting, and audio have been tested locally.
- The Release executable builds with Visual Studio 2022. OpenBIOS is supplied by the pinned framework.
- This is a hybrid runtime: the boot executable is translated into C, while loaded game code also runs through the framework's interpreter. The project does not recover the original developers' C/C++ source.
- Development is ongoing. Testing does not yet cover every game mode, team, or hardware configuration. The launcher and netplay are currently disabled.

## Game improvements

| Improvement | What it changes | Availability |
| --- | --- | --- |
| Court flicker fix | Corrects a skipped geometry instruction during interrupt handling that could make painted floor triangles disappear. | Included in the pinned runtime. |
| Higher-resolution rendering | 4x internal resolution draws gameplay at 2048x960 instead of 512x240, making the original court textures, lettering, and players clearer. | Optional `supersampling` setting; tested at 4x. |
| Reduced polygon wobble | Preserves fractional screen positions so the court moves more steadily as the camera pans. | Optional geometry correction; tested with 4x resolution and `pgxp_tolerance = 1.0`. |
| Smoother court markings | Keeps the original marking polygons while removing the extra rounded-coordinate line pass that creates uneven joins. | Bundled `nba97.smooth-court-lines` mod; opt-in, tested with 4x resolution and geometry correction. |
| Upscaled menu artwork | Supports locally generated replacements for quarter-length cards, yellow highlights, and all 95 random menu action photos. | Optional HD menu pack, generated from your own disc. |
| Faster data loading | Reduces the game's CD data-pause delays; the 1 ms experiment reached gameplay with no reported gameplay or audio issues. | Opt-in loading experiment. |
| Custom shooting motion | Generates a separate smoothed shooting variant and supports an in-game comparison with additional intermediate poses. | Opt-in animation experiment; timing remains under evaluation. |

These enhancements use the original game data supplied locally. Extracted assets and generated replacement packs are not distributed with the repository. The loading and animation experiments have limited playtest coverage and remain optional.

## What is tracked

Git tracks project code, build scripts, function-address seeds, symbol names, an example configuration, and the pinned framework submodule.

Personal configuration (`game.toml`, `game_options.toml`), disc paths, probe reports, disc images, extracted game files, generated game C, saves, logs, and build outputs stay local and are ignored. A fresh clone must generate its own game C from its own disc image.

## Clone

```powershell
git clone --recurse-submodules https://github.com/schulerj89/nbl-97-recomp.git
cd nbl-97-recomp
```

Requirements: Python 3.11+, Git, Visual Studio 2022 with C++ build tools, CMake 3.20+, and Ninja. The build script discovers Visual Studio automatically; an x64 Developer PowerShell can also supply the compiler environment.

## Configure locally

Supply a CUE with its referenced disc tracks available. The project's initial image was a single-track, unscrambled MODE2/2352 CloneCD image; its CUE descriptor was derived from its CCD metadata. Do not assume other images share that layout.

Run the framework probe with your own CUE path to write an ignored local config and extract the boot executable:

```powershell
$discPath = (Resolve-Path -LiteralPath 'path-to-your-game.cue').Path
python psxrecomp/tools/new_project_layout/probe_disc.py $discPath `
  --write-game-toml game.toml `
  --write-boot-exe disc `
  --disc-rel $discPath `
  --out-dir disc `
  --players 2 `
  --display-name 'NBA Live 97'
```

Check that the detected serial is **SLUS-00267** before building; the tracked seeds and runtime wiring target that release. `game.example.toml` documents the expected layout and initial disc identity, with generic relative paths. Actual disc filenames, fingerprints, and user preferences belong only in the ignored `game.toml`. The external disc must remain available while playing.

## Generate, build, and launch

```powershell
.\build.ps1 -GenerateOnly   # Generate boot-executable and OpenBIOS C
.\build.ps1 -SkipGenerate   # Compile existing generated C and the runtime
.\build.ps1                 # Generate and build
.\run.ps1                   # Launch the game
```

Output: `build-release/NBALive97_Recompiled.exe`. The project enables MSVC's required C11 atomics option for runtime C files.

## Development map

- `generated/`: local translated C and address manifest; regeneration can overwrite direct edits.
- `seeds/ghidra_funcs.txt`: initial function-address seeds, expanded as more code is identified.
- `symbols.toml`: named functions; run `python tools/sync_symbols.py` after editing.
- `mods/preloaded/packages/`: source manifests for bundled mods.
- `tools/disc_inventory.py`: reads the disc specified in local `game.toml` and writes `analysis/disc_inventory.json` without copying the image; currently expects MODE2/2352 sectors.
- `psxrecomp/docs/`: framework setup, execution model, debugging, symbols, and mod documentation.

The framework and its nested dependencies retain their upstream licenses and are pinned by Git submodule commits. This repository does not include the original game assets or generated game code.

## Readable frontend boot call

The generator reads `recompiler_overrides.toml` and emits the FEONLY.BIN boot
call directly as `nba97_boot_load_frontend()`. The helper in
`src/boot_frontend.c` compiles with the game normally; there is no generated-C
replacement step. The framework submodule pins our fork's emitter extension.
See [readable boot notes](docs/readable-boot.md) for the generation rules,
address mapping, timing constraints, and original-versus-replacement test.

## Local asset browser

```powershell
.\browse-assets.ps1
```

Opens Asset Studio at `http://127.0.0.1:9797`: a searchable file library on the
left, image preview and thumbnail selection in the center, and source details
and palettes on the right. **Image gallery** shows a grid of decoded graphics.
Use **Text** to find menu strings, **Hex** to inspect the first 4 KiB, and **PNG**
to download the selected preview. Arrow keys switch images; `/` focuses search.
Favorites are saved in this browser's local storage.

Reads your existing local `game.toml` and disc. Python 3.11+ is the only runtime
requirement for the image/text browser; no package install or game rebuild is needed. The first launch
generates previews under ignored `analysis/asset-browser/`; later launches reuse
them. The server stays on loopback and serves only its UI, catalog, and previews.
It does not modify the disc, game configuration, mods, or saves.

The current disc yields 9,273 image entries, with 9,269 decoded and four marked
unavailable. Counts include repeated assets and smaller texture variants.
The **Player models** view also previews 29 team model families, six front-end
motion clips, and 84 gameplay motion slots, with orbit controls, scrubbing,
part selection, and wireframe display. It requires the separate native model
exporter build. Inspection colors are used in place of the original player
materials. Motion clips can also be exported to Blender as animated shape keys.

See the [asset browser](docs/asset-browser.md), [player model viewer](docs/player-model-viewer.md),
and [Blender export](docs/blender-motion-export.md) pages for details.

## External HD menu image test

`./run-hd-menu-test.ps1` enables the local PNG replacement experiment for the
3, 5, 8, and 12 minute quarter cards, their yellow highlight, and all 95 random
action photos inside the menu cards. Generate the
complete pack with `python tools/build_quarter_texture_pack.py`; it extracts
the original disc artwork and applies Python/Pillow 4x Lanczos resizing.
Run `python tools/build_player_texture_pack.py` to generate the photo pack.
`-Original` runs a comparison at the same 4x internal
resolution. See [test setup and limitations](docs/hd-menu-test.md). Replacement
artwork is local and ignored by Git; no disc modification is needed.