Change archive¶
Dated notes written by the sessions that built Napple (2026-10-20 to 2026-10-26). They are the history of how and why each part came to be, kept unchanged. Notes can be out of date: for current behaviour read architecture, guides and reference; facts that were still true have been folded into those pages. Links inside a note point at the paths of the time and are not checked.
New change notes go in this folder as <date>-<branch>.md and get a line in this index.
Status words in the notes: verified (ran on a Mac), tested (unit test passed), unbuilt (never compiled on macOS), untested, proposed.
Build pipeline (Rust: ingest, rewrite, package, signatures)¶
| Note | Summary |
|---|---|
| 2026-10-20-ingest | Milestone 1: XCI/NSP containers, keys, NCA3, ExeFS and RomFS reading in napple-core. |
| 2026-10-20-decomp-plan | napple plan/decomp: base, update and DLC selection, NSO loader, rewrite-site scanner. |
| 2026-10-20-signatures | Shared signatures: schema, stores, matcher, resolver, REA adapter, opt-in share flow. |
| 2026-10-20-compat-matrix | Per-game, per-stage compatibility matrix (napple-compat) and NPDM/NACP parsers. |
| 2026-10-21-rewriter | Generic A64 NSO rewriter: x18, TLS registers and svc/counters through a host gate. |
| 2026-10-22-packaging | napple build: one-process pipeline to a locally signed .app, no Python. |
| 2026-10-24-claude-nsz-zstd-2026-10-24-plan11 | NSZ/XCZ ingest (zstd NCZ streaming and block forms). |
| 2026-10-24-claude-sysdata-firmware-2026-10-24-plan10 | Firmware data archives written to sysdata/ and served by fsp-srv. |
| 2026-10-26-claude-nx-rewriter-2026-10-26-nx | Rewriter correctness and size fixes from the nxnative review (jump tables and others). |
| 2026-10-26-claude-mk8d-64-2026-10-25-titles | MK8D update and DLC on the 64-bit path, in-place RomFS (romfs.map), A32 start-up faults. |
Runtime core, kernel and services¶
| Note | Summary |
|---|---|
| 2026-10-21-runtime-core | Game-agnostic native runtime: loader, Horizon kernel surface, IPC framework. |
| 2026-10-22-integration | Runtime, gfx, audio, input and frontend linked together; first rendered frames. |
| 2026-10-23-input-audio-runtime-round2 | Input remapping, transactional saves, frame pacing, settings overlay, packaged .app checks. |
| 2026-10-24-loader-kernel | Guest IPC, code memory, NRO loading, host1x channels, save data management (Linux-written). |
| 2026-10-24-services-unbuilt | 24 new HLE services and deeper commands, written unbuilt on Linux. |
| 2026-10-24-services-VERIFY | Verification prompt for the Mac session that builds the services branch. |
| 2026-10-24-claude-services-verify-2026-10-24-plan5 | Result of that verification: services build and tests on macOS. |
| 2026-10-24-applets-dlc | DLC mounting (aoc:u) and the error, player-select and controller applets. |
| 2026-10-24-applets-real | Software keyboard config parsing, controller applet answers. |
| 2026-10-24-claude-cloud-small-2026-10-24-plan11 | ncm as real in-memory tables, caps, audren performance metrics. |
| 2026-10-24-claude-tipc-dispatch-2026-10-24-plan8 | TIPC request dispatch in ipc.c. |
| 2026-10-24-claude-fonts-fallback-2026-10-24-plan7 | Placeholder shared font when system/fonts is missing. |
| 2026-10-24-cleanup-small-plan6 | Follow-ups of the services round: result-code constants and verification on a Mac. |
| 2026-10-24-guest-handle | AC "request on handle 0" abort: sm GetServiceHandle refusal over TIPC. |
| 2026-10-24-boot-crash | Module-init SIGSEGV that did not reproduce (no source change). |
| 2026-10-26-nx-kernel | Kernel, thread, input and service fixes from the nxnative review (same-core handoff and others). |
Graphics and shaders¶
| Note | Summary |
|---|---|
| 2026-10-22-graphics | libnapple_gfx first slice: NVN on Metal, native Maxwell to MSL translator, headless tests. |
| 2026-10-23-graphics-round2 | LAS white-out root cause (missing vertex format) and shared correctness fixes. |
| 2026-10-23-crash-and-gfx-round3 | LAS crash on leaving Marin's house, graphics backlog, SMO. |
| 2026-10-23-smo-round | SMO black world and deformed characters: command-buffer handle lifetime, crash fixes. |
| 2026-10-24-nvn-pipeline | Pipeline-build hang, more NVN entry points and pipeline features. |
| 2026-10-24-claude-nvn-getters-2026-10-24-plan5 | NVN getters/setters visible to the coverage scanner, transform feedback and GL-sync entries. |
| 2026-10-24-shader-isa | Maxwell ISA gaps (LDS/STS, TLD, TXD, atomics, VOTE and more). |
| 2026-10-24-shader-isa-INTEGRATE | How the shader ISA branch was landed. |
| 2026-10-25-nx-shader | Translator items from the nxnative review (VMNMX and others), SMO glitch triage. |
| 2026-10-26-nx-gfx | Animal Crossing window pass investigation; wrapped up early. |
| 2026-10-26-claude-gfx-correctness-2026-10-26-macos1 | gfx correctness (macOS-100% batch 1): command-list lifetime, block-compressed render targets, D24/integer MSAA, golden-frame harness, ACNH window-pass root cause. |
Audio, input, media¶
| Note | Summary |
|---|---|
| 2026-10-21-audio-input-frontend | The audio, input and frontend static libraries and their C headers. |
| 2026-10-24-audio-i3dl2-audin-review | I3DL2 reverb fixes, audin:u, audren review. |
| 2026-10-24-audio-small | audrec:u, svc 0x23, shader IMAD and LEA; reverb already present. |
| 2026-10-24-claude-media-h264-2026-10-24-plan5 | VideoToolbox H.264 decoder for the movie library. |
| 2026-10-24-h264-decoder-type | Decoder type to mime table read from the movie library. |
| 2026-10-24-verify-media-dlc | Scripted checks of H.264, DLC and a flaky guest Break. |
Game bring-up (Animal Crossing, Link's Awakening, Odyssey)¶
| Note | Summary |
|---|---|
| 2026-10-24-ac-boot-spin | Boot-thread spin on a never-signalled system event fixed, ngc:u added. |
| 2026-10-24-ac-games | Animal Crossing past its aborts, delta RomFS, DLC check. |
| 2026-10-24-ac-shaders | "Loading shaders" screen is not shader work: the game submits no shader. |
| 2026-10-24-claude-ac-boot-crash-2026-10-24-plan8 | AC v0 SIGSEGV from the NVN API version check. |
| 2026-10-24-claude-ac-services-2026-10-24-plan9 | Service blockers for Animal Crossing (fsp-srv 202 and others). |
| 2026-10-25-claude-ac-render-2026-10-25-titles | AC 3.0.3 main loop and first frames; Npad lifo reader loop. |
| 2026-10-25-perf-las-live | LAS slowdowns measured in live play. |
AArch32 (Mario Kart 8 Deluxe)¶
| Note | Summary |
|---|---|
| 2026-10-25-aarch32-core | The AArch32 CPU core (interpreter): why it is separate, status, plan. |
| 2026-10-25-aarch32-recompiler-plan | Measurements on the real game and the recompiler plan. |
| 2026-10-25-mk8d-recompiler | Ahead-of-time AArch32 to AArch64 recompiler producing a32jit.dylib. |
Studio and iOS¶
| Note | Summary |
|---|---|
| 2026-10-20-studio | Napple Studio (SwiftUI): key sets, drop zone, plan, build, compat banner. |
| 2026-10-22-studio-final | Studio driving the real napple build. |
| 2026-10-25-studio-redesign | One-window library design. |
| 2026-10-24-ios-support | iOS/iPadOS 26+ target: dylib modules, signing, IPA, install. |
| 2026-10-25-ios-sim-titles | The four titles on the iOS Simulator. |
Process, CI, reviews¶
| Note | Summary |
|---|---|
| 2026-10-23-cloud-session | First Linux cloud session: Rust workspace off macOS, rewriter fixes, gfx proposals. |
| 2026-10-25-nxnative-review | Review of the nxnative project: what Napple can take (review only). |
| 2026-10-26-nx-ci-docs | CI workflow, symptom index, subsystem reference, title notes, docs check. |
| 2026-10-26-code-slim | Slim batch: one-time clang-format/rustfmt pass, warnings and clippy to zero, dead code, TODO triage into docs/todo.md. |
| 2026-10-26-repo-hygiene | Slim batch: LICENSE and community files, README, tools/dev and tools/legacy, process archive, legacy projects removed. |
| 2026-10-26-docs-consolidate | Slim batch: docs restructured into architecture, guides, reference, process and archive; mkdocs site; docs check extended. |
| 2026-10-26-mac-slim | Slim batch (Mac): Obj-C and Swift warnings zero, smaller runtime, shader cache cap, napple clean, Makefile dependency tracking. |
| 2026-10-26-f64-isa | Bit-exact double precision (DADD/DMUL/DFMA/DSETP/DMNMX/DSET, 64-bit conversions) for the Maxwell translator and the 40-item rare-ISA audit. |
| 2026-10-26-claude-support-tables-2026-10-26-cloud2 | Generated support matrix, feature-support table and site JSON with a --check staleness guard. |
| 2026-10-26-claude-media-services-2026-10-26-cloud2 | nvdrv multimedia engines (NVDEC/VIC/NVJPG/MSENC) over a DecoderBackend, portable JPEG codec, caps album images, Vorbis/Opus movie audio (cloud, Linux-tested). |
| 2026-10-26-runtime-depth | Stub IPC rows become real behaviour with host tests: hid, bcat, audio, psm, lbl, settings, apm, pdm, pctl/aoc and part of spsm/ovln/ectx/fgm/olsc/time/ns/ncm/ngc. |
| 2026-10-26-shader-surface | SULD/SUST/SUATOM/SURED translated to Metal image calls, with the image binding contract. |
| 2026-10-26-mii-firmware | Mii data and services from the firmware (default Miis, shared Mii database, mii:u/mii:e), the real Mii Maker applet booted as a child process or in-process library. |
| 2026-10-26-claude-studio-redo-2026-10-26 | Napple Studio rebuilt from zero (Liquid Glass), iOS install/IPA export, per-title bundle ids, free/paid memory-limit rule; amiibo and IR camera tabs in the in-game overlay. |
| 2026-10-27-claude-render-scale-2026-10-27 | Render scale 10..800 %, output fit incl. integer scale, built-in upscaler (FSR-like, CAS), MetalFX fallback, budget, per-title rule table, two render-pass fixes found at non-1x scales. |
| 2026-10-27-claude-contributor-kit-2026-10-27 | Contributor kit: legal rules and DCO sign-off in CONTRIBUTING, issue forms, PR template, contributor guides, catalogue field reference, labels and Discussions proposal, issue-form check (cloud, Linux-tested). |
| 2026-10-27-claude-youtube-script-2026-10-27 | YouTube video kit under docs/media/youtube/: shooting script, call to action, shot list, titles/thumbnails/description. Docs only. |
| 2026-10-27-mod-framework | The shareable .napmod mod and fix format: IPS/IPS32/pchtxt patches, cheats, romfs overlay, config, shader files, trust model, napple mods CLI and the pre-rewrite apply hook (portable core, Linux-tested). |
| 2026-10-27-claude-small-gaps-2026-10-27 | Nine small catalog items: personalized tickets, IVFC verification, NCA2/NCA0, NCZ edge, audren performance history, audin sources/mic, GC/Palma/NES styles, irs rows, bcat provider (cloud, Linux-tested). |
| 2026-10-27-claude-ipc-depth-rest-2026-10-27 | 137 more stub IPC rows become real behaviour with host tests: offline (mm, friend, nifm, nsd, prepo, ssl, nfc), btm, hidbus, ldn, ns, ncm, sfdnsres, ngc, push. |
| 2026-10-27-fps-unlock-2026-10-27 | Present rate (fps_mode: game / display / custom / uncapped) decoupled from game speed: guest vsync and game clocks unchanged, vsync setting drives the layer, frame-trace gate. |
| 2026-10-27-claude-media-nvdrv-2026-10-27 | Vorbis out-of-band headers (on by default), nvdisp-disp0/1 query ioctls, nvdrv stub rows 7 -> 1, DecoderBackend ABI 1 frozen with SPS/PPS/vpcC hand-off for a VideoToolbox backend (cloud, Linux-tested). |
- 2026-10-27-tie-up.md: tie-up: one system data root, Studio Mii/Amiibo/Online panes, amiibo loader, Mii Maker host, camera/microphone entitlements, tools/e2e end-to-end run per title. |
|
| 2026-10-27-claude-content-real-2026-10-27 | NSZ/XCZ written by the nsz tool, NCA2/NCA0 after hactool, personalized tickets through Container::load: fixtures, round trips, and the XCI header offsets the real writer exposed (cloud, Linux-tested). |
| - 2026-10-27-claude-applets-host-2026-10-27.md: generic library applet host: handler registry, firmware applet table, interactive channel, swkbd inline, applet.c + applet_ae.c stub rows 84 -> 10 (tested on Linux). | |
| 2026-10-27-mod-glue-core | napple build --mods (patches before the AOT rewrite, manifest record, mod-set cache key, mods/overlay.json), runtime romfs overlay lookup in romfs_map.c, control.nacp in every data dir (cloud, Linux-tested). |
| - 2026-10-27-claude-shader-stages-2026-10-27.md: translator side of geometry, tessellation and transform feedback stages, OUT/VABSDIFF4/TXA/IMADSP (Metal-compiled on the Mac). | |
| - 2026-10-27-claude-small-catalog-2026-10-27.md: audren performance, npad style bits, IR tera/pointing processors, bcat layouts. | |
| - 2026-10-27-claude-ipc-depth-rest2-2026-10-27.md: remaining stub IPC rows (account, vi, ns, settings, offline, miiimg) and network rows through OnlineProvider. |
- 2026-10-27-claude-applets-rare-2026-10-27.md: HLE web / offline web and photo viewer / album library applets over the handler registry, applet_ui.h hooks (tested on Linux, unbuilt on macOS).
- 2026-10-27-kernel-threads.md: kernel-threads: timer preemption of spinning guest threads (SMO stall fixed), LAS save-commit race (0x35f202), post-mortem svc ring, ACNH load-only null deref documented.
- 2026-10-27-gfx-depth-views.md: ResolveDepthBuffer, depth/stencil texture views, SetSampleShading side table, SetDebugLabel, gfx warning fixes.
- 2026-10-27-claude-ios-candidate-2026-10-27.md: iOS Simulator profiling, memlog, handheld default on iOS, build_ios fixes (iOS-only code paths; guide
docs/guides/ios-device-candidate.md). - 2026-10-27-claude-fuzz-hardening-2026-10-27.md: seeded-mutation tests and cargo-fuzz / C fuzz drivers for the untrusted-input parsers; 26 findings fixed with regression tests (cloud, Linux-tested).
- 2026-10-27-claude-ipc-polish-2026-10-27.md: IPC command depth toward 100% (remaining stub rows, titles' known-call list, check_known_calls on every list).
- 2026-10-27-claude-shader-rare-ops-2026-10-27.md: the last 18 rare Maxwell ops and stencil texture bindings in the translator (ShaderKey.stencil_slots).
- 2026-10-27-claude-build-content-2026-10-27-b6.md: NSZ/XCZ zstd containers and HtmlDocument extraction to
<data-dir>/html(cloud, tested on Linux). - 2026-10-27-claude-media-mac-2026-10-27-b6.md: VideoToolbox DecoderBackend, MK8D's NVDEC/VIC stream shape, movie audio and JPEG (Mac; the Grand Prix preview panel still shows no video).
- 2026-10-27-glue-up.md: glue-up pass on the Mac: web/album applets and stencil view slots hooked, fs log rows, timescale flake, deterministic a32jit, every suite and the e2e/golden/Studio runs; the bigger-work list for the next round.
- 2026-10-27-claude-runtime-small-2026-10-27-b6.md: vi producer transactions (TransactParcel rows implemented), npad style helpers (GameCube/Palma/NES in the system policy), tests for the unused core API; audin/audren already covered elsewhere.
- 2026-10-27-claude-applets-frontend-2026-10-27.md: AppKit sheets for the controller, error, player select, web (WKWebView) and album applets, scripted headless answers,
make -C frontend test-sheets. - 2026-10-27-claude-gfx-features-2026-10-27-b6.md: replay of transform feedback, geometry shaders (compute emulation) and tessellation (TCS kernel + drawPatches); stencil view sampled in a shader test.
- 2026-10-28-claude-runtime-small-2-2026-10-27-b7.md: test_timescale measured jump bound, audin mic permission hook, Linux ipc fuzz target builds again; the other runtime-small-2 items were already in place (tested, not verified)
| 2026-10-27-claude-mods-runtime-2026-10-27-b7 | Mods in the runtime: merged RomFS image for the path-level overlay (fs.c), cheat VM with loops/registers/pointer chains (Rust + C twin) run per frame, mod config applied to the run's settings,
--mods-strict, stale mods files cleared on rebuild (cloud, Linux-tested). | - 2026-10-27-claude-media-nvdec-preview-2026-10-27-b7.md: MK8D's preview videos play through nvhost-nvdec + VIC (VIC config at 0x1c2, NVDEC slot from curr_pic_idx, 15 reference frames in the synthesized SPS); decoder pitch, real VIC layout, caps:dc DecodeJpeg.
- 2026-10-28-claude-gpu-title-scanner-2026-10-28-b8.md: tools/gpu/scan_stages.py (control-section stage scan, RomFS scan, set-cover of titles); tested on synthetic sections, not verified on real titles
- 2026-10-28-claude-gfx-recorder-flake-2026-10-28-b8.md: ACNH start crash: command buffer host parts by slot+generation, locked recording state, NAPPLE_GFX_CBTRACE tracer, t_cmdshare; guest double-job race still open
- 2026-10-28-claude-gfx-stages-complete-2026-10-28-b8.md: software tessellator (isolines, TES XFB, GS after tess), gs_run refactor, control-section length fix
- 2026-10-28-claude-nvdrv-media-devices-2026-10-28-b8.md: NVDEC/VIC pitches, VP9, NVJPG encode, MSENC encoder backend (VideoToolbox H.264)
- 2026-10-28-claude-nvdrv-device-nodes-2026-10-28-b8.md: state-tracked ioctls for nvhost-gpu, nvhost-as-gpu, nvhost-ctrl-gpu
Unattended rounds (2026-10-27-b7 to 2026-11-02-r7)¶
Batch 2026-10-27-b7 (notes not listed above)¶
| Note | Summary |
|---|---|
| 2026-10-27-claude-applets-on-title-2026-10-27-b7 | The b6 applet sheets in front of a running title, an e2e step, the sheet input / focus fix. |
| 2026-10-27-claude-gfx-stages-real-2026-10-27-b7 | Stage parameters from the GLSLC control section, the rest of the geometry / tessellation / transform feedback replay, MSAA views and resolves. |
| 2026-10-28-claude-applets-live-2026-10-27-b7 | swkbd header / sub / guide text, per-profile account rows, player select (Linux, tested). |
| 2026-10-28-claude-content-real-2-2026-10-27-b7 | Container and content gaps left after b6 (Linux, tested). |
Round 2026-11-01-r1¶
| Note | Summary |
|---|---|
| 2026-11-01-claude-sched-applets-2026-11-01-r1 | Two Horizon scheduler divergences fixed; swkbd and the offline web applet verified on real titles. |
| 2026-11-01-claude-gfx-msaa-views-2026-11-01-r1 | MSAA views, copy-backed texture views, sample shading, depth resolve, sparse. |
| 2026-11-01-claude-gfx-stages-live-2026-11-01-r1 | The four titles scanned for stage programs, the GLSLC geometry vertex handle fix, real programs through the replay. |
| 2026-11-01-claude-media-live-2026-11-01-r1 | Video, movie audio and album JPEG verified on real titles. |
| 2026-11-01-claude-sweep-small-2026-11-01-r1 | Seven small items: audren performance metrics, audin, npad, content, bcat. |
Round 2026-11-01-r2¶
| Note | Summary |
|---|---|
| 2026-11-01-claude-gfx-nvn-api-2026-11-01-r2 | The 14 missing NVN entry points, refused MSAA branches, the ACNH program hash. |
| 2026-11-01-claude-gfx-shader-views-2026-11-01-r2 | The four titles' shader corpus through the translator and Metal, integer sampled textures, cube and sparse views. |
| 2026-11-01-claude-ipc-depth-hid-2026-11-01-r2 | IPC reference lists and their runner; the missing hid / audio / system-device rows. |
| 2026-11-01-claude-ipc-depth-sys-2026-11-01-r2 | Reference fixtures and a row for every application-reachable command of the system / offline services. |
| 2026-11-01-claude-sweep-media-r2-2026-11-01-r2 | Movie AAC / VP8 / ARGB, clean guest exit, npad device types, the LAS golden route. |
Round 2026-11-01-r3¶
| Note | Summary |
|---|---|
| 2026-11-01-claude-acnh-race-atomics-2026-11-01-r3 | ACNH start crash: guest spinlocks without acquire ordering, fixed in the AOT rewrite (ordering.rs). |
| 2026-11-01-claude-am-depth-applets-2026-11-01-r3 | am reference fixtures and rows, the remaining offline web document kinds, applets on real titles. |
| 2026-11-01-claude-gfx-replay-gaps-2026-11-01-r3 | D24 / D24S8 readback, separate texture / sampler handles, integer 3D / cube / multisample textures. |
| 2026-11-01-claude-ipc-local-stubs-2026-11-01-r3 | 66 documented-default stubs of local services turned into real behaviour, IAudioOut gain. |
| 2026-11-01-claude-nvn-object-layouts-2026-11-01-r3 | Guest-visible NVN objects kept within the titles' object sizes (NVN_MIN_*, t_obj_canary). |
Round 2026-11-02-r4¶
| Note | Summary |
|---|---|
| 2026-11-02-claude-am-stubs-legal-2026-11-02-r4 | Title legal pages, am stub rows made real, the offline network-connection applet. |
| 2026-11-02-claude-core-ordering-kernel-2026-11-02-r4 | Acquire / release for every lifted AArch32 exclusive, lda / stl as ldar / stlr, svcGetInfo 19 / 27, ExitProcess after nnMain. |
| 2026-11-02-claude-gfx-views-raster-2026-11-02-r4 | Stencil cube views, the remaining integer views, separate-texture slot masks, viewport swizzles, provoking vertex. |
| 2026-11-02-claude-ipc-reference-audit-2026-11-02-r4 | 65 IPC rows whose name differed from the reference fixture resolved. |
Round 2026-11-02-r5¶
| Note | Summary |
|---|---|
| 2026-11-02-claude-leftovers-a32-viewport-docs-2026-11-02-r5 | Interpreter lda / stl seq_cst with the alignment fault, per-viewport swizzles, these archive indexes. |
| 2026-11-02-claude-nifm-netconnect-2026-11-02-r5 | nifm Cancel keeps a rejected request's result, GetAppletInfo storages, the real NetConnect output (MK8D Online Play: one applet per attempt), vi ConvertScalingMode. |
Round 2026-11-02-r6¶
| Note | Summary |
|---|---|
| 2026-11-02-claude-net-host-provider-2026-11-02-r6 | Opt-in macOS host network provider (NAPPLE_NET=host): BSD sockets, host resolver with the console vendor's domains refused, TLS with the host trust store, nifm from the host, LDN over the LAN. |
| 2026-11-02-claude-error-applet-output-2026-11-02-r6 | Empty applet storage channels answer NoDataInChannel 0x480 (the SDK aborted on 0x680 after every error applet), unimplemented applets end Canceled 0x2c80, every error applet mode decoded (MK8D Online Play with NAPPLE_NET=host returns to its menu). |
| 2026-11-02-claude-gfx-multi-viewport-2026-11-02-r6 | Viewport / scissor / depth-range arrays on the encoder, viewport index and layer outputs, layered passes on demand. |
Round 2026-11-02-r7¶
| Note | Summary |
|---|---|
| 2026-11-02-claude-napple-infra-2026-11-02-r7 | AWS auto-deploy of the game servers to pretend.napple.lat (OpenTofu, Docker + Caddy, a workflow that skips without secrets), napple.lat DNS to GitHub Pages, the native local test stack. |