Getting Started · what customizing an NES Classic means
The NES Classic Edition (2018 North American model, CLV-101) ships with 30 games and a fixed menu. Customizing it means deciding what that menu shows: keep some of the 30, hide others, add games you own. The console's look and controls stay the same.
What changes on the console
A custom kernel (from the Hakchi project) is written once, after the original is backed up; it lets the console mount user storage. Your game files and menu entries are copied into that storage. Built-in games you leave unselected are hidden from the menu, not deleted; selecting them again restores them. Every change the Studio makes on this PC is backed up and can be undone.
Getting an NES Classic · the console this Studio is for, and where the creator bought one
The Studio supports the 2018 North American NES Classic Edition (model CLV-101). The console has been out of production since 2018, so most units are sold second-hand. Any genuine CLV-101 works; check that the seller states the model and that the console powers on and shows its 30-game menu.
The creator bought a console for this project from this eBay seller: ebay.com/itm/302788782864. That is a personal recommendation only. It is not a sponsored listing and there is no affiliate relationship: the creator receives no commission or referral compensation if you buy there, and buying a console does not benefit Rance9 financially in any way.
Separately, the Studio can be supported through GitHub Sponsors. That is entirely optional and independent of the seller recommendation; the Rance9 Sponsors account supports the creator's independent development work, including NES Classic Collection Studio, and nothing in the Studio depends on it.
How This Application Works · Game Library, My Collection, Install
Three areas, in order: the Game Library is everything the Studio can identify, My Collection is what you chose, and Install on NES Classic is where the collection becomes files and settings for Hakchi2 CE.
| Area | What it is | What it is not |
|---|---|---|
| Game Library | A curated set of North American releases, plus the Extended Library when switched on. | Not your files. Browsing changes nothing. |
| Your games | Files you imported or games found in your Hakchi library, marked Personal Game when the Studio does not know them. | Not selected automatically. |
| My Collection | Exact titles and exact versions, with your decisions about the built-in games. | Not on the console until installed. |
| Prepared on this computer | The collection written into Hakchi's games folder and config, verified. | Not on the console yet. |
| Installed on the console | Transferred by Hakchi2 CE and visible in the console menu. | Not automated in this version. |
The status next to the collection name tells you how far it got: saved in this browser, saved to a file, prepared on this computer. Saving is not preparing; preparing is not installing.
Website vs Companion · what runs where
The website runs in your browser and needs nothing installed: browse, filter, build a collection, save it to a file, load it back. Your collection lives in the browser's storage and never leaves your PC. The companion is a small Windows program for everything that touches files: reading your Hakchi library, keeping copies of imported ROMs, preparing a collection, opening Hakchi2 CE.
The companion listens on 127.0.0.1 only. Edge and Chrome ask once whether this website may reach programs on your local network; allow it for this site. Nothing either part does reaches the console: Hakchi2 CE is what talks to the console, and you operate it.
Installing the Companion · download, verify, install, upgrade, uninstall
Verification in PowerShell (letter case does not matter; the same value is in SHA256SUMS.txt on the release):
Get-FileHash -Algorithm SHA256 "$env:USERPROFILE\Downloads\NESClassicCollectionStudio-Setup-<version>.exe"Upgrade: run the newer installer; data is kept, and the website tells you when the companion is older than it expects. Uninstall: Windows Settings → Apps. Your imported games, personal games and collections stay in %LOCALAPPDATA%\NESClassicCollectionStudio until you delete the folder.
Why the installer is not code-signed
A code-signing certificate costs money and binds a legal identity; the project has none yet. Every release is instead built by a public GitHub Actions workflow from the tagged source, with the run linked from the release notes, a build-provenance attestation attached, and the installer's SHA-256 published. The hash check is what protects you.
What the installer changes
Program files under %LOCALAPPDATA%\Programs\NESClassicCollectionStudio, a Start-menu shortcut, an optional desktop shortcut, and a per-user nesstudio:// link type. No service, no scheduled task, no driver. The console USB driver is a separate step on the Install screen and is the only thing that asks for administrator approval.
Choosing Games · search, filters, select, favorites, the Tray
The 30 built-in games
They sit in the Game Library like any other title. Selected means visible on the console; unselected means hidden there (never deleted). Selecting a game the console already has never installs a second copy.
Understanding Game Versions · regions, revisions, re-releases, alternate ROMs
One game usually exists as several ROMs: regions, revisions, a Japanese original, a prototype, a later re-release. The Game Library lists each game once; the version chip next to the title (for example USA · Rev 1▾ 8) opens the list.
| Term | Meaning |
|---|---|
| Region | Where the cartridge was sold (USA, Europe, Japan, World). Mostly language and timing differences. |
| Revision (Rev 1, Rev 2) | A later manufacturing run with fixes. The highest verified US revision is the default recommendation. |
| Re-release | The same game as shipped in a later product (Virtual Console, compilation cartridges). Bytes may differ. |
| Prototype / Beta / Sample | Unfinished or demonstration builds. |
| Pirate / Unlicensed | Not published under Nintendo's license; includes legitimate independent releases. |
| Translation / Hack | A fan-modified ROM, kept as its own version of the original. |
Your choice is kept exactly. A version you pick is never swapped for a "better" one, and a game loaded from your Hakchi library keeps the exact version that was there. Two versions of one game on the console at once is allowed: tick Keep more than one version of this game in the version list.
How versions are told apart
By content, never by file name: the SHA-256 of the file and of the headerless PRG+CHR data. Bytes that match the No-Intro database carry its name as a verified identity; a NesCartDB or Mesen match is shown as "cartridge DB"; anything else keeps its file name and is marked unverified. Two files with different names and identical bytes are one version.
Extended Library · everything beyond the curated set
The default library is a curated set of North American releases with complete metadata. The Extended Library switch (toolbar, second row) adds the rest of the index: other regions, prototypes and betas, unlicensed and pirate releases, re-releases, translations, multicarts, and extra versions of games already shown.
- No duplicates: extra versions appear inside the existing version chip.
- Some entries have incomplete metadata or unverified compatibility. The Studio says so rather than guessing.
- Switching it off hides those games from browsing but never deselects them; selected ones stay in the Tray marked Extended.
Loading Existing Games · from your Hakchi library or a saved file
My Collection ▾ → Load Existing Collection has two sources.
Selected Games Only vs Entire Game Library
Selected Games Only brings in the games currently ticked in Hakchi. Entire Game Library also brings in the unticked ones as available games; only the ticked ones are selected. With 400 games set up and 75 ticked you get 400 available and 75 selected, plus whichever built-in games were ticked, and the Studio names both parts in its count.
Known games are matched by their bytes, never by name. Unknown ones become personal games with their original name. A game whose ROM file is missing is listed, not dropped.
Adding Your Own Games · one file, described by you
Personal games take part in everything: search, grid, list, Tray, favorites, versions, Technical Details, saved files and preparation. They carry the Personal Game badge. For many files at once, see Adding Games from Files and Folders.
Adding Games from Files and Folders · ZIP archives, bulk import, exact identification
Add Your Own Games also offers files (any number of ROMs or ZIPs) and a folder (everything in it, recursively). Both run as a background job with progress, a running list and a summary. Stop at any time; what was already examined stays.
Originals are never changed, moved or deleted. Limits: 8 MiB per file, 32 MiB per archive, 64 members per archive, 8 KiB minimum. Import only files you own; see Your Files, Ownership and Redistribution.
Missing Game Files · pending dependencies and Locate Game File
The index knows thousands of versions by hash, but a version can only be prepared when this PC has its file. A selected version without a file is a pending dependency: it stays in the collection, Check lists it as "missing ROM payload", and preparing waits until the file exists. Nothing is substituted; a different revision or region is a different game.
Importing a folder does the same for every known version it contains. The Check summary shows how many selected games have files on this PC and how many are missing.
Your Files, Ownership and Redistribution · what this project does and does not do with games
The Studio is a collection manager. It identifies games through public identification data (titles, publishers, hashes from the No-Intro, NesCartDB and Mesen databases). It contains no game files and no downloader. The ROMs it works with are the ones you provide and own, such as dumps of your own cartridges, plus the 30 games on your console.
- Copies the companion keeps stay on your PC; nothing is uploaded.
- Saved collection files hold names, hashes and choices, not game data, so they can be shared.
- Mentions of the Internet Archive or similar sites in the documentation describe where identification data originates; they are not an invitation to download copyrighted games, and the Studio will not do it for you.
- The pixel artwork, interface icons and box art are shown to identify and present the games: Nintendo's renderings from the NES Classic Edition system software, documented community sprite rips (origins in the footer parade) and community box-art scans. All rights remain with their owners.
NES Classic Collection Studio is an independent project, not produced, licensed, sponsored, approved or endorsed by Nintendo. Nintendo, Nintendo Entertainment System, NES and NES Classic Edition are trademarks of Nintendo.
Saving and Loading Collections · what a collection file is, and is not
Save / Load ▾ → Save Collection to File writes a small JSON file: games, exact versions, built-in game decisions, personal games' names and identities, and how far the collection got. Load Collection from File opens one. The browser also keeps an automatic draft, and the Studio takes snapshots before New Collection, before loading and before restoring (Restore a Previous Collection).
- A collection file contains no game files. On another PC it lists what it needs; missing files can be located, never substituted.
- The three earlier file formats of this project still open and are saved again in the current one.
- Saving is not installing, and preparing is not installing. The status line keeps them apart.
Another browser, or the website. Export Studio Data writes favorites, snapshots, settings and the current collection to one file; Import Studio Data merges favorites and snapshots and offers to restore the collection. Browser storage is per site address, so this file is how data moves across. No account is involved.
Connecting Your NES Classic · cable, FEL mode, driver
You need the console, a micro-USB data cable, and this PC with the Studio running. HDMI can stay in the TV.
First-Time Console Preparation · what happens before a console accepts games
A stock console runs only its original software. Four things happen once, in this order, each a real change to the console and each only with your explicit go-ahead. This version of the Studio describes them; Hakchi2 CE performs them.
Installing Your Collection · what the Studio does and what you do in Hakchi
Install on NES Classic has eight steps. In this version the Studio runs Check, Prepare, Connect (detection only) and Review; the console-side steps are shown as not available.
| Step | What happens | This version |
|---|---|---|
| 1 Check Collection | File present, exact version, compatibility, controller needs, estimated size. | runs |
| 2 Prepare Games | Files and selection written into Hakchi's layout on this PC; backed up first, verified after; repeating with no changes is a no-op. | runs |
| 3 Connect Console | Connection steps; read-only USB detection. | runs (detection only) |
| 4 Inspect Console | Recognized, already modded, backed up, compatible? | not available |
| 5 Review Changes | Added, removed, changed versions, built-in games shown or hidden, modules, storage. | runs |
| 6 Install | Transfer to the console. | not available |
| 7 Verify | Read back what the console shows. | not available |
| 8 Ready to Play | Disconnect and test on the TV. | not available |
The transfer in Hakchi2 CE 3.9.3
Hakchi has no automation interface for synchronizing, so the transfer is a click in Hakchi. After Prepare Games, Hakchi opens with exactly your collection ticked.
- Finish Prepare Games (status prepared on this computer). Verify in the console-management app opens Hakchi and reads its list without clicking anything.
- Connect the console (Connecting Your NES Classic): POWER on for a modded console, the RESET procedure for a stock one. For a stock console, read Backups and Recovery first; Hakchi will offer the kernel steps.
- Hakchi's status bar must say Online. The game list on the left is your collection, already ticked.
- Click Synchronize selected games with mini. Do not disconnect while the transfer runs.
- Close Hakchi when it reports completion.
- Unplug USB, power-cycle, and check the menu on the TV.
Updating an Existing Console · later changes are smaller than the first setup
Once a console is modded, changing the collection is routine: adjust My Collection, run Prepare Games (only changes are prepared, games already prepared are reused by hash, removed games are unticked rather than deleted), connect with POWER on, synchronize in Hakchi. No kernel is reinstalled to add a game; modules are only needed when a new game requires them.
If your Hakchi library changed since you loaded it (for example you used Hakchi directly), Check Collection notices and offers to review the differences, reload what is on this PC, or keep your changes. Nothing is overwritten silently.
Future: Automatic Console Sync · what a later version may add
Today the Studio prepares everything on the PC and leaves the console writing to Hakchi2 CE, operated by you. A later version may drive those steps from the Install screen: detect the console, confirm the backup, synchronize, read the result back. None of that exists yet, and every unavailable step says so.
Whatever is added keeps the same rules: nothing is written to the console without an explicit go-ahead, the original software stays backed up and restorable, and every step reports what it actually did.
Emulators and Compatibility · kachikachi or RetroArch
The console's own emulator, kachikachi, handles the mappers used by the built-in games and many more, but not all of them. Games on mappers it does not support run through RetroArch with the FCEUmm core, an optional hmod on the console.
- Every game shows a recommended emulator, derived from the header's mapper and from documentation and community reports. Nothing has been tested on this particular console, and the Studio says so wherever the recommendation appears.
- A game that needs RetroArch is prepared anyway; Check reports the missing module as a prerequisite instead of pretending the game will run.
- Known problem titles (audio glitches or crashes on kachikachi) carry a note with its source; Technical Details shows the evidence.
Special Controllers · accessory limitations, including light guns
The NES Classic has two Wii-style controller ports. Games that need other hardware (Zapper, Power Pad, R.O.B., Four Score, Miracle Piano and others) carry a controller icon in the Game Library and appear in the Tray's hardware warning.
- Light-gun games (Duck Hunt, Hogan's Alley, Wild Gunman): the Zapper needs a CRT, and no light-gun solution has been verified on this HDMI console. They install fine but stay marked unverified.
- Power Pad, R.O.B., Vaus, keyboards, pianos: no supported way to connect them; marked unsupported.
- Four Score (3 to 4 players): not possible with two ports.
- Games playable with standard controllers in some modes are marked optional or mode-specific.
The Studio does not recommend accessories and does not assume compatibility with hardware that has not been verified on this console.
Backups and Recovery · two kinds of backup, and what to do after an interruption
Console backups (original kernel and NAND, read before any change, verified by checksum, kept in two places) are the way back to factory software. Preparation backups are taken on this PC before every Prepare: the previous selection and files are kept so any run can be undone.
If something is interrupted
- During Prepare: the Studio rolls back to the previous setup and says what happened. Nothing is left half-written. Run it again once the cause is fixed.
- Hakchi does not start after Prepare: the collection is still prepared and verified; start Hakchi manually, or undo the run from the undo point shown.
- A sync to the console is interrupted (cable, power): reconnect and sync again; Hakchi transfers only what is missing. Never power off during a kernel step.
About the Technology · what is under the hood
Hakchi2 CE 3.9.3 does the console side: custom kernel, user storage, game folders, hmod modules, hiding built-in games, synchronization. The Studio does not reimplement any of it. It writes collections in the exact layout Hakchi reads (one folder per game with the ROM and its .desktop entry, plus the selection in Hakchi's config) and leaves the console to Hakchi.
- Identification: SHA-256 of each ROM's bytes and of the headerless PRG+CHR data, matched against No-Intro and against the NesCartDB and Mesen cartridge databases; iNES headers for headerless files come from those databases, never guessed.
- Companion: a loopback-only HTTP server on 127.0.0.1:8765. The website reaches it through CORS with an exact-origin allow list; access is granted per site by the pairing window and expires when the companion closes. Its data lives under
%LOCALAPPDATA%\NESClassicCollectionStudio. - Preparation: every run keeps a backup, a journal and a ledger under
hakchi-staging; a run with no changes is a verified no-op; interrupted runs roll back. - Source and formats: the project repository documents the collection file schema and the acceptance evidence; see Credits for licenses.
Legal, Privacy & Disclaimers · the consolidated reference
Independent project. NES Classic Collection Studio is made by an independent developer (Rance9). It is not produced, licensed, sponsored, approved or endorsed by Nintendo, and it is not affiliated with the Hakchi project. Trademarks: Nintendo, Nintendo Entertainment System, NES, NES Classic Edition and the game titles and publisher names shown belong to their respective owners and are used only to identify and present the games.
Copyright and game files
The Studio contains no commercial game files and no way to download them. The files it works with are the ones you provide, such as dumps of your own cartridges, and the 30 games that came with your console. You are responsible for the rights to the files you use and for the laws that apply where you live. Owning a cartridge does not by itself authorize downloading someone else's copy of that game.
Artwork and third-party rights
The project's own code is released under the MIT license. The pixel characters, interface icons and console renderings come from the NES Classic Edition system software and from documented community sprite rips (origins listed in the footer parade); box art comes from community thumbnail collections; identification data comes from the No-Intro, NesCartDB and Mesen databases; the Press Start 2P font is under the SIL Open Font License. All of that stays under its owners' rights and is not covered by the MIT license. Attribution is given where it is known; no license beyond that is claimed. Details: THIRD_PARTY_NOTICES.md.
Privacy
The website keeps your collection, favorites, snapshots and settings in your browser's storage only. The companion keeps its data, including copies of game files you import, under your Windows user profile and talks only to your own computer (127.0.0.1); a website may use it only after you click Allow, for that site and that session. There is no account, no analytics and no telemetry. Loading the website requests its own files from GitHub Pages; the download section asks GitHub for the latest release; nothing else is contacted. The storage figure shown is a reference estimate for a stock console, not a measurement from your device. Full text: PRIVACY.md.
Software warranty
The software is provided "as is", without warranty of any kind, as the MIT license states. Compatibility notes come from documentation and community reports and are not tested on every console; unsupported configurations may not work.
Console risks
Modifying a console carries risk. Back up the original kernel and storage first and keep the backup. This version of the Studio prepares everything on the PC; writing to the console is done by Hakchi2 CE under your control, and this Studio never writes to the console.
External services
GitHub (repository, releases, Pages hosting), GitHub Sponsors (optional support), Hakchi2 CE (downloaded separately from its own releases and verified by hash), and eBay (one seller recommendation in Getting an NES Classic). Each has its own terms and privacy practices.
Donations
The Studio is free. Support through GitHub Sponsors is optional and goes to the developer identity Rance9 for independent development work; nothing in the Studio depends on it. The eBay recommendation carries no affiliate or referral compensation.
Documents: LICENSE · PRIVACY.md · THIRD_PARTY_NOTICES.md
Credits · the projects this Studio stands on
- Hakchi2 CE by TeamShinkansen and contributors, GPL v3 (github.com/TeamShinkansen/Hakchi2-CE); original hakchi2 by madmonkey and ClusterM. Not bundled: the companion downloads the pinned 3.9.3 release from the Hakchi2 CE releases page and verifies it by SHA-256 before use.
- No-Intro, NesCartDB and the Mesen database: identification data (names, hashes, cartridge boards).
- Press Start 2P by the Press Start 2P Project Authors, SIL Open Font License.
- Pixel artwork and interface icons: Nintendo's renderings from the NES Classic Edition system software and documented community sprite rips (origins in the footer parade); box art from community thumbnail collections. Shown for identification and presentation; not covered by this project's license.
Source code and releases: github.com/Rance9/NES-Classic-Collection-Studio (MIT license for this project's code). Independent project; not affiliated with Nintendo or with the Hakchi project.
NES Classic Collection Studio is free and open source. If you've found it useful, optional contributions through GitHub Sponsors are always appreciated and help support continued independent development. Nothing in the Studio depends on it.
Troubleshooting · short answers, details on demand
"Install on NES Classic" checks and prepares but does not install
Correct for this version: console writing is disabled until it has been reviewed and approved for this project. Preparing is complete and verified; Installing Your Collection covers the sync in Hakchi.
The button shows a setup screen
The Studio requires Hakchi2 CE 3.9.3, exactly that build. If it is missing it offers to set it up from the verified package; if a different build is present it says so and leaves it alone.
"Hakchi is open — close it first"
Hakchi rewrites its config on exit, so the Studio never changes it while Hakchi runs. Close Hakchi, prepare again.
"The console is connected — disconnect it first"
Prepare is PC-only; it refuses to run with the console attached so nothing can reach the console by accident.
"cannot be prepared" or "Game File Missing"
Either the ROM has no header and the Studio will not guess a mapper, or the companion's copy of the file is gone: use Locate File with a file that has the same bytes.
My Hakchi library changed since I loaded it
Something changed the selection outside the Studio. Check Collection offers: review the differences, reload from this PC, or keep your changes. Nothing is overwritten until you choose.
Windows asks for administrator approval
Only the console USB driver needs it, once, after you click Install console driver. The Studio and the companion never run elevated.
The pill says "Connect to Your Computer" and nothing happens
Start the companion (Start menu → NES Classic Collection Studio Companion), then pill → Connect → Allow in its window. If the pop-up was blocked, use the link in the dialog or enter the 6-digit code the companion shows.
"Local network access blocked" or "could not be reached"
Edge and Chrome ask once whether a website may reach programs on your PC. If it was declined: lock icon left of the address → Permissions for this site → Local network access → Allow, then reload.
"Companion needs an update"
The website expects a newer companion. Pill → Get the companion, verify the hash, run the installer; your data is kept.
SmartScreen says "unknown publisher"
The installer is unsigned. Verify the SHA-256 as described in Installing the Companion; if it matches, More info → Run anyway.
The companion says the port is in use
Another program is listening on 8765, or an older companion is still running. Close it and start the companion again.
The companion was closed or restarted
Website access is forgotten when the companion closes, by design. Start it, pill → Connect → Allow. Imported games and collections are unaffected.
A file "could not be read" during import
The summary names the reason: not a ROM, too small, unsafe archive paths, suspicious compression, damaged ZIP. The file is skipped; nothing else is affected.
Where the companion keeps things
%LOCALAPPDATA%\NESClassicCollectionStudio: logs\companion.log (no tokens), exports (saved collection files), hakchi-staging (backup, journal and ledger per preparation run), personal (imported and personal game copies).