nxnative-easy/AGENTS.md

Notes for agents

• This repository runs Nintendo Switch games natively on Apple platforms: the game's own code runs, rewritten only where Apple's kernel requires it. Thirteen games are playable on the iPhone: Super Mario Bros. Wonder (update 1.2.1, profile 010015100B514000), Fire Emblem Engage (update 2.0.0, 0100A6301214E000), Metroid Dread (update 2.1.0, 010093801237C000), 13 Sentinels: Aegis Rim (update 1.10, 01003FC01670C000), Super Mario 3D World + Bowser's Fury (update 1.2.2, 010028600EBDA000), The Legend of Zelda: Breath of the Wild (update 1.9.0, SDK 20, 01007EF00011E000), The Legend of Zelda: Link's Awakening (update 1.1.0, SDK 8, 01006BB00C6F0000) Super Mario Odyssey (update 1.4.1, SDK 7, 0100000000010000), Hades (update 1.0.38233, SDK 9, 0100535012974000), Hyrule Warriors: Age of Calamity (update 1.3.0, SDK 9.6, 01002B00111A2000), Fire Emblem: Three Houses (update 1.2.0, SDK 6.5, 010055D009F78000), Super Mario Galaxy (update 1.3.1, SDK 18, 010099C022B96000) and The Legend of Zelda: Tears of the Kingdom (update 1.4.3, SDK 20, 0100F2C0115B6000). Hades renders with Vulkan, which the host implements on Metal (dm/gfx/vk/hle_vk.m, profile key graphics vulkan). Age of Calamity is Koei Tecmo's KTGL engine: files in RDB archives, shaders as GLSLC outputs (shader_split.py idrk_shaders). Three Houses is KTGL too; 9 of its shaders exist only as compiles of the game's own GLSLC at run time, captured once on the Mac (profile key shader_glslc_capture). Tears of the Kingdom runs at 60 fps through an elapsed-time frame step (patch_nso.py FRAME_STEP_BUILD, profile key fps_target; 5 GB guest layout). Monster Hunter Rise (update 16.0.2, SDK 11.4.3, 0100B04011742000) is being ported too: RE Engine, files in KPKA PAK archives (shader_split.py kpka_jobs, shaders in SDF files), the base game an XCI, its GPU heap a 64 GB sparse virtual pool (hle_nvn.c vpool_*, a 4 KB page table the replay reads textures through); it runs on an iPhone at 30 fps from character creation into the opening in Kamura village. Super Mario Galaxy is the Wii game on NERD's Hagi layer (PowerPC code recompiled into main), renders with Vulkan, and generates its shaders at run time, which the NSP script captures on the Mac (profile key shader_vk_capture); its pointer is the touch screen in handheld mode (profile key op_mode). README.md is the player-facing page (games, packing, playing); docs/development.md has the internals, the script's options, building by hand, prewarm lists and per-game notes.

• Each game's constants and shader tables form a game profile in dm/games/<id>/, where <id> is the base game's title ID: game.tsv plus the tables and dmsh_chain.h. Mario's profile is 010015100B514000. Tools pick the profile with DM_GAME; make -C dm/host and build_ipa.sh pick it with GAME. There is no default game: set it every time (the tools stop and list the profiles otherwise). Put per-game values in the profile, not in code (dm/games/README.md).

• Per-build knowledge is keyed by the NSO build ID: rewriter cuts in dm/tools/patch_nso.py, the profile's build rows (the builds the NSP script accepts, and their display versions), and host behaviour that uses fixed module addresses checks module_t.build_id (from fixups.tsv; dm_main_build(), DM_D2R_BUILD for code inherited from D2R). When a new game build appears, carry addresses over with dm/tools/nso_fnmap.py and check them by disassembly; never let fixed addresses run on a build they were not found in.

• To analyse or port another Switch title, first run scripts/build_ipa_from_nsp.py on its NSP folder. With no matching profile, it writes a survey to <NSP folder>/<title ID>_survey/survey.md, then a provisional profile guessed from the game files (dm/games/profile_guess.py; <NSP folder>/<title ID>_build/profile/<title ID>/, found by the tools through DM_GAMES_DIR), with a short heap check on the Mac when the game has virtual address memory, and a best-effort IPA that may not boot. Then follow docs/agents (extraction, binary survey, host bring-up failure catalogue, graphics specifics, debugging recipes) and add a profile.

• Scripts the user runs live in scripts/ at the repository root (now build_ipa_from_nsp.py). Each one runs both in Spyder (F5, configured by the settings block at its top) and from a terminal (command-line options override those settings; non-zero exit on error). Tools that only agents or other scripts call stay under dm/.

• Game files, keys and anything extracted from them live in the game's NSP folder, never in this repository and never in the home folder (it is nearly full): the work folder <NSP folder>/<id>-work for extraction, runs and analysis, beside the NSP script's <id>_build/. Tool venvs and other large scratch data go on that drive too. Do not print key values.

• Language: everything is in English: README.md, docs, code comments, log messages, script output and other files. Red log lines (something unimplemented or wrong) start with [RED] . Text that must match a game's own Chinese data is written as escapes ("\xE8\xB5\xB7"), never as characters.

• After changing anything on the shader translation chain, run the chain procedure for each affected profile. The chain covers dm/gfx/tools/dmsh_*, Program.cs, the profile's shader_map.tsv / shader_facts.tsv / shader_pairs.tsv, and its nvn_* / shader_* keys. The procedure:

  1. Run dmsh_chain.py --header, which writes the profile's dmsh_chain.h.
  2. Rebuild the shaders (Mac and, with IOSOUT, iOS).
  3. Regenerate the profile's c1_full.tsv.
  4. Rebuild the host.

  The host only loads libraries of its own chain version. The translator is dm/gfx/tools/dmsh_xlate_bin, which matches dmsh_chain.lock; a fresh dotnet publish does not.

• iOS builds are unsigned IPAs that the user sideloads and tests; diagnostics come back as the app's Documents/log.txt. Do not sign or install builds on the user's devices.

• Commit only when asked, with git -c user.name=seedds -c user.email=ext6@xcra.ai commit.