nxnative-easy/docs/game-analysis.md

Optional original-game analysis with REA

The normal preparation flow still uses nxnative's rewriter, profiles and Metal translation chain. REA is an optional static-analysis companion, not a replacement compiler, an AI agent or automatic compatibility for unsupported games.

Desktop flow

1. Prepare your own game once, so its original NSO modules exist locally.
2. In the menu bar, choose Analysis tools → Analyze with REA.
3. Export for analysis converts the newest extracted original main NSO to an AArch64 ELF using the existing dm/tools/nso2elf.py. It does not analyze the rewritten host executable, run the game or edit the original module.
4. For native analysis, install/configure a compatible Ghidra, Hopper or IDA provider using REA's official instructions. The sheet can select an existing Ghidra folder directly, without relying on shell environment variables inherited by Finder. Provider version/native decompiler/Java requirements still apply; REA reports those failures.
5. Export and run REA creates a separate workspace and runs the official published CLI, pinned to rea-agents@6.8.0 with node@24.22.1. An existing npm bootstraps those exact packages into a game-local cache. It does not upgrade global Node/npm, register MCP servers or change your agent configuration.
6. Open the retained workspace to review main.elf, analysis.json, rea.json (Evidence when analysis succeeds), rea-stderr.log and instructions. Failed provider runs retain the ELF and diagnostics. Export-only needs no npm or REA.

The entry is optional and does not clutter game preparation. Provider products have their own installation requirements and licenses. This wrapper neither bundles nor automatically installs their engines. It requires a prepared game's local Python environment and dependencies; npm is required only to run REA.

Files and identity

Every run creates a new private folder under <game>/nxnative-tools/analysis/<unique-run>/, never overwriting a previous run. The manifest records Title ID, selected extraction package, original main NSO build ID, SHA-256 and pinned tools. It refuses mixed-title folders, symlink escapes and outputs outside the game's analysis area. Original game files, keys, saves and nxnative profiles are not modified or sent to GitHub. Keep all exported game code and Evidence outside the repository. Downloading tools requires network; this adapter passes only the exported ELF to the local REA CLI.

The newest extracted package is chosen numerically; adding an unprepared update file alone does not make it the analysis target. A script can export without running an analysis provider:

python3 scripts/analyze_game.py /absolute/path/to/your-game

Add --run to perform native analysis, and --provider ghidra, hopper or ida when several compatible providers are available. The UI uses REA's automatic provider selection. No setup command is invoked on the user's behalf.

How an agent uses the result

REA's CLI exposes an overview, functions, pseudocode, instructions and references through a local provider. Use the exported ELF and its exact build ID in a separately configured agent to investigate a specific function or hypothesis. Decompiled pseudocode does not restore the original Unity project, assets, variable names or complete source. Any proposed change still needs a build-ID-gated patch, rebuild and testing in nxnative before it can enter a game profile. Nothing here automatically patches, ports or publishes an unsupported title.

The project is morluto/rea, published as rea-agents, under its MIT license. This repository integrates the external CLI; it does not vendor REA source.