THE ROM CODEX is a browser-based retro ROM collection manager. Point it at a local folder full of ROM files and it will scan, sort, and display your entire library by console and genre — no server, no install, no internet required.

The project started as a personal tool to manage large ROM collections stored on flash cartridges and ODEs (optical drive emulators) for a physical retro console collection. Sorting hundreds of games by genre was the core need — the folder structure Console → Genre → ROM reflects that origin directly, making it easy to browse by genre on any device that reads from SD card or USB storage.

Your ROM folder must follow this three-level structure for the Codex to read it correctly:

📁 Console Name
    📁 Genre
        🎮 game.rom

Example: SNES / Platformers / Super Mario World.sfc

1. Organise your files into Console Name → Genre → ROMs before loading. The folder names become the console and genre labels shown in the Codex.
2. Click SELECT FOLDER TO LOAD ROMS on the main screen.
3. Grant permission when your browser asks.
4. The Codex will scan all files recursively and sort them automatically.
5. Tick ALWAYS USE THIS FOLDER to remember the folder between sessions — it will auto-load on the next visit (browser permission prompt may still appear once).

💡 TIP: You can also drag & drop ROM files directly onto the page.

💡 Detection is based on file extension (.nes, .sfc, .gb, .gba, .n64, .md, .iso, .cue, .chd, etc.)

• Use the SEARCH box to filter by game name in real time. Click the ✕ button to instantly clear the search and all filters.
• The CONSOLE and GENRE dropdowns support multi-select — tick as many as you like.
• Tick ALL CONSOLES or ALL GENRES to clear that filter.
• Consoles are collapsible — click a console header to expand or collapse it.
• Genre sections inside each console are also collapsible.
• Use the ▶ EXPAND ALL and ▼ COLLAPSE ALL buttons above the tiles to expand or collapse every console at once.
• Each genre header has a SORT dropdown. Choose from: A → Z or Z → A (alphabetical), SIZE ▼ / ▲ (by file size), ★ ▼ / ▲ (by your star rating), or 🫑 ▼ / ▲ (by your difficulty rating). The sort applies instantly to the games in that genre tile.
• Right-click any genre header and choose 🙈 HIDE GENRE to remove that genre from all views. Hidden genres are remembered between sessions. To restore them, open ⚙ OPTIONS → 🙈 HIDDEN GENRES.

• Each game tile has a YOUR SCORE 5-star rating (1–5). Click any star to set your score — it saves automatically.
• Each tile also has a 🫑 DIFFICULTY 5-pepper rating. Click a pepper to mark how hard the game is, from 1 (easy) to 5 (brutally hard). Saved the same way as scores.
• Click the 📝 NOTES button on any tile to open a free-text notes area. Type anything — strategies, passwords, progress notes. Notes auto-save as you type.
• Sort options in each genre header include 🫑 ▼ / ▲ to sort games by your difficulty rating.
• Each game tile shows the title on its own full-width row at the top. Click the ✏ pencil icon next to any game name to set a custom display name. Press Enter to confirm or Escape to cancel. Custom names are saved in browser storage.

⚠ Clearing browser data will erase scores, difficulty ratings, notes, and custom game names. Use DATA MANAGEMENT to export a backup.

• Click 📚 WIKIPEDIA on any game tile to fetch its Wikipedia summary, cover art, and aggregate score.
• The INTERNET SCORE is sourced from Wikidata critic review data (P444) when available, with a Wikipedia extract scan as fallback. Displayed as a percentage with colour coding: green ≥ 75%, yellow ≥ 50%, red below.
• The Codex uses a 2-pass lookup: exact title → search API fallback, to reduce wrong matches.
• If the result looks wrong, renaming the ROM file closer to the official game title improves accuracy.

• Press the ● red button in the MENU bar to open the suggestion overlay.
• Filter by one or more CONSOLES, GENRES, a ⭐ MIN SCORE threshold, and a 🫑 MIN DIFF threshold.
• Click 🎲 SUGGEST RANDOM GAME to draw a weighted-random match from your collection. Games you have rated higher are more likely to be suggested — unrated games are still included. Adjust the weighting in OPTIONS → 🎲 SUGGESTION WEIGHTS.
• The result shows your YOUR SCORE star rating and an INTERNET SCORE percentage fetched live from Wikidata/Wikipedia.
• Click the ✏ pencil icon next to the suggested game's title to set a custom display name, same as in the game tiles.
• Wikipedia summary and cover art are loaded automatically when a game is suggested.

• Every game tile has a 🔍 VERIFY GENRE button. This fetches the Wikipedia page, analyses the description, and suggests the best-matching genre from your collection.
• If a better genre is found, click ✔ ACCEPT to update the display only, or 📂 ACCEPT & MOVE FILES to physically move the ROM file into the new genre folder on disk (requires write permission).
• Every game tile also has a ✏ pencil icon next to the genre label. Click it to open the ✏ EDIT GENRE overlay and type any genre name manually — no Wikipedia lookup needed.
• The genre input shows a dropdown of all genres already in your collection for quick selection.
• Click ✓ UPDATE DISPLAY to change the genre in the current view only, or 📂 UPDATE & MOVE FILES to also move the ROM file to the matching folder on disk (requires write permission via a saved folder).
• Genre is inferred from folder names — both tools help correct misclassifications in your folder structure.

• SAVED FOLDER — shows the folder currently remembered for auto-load.
• SET FOLDER — pick a new folder to remember.
• CLEAR — forget the saved folder.
• AUTO-LOAD ON STARTUP — toggle whether the saved folder loads automatically when you open the Codex.
• 💾 DATA MANAGEMENT — export all saved data (scores, difficulty ratings, notes, custom names, suggestion weights, hidden genres) to a .json file; import a previously exported file to restore it; or clear all saved data at once. The saved folder path is not included in exports.
• 🎲 SUGGESTION WEIGHTS — six sliders (Unrated through ★★★★★) controlling how much more likely each score tier is to be picked during random game suggestion. Higher value = more likely. Click ✓ APPLY to save, ↩ RESET to restore defaults.
• 🏷 CONSOLE NAMES — type a custom display name for any detected console, then click ✓ APPLY. The new name appears on the tile header and in all filter menus. Click ↩ RESET ALL to restore original names. Names are saved in browser storage.
• 🙈 HIDDEN GENRES — lists every genre you have hidden. Click ↩ SHOW next to a genre to restore it, or ↩ SHOW ALL GENRES to restore everything at once.

• The MENU bar is fixed to the top-right of the screen. Hover over it to reveal buttons.
• REPORT / SUGGEST (D-pad) — submit a bug report or feature suggestion.
• HELP / MANUAL — opens this documentation.
• OPTIONS — folder and auto-load settings.
• ● RANDOM GAME — opens the random game suggestion overlay.
• The NAV bar is fixed to the bottom-right. Hover to reveal navigation shortcuts: scroll to top, or collapse all tiles and scroll to top.
• The ☕ button below the menu bar links to the project's support page.

THE ROM CODEX runs entirely in your browser. No files, scores, or folder paths are ever uploaded anywhere. External requests are made only to the Wikipedia and Wikidata APIs (for summaries, cover art, and review scores) and to FormSubmit when you send a bug report or suggestion.