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.

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 game tile has a YOUR SCORE 5-star rating panel.
• Click any star to assign a score from 1–5. Click again to clear it.
• Scores are saved automatically in your browser's local storage and persist between sessions.
• 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. Leave the field blank (or equal to the original name) to remove the custom name. Custom names are saved in browser storage.

⚠ Clearing browser data will erase scores and custom game names. Keep a backup if needed.

• 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, and a ⭐ MIN SCORE 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, custom names, suggestion weights) 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.

• 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.