TEAM Nyorai Patcher
===================

For players and romhackers: The options in TEAM Nyorai Patcher are not just for changing how a
game plays. They are also meant to give romhackers a solid base of tools from the very start (a
documented ROM layout and manifest, a utility library, fonts and symbols, an on-screen overlay,
saves to .srm files, freeze / frame step and speed control, MSU-1 music, SA-1, SuperFX headers)
so that hacking a game, by hand or with AI, is easier and faster.

Run TeamNyoraiPatcher.exe. Nothing to install; keep the "lib" folder next to it (the game
database and the command-line tool live there).

1. Open NES ROM...   pick your own NES ROM. The patcher recognises the game and builds the
                     TEAM Nyorai SNES port from it. Wrong file? It tells you which dump to look for.
2. Choose options    Switches, Controls, Splash & Sound, Fonts & Symbols, Music (MSU-1).
3. Output            Save the SNES ROM (.sfc) or a BPS patch of your choices.

Romhackers: Switches > Extras > "Utility functions & engine reference..." documents every
utility-library function and the engine (trampolines, the .srm save API, memory map, ROM layout...).

Command line: lib\tnp.exe (run it without arguments for help).
Also available for Linux (one .AppImage) and in your browser: https://teamnyorai.com/
No ROM data ships with the patcher: each port is a patch against your own NES ROM.

Every item in the app
=====================
The desktop app (Windows, Linux) and the web patcher have the same items, in the same places (the
web version has no Help menu, and saves go to your browser's downloads instead of a save dialog). A
port's own switches decide which items appear: a switch the loaded ROM doesn't have is hidden, and
tabs it has no tables for (fonts, music) stay greyed out. Until a TEAM Nyorai ROM is loaded only
Info and Output open.

Top buttons
-----------
- Open NES ROM...: Pick your own NES ROM. The patcher checks it against the game database, applies
  the game's base patch and loads the SNES port it builds (nothing is saved yet). The same game data
  with a different iNES header is accepted (the expected header is used). A ROM that isn't a
  supported dump opens a Wrong ROM box that names the dump to look for and shows your file's sizes
  and hashes; Copy details puts them on the clipboard.
- Open SNES port...: Open a TEAM Nyorai .sfc built earlier (by this app, the web patcher or a BPS).
  Every setting is read back out of the ROM, so you can change it and save again. Ports carry a copy
  of the NES ROM they were made from, so a BPS can be made without the NES file. A 512-byte copier
  header is removed. A SNES ROM that isn't a port says what it is (its header title and hashes).
- Apply patch file...: Works with any BPS or IPS patch and any ROM, like Flips: pick the ROM, pick
  the patch, choose where to save. If the result is a TEAM Nyorai port, the app offers to open it.
- teamnyorai.com: (the blue link at the right end of the button row) Opens the TEAM Nyorai website
  in your default browser: releases, downloads, the web patcher. Desktop app only.
- Help > About: The version, the TEAM Nyorai banner and Play (the banner and its stamp sound again).
  Desktop app only.
- The line under the buttons shows the loaded port and where it came from; the status bar at the
  bottom reports each action (saved, patched, chip changes, the ROM's size).

Info tab
--------
Everything about the loaded ROM, as it would be saved now: the SNES header (title, map mode,
cartridge, ROM size, SRAM, region, version, checksum), the ROM's hashes, the TEAM Nyorai manifest
(spec, table layout, flags, switches on, palette slot, chip, fonts, splash sounds, MSU-1, where the
content ends and the smallest valid size), the source NES ROM (expected SHA-256, the embedded copy,
the file in use and its iNES header), and every game in the database with its dump name, other
names, hashes with and without the header, the cartridge and the base patch. Copy all copies the
page as plain text (for a bug report or a forum post).

Switches tab
------------
Each switch explains itself in its tooltip; hover a switch on a loaded ROM to also see that ROM's
own notes.

[Controls]
- Soft reset (L+R+Select+Start): Hold all four on pad 1 to go back to the title (a warm reboot).
- Freeze / frame step (L+R+Select): Hold the chord to freeze the game; while frozen, tap Select to
  advance one frame.
- Speed control (L+R+Start+X/Y): X = faster, Y = slower, in steps: 1/10, 1/4, 1/2, 3/4, 1x, 1.5x,
  2x, MAX (about 2x, the CPU's ceiling). Plain L+R+Start still reaches the game.
- Save / load (L+R+X / L+R+Y): Saves the game's progress (not a save state) into the cartridge's
  battery save, the .srm file: next to the ROM in emulators, /sd2snes/saves/ on the FXPak Pro. L+R+Y
  loads it back. Copy the .srm to back up or move saves. Works on SA-1 builds too.

[Extras]
- Debug stage select (Y+Start on the title): An easter egg: hold Y and press Start on the title for
  the debug stage select (Mega Man: the Wily stages, invincibility, infinite energy).
- Symbol / font viewer (X+Start on the title): Browse the fonts and symbols built into the ROM on
  the console: Left / Right change pages, Start goes back to the title.
- Utility library (for romhacks): Turns on the engine's library of utility calls for hack code
  (lib_call).
- Diagnostics overlay: Shows engine counters on the top band of the screen.
- MSU-1 music (your own tracks): Plays the songs you add on the Music tab through MSU-1. It switches
  itself on when you choose a song and off when you clear the last one. Without it the NES music
  plays.
- Utility functions & engine reference...: Opens the romhacker documentation window: the Functions
  tab lists every utility-library call the loaded ROM has (id, name, parameters, results, what it
  does) with a Search box; the Engine reference tab covers the trampolines, the .srm save API, text
  and the overlay, the hack registry, the memory map, the ROM layout and manifest, player chords,
  splash, MSU-1, palette tables and the coprocessor chips. Copy all as text copies both. (The same
  text is in Romhacker reference below.)
- Game Genie codes: NES Game Genie codes, one per line (6 or 8 letters). Each code is checked as you
  type and shows what it does (a tick or a cross with the reason). They are written into the ROM /
  BPS when you save, so they work on real hardware without a cheat device. 8-letter codes only patch
  where the original byte matches; a code that lands on something the port itself changed is not
  applied (and says so).

[Accuracy]
- NES sprite limit (8 per line): Authentic NES sprite flicker. Off = no flicker.
- 4bpp tiles (Mode 1): A hack-friendly 4bpp graphics mode: two spare colour planes per tile.
- PAL: run 1:1 at 50 Hz: On a PAL console, run at the NES PAL speed. Off = speed-corrected to 60
  game frames per second.
- Deterministic boot: A cold boot clears all WRAM, so every start is identical (TAS, replays).
- Silence (no audio): Mutes the sound chip.

[System]
- FastROM: 3.58 MHz ROM access (needs 120 ns ROM; every flash cart has it). Off while a coprocessor
  chip is set.
- NES palette: Which of the ROM's 8 NES-to-SNES colour tables the game uses. Slot 0 is the canonical
  one.
- Chip: For romhacking: writes a coprocessor cartridge header so the ROM starts on that board (FXPak
  Pro and emulators). Choices: None, SuperFX (GSU-1), SuperFX 2 (GSU-2), SuperFX 2 Rev 1
  (GSU-2-SP1), SA-1. It does not make the game faster: the chip only works when a romhacker's own
  code uses it (on SA-1 the port's helper runs utility calls 83-90). SuperFX turns FastROM off and
  limits the ROM to 1 MB (GSU-1) or 2 MB (GSU-2). Saves keep working on every chip. None undoes it
  exactly. See SuperFX chip and SA-1 chip below.

Controls tab
------------
- Preset: Fills in all 12 buttons at once: Standard (B jump, Y fire, A / X turbo), NES layout (B =
  NES B, A = NES A), Turbo on L / R, No turbo. (as in this ROM) shows the current mapping.
- SNES B, Y, Select, Start, Up, Down, Left, Right, A, X, L, R: What each SNES button does: NES A,
  NES B, Select, Start, Up, Down, Left, Right, Turbo A, Turbo B or (nothing).
- Turbo cycle: 2-60 frames per press; the presses-per-second figure is shown next to it.
- Chord hold: 1-255 frames (default 30): how long the freeze / save / load chords must be held
  before they act.
- Engine chords always read the raw buttons, so remapping never breaks them; L+R stay the chord
  prefix even when they are turbo buttons.

Splash & Sound tab
------------------
- Splash slot 1 (game clip), 2 (TEAM NYORAI banner), 3: Turn each splash screen on or off. Each game
  has its own opening clip; the banner and its stamp sound are shared. Start skips the splashes.
- Remove sound: Removes that slot's sound (the label shows with sound / no sound).

Fonts & Symbols tab
-------------------
- Page: Symbols (text codes 0-127), Symbols 2 (codes 128-255) and each of the ROM's fonts (ASCII
  32-127).
- Glyph grid: Click a glyph to edit it. The label shows its character, or its text code for a symbol
  ($01 + code).
- Editor: An 8x8 pixel editor: click or drag to draw, click a lit pixel to erase. Changes go
  straight into the ROM.
- Palette hint: Symbols only: the colour row the symbol is drawn in by default (current row, yellow,
  red, green, blue, cyan, orange, grey).

Music tab
---------
One row per song in the game (its name and id):
- Choose...: Pick your own WAV, MP3, OGG or FLAC for that song (any length).
- Loop from: For looping songs: tick it and set the second the song jumps back to when it reaches
  its end.
- Clear: Back to the original NES music.

Sound effects are not changed. When you save, the tracks are converted to MSU-1 .pcm files and
written beside the ROM / patch as <name>-<n>.pcm with an empty <name>.msu; keep them together (the
web version saves one .zip with all of them). Players without MSU-1 hear the NES music.

Output tab
----------
- ROM size: Smallest (cut the empty space), As it is, 2 MB (room for hacks) or 4 MB (largest LoROM).
  The current and smallest sizes are shown. 4 MB needs Chip = None; 2 MB isn't possible with GSU-1.
- Save SNES ROM (.sfc)...: Saves the port with everything you chose (switches, controls, splash,
  fonts, Game Genie codes, size), plus the MSU-1 tracks. The default name is TEAM Nyorai - <your NES
  ROM's name>.sfc in the NES ROM's folder.
- Create BPS patch (against the NES ROM)...: A patch anyone can apply to their own NES ROM to get
  exactly this configuration (checked by applying it before it is saved). A port opened without its
  NES ROM asks for it and checks it is the right one.
