GitHub - giancarloerra/Degauss: Official repository for Degauss, the blazing-fast, lightweight frontend for MiSTer FPGA. CRT & HDMI, integrated with the standard MiSTer setup, folders and scripts. Browse games already on your card, scrape artwork and metadata directly on MiSTer, use local artwork databases, customise themes and views, and launch without background processes.

A blazing-fast, lightweight frontend for MiSTer FPGA.

Degauss plays nice with the standard MiSTer setup, folders and scripts, instead of trying to replace it all.

Blazing-fast browsing through large collections, with nothing left running while you play.
Your existing MiSTer library, as it is, including SD, external storage and ZIP games that do not need unpacking.
Six built-in views, with a different view for each system or folder if you want.
Layouts Designer lets you choose a template, arrange list, artwork and information panels, and save your own named layouts.
Artwork and full game information from existing files and artwork packs, or Degauss's built-in scraper.
Libretro Integration adds an optional, account-free source for game information, screenshots, box art and title screens alongside ScreenScraper.
Themes with an on-device editor, font choices and custom system images.
Home Editor lets you reorder Home entries and choose which ones to show or hide.
Custom Folders & Collections group games, systems and folders your way, keeping filtered searches as reusable collections, with names and custom images.
Made for CRTs and HDMI, with smoother CRT artwork, screen-alignment controls and a rotatable interface for vertical displays.
Optional HDMI CRT effects for the interface, including scanlines and shadow masks.
Games Explorer optionally searches across your library, combines filters and follows metadata links, alongside shared favourites, Last Played and random picks.
Attract Mode showcases your collection and lets you switch systems or launch the pictured game.
Expanded Core Updates shows installed cores, available updates and What's New, with latest-first sorting and cached browsing while refreshing.
Core choice per system or game, including installed RetroAchievements, Unstable and Dual SDRAM builds.
Fits into MiSTer: configured controllers work straight away, and you can run installed scripts or use Zaparoo Core launches.

Source available, written in Rust and using Slint, and licensed for non-commercial use.

Feature request or bug report? Star this repository as well to support it ⭐️

Degauss is written and maintained by one person in his own time. A star is the whole of what it costs you and the clearest signal that the work is worth continuing! If you want something changed or something is broken, open an issue and if you starred it I'll know it matters to you beyond just requesting things :-)

Screenshots

The images below are captured from the actual MiSTer framebuffer, mainly using the Blue-Yellow GE custom theme, with Standard-theme comparisons labelled separately. CRT presentation is applied for the README.



Home	Explore Games	Explore Filters

Personal Folders	Home Folder Editor	Optional Handheld Category

Details View	Large Artwork Details	List View

Gallery View	Multi List View	Carousel View

Tiled View	Named Custom View	Custom View Editor

Per-system Core Selection	Extensive Options	Configurable Hold Shortcuts

Appearance Settings	Library Visibility	90° Screen Rotation

Core Updates	Installed Cores Browser	Metadata Filters

Drawing and Performance Controls	Actions for This Place	Random Game or Random Favourite

A Different View for Every Place	Full Game Information	Indexing Progress

Indexing Details	Indexing Complete	Automatic, Gamelist or Artwork Pack

Choose an Installed Artwork Pack	Libretro Scraping	Libretro Match Selection

Single-game Scraper Controls	Enter a Manual Search	Choose the Matching Game: 1944

Scraper Preparation	Single-game Scrape Complete	Browse Installed Scripts

Confirm Before Running	Standard Theme: Details	Custom Theme

Amber Theme	Blue-Orange Theme	Mono Theme

Green Mono Theme	Modern Theme	Neon Theme

Theme Editor	Category & System Image Picker	A Saved Custom Theme

Attract Mode	Video Effects

Watch Degauss in action

Click the image to watch Degauss on YouTube.

Using it

Control	Does
up / down	move through lists
left / right	scroll speed, 0.5x to 12x, or what Left and Right Behaviour says: letter jumps, page jumps, or plain movement. Inside an Options page, left chooses the previous ordered value and right chooses the next; either direction toggles two-choice values
A (enter)	open a folder, launch a game; in Options, choose the next value or run an action
B (escape)	back, out of the folder
X (tab)	Actions for the current selection and location: Game Information, random game, random favourite, keep a favourite in Main Favourites or in a folder, drop a favourite, rename or remove an empty Favourites folder, jump to letter, search or filter games, hide a row, rebuild this system, change view, etc.
Y (space)	Menu: Options, Help, About, Exit to MiSTer. Scripts and optional Attract Mode are on Home

Options → Shortcuts can assign an optional one-second hold to A, B, X or Y. A short press keeps the button's normal action. An available hold runs once and does not also run the short action when released. If the assigned action is not available at the current browse location, the normal action remains immediate.

Actions groups the available controls into Game, Find, Library and Appearance. Groups without applicable actions are omitted. A opens a group; B returns to the group list, then to browsing. Each selected control has an explanation below the list. Home keeps its flat Actions menu for personal folders, editing, images and views. Explore has its own search, filter and collection actions.

Game contains Game Information, separate Random Game and Random Favourite actions, and adding/removing favourites. Adding one opens a chooser that lists Main Favourites (the _@Favorites folder itself) first, then the folders already inside it, then New folder.... Choosing Main Favourites writes the .mgl, or the link for a core file, directly under _@Favorites; no folder of that name is made, and a folder somebody has really called Main Favourites is listed after it as a folder of its own. When a real folder is selected in the Favourites shelf, the same Game group also offers Rename Favourite Folder and Delete Favourite Folder. Rename keeps everything inside and never overwrites another entry. Delete names the folder in its confirmation and works only when it is empty; it never removes contained favourites, nested folders, hidden entries or other files. If empty folders are hidden, turn on Options → Library → Show Systems with No Games to make the folder selectable for deletion. On a card that had no _@Favorites when Degauss started, the first favourite makes it, but the Favourites shelf is only listed after Rebuild All System Lists. Both random choices use the currently open folder and Random Game Behaviour. Find contains jump, search, metadata filters and hiding controls; Library contains scraping, core choice, data source and rebuilding; Appearance contains view and image controls.

When Degauss creates an Arcade favourite, it also prepares MiSTer's native menu link if the Favorites script has not already done so. New favourite folder names start with _: keep it to show the folder in both Degauss and MiSTer's native OSD, or remove it with X to make the folder Degauss-only. The naming grid starts with lowercase letters; Y cycles through lowercase, uppercase and symbols, SP enters a space and Clear clears the complete name. Existing folders remain unchanged unless their Rename action is explicitly used.

A gamepad needs no extra setup and browsing and settings need no keyboard. While Degauss owns the screen, MiSTer sends the d-pad as arrows and the face buttons as Enter, Escape, Space and Tab. One physical press counts once even when a controller or the input stack delivers it as two press and release pairs within 40 ms; held scrolling and deliberate repeated taps are not affected. Options → Navigation → Swap A and B / Swap X and Y can independently swap the controller actions inside Degauss. Keyboard controls, MiSTer's controller mapping and launched games remain unchanged. On-screen control hints follow the selected swaps; the Hold A/B/X/Y rows always name the physical buttons.

Explore Games and saved collections

Explore Games on Home browses the visible games in already indexed systems. It does not scan ROM folders, prepare an Artwork Pack or contact a game service. Unavailable or unindexed sources are reported; Actions → Indexed Coverage shows the complete report. Rebuild an affected system through its ordinary Library actions before reopening Explore if it has not yet been indexed. Games missing since indexing are skipped with a warning; healthy entries remain available, and Indexed Coverage lists the missing paths.

Combine title search, category, system, decade and the existing six metadata fields. Filters combine together; each value's count respects the other chosen filters. Unknown selects games without that field. Identically named games retain their owning systems and exact launch targets. Existing views, artwork, Game Information, favourites and core choices remain available.

Actions → Save Collection saves the current criteria under a name. Saved Collections opens, renames or deletes those saved searches without copying games. More by Developer, More by Publisher and Same Genre start a cross-system search using the selected game's existing metadata. Back returns to the previous query or originating browser location. Returning from a game restores the query and selection; a fresh start begins unfiltered. Explore Games is Off by default. Enable Options → Library → Show Explore Games, or show it in Edit Home and save. Its default position is after Last Played. Entries with the same full name and launch identity within a system appear once, even in different folders. Different variant filenames or core choices remain separate and include their filename when their displayed titles would otherwise be identical. Explore does not read ROM contents to compare copies.

Personal Home

Actions → Add to Home saves an exact shortcut to a game, system, library folder, saved collection, installed core, script or Home category/action. Choose Home, an existing personal folder or New Personal Folder. The shortcut is saved and appears immediately, without opening Edit Home. Removing a shortcut is also immediate. This does not copy games or change MiSTer Favourites.

On Home, Actions → Edit Home lists standard and personal rows, including hidden ones. Select a row to move it up/down or hide/show it on Home. Inside a personal folder this is Edit Home Folder. Moving or hiding a row returns to the entries list with that row selected and its status updated. Personal entries can also be renamed, moved to another personal folder or removed. Folders can contain mixed shortcuts and other personal folders, up to three folder levels, and use images chosen from the existing logos folder. Save Changes keeps ordering, visibility and other draft edits; Cancel Changes discards those edits. Additions and removals are immediate.

Existing Library visibility switches remain authoritative. Missing or hidden targets stay saved and visibly unavailable; they are not redirected to a different game. Removing a personal folder removes only its organisation. Back from an opened target and return after play restore its originating personal-folder entry. Start Folder continues to use the existing category identity, independently of Home ordering.

Running MiSTer scripts

Open Scripts from the main browser to browse the installed scripts and their subfolders. The browser starts at Scripts under the configured menu_root, normally /media/fat/Scripts. It lists .sh files, with folders first. Hidden files and folders, and Degauss's own degauss.sh, are excluded.

Executable .sh files run directly, including compiled MiSTer utilities and scripts with their own interpreter. Non-executable shell scripts run with Bash.

A opens a folder or asks for confirmation before running a script. B goes to its parent folder, or returns to Home at the Scripts root. Choose A Run to execute the selected script or B Cancel to leave it untouched. Only run scripts you trust: they retain their normal access to the card and may require a keyboard or other interaction.

Degauss exits before the script runs, restoring its terminal rather than remaining behind it. After completion, failure, or interruption with Ctrl-C, the terminal keeps the result visible and asks for a key to return. Degauss then reopens at the same Scripts folder and selection. A script that reboots or shuts down MiSTer keeps that behaviour.

If a script reloads MiSTer's menu before returning, the new launcher restores the same script selection. A later Menu reload, after Degauss has already returned, uses the normal startup screen. Neither path starts a second frontend. Scripts that load a game core keep that core on screen.

Scripts launched from Degauss receive LAUNCH_ORIGIN_ID=degauss while they run, so they can identify the launcher without inspecting the MiSTer setup.

Options → Library → Show Scripts Folder is On by default. Switching it Off hides the Home entry without changing any script files; the choice is saved with the other Options settings. Missing or unreadable script folders and scripts report their underlying error.

Automatically launching physical discs

Options → Library → Auto-run Physical Discs is Off by default. When enabled, inserting a supported disc launches it through an installed MiSTer_Physical-CD or MiSTer-disc provider. PlayStation, Saturn, Mega CD, PC Engine CD, Neo Geo CD, 3DO, CD-i, MD+ and SNES MSU-1 media are recognised.

Enabling this option does not install physical-disc support. Automatic launch requires Degauss's bundled MiSTer_Degauss Main; script-only use with stock MiSTer Main does not provide it.

Physical-disc setup

Keep main=degauss/MiSTer_Degauss in the active MiSTer INI's existing [MiSTer] section, as in the recommended Degauss installation.
Install one supported provider, including its executable and MGL launchers:
- Physical Disc Support: /media/fat/MiSTer_Physical-CD and /media/fat/_Physical Disc Cores/. Its documentation covers installation through MiSTer Companion or Update All.
- mister-disc: /media/fat/MiSTer-disc and /media/fat/_Disc_Cores/. Use its scoped installation method, not its global Main replacement.
The corresponding cores and their usual BIOS files must also be installed.
Back up the active MiSTer INI, then add or update the section for the installed provider. For Physical Disc Support:
```
[A0CD-*]
main=MiSTer_Physical-CD
```
For mister-disc instead:
```
[CD-*]
main=MiSTer-disc
```
Do not add a duplicate section or remove unrelated settings. Keep these entries in each INI profile used with physical discs. They select the provider's Main only for its physical-disc launchers, leaving Degauss as the menu. Do not change the global or [Menu] Main to the provider's executable to enable its own menu auto-detection. Degauss handles that detection itself.
Confirm that the appropriate MGL in the provider's folder plays the disc when selected manually from MiSTer's menu, then enable Options → Library → Auto-run Physical Discs in Degauss.

Degauss identifies the disc and launches the provider's MGL. The INI section then selects the provider's Main, which supplies physical-disc playback for that core. Installing the binary without the INI routing is not sufficient. If both providers are installed, Degauss prefers a matching Physical Disc Support launcher when one is available.

MD+ and SNES MSU-1 require the Physical Disc Support provider in Degauss's current integration. These are specially prepared data discs, not ordinary Mega CD or SNES cartridges. MD+ automatic identification looks for matching .md and .cue filenames in the disc's root; SNES MSU-1 identification looks for a .sfc or .smc file there. Follow the provider's disc-burning guide.

Degauss uses the provider's existing MGL and the same launch handoff as any other game. A disc is handled once and is not launched again until it has been ejected. Unknown and audio-only discs are ignored. If the matching provider or launcher is missing, Degauss reports that instead of changing the disc or the MiSTer installation.

Browsing core updates

Options → Library → Show Core Updates adds an optional shelf to the home screen. It is Off by default. Degauss reads the same databases and filters that are configured for MiSTer's Downloader in downloader.ini, downloader/*.ini and downloader_*.ini.

All Cores is the initial view, sorted by the latest build date first. X Actions → Sort by Name changes the order; Sort by Latest Updated restores it. What's New compares listings with the previous complete check. X Actions → Updates Available shows installed cores with a newer configured build, and All Cores shows the complete list. In All Cores, every installed core remains visible, including one that has no configured database source. An uninstalled core appears only when one of this MiSTer's configured databases selects it, so it is content the next Downloader run can provide. Degauss does not classify databases as official or unofficial and does not download, install or execute a remote core. It reads only their database manifests and the archive summaries needed to find core files.

Each row shows the core type, configured source and local state. Dated core filenames are compared by build date; undated cores are checked by the MD5 recorded in the database. X Actions provides title search, jump-to-letter, Filter Core Updates by type and source, Refresh and a short explanation of the data source. These temporary filters clear when the shelf is left.

In Details view, the final line shows how many games use the selected core. Game Information lists their titles. When matching game artwork is available from that system's selected Gamelist or Artwork Pack, the preview cycles through the images once per second. Game data is read on demand for the selected core and then reused; Core Updates does not preload another copy of the library.

Opening uses compatible saved results and rechecks installed cores without forcing a download. Refresh reads the configured databases again while saved rows remain browsable; Cancel Refresh stops the background check without leaving the saved rows. No check runs while this browser is unopened. If one source times out or returns unusable data, Degauss shows the results from the others and names the skipped source at the end; partial results are not saved as a complete catalogue. If none can be read, the last valid saved result remains available. B cancels and returns Home. A first-use failure shows a concise cause, while /tmp/degauss.log keeps the technical detail.

What's New compares exact configured listings with the last complete check you viewed. On the first visit it explains that there is no previous history and shows current information without marking everything new. Leaving after a complete fresh check has appeared saves one baseline for the whole catalogue, including rows hidden by temporary filters. Changes stay visible throughout that visit, including after Refresh. Cached, partial, failed and cancelled checks never advance history. New source/filter/precedence settings establish a comparison for the affected sources without treating their entire contents as newly released. A changed dated filename is labelled New or changed listing, not a claim that the core has just debuted. Known dates are build dates, and Game Information includes the actual checked time.

The small cache/core-updates-seen.json history file is separate from the existing core catalogue cache. If damaged, What's New explains the failure; All Cores remains usable. Repairing or removing that history file starts a new comparison without changing installed cores or the library.

Why Degauss

Three pillars. Performance (for large libraries and images), Simplicity (vs overengineering), Adherence to the MiSTer way (standards, scripts, folders).
Fast. 0.47 s from launch to first frame. 0.57 s to open a folder of 12,605 games.
Artwork instant browsing. Artwork is read straight from the card as you scroll, with nothing pre-generated. After the selection settles, Degauss prepares upcoming images in memory one at a time, spaced 250 ms apart and bounded by the existing cache; scrolling through cached images keeps preparation moving in that direction. Gallery reduces visible images to its cell size in memory only. Nothing is written beside the artwork.
Nothing resident. No service, no daemon, no port, no background process, nothing at boot. One program, running only while you are looking at it.
Self-contained. One program, with no runtime, toolkit or library to install beside it, and small footprint while it runs. Optional online features use the curl command already included in a normal MiSTer installation. The index Degauss builds costs about 300 bytes a game, so it stays in the low megabytes for an ordinary collection and is the only thing that grows with the size of yours.
CRT-optimised. 352×240 with 1:1 pixel mapping to a 15 kHz analog output. Overscan margins and screen position are settings. Larger framebuffers are laid out from their own size, so HDMI works too. The complete interface can rotate 90° clockwise or counterclockwise for a vertical display.
The card is the truth. Reorganise, rename or move files with any tool and the browser follows: nothing has to be re-imported or re-tagged. The index it keeps is only a copy of what the card already says, and Options → Library → Rebuild All System Lists updates all systems after an update, and Actions → Library → Rebuild This System List does one system alone.
Full metadata. Read the complete description and available publisher, developer, release date, players, language and genre in Game Information, from the system's selected Gamelist or Artwork Pack source.
Favourites are MiSTer's favourites, written directly into _@Favorites or into one of its folders, in MiSTer's own format. One made here works in the stock menu; one made anywhere else appears here: the stock script's absolute paths, the root-relative paths Degauss writes, and hand-written paths relative to the core's games folder are all read the way MiSTer Main reads them. A favourite any of whose files sits in two of its system's folders at once is kept, reported in /tmp/degauss.log and Game Information, and refused at launch with the same line, rather than pointed at one of them by folder order.
Awkward systems handled without hassle: AmigaVision and its standalone Amiga CD32 package, DOS, Neo Geo, Arcade, X68000, and cores that are several machines.

Measured on the DE10-Nano's own hardware, with a large multi-system collection indexed.

Installing

Installing through Update All (recommended)

Degauss is available directly in the official Update All settings. To install it and keep it updated:

Run Scripts → update_all on MiSTer.
Press up during the opening countdown to enter Settings.
Open Frontends.
Select Degauss so it shows On.
If Update All offers its optional Game Artwork DBs, choose the ones you want or select No.
Return to the main Settings screen, choose SAVE, then EXIT and RUN UPDATE ALL.

Open Frontends in Update All Settings.

Select Degauss so it shows On.

Update All downloads the Degauss files, sets main=degauss/MiSTer_Degauss in MiSTer.ini, and keeps the installation current on later runs. MiSTer can use only one main= frontend, so selecting Degauss switches any other frontend off.

Using an SS1 with Console Mode? Follow the SS1 installation steps before rebooting so Degauss uses the Main INI profile.

To remove an installation managed by Update All, return to Settings → Frontends, highlight Degauss, and choose Uninstall.

Installing through Downloader

If you use MiSTer's Downloader without Update All, add these lines to the bottom of /media/fat/downloader.ini:

[degauss]
db_url = 'https://github.com/giancarloerra/Degauss/releases/latest/download/degauss.json.zip'

Then run downloader as usual. Both binaries and the files beside them come down and stay updated. Add this line to the [MiSTer] section of /media/fat/MiSTer.ini once:

main=degauss/MiSTer_Degauss

Installing manually

Download the archive from the latest release and copy its contents onto the card, so the files land here:

/media/fat/degauss/MiSTer_Degauss
/media/fat/degauss/menu.rbf
/media/fat/degauss/Degauss_Menu.SOURCE.txt
/media/fat/Scripts/degauss.sh
/media/fat/Scripts/.config/degauss/degauss
/media/fat/Scripts/.config/degauss/degauss.toml
/media/fat/Scripts/.config/degauss/systems.toml
/media/fat/Scripts/.config/degauss/logos/
/media/fat/Scripts/.config/degauss/themes/

Then add one line to the [MiSTer] section of /media/fat/MiSTer.ini:

main=degauss/MiSTer_Degauss

Reboot. Degauss comes up in place of the stock menu, and leaving a game returns to it.

To remove Degauss, delete the main= line and the files above. If a return shortcut was configured, also delete /media/fat/config/degauss/frontend_shortcut.bin to remove its saved assignment. Nothing else on the card is touched.

Upgrading from an earlier release

Earlier releases lived in /media/fat/Scripts/.degauss/. When updating over one, degauss.sh moves everything into the new folder on its next start, says Migrating Degauss data to Scripts/.config/degauss... on the console while it does, and removes the old folder: your settings, resume state and index carry over, a degauss.toml, systems.toml or logo you edited stays the active copy, and any other file you kept in the folder follows the move untouched. There is nothing to do.

If anything about an install or upgrade looks wrong, the binary can look itself over:

/media/fat/Scripts/.config/degauss/degauss --check-install

It reports what is present, missing, broken or still waiting in the old folder, and says ok when there is nothing to say.

Showing Degauss on an analog CRT

Degauss is drawn through MiSTer's Linux framebuffer. Seeing the native OSD on an analog CRT does not by itself mean that the framebuffer is routed there. If Degauss appears over HDMI while the CRT shows MiSTer's vga_scaler message, use the native analog route below with Degauss's bundled Main and Menu.

CRT and HDMI at the same time

This example shows the same Degauss interface on both displays. HDMI scales up the CRT image to 1080p60; it does not render a separate interface. Back up the active MiSTer.ini, then update these entries in its existing [Menu] section. Replace the previous [Menu] video_mode line rather than adding another one:

[Menu]
fb_terminal=1
vga_scaler=0
degauss_native_analog=1
video_mode=8

Keep the other settings and do not create a second [Menu] section. For a different HDMI mode, replace 8 with the mode supported by that display.

The [Menu] section applies these settings to Degauss without changing the video configuration used by game cores. With Degauss's bundled Menu core, degauss_native_analog=1 sends the framebuffer to analog at native 15 kHz while HDMI keeps its configured video_mode. It is off by default, so existing HDMI-only and shared-scaler setups do not change.

Optional: keep an existing CRT timing

Start without degauss_analog_video_mode. The bundled Menu uses its default native CRT timing, which may size or position the picture differently from the previous shared-scaler setup.

To retain a compatible CRT's existing width and position, add this optional entry in the same [Menu] section. Replace the placeholder with the numeric values from that display's known-working custom CRT video_mode, then remove the leading #:

# degauss_analog_video_mode=<your compatible CRT timing values>

Leave video_mode=8 for HDMI. The optional entry controls only analog timing and is supported by both bundled Main choices. It requires a progressive custom timing with nonzero horizontal and vertical sync widths; it does not accept an HDMI mode number such as 8.

Some older CRT timings use a zero sync width. They can work with the older shared-scaler route below, but cannot be copied unchanged into degauss_analog_video_mode. Do not change a timing value at random to make it accepted. Leave the optional entry out to use the default CRT timing. An invalid entry reports an INI error; remove it to return to the default.

Older shared-scaler setup

To retain the older shared-scaler route, use vga_scaler=1. In that mode the scaler needs a 15 kHz video_mode supported by the CRT. A mode already known to work with MiSTer's Menu on that display is the best choice. If none is configured, this common MiSTer Menu mode is a reasonable starting point:

video_mode=640,54,56,106,224,16,0,28,13764

That is a custom timing rather than a universal setting, so some displays may need a different compatible mode. With vga_scaler=1, both connected displays receive the same scaler timing and both must support it. See MiSTer's INI settings for more detail.

The recommended installation also uses Degauss's private /media/fat/degauss/menu.rbf while the frontend is open. This preserves colour for framebuffer output over an already configured S-Video or composite setup without replacing MiSTer's /media/fat/menu.rbf. The same fix also restores colour to MiSTer's framebuffer menu wallpapers while this core is active; it is not limited to Degauss's own interface. The stock-menu on-demand mode does not use this private core.

Returning to Degauss from a running core

The recommended installation uses Degauss's MiSTer_Degauss Main binary. While a game core is running, open the OSD and select System → Frontend. Pressing A on Frontend keeps the direct route: it closes the current core and returns to Degauss.

Select System → Frontend shortcut, directly below Frontend, and press A to open the optional keyboard shortcut setting. It defaults to Off, so an existing installation keeps its current input behaviour until it is configured.

Select Keyboard and press A, then press the physical keyboard key to capture. Press X on the row to disable it. Menu or B cancels capture.

A configured shortcut works only while a non-menu core is running, the OSD is unlocked, and no other framebuffer script owns the screen. The setting is stored in /media/fat/config/degauss/frontend_shortcut.bin. A missing file means the shortcut is Off. An invalid or unsupported file is identified in the shortcut screen and can be replaced by selecting Reset shortcut.

This screen and shortcut belong to MiSTer_Degauss. They are not available when Degauss is launched on demand from the stock Main binary as described below.

Optional: starting Degauss from the stock menu on-demand

The installation above is the recommended way to use Degauss. It opens Degauss automatically on boot, returns to it after leaving a game, and adds a Frontend entry to the System menu while a game is running.

If you prefer to keep the stock MiSTer menu as the default, leave the main= line as it is in MiSTer.ini. You can then start Degauss when wanted by opening the OSD and selecting Scripts → degauss.

This requires MiSTer's framebuffer terminal to be enabled:

fb_terminal=1

It is enabled by default in the standard MiSTer configuration.

Degauss can browse the collection and launch games normally when started this way. However, after leaving a game/core, MiSTer will return to the stock menu instead of reopening Degauss automatically. There's not going to be the Frontend option anymore in the cores menu, and you'll need to re-launch Degauss from the OSD if you want to go back to it.

Doing it in this way, the installed /media/fat/degauss/MiSTer_Degauss file is not used.

Using Zaparoo Core with Degauss

Zaparoo Core can run as a separate background service while Degauss remains the selected frontend in MiSTer.ini. Install and start Core using Zaparoo's MiSTer instructions; its optional Zaparoo Frontend is not needed.

A valid launch from a Zaparoo reader, App, Web UI or API closes the active Degauss screen and starts the requested game or core. Returning to Menu opens Degauss again. Zaparoo's mappings and launch settings apply to Zaparoo launches; games started inside Degauss keep using Degauss's own launcher. Degauss does not install or manage Zaparoo Core.

External storage support

Games on a USB stick, the network share or the CIFS mount are found without any setup, in the order MiSTer's own loader searches: /media/usb0 to usb5, then /media/network, then /media/fat/cifs, then the card, each under its games folder. For each system folder the first place that has it wins, so a system kept on both the stick and the card browses from the stick, exactly as the stock menu would load it. Different folders of one system may resolve in different places. The files an MGL names by a relative path are looked for in the same order, under the folder MiSTer Main would use for that core and set name. When only one configured folder actually contains games for that system, Degauss opens it directly. The folder chooser appears only when two or more real locations contribute compatible games.

Degauss checks configured game locations at startup and when opening or returning to the category or system browser. A previously indexed drive that arrives later uses its saved lists without rebuilding. New folders or a newly available higher-priority location prompt Rebuild affected systems or Not Now. Only the affected systems are indexed after confirmation. Not Now keeps usable previous sources and their caches unchanged. The offer can return after browser checks observe the drive disconnected and then reconnected, or after restarting Degauss. Unplugging and reconnecting entirely between checks may keep the previous answer. Storage is not continuously monitored while the browser is idle.

game_roots in degauss-user.toml controls where to search; an absent optional root never causes a startup wait. To require a late mount before startup, add its actual mountpoint to wait_for_mounts in that user file:

# Games are directly mounted here:
wait_for_mounts = ["/media/fat/games"]

If the games root is inside a mounted parent, name the parent instead:

game_roots = ["/media/fat/games", "/media/fat/cifs/games"]
wait_for_mounts = ["/media/fat/cifs"]

An existing directory is not enough: the listed path must be mounted. Degauss starts immediately when every required mountpoint is already mounted; otherwise it waits up to 180 seconds, then offers Retry or continuation with available local games. The complete library index is not replaced by a partial one. Installations that relied on the previous automatic wait based on the stock CIFS script must now explicitly list their required mountpoint. Changes to game files on an already connected drive still need Rebuild this system or a full rebuild. A layout the defaults do not cover is one game_roots edit in degauss-user.toml away. See Manual configuration overrides.

The first run reads the card and writes an index, about a minute for a full one of 97k+ games. It reads the ordinary game libraries only: an installed Artwork Pack is not opened until its system is entered and you say so. Ordinary folder libraries then reuse their saved lists: Options → Library → Rebuild All System Lists is how you tell Degauss the card has changed (for example after adding new games). New images and metadata are read on the fly. A system whose Artwork Pack you chose yourself is prepared again as part of that rebuild, without a question: the choice is the consent. A system that said yes to its pack under Automatic is read the ordinary way, without its pack, and what was prepared for it is left as it was; the next entry into it asks whether to update the pack data for the list just read, and Keep Current goes on browsing on the previous mapping. A system that declined its pack, or was never asked, is read the ordinary way and Rebuild All does not ask it; Rebuild This System List inside that system is what asks again. Automatic Artwork Pack preparation is described below. Adding games to one system does not need the whole card read again: X Actions → Library → Rebuild This System List inside that system reads just its folders. Running it from a subfolder still rebuilds the complete containing system, not only that subfolder. A successful rebuild reflects additions and removals. An unreadable folder reports its error and keeps that system's previous complete list. A malformed archive, or a member inside one that MiSTer cannot launch, is skipped with a warning and the rest of the system is published; the rebuild then finishes as Finished With Problems, naming the system, the archive and the reason (a system prepared from an Artwork Pack names them in its completion message, as does a change of its game data source), with every skipped member written to /tmp/degauss.log.

Global and single-system rebuilds show a progress dashboard with the active system and folder, processed systems, folder/game counts and elapsed time. A Details opens the full scrolling text report; B Overview returns to the dashboard. B Cancel requests cancellation while the rebuild is active. Progress with an unknown total is shown without a percentage; it never performs a second scan just to count the work. Input and repaint stay responsive, and the screensaver stays off during indexing. Completion, cancellation and errors keep their report available until B Back. These operation controls remain visible even when Bottom Bar While Browsing is Off.

ZIP libraries

ZIP archives open as folders, including their internal subfolders, without extracting the library. Systems that already launch ZIP files as individual games keep that behaviour. ZIP64 is supported within the documented bounds. Metadata for a multi-game archive identifies each game by its full archive/member path; single-game archives retain legacy archive-level metadata. An archive holding one game with artwork shows that artwork on its row before it is opened. A damaged archive is skipped whole; a member MiSTer cannot launch (an inner archive, an encrypted entry or one using an unsupported compression method, a legacy-encoded or ambiguous name) is skipped on its own while the other members stay, as is a folder inside an archive that sits deeper than the folder depth Degauss walks, with everything under it, and each skip is reported. See ZIP libraries for details and launch limits. The one exception is a Neo Geo ROM set, described next: a ZIP the Neo Geo catalogue names is one game and is never opened.

Neo Geo ROM sets

The Neo Geo core takes three kinds of game, and Degauss lists all three the way the stock menu does. A .neo file and an .mgl shortcut are games as before. A zipped ROM set such as mslug.zip and an unzipped one, a folder such as mslug/ holding the raw ROM components, are recognised through romsets.xml, the catalogue shipped with the core and placed at the top of games/NEOGEO. A folder carrying its own romsets.xml uses that one instead, exactly as MiSTer Main does; any other folder answers to the catalogue at the top of the first declared game folder, the one MiSTer Main treats as the core's home folder. A library declared over more than one folder (card, USB stick, network share) therefore shares that one catalogue unless a folder carries its own. This applies to Neo Geo and Neo Geo MVS, which share the folder and the catalogue.

A ZIP or folder whose name matches a catalogue entry, ignoring case and including every comma-separated alias the entry lists, is one game. It shows the catalogue's altname; a later alias of a multi-name entry shows as Title (alias), as Main prints it; an entry with no altname keeps the name on the card. An entry carrying the hide attribute is not listed at all, and a folder holding only hidden sets counts as empty. A folder carrying its own romset.xml is a game titled by that file, whatever the catalogue says. A ZIP or folder the catalogue does not name keeps the generic behaviour: the ZIP opens as an archive and the folder as a folder, so organisational folders stay navigable and a Neo Geo folder can still hold ordinary sub-folders of .neo files.

Nothing inside a set is read to list it. A recognised ZIP is never opened or extracted, a set folder is never entered, and its components are not counted or checked: Main validates and loads the selected set at launch, and the MGL Degauss writes names the complete ZIP or folder path in the same file slot a .neo uses. A favourite made from a set is the ordinary MGL MiSTer's own favourites script would write, with the absolute set path, so it works from the stock menu as well for any set the catalogue names. A folder known only by its own romset.xml is the exception: given an absolute path, Main looks for that file under the card root and, not finding it, falls back to the catalogue, so such a favourite starts only if the catalogue names the folder too. A favourite written elsewhere with a bare set name (mslug or mslug.zip, no folder) starts the set as well: the MGL is handed to Main as written, and Main prefixes the core's home folder to a bare path. Degauss looks such a name up in the system's game folder to mark the favourite on its row only when one Neo Geo system claims the name; with the shipped table, where Neo Geo and Neo Geo MVS declare the same folder, the row keeps no heart for it. Gamelist entries bind to a set by its path (./mslug.zip or ./mslug), and an Artwork Pack matches it by set name, an .mgl pointing at a set included.

A catalogue or romset.xml that cannot be read, or whose presence cannot be established, is reported by --report and --audit as an unreadable file, in the log, and with the report of the library build or system rebuild that met it, whether the system uses a Gamelist or an Artwork Pack; each line of that report names the system, since Neo Geo and Neo Geo MVS share the folder and a full rebuild meets the file once for each. A folder listed straight from the card, with no index to report through, says the same line on screen once. Its scope then holds no recognised sets, so ZIPs and folders there fall back to archives and folders, while every .neo and .mgl stays listed. --report also prints the time the catalogues took to read on its metadata line. After upgrading from a release that listed sets as folders, rebuild the system list of Neo Geo and of Neo Geo MVS once each (or run one full rebuild) to pick the sets up: the two keep separate caches even when they share the folder. Nothing else needs resetting.

Installed core launchers, RetroAchievements and Unstable cores

Installed RetroAchievements and Unstable cores can be browsed even when there is no standard version of that core. Degauss discovers these installations; it does not install the cores or configure a RetroAchievements account.

The optional Cores browser also lists direct .mgl profiles from _Console, such as separate SFC and BSX launchers that share the SNES core. Degauss launches the original profile unchanged, preserving its MiSTer setname. Nested per-game MGL collections are not added to the Cores browser.

X Actions → Library → Core Version chooses Default, Standard, RetroAchievements, or a matching Unstable build. The choice is saved for that system and applies to its games and recognized favourites. Use Default Core Version removes that override. Default follows Options → Library → Core Preference and never automatically chooses an Unstable build. A missing explicitly selected version produces an error; it does not launch another version.

When a system declares more than one compatible core family, X Actions → Library → System Launch Core chooses the family for that system. On a playable game, X Actions → Game → Launch Core can override that family for only that game. Use System Setting removes the game override. The choice also applies when the same game is opened through Last Played or a Degauss Favourite; self-describing MGL, MRA and RBF launches and formats with a fixed core do not offer it.

Installed Dual SDRAM builds are labelled Dual SDRAM in the Cores browser and offered in System Launch Core and the per-game Launch Core chooser. The supported layouts are _Console (Dual SDRAM)/Core_YYYYMMDD.rbf and Core_DualSDRAM_YYYYMMDD.rbf (including the published MiSTer-DB9 suffix). Existing core choices and custom systems tables are preserved. These builds require two SDRAM modules; selecting one does not detect or change the hardware. Core Version stays within the selected family: folder-distributed Dual SDRAM builds do not borrow a single-RAM RA or Unstable build. Other filenames or locations can still be declared explicitly through compatible_cores.

The Unstable group browses installed _Unstable cores by their full build names. MiSTer-DB9 builds ending in _YYYYMMDD_<hash>_DB9.rbf are recognized as the corresponding Standard core; matching unstable DB9 builds are recognized too. RetroAchievements requires a compatible RA installation, including its Main profile. Degauss releases include a separate RA Main that retains Frontend and the saved shortcut without being overwritten by the upstream RA updater. Select it in the RA Main profile as described in the RA Main installation instructions. It uses the same saved Frontend shortcut as normal Degauss Main. Unstable cores running under Degauss Main already have the Frontend menu and shortcut.

Views

List: plain text in one column.
Details: the list beside a large picture. Options → Appearance → Details Style chooses how the two share the screen while browsing games: Information, the default, keeps the list wider with a compact year/players and publisher summary under the picture; Large Artwork gives the picture most of the width and the whole height of its column, with no lines under it; Compact gives about one third of the width to the picture and shows more game rows on higher-resolution screens. Game Information in Actions opens the complete metadata in every style.
Tiled: a grid of pictures with their titles underneath.
Carousel: one large cover with its neighbours either side.
Multi list: two text columns in reading order, showing twice as many entries as List. Only the selected long title scrolls.
Gallery: a denser image grid with no permanent captions. The selected image has an outline and its title appears above the bottom bar for half a second. Entries without artwork remain visible as named text cells.

The Details Style changes only the games level of Details: the Home, category and system screens and the other views keep their proportions, and switching it does not rebuild the library or the artwork cache. It is saved as details_style in settings.toml; a saved value that is neither information, large-artwork nor compact draws Information and is left in the file for you to correct. That substitution is reported on the first screen, unless a library read starts at the same time and takes the screen first, and always in /tmp/degauss.log, which is the copy that survives such a read. Pictures are decoded to cover_size under [app] in the effective configuration or half the longer screen edge, whichever is larger. With the shipped cover_size of 320 and the default screen margins, the Large Artwork box outgrows that decode on landscape screens wider than about 600 pixels (a little sooner for a portrait picture on a 4:3 or 5:4 screen), so a picture is drawn slightly enlarged there; on a landscape screen, a cover_size of at least two thirds of the screen width keeps every picture within its decode.

Options → Appearance → View is the global default. Every browse place can instead keep its own custom view: Home, each category's Systems screen, each system root, and every folder inside a system. Use X Actions → Appearance → Change View at that place to create or update its custom view. Use Global View, in the same group, removes only that place's custom view; it then follows later global changes again. A custom view remains custom even when it currently matches the global setting. At Home these view controls are directly in its flat Actions menu.

X Actions → Appearance → Custom Views creates named views from four templates: two columns, a left column with two panels on the right, two panels on the left with a right column, or two stacked panels. On Home and in Explore, Custom Views is directly in Actions. Exactly one panel is the browser list; the others can show artwork, short information or full information. Choosing a new list panel moves the existing list rather than creating a second selection.

Options → Appearance → Custom Views opens the same manager from the general menu, immediately below View.

In the editor, Up/Down chooses a panel or divider and Left/Right changes its content or proportion with a live preview. X Save stores the view; B Cancel leaves saved views unchanged. Saved names appear alongside the six built-in choices in View and Change View. Custom Views also offers Use Here, Use Globally, Edit, Save As, Rename and Delete. Deleting a named view removes its assignments; existing built-in assignments are unchanged. Proportions adapt to the screen and its safe area, including portrait. Core Updates keeps its dedicated Details presentation.

Full information is read only for the settled selected game, from its configured Gamelist or Artwork Pack. Long information scrolls slowly after a brief pause. Actions → Game → Focus Information gives Up/Down to text scrolling; B returns to list navigation. On Home and Explore this action is directly in Actions. Non-game rows do not show invented game metadata.

View changes are saved when leaving the Actions page, before returning to browsing or opening another action. A save error keeps the menu open with the underlying problem, so the change is not silently lost after a restart.

For a playable game, Game Information is the first entry in X Actions → Game from any browsing view. It shows the title, artwork, description, publisher, developer, full release date, players, language and available genre. Scroll to inspect long values and the full description; left/right moves by a page. B or X returns to Actions / Game, and backing out restores the same game without launching it or changing the view. Information comes from the system's selected Gamelist or Artwork Pack source, including for favourites. Missing fields remain empty. Details in its Information style keeps the compact summary; Large Artwork and Compact leave it to Game Information, where all available fields and the complete description can be read.

Complete descriptions are read only when Game Information opens, with a visible loading or error state. Existing compact caches remain valid; no library rebuild is required. This does not add description reads to ordinary browsing or indexing.

Folders appear in square brackets with the number of games inside them, counted through every subfolder, and can sit before the games or after them. Favourites carry a heart in every view and can be gathered at the top of their folder.

A folder or ZIP that holds exactly one game with artwork, whatever else without a picture sits beside it, or several entries that all share one picture such as a multi-disc game, shows that game's artwork in Details, Tiled, Carousel and Gallery before it is opened. It is still a folder: it keeps its own name and count, opens as a folder, and inherits nothing else from the game. A folder holding two or more games with different pictures, no artwork at all, or several entries sharing a picture beside one without, keeps the system logo. List and Multi list stay text. Hidden entries never contribute their artwork, Favourites shelves keep their heart, and the picture follows the selected data source of the system. The picture is answered from the system's saved list, so a system browsed before its list has been written keeps the system logo on its folders until it is indexed or rebuilt.

By default, handheld systems remain in the same MiSTer categories their cores use. Options → Library → Separate Handheld Category can instead present recognised handheld systems in a dedicated Handheld category. This changes only navigation: system discovery, games, artwork, favourites and launching keep their existing system identity.

Filter Games, in Actions → Find, temporarily narrows the current folder by genre, year, players, language, developer or publisher. Values come from the complete unfiltered folder; Unknown means the field is missing and Unavailable means no game supplies it. Selected fields combine with each other and with Search, while folders remain visible. B keeps the selected filters. Clear Filters leaves any title search in place, and Clear Search leaves the metadata filters in place. Random Game and Random Favourite use only the matching games in the current folder while a metadata filter is active. Filters are not saved and clear when the folder is entered or left, its system list is rebuilt, or Degauss restarts.

Hide This, in Actions → Find, takes any row out of the list: a game, a folder, or a whole system while you are looking at the system list. That is separate from the folders and systems left out because they hold no games at all, which Show Systems with No Games governs. Show What You Hid shows the rows you hid without unhiding them, and Unhide Everything puts them all back. These settings are in Options → Library.

The screensaver, after the set time, drifts through game images taken from your own card. Optional Attract Mode lets A launch the pictured game, Left/Right move between systems and B return to Degauss. It is off by default, so any button still just wakes the ordinary screensaver. Separately, Show Attract Mode on Home adds an immediate launcher to the main browser, even when the idle screensaver and automatic Attract Mode are off. Options → Shortcuts can instead assign Start Attract Mode to a one-second button hold without enabling the Home entry.

Settings

Open Y Menu → Options, then choose Navigation, Shortcuts, Appearance, Library, Display or Developer. A enters a page; B returns to the Options categories. Left and right do nothing on the category list. Each page keeps its selected row during the current session. Inside a page, left/right adjust values and A adjusts a value or runs the selected action. Reset actions require A and confirmation, never a sideways press.

Page	Setting	Does
Navigation	Scroll Speed	How fast a held direction moves through the list. 3x out of the box
Navigation	Skip Artwork Faster Than	Above this speed, pictures wait until the list stops. 6x out of the box
Navigation	Left and Right Behaviour	What left and right do while browsing: Scroll Speed Change (the default), Letter, Page or Direction. Letter and Page repeat while held; in Direction, left and right move one entry and up and down move a whole row in Tiled, Multi List and Gallery
Navigation	Swap A and B	Off by default. Swap the controller's A and B actions inside Degauss only; keyboard controls and launched software are unchanged
Navigation	Swap X and Y	Off by default. Swap the controller's X and Y actions inside Degauss only; keyboard controls and launched software are unchanged
Navigation	Random Game Behaviour	Whether either random action starts the game, or only moves to it so you can look first
Shortcuts	Hold A / Hold B / Hold X / Hold Y	Off by default. Assign None, Cycle View, Random Game, Random Favourite, Add/Remove Favourite, Game Information, Search This Folder, Jump to Letter, Actions, Menu or Start Attract Mode to each one-second hold. Assign Actions and Menu to A/B for two-button controllers. Short presses retain their normal action. Holds work only while browsing and only where the chosen command is available; otherwise the normal press is immediate
Appearance	Theme	Left and right choose a palette. Press A to open the editor. Standard uses the colours in `degauss.toml`. See Themes and colours
Appearance	View	The global default for places without a custom view: Details, Tiled, Carousel, List, Multi List or Gallery
Appearance	Custom Views	Create, edit or choose a named template-based view
Appearance	Reset Views Selections to Global	With A and confirmation, remove every place-specific view selection without changing the global View or deleting named custom views
Appearance	Start Folder	Home by default, or any currently available top-level folder. If the saved folder is no longer present, Degauss safely starts at Home without replacing the choice
Appearance	Details Style	How Details shares the screen while browsing games. Information (default) keeps the list beside a picture of about 42% of the width, with the summary under it; Large Artwork gives the picture about 62% and the whole column height; Compact uses about 33% for the picture and shows more rows on higher-resolution screens
Appearance	Game Name Display	Full (default), remove parenthesised tags, remove square-bracketed tags, remove both, or retain only recognised region and/or disc-index tags. This changes presentation, sorting and search only; names stored in files and caches are unchanged
Appearance	Use MRA Filenames for Arcade Titles	Off by default. On shows each Arcade MRA's exact filename without `.mra`, retaining variant tags regardless of Game Name Display. Sorting and search follow the displayed title; artwork, metadata and launch targets stay unchanged
Appearance	Folder Brackets	On by default. Turn off only Degauss's outer `[ name ]` marker for folders; square brackets that are part of the underlying name still follow Game Name Display
Appearance	Game Total/Position	On by default. Turn off the selected-position and total counter while browsing games
Appearance	Text	The typeface: Smooth, Pixel (a DOS font on whole pixels), and the bolder Smooth 2 and Pixel 2
Appearance	Artwork	Turn pictures off entirely
Appearance	CRT Image Smoothing	On by default for 240p/288p output: smoother artwork and logos in the browsing views and screensaver. Off uses the original, faster scaling; higher-resolution output is unchanged
Appearance	Artwork Scale Factor	Framebuffer keeps the original square-pixel fit and is the default. 4:3 and 16:9 correct game artwork for that physical display shape in Details, Tiled, Carousel and Gallery, including a folder or Last Played showing a game's artwork. Category logos, system logos and the screensaver are unchanged
Appearance	Bottom Bar While Browsing	On by default. Show the time and button hints while browsing. A saved Off choice stays Off after updating or restarting; menus and operation controls remain visible
Appearance	Screensaver	How long with nothing pressed before pictures start
Appearance	Attract Mode	Off by default. When on, A launches the game pictured at the centre and Left/Right moves between systems
Appearance	Show Attract Mode on Home	Off by default. Add an immediate Attract Mode entry to the main browser, independently of idle screensaver settings
Appearance	Screensaver Speed	Normal (default), 2x or 4x picture movement, independent of the idle time
Display	Video Effects	Off by default. Choose a supplied or custom Degauss mask, one of the general MiSTer presets, or a user-created preset in `Presets/Degauss`. Core-specific and incomplete presets are not offered. Off removes both kinds of Degauss effect. Effects apply only while Degauss is open, on HDMI and scaled analog output, not games
Library	Favourites First	Show favourites first in each folder, keeping them in alphabetical order
Library	Folders Before Games	On, folders lead a system's listing; off, the games come first
Library	Core Preference	Standard First (default) or RetroAchievements First. Used by systems whose Core Version is Default; the other version is used only when the preferred version is absent
Library	Automatic Data Source	Gamelist First (default) or Artwork Pack First. Applies only to systems whose Game Data Source remains Automatic; explicit per-system choices always win
Library	Auto-run Physical Discs	Off by default. Launch supported inserted discs through an installed `MiSTer_Physical-CD` or `MiSTer-disc` provider
Library	Separate Handheld Category	Off by default. When On, recognised handheld systems appear in a Handheld category after Console. This is a display-only grouping and does not change core or game launching
Library	Show Other Folder	Show the Other group, the cores that are not games
Library	Show Utility Folder	Show the Utility group, test patterns and measurement cores
Library	Show Unstable Folder	Show installed Unstable cores. On by default
Library	Show Scripts Folder	On by default. Show Scripts in the main browser to browse and run installed `.sh` files. Turning this Off hides the entry without changing the files
Library	Show Core Updates	Off by default. Show every installed core and uninstalled cores selected by this MiSTer's configured Downloader databases
Library	Show Explore Games	Off by default. Show Explore after Last Played on Home. Edit Home can also show or hide it
Library	Show Systems with No Games	Systems and folders holding nothing are left out on their own; this shows them. Off by default
Library	Show What You Hid	Show what you hid yourself with Hide This
Library	Unhide Everything	Press A and confirm to put back everything you hid yourself, in every folder and every system. Left and right do nothing
Library	Rebuild All System Lists	Press A to read the whole card again. Run it after adding games, cores or artwork; Actions → Library → Rebuild This System List rebuilds just the containing system. Left and right do nothing
Library	Scrape All Systems	Press A to choose ScreenScraper or Libretro for all supported systems. Artwork Pack systems are skipped; the master Favourites system is not a scrape target
Display	Edge Margin, Sides	Keep this much of each side clear of the bezel
Display	Edge Margin, Top and Bottom	The same, vertically
Display	Screen Position, Sideways	Nudge the picture, for a screen that sits off centre
Display	Screen Position, Up and Down	The same, vertically
Display	Screen Rotation	Off by default. Rotate the complete Degauss interface 90° Clockwise or Counterclockwise for a vertical display. A keeps the preview; B or the 15-second timeout reverts it. This does not change MiSTer video modes or game rotation
Developer	Switch INI	Choose Main or an available alternate MiSTer INI profile, then confirm. This reloads Menu and uses the selected profile's `main=` frontend. If video is invisible while Degauss remains running, hold B/Back and press Right for Main, Left for the first alternate, Up for the second or Down for the third. Unavailable slots do nothing
Developer	Drawing Path	Draw into the screen directly, or into memory first
Developer	Performance Readout	Replace the key hints with frame timings

degauss.toml contains shipped defaults. Changes made in Options are written to settings.toml beside it when leaving an Options page. If saving fails, the page stays open and a message explains the problem. Changes remain active for the current session; dismiss the message and press B again after resolving the storage problem to retry saving. Delete settings.toml to reset UI preferences. Manual overrides still apply.

Manual configuration overrides

Create degauss-user.toml beside degauss.toml, normally at /media/fat/Scripts/.config/degauss/degauss-user.toml, only when manual configuration is needed. Updates deliver degauss.toml, not your user file. With --config, the user file is looked for beside the selected configuration.

Put only intentionally overridden values in it. Keys omitted at the root or inside a section retain the shipped defaults. Arrays replace the complete array and keep the order you supply. For example, to wait for a mounted share:

wait_for_mounts = ["/media/fat/cifs"]

Manual settings include game_roots (game search locations and order), wait_for_mounts (required startup mounts), menu_root (a custom MiSTer menu root), and optional artwork tuning cover_size and art_cache under [app]. For example, changing only the decode size requires:

[app]
cover_size = 400

Do not copy all defaults into the user file. UI preferences remain in settings.toml; edit and save colours through Options → Appearance → Theme → press A. The user file is not rewritten by Options. An unreadable or invalid user file is ignored for that run, with its path and underlying cause in /tmp/degauss.log; the base configuration, UI preferences and themes still apply. No partial overrides are used. --check-install reports an invalid or unreadable user file separately.

Move only custom values you manually edited in degauss.toml into degauss-user.toml once, keeping any required TOML section headers, so future updates preserve them. Preferences chosen in Options and saved themes do not need moving.

Themes and colours

Edit all ten palette colours through Options → Appearance → Theme → press A, then save a named theme. The colours are roles rather than fixed hues:

Role	Does
`background`	The ground behind everything
`panel`	The title strip across the top of menu screens
`surface`	Raised surfaces: cards, the artwork plate, modal panels
`bar`	The strip along the bottom, darker so its small text reads
`text`	Ordinary text
`text_dim`	Secondary text: counts, hints, the clock
`accent`	The selection bar and focus ring
`accent_text`	Text drawn on top of `accent`
`state`	Toggles, progress, anything that is "on"
`favorite`	The favourite markers

A theme is one .toml file in the themes/ folder beside degauss.toml (Scripts/.config/degauss/themes/ on a card), naming any of those ten roles, and its file stem is its name in the Theme row of Options. The roles go in as bare keys or under a [colors] header in a theme file. Roles it does not name use the shipped palette. One more key, logo, at the top level, draws the wordmark as a flat silhouette in that colour; leave it out and the wordmark keeps its own three colours. The optional top-level logo_opacity is an integer from 0 to 100: 0 keeps the original three-colour artwork, 100 uses only the selected logo colour, and values between them blend the two without making the wordmark transparent. Leave it out and a named logo colour keeps the fully monochrome result used before this setting existed.

The optional top-level font sets the theme's default typeface when that theme is selected. Its values are smooth, pixel, smooth 2 and pixel 2. A theme without font, or with an unrecognised font, uses the system-wide Text choice. It never inherits the font of the theme selected before it. An unrecognised value is also reported. After selecting a theme, Text remains an independent option: changing it overrides the current theme default and that choice continues across restarts.

The optional top-level text_size sets list and menu text to smaller, small, default, large or larger. It does not change the number of rows, artwork, the bottom bar, dialogs or Theme Editor controls. Themes without this key retain the original Default size. The same setting is available as List text size in the Theme Editor, with a live preview.

A theme can be five lines. themes/Night.toml:

font = "pixel 2"
background = "#101318"
accent = "#33FF33"
logo = "#33FF33"
logo_opacity = 80

picks a darker ground, a green selection bar and a wordmark blended 80% towards green from its original colours, and every other colour uses the base palette. The on-device editor can save a complete theme without manually editing configuration files.

Six themes are available as starting points: Amber, Mono, Blue-Orange, Green Mono, Modern and Neon. Green Mono defaults to Pixel 2, Neon to Pixel, and Modern to Smooth 2. The three older file-based themes do not set a font, so they use the system-wide Text choice. None of the six names favorite, so the hearts keep your own favourite colour under every palette: red unless changed in your saved theme.

The updater manages the Amber, Mono and Blue-Orange files, so edits to those files are overwritten on the next update. Copy one under a new file name to keep your version. Green Mono, Modern and Neon are built into the program, so an update does not write files with those names. A theme file on the card with the same name takes precedence.

The card-theme folder is read once at startup, so a file added while Degauss is running appears after the next start. Green Mono, Modern and Neon remain available without files because they are built into Degauss. The chosen theme is remembered by name in settings.toml. If that name resolves to neither a built-in theme nor a valid card-theme file, Degauss uses the standard palette and a message says so on the first screen (unless a library read starts at the same time and takes the screen first) and in /tmp/degauss.log. A same-name card file takes precedence over a built-in; if that file is broken, Degauss reports it instead of concealing it with the built-in theme.

Editing a theme on-device

Highlight Theme in Options → Appearance and press A. The editor starts from the currently selected palette and previews every change immediately.

Control	Does
up / down	choose a colour role or control; in the continuous picker, choose the red, green or blue channel; in hexadecimal editing, change the selected digit with an immediate preview
left / right	choose another starting point, change the theme's Default text or List text size, change the selected RGB channel through its smooth gradient in five-unit steps (hold to repeat), switch logo colour between Original and Selection, change logo colour mix in five-percent steps, or select a hexadecimal digit
A	open the continuous colour picker, apply the already-live colour, or activate Save changes, Save as and other controls
X	choose another palette role and swap its exact colour with the selected role; switch between the continuous picker and exact hexadecimal editing; in the name grid, delete one character
Y	restore the colour that was present when the picker opened; in the name grid, cycle lowercase, uppercase and symbol pages
B	cancel the current edit or leave the editor; changed themes require explicit discard confirmation

An editor-created theme has Save changes, which updates that theme under the same name, and Save as, which keeps it and creates another theme. Built-in and hand-written themes remain protected and offer Save as only. Updating is transactional: if the replacement or settings cannot be saved, the previous theme file remains usable and the error stays on screen.

Save as opens a paged controller-operated name grid. Y cycles its lowercase, uppercase and symbol pages, X deletes one character, SP enters a space and Clear clears the complete name. Its green checkmark saves and its red X cancels. Saving writes a complete .toml file into Scripts/.config/degauss/themes/, selects it, and stores its name in settings.toml; the default text and list-size choices remain part of the theme file. Names use the characters shown on the grid; \, /, :, *, ?, ", <, > and | are excluded because they cannot be used in these filenames. An existing theme is never overwritten. A save error remains on screen and the unsaved draft stays in the editor.

A theme saved by this editor also has a Delete theme control. Existing canonical editor-saved themes are recognised too. Deletion requires confirmation and removes only that selected custom theme; shipped themes do not expose this control.

Proposing a theme for an official release

Start from the complete theme-template.toml, change all ten colour roles, and test the file in Degauss. Put it in /media/fat/Scripts/.config/degauss/themes/ under a new file name and restart Degauss. The file name without .toml is the name shown in Theme under Options. The optional top-level logo key can colour the wordmark; leave it out to keep the original three-colour wordmark.

Open a Theme proposal, paste the complete TOML, and attach at least one screenshot showing the theme in Degauss. Do not include private information in the screenshot.

A proposal becomes eligible for release review when at least three distinct GitHub accounts other than the submitter each add a comment whose complete voting line is:

Vote: include

Reactions, repeated comments from the same account, the submitter's own comment, and comments with different voting text do not count. Reaching three eligible comments does not guarantee inclusion. The theme must still parse, keep every UI role readable, and pass the project checks.

Artwork and metadata

Degauss reads gamelist.xml in the EmulationStation format, in the same folder as the games. Paths inside it are relative to that folder. Normal browsing is read-only. Only the optional scraper described below writes a gamelist, and only after you explicitly start a scrape.

The minimum useful entry is a path, a name and a picture:

<gameList>
  <game>
    <path>./Boulder Dash.d64</path>
    <name>Boulder Dash</name>
    <screenshot>./media/screenshot/Boulder Dash.png</screenshot>
  </game>
</gameList>

Everything Degauss reads, in one entry:

<game>
  <path>./Gran Turismo 2 (Arcade Mode).chd</path>
  <name>Gran Turismo 2 (Arcade Mode)</name>
  <desc>Gran Turismo 2 is fundamentally based on the racing game genre.</desc>
  <publisher>Sony Computer Entertainment</publisher>
  <developer>Polyphony Digital</developer>
  <releasedate>19991223T000000</releasedate>
  <players>1-2</players>
  <lang>en</lang>
  <genre>Racing</genre>
  <favorite>false</favorite>
  <image>./media/covers/gt2.png</image>
  <screenshot>./media/screenshot/gt2.png</screenshot>
  <thumbnail>./media/thumbs/gt2.png</thumbnail>
</game>

<image>, <screenshot> and <thumbnail> are all read, in that order of preference. <releasedate> is the EmulationStation timestamp form and is shown as a date; a month or day of zero means only the year is claimed. Only <path> is required.

The same file works for every system, awkward ones included. What changes is only what <path> points at:

<!-- AmigaVision: a title inside the disk image, not a file on the card -->
<game>
  <path>./Games/Zool 2 (AGA)[en]</path>
  <name>Zool 2 (AGA)[en]</name>
  <image>./media/screenshots/zool2.png</image>
</game>

<!-- Neo Geo: a ROM set is a folder of ROMs, or a ZIP of them -->
<game>
  <path>./mslug</path>
  <name>Metal Slug</name>
  <screenshot>./media/screenshot/mslug.png</screenshot>
</game>
<game>
  <path>./mslug.zip</path>
  <name>Metal Slug</name>
  <screenshot>./media/screenshot/mslug.png</screenshot>
</game>

<!-- Arcade: an .mra names its own core and ROM set -->
<game>
  <path>./DoDonPachi (World, 1997 25 Master Ver.).mra</path>
  <name>DoDonPachi</name>
  <screenshot>./media/screenshot/ddonpach.png</screenshot>
</game>

Using MiSTer Game Artwork Databases

Degauss can also read the local MiSTer Game Artwork Databases installed by MiSTer's Update All and Downloader tools. Automatic is the default when no per-system source choice has been saved. Options → Library → Automatic Data Source sets its priority:

Gamelist First is the default and preserves existing behaviour. A gamelist.xml in any library root keeps the system on Gamelist; otherwise Degauss looks for an installed pack.
Artwork Pack First offers or reuses an installed pack when available; otherwise the system uses Gamelist.

This option never rewrites explicit per-system choices. In either priority, pack discovery stays lazy: when the relevant Automatic system is entered, Degauss looks under docs on SD, then USB0 through USB7, and asks before reading an unprepared pack:

Artwork Pack Available

An installed Artwork Pack was found for NES. Prepare its artwork and metadata now?

A Prepare   B Not Now

Prepare reads the pack and matches that one system's games, with the same progress, Details and B Cancel as a system rebuild; the system opens with the pack's artwork and metadata once the result is installed. Not Now opens the system with its ordinary data and is remembered for that pack as it is, so the same unchanged pack is not asked about at every entry; a pack that has changed since is offered again. Any other press takes the question down without deciding anything. A system you never enter causes no pack work at all, however many packs are installed, and installing every pack through Update All does not make the first run prepare them. With neither a gamelist nor a pack, the usual filesystem presentation remains available. A candidate location that cannot be looked at is reported, not silently skipped to another source; a docs, or a mapped Artwork folder under it, that is a link to somewhere outside its own mount is not offered, and degauss.log says so. Existing saved Artwork Pack locations retain their meaning.

Older settings did not record an explicit Gamelist choice. An existing settings file without a saved Pack choice therefore uses Automatic, so an installed pack is offered according to the global priority when the system is entered. Choosing Gamelist now saves that explicit choice. No migration or reset is needed. If the new global setting is absent, it resolves to Gamelist First, so existing installations retain their current source behaviour.

Install and update a database through Update All → Settings → Extra Content → Game Artwork DBs. Update All also chooses its 2D, 3D or mixed artwork style. Degauss does not download, update, repair, change the style of or uninstall these databases; it reads whichever complete local style those tools installed.

Databases can also be downloaded directly from the original MiSTer Game Artwork Databases repository. Degauss reads the installed database in place rather than importing or copying it. Game Data Source is selected separately for each supported system from its X Actions → Library menu. The global option changes only the priority used by systems still set to Automatic.

To choose a pack manually:

Highlight a supported system, or browse inside it, and press X.
Open Library → Game Data Source.
Choose Artwork Pack.
Confirm the detected docs location. If more than one installation is present, choose the one Degauss should use.

Degauss checks the normal SD, USB and network mount points and the mounts used by configured game roots. A normal installation is under docs/<System>/Artwork, for example /media/fat/docs/SuperGrafx/Artwork or /media/usb0/docs/SuperGrafx/Artwork. Games and artwork do not have to be on the same device. A directory browser is available for a valid installation in another permitted MiSTer storage location; it starts at /media, above the normal SD, USB, network and CIFS mount directories. A directory whose mapped Artwork folder is a link to somewhere outside that permitted storage is not accepted as a pack, and degauss.log names the folder.

The choice applies to the complete system, including all of its game folders. Neo Geo and Neo Geo MVS share one choice because they use the same library and database; what they share is the saved mode, so under Automatic each of the two is still asked about, prepared and remembered on its own. Favourites have no separate choice: each one follows the current source of the system that owns its game.

The source menu shows both the saved mode and its effective source, for example Automatic (Using: Gamelist). Under Gamelist First, a root gamelist.xml takes the system back to Gamelist at the next entry and next start. Under Artwork Pack First, an accepted prepared pack stays in use when a gamelist is also present. Switching the global priority leaves prepared Pack state intact, so an unchanged Pack is reused without another scan. A previous Not Now decision remains respected for that same Pack state. Automatic checks only standard SD/USB locations; the explicit Pack picker continues to support network and custom locations.

What a preparation remembers is written beside the system's cache: the system, the pack location, a signature of the pack's tables, the language the descriptions were prepared for, the version of the matching rules and the list the mapping was prepared from. Entering the system again, after a game or a restart, checks that signature against the pack with a handful of file stats, then opens at once: no table is parsed, no row is walked and no ROM is checked again. The manifest, whose size grows with the number of images in the pack, is read and checksummed again only when the Artwork directory or the manifest's own size or time changed. The stats cover the tables that were there at preparation and the fixed names, index.tsv, gameinfo.tsv, manifest.tsv and the synopsis tables of the preferred language and of English; a synopsis in another language added later is picked up by Rebuild This System List. Images are read from the pack on demand as before, so an image replaced at its path shows its new picture without any rebuild: a file renamed into place, added or removed shows, or stops showing, at the next entry; a file overwritten in place, or copied over its existing name, at the next start or after Rebuild This System List. The mapping itself is not touched by any of these; only the pack's completeness warning waits for the next preparation. Favourites and the screensaver use the same written-down mapping; a system that has not been prepared contributes its ordinary data to them. A state file beside the cache that cannot be read is reported when the system is entered, and nothing is asked or written over it.

When the check finds that a table, the pack location, the language or the system's own list has changed since the preparation, Degauss asks before doing the work again:

Artwork Pack Changed

The installed Artwork Pack data for NES has changed. Update its prepared artwork and metadata now?

A Update   B Keep Current

Update prepares that one system again and replaces the previous result only once the new one is complete. Keep Current keeps browsing on the previous mapping and is remembered for that change, so it is not asked about again until the pack, the language or the system's own list changes once more. When the system's own list changed, after Rebuild All System Lists, the previous mapping is applied to the new list: games it knows keep their pack data, games added since have none until the pack is prepared again. When the prepared list itself is gone, there is no previous result to keep, and Keep Current opens the system with its ordinary data. The system's prepared data is never written again without one of these answers. An image added or removed is not a change to the mapping and asks nothing: the picture shows, or stops showing, at the next entry, and the pack's completeness is looked at again at the next preparation. Rebuild This System List is the deliberate way to prepare the current pack whatever was kept, and on a system whose pack was declined it asks the question again first. A cancelled or failed preparation writes nothing: without a previous result the system opens with its ordinary data, with one the previous result stays in use, and the next entry asks again. If the storage holding a prepared pack is missing, the system says so at every entry while it is missing, and opens on its ordinary rows only behind that message; the prepared result is kept for when the storage is back, and the favourites and the screensaver use it again as soon as it is. Two systems that share one database, such as Neo Geo and Neo Geo MVS, are each asked about and prepared on their own.

Explicit choices need no question: Artwork Pack is the consent, and the pack is prepared as the source is switched; Gamelist stops every pack check and question for that system. Caches prepared by the previous release keep working: each is tied to its pack the first time its system is entered, by one worker read with the usual overlay, and reused from then on. Nothing is reprocessed at startup and nothing needs a reset. A cache that no longer matches the pack installed now is kept and asked about instead, with the same Artwork Pack Changed question: there is no current result to keep browsing on, so Keep Current keeps the file but opens the system with its ordinary data; Rebuild This System List, and Update when it asks, is the way to use the pack again.

The two effective sources are deliberately exclusive:

Gamelist is an explicit saved choice, even without XML, and uses the existing gamelist.xml name, artwork and metadata. It disables automatic pack selection until Automatic is chosen again.
Artwork Pack uses only the selected local database for game artwork, display name, year, genre, developer, players and description.

If an individual game or field is absent from the database, Degauss keeps the filesystem-derived game name and leaves that artwork or field empty. It never fills the gap from the gamelist or ScreenScraper. Publisher and game language also remain empty because the database format does not provide them. A folder showing its game's artwork takes that picture from the selected source too, and keeps the system logo while the Pack is unusable or has no picture for the game. System logos and category images remain independent of this choice.

MRA entries are matched by their <setname>, including MGLs that point to an MRA. Large embedded hexadecimal ROM, patch and cheat payloads do not impose a whole-file size limit on that lookup. XML identity metadata remains bounded to 1 MiB; this is separate from artwork image limits. A descriptor Degauss cannot read (missing or a dangling link, unreadable, malformed XML, an MGL chain that loops or runs past eight files, or one whose game is missing or found in two of its system's folders) is left out of the pack mapping only: the game stays listed with its filesystem name and no pack artwork, the preparation finishes as "prepared with problems" saying how many games and why, each path is written to /tmp/degauss.log, and Rebuild This System List after repairing the file matches it normally. A missing or unreadable database location, a damaged database, a cache that cannot be written, or a read error that is the process's or the storage's rather than the file's (out of file descriptors or memory, a device error) still stops the whole preparation and keeps the previous complete result.

An MGL is read the way MiSTer Main reads it. A <file path> written absolute is used as written. Any other path, ./ and ../ forms included, is looked for under the core's home directory, never beside the MGL: games/<setname> when the MGL carries a <setname> (without same_dir="1"), otherwise the core's own games folder, found in the same storage order as the system folders. An MGL for one of the systems in the table is identified by the game it names, its last <file>, as before. An MGL for a core outside the table, such as an arcade core with its ROM set spelled out as several files under _Arcade, is identified by its own name and <setname>: every file it names by a non-absolute path has to exist under that home directory, and none of them is hashed. A file present in two of a system's folders at once is reported in /tmp/degauss.log and left unmatched rather than picked by folder order. A <setname> that is not one folder name (a /, . or .. step in it) is looked for nowhere, so a <setname> cannot lead that home directory lookup outside the game roots; a <file path> written absolute is used as written, wherever it points. Neo Geo ROM sets, zipped or unzipped, are matched by their set name (the ZIP's stem or the folder's name), which the Neo Geo database indexes with every catalogue alias; a set is never opened or hashed for the lookup.

Selecting an Artwork Pack never edits or removes the existing gamelist or its media. Choose Gamelist again to restore them immediately. While Artwork Pack is selected, that system's scrape entries in Actions are hidden and Scrape All Systems reports it as skipped before checking scraper login or making a request.

Correct a missing or wrong Pack match

While a game uses Artwork Pack data, open X Actions → Game → Artwork Pack Match. Choose from up to eight nearby names with picture previews, or use Search Pack... (X) to enter a title. A applies that entry's artwork and metadata to the selected game; B leaves without saving.

The choice is saved in Degauss's settings.toml, outside the pack. No pack file is edited and no image is copied. The game's launch target is unchanged, and the same choice appears in Favourites, Last Played and Attract Mode. Automatic Match removes the choice and restores normal matching.

Choices refer to the pack's index names. When accepting a normal pack update or rebuilding the system list, they resolve against the updated data, including corrected pictures. If a saved name disappears, Degauss reports the unavailable match rather than choosing a different game. Select another entry or Automatic Match to clear it. Switching to Gamelist keeps saved Pack choices but does not use them until Pack is selected again.

This matches games to pictures already in the pack. It does not scrape new pictures or fill Pack gaps from a gamelist. To use scraped pictures for a system, select Gamelist as its Game Data Source.

Degauss rechecks a selected database when the system is entered, with the lightweight signature described above. After Update All replaces a style or updates the database, leave and reopen the system: it asks whether to update the prepared result. A damaged database is reported as incomplete once per database state: dismissing the warning writes it down in artwork-pack-warnings.toml beside settings.toml, so it does not come back after a game launch or a restart until the selected location, the database content, its health or its diagnostic changes. A missing or invalid database is reported again at every start of Degauss; it remains selected and produces no stale or gamelist fallback data. Reconnect its storage, repair it through Update All, or choose Gamelist. The complete diagnostic is still written to /tmp/degauss.log and printed by --system <id> --report; delete artwork-pack-warnings.toml and restart Degauss to see acknowledged warnings again. Games remain browseable and launchable from their normal filesystem entries.

Only systems with a reviewed database mapping show Game Data Source. Currently supported systems are 3DO, Amiga CD32, Arcade, Atari 2600, Atari 5200, Atari 7800, Atari Lynx, CD-i, ColecoVision, FDS, Game Boy, Game Boy 2P, Game Boy Color, Super Game Boy, GBA, GBA 2P, Game Gear, Game Gear 2P, Genesis, Intellivision, Jaguar, Mega CD, Nintendo 64, Neo Geo, Neo Geo MVS, Neo Geo CD, Neo Geo Pocket, Neo Geo Pocket Color, NES, Odyssey 2, PlayStation, Sega 32X, SG-1000, Master System, SNES, Saturn, SuperGrafx, TurboGrafx-16, TurboGrafx-16 CD, Vectrex, Virtual Boy, WonderSwan and WonderSwan Color.

Scraping with ScreenScraper

Degauss can create or update these same gamelists from ScreenScraper.fr. A free ScreenScraper account is required. Open Y Menu → Options → Library → Scrape All Systems for the whole card, or press X to open Actions → Library and choose Scrape This System, Scrape This Folder or Scrape This Game. The master Favourites shelf is never a scrape target.

Official Degauss binaries already contain the application authorization needed to contact ScreenScraper. Users enter only their own ScreenScraper username and password.

Enter the ScreenScraper account username and password, then choose separate policies for pictures and metadata:

Setting	Behaviour
Images: Off	Never downloads or changes artwork.
Images: Missing only	Keeps the effective `<image>`, `<screenshot>` or `<thumbnail>` when its file exists, and fetches a picture only when artwork is absent or broken.
Images: Replace existing	Downloads the selected ScreenScraper media and makes it the entry's `<image>`. The previous media file is not overwritten or deleted.
Metadata: Off	Never changes metadata.
Metadata: Fill missing	Fills empty fields and preserves every non-empty local or inherited value. A folder, system or all-systems run treats an entry with any non-empty local or inherited field as complete; Scrape This Game and Search Manually fill its empty fields one by one.
Metadata: Replace existing	Replaces only fields ScreenScraper actually returned. A missing upstream value never erases a local one.

Both settings cannot be Off when a scrape starts. The metadata fields are name, description, publisher, developer, release date, players, genre and language.

Pictures and metadata are checked independently before any ScreenScraper request. Under Images: Missing only a picture is requested only when the effective image is absent or its file does not exist. In a folder, system or all-systems run, Metadata: Fill missing requests metadata only when every one of the eight fields is empty: a game with an existing picture and at least one non-empty local or inherited field is skipped without a request, so a blank language, publisher or other optional field does not send the same games back on every run. An entry with metadata but no picture receives only its picture; an entry with a picture but no metadata receives only metadata, and its picture is not downloaded again. Scrape This Game and Search Manually keep filling individual empty fields, because choosing one game is permission to complete that record field by field; a field ScreenScraper does not supply remains blank and is retried on the next single-game scrape. Replace existing requests and replaces the selected data as before.

Ordinary ROM files are matched by CRC32, MD5 and SHA-1 when they are no more than 64 MiB. Larger files, archives, .mgl, .mra and other wrappers use an exact normalised-title search instead. A unique exact match is applied automatically. If Scrape This Game finds no exact match or more than one, Degauss shows the available candidates and previews the highlighted game's artwork. Press A to confirm one, X to edit the pre-filled search title and try again, or B to leave the game untouched. A search with no suitable result stays editable so a shorter or alternative title can be tried.

An exact hash match uses the matched ROM's region for its regional title, release date and artwork when ScreenScraper supplies them. The configured or account region remains the fallback and continues to control title searches.

For a direct title search without first running automatic matching, open Scrape This Game and select Search Manually, immediately below Start Scraping. It searches the selected game's system using its pre-filled title. The same candidate picker lets you edit the title, preview a match and confirm its use. B returns to the single-game scraper settings. The account, password-storage confirmation and chosen Metadata policy still apply. Accepting a manual match replaces its picture even with Images: Missing only; Images: Off still downloads no picture. This action is available only for an individual game, not folder, system or all-system jobs.

Use Search Manually when an automatic match was wrong. To correct existing metadata, set Metadata: Replace existing before confirming the replacement match. Automatic single-game and batch scraping still respect Images: Missing only. These rules also apply to Libretro.

Folder, system and all-systems scrapes never stop for a match choice. Missing and ambiguous ScreenScraper matches are counted, skipped without changes, and the remaining games continue. A search ScreenScraper rejects for one game, or a genuine ScreenScraper answer for one game whose content cannot be read, is counted as failed for that game and the run continues. If only the picture request is rejected, any metadata the run was also asked to fill for that game is still written and the game is listed with the picture error; a game whose metadata was already complete is only listed. A file whose name leaves nothing to search for once its extension and dump tags are removed is counted as missing with the reason "no searchable title" and no title search is sent, although a hash lookup is still made for a file that can be hashed. A network failure, a rejected login, a rate limit, a service outage, a refused client, an exhausted allowance, a request address reported as incomplete (Degauss sends the same fields for every game) or a response that is not a ScreenScraper answer at all (an empty body, a body that is neither text nor XML, or a maintenance or intermediary page) stops the run. The log names the rejection or page behind each of these. Unsupported systems are also skipped and counted. If two systems use the same folder but require different ScreenScraper platform IDs, the all-systems scrape skips that shared target; a per-system scrape remains available.

Symlinked copies share a single scrape and gamelist update only when they point to the same physical file and the same existing gamelist entry; extra paths are counted as Linked copies. Conflicting mappings to different files and ambiguous entries are reported as errors. During Checking existing data, planning shows known totals and can be cancelled.

During a run, the progress dashboard shows current work, game progress, written, unchanged, unresolved and failed counts. A Details opens a scrollable report with status, scope, current title, completed/total, written, unchanged, linked copies, unresolved and skipped/error breakdowns, allowance, throughput and the last problem. After the run, the report continues with every game the run attempted and could not resolve, one row per game with its reason: "no match", "no searchable title", the number of matches (for example "3 matches"), "no image", or the message of a failed lookup, download or gamelist write. A game whose image failed, or whose match has no image, is listed even when its metadata was written, so the rows agree with the "no image" count. Games not reached before a failure or cancellation are not listed. A missing, ambiguous or rejected game can then be found and scraped individually. B Overview returns without cancelling. The report retains worker counts, account limits reported by ScreenScraper and Degauss's allowance estimate. Another program using the same account can change the server's counters while the run is in progress. The estimate covers API lookups, not the separate media-file transfers. Media transfers obey the download-speed limit reported for the account. On the running dashboard, press B, then confirm, to cancel. Cancellation stops card enumeration and new requests, and safely finishes installing results that already completed.

After results are saved, Refreshing Lists rebuilds each affected system's complete list, including after a single-game scrape. This work runs in a Degauss-owned worker, with the system/folder and read counts shown while the interface remains responsive. It is not a targeted one-game refresh. The dashboard shows safe finishing until that work completes; Details remains available. An archive or member a refresh skips is shown as the last problem, named by the system, and is not counted as a failed system. No helper or background service stays running after Degauss exits.

Connection and server failures remain on the progress screen until they are dismissed. The on-screen message is kept concise; technical curl and HTTP details are written to /tmp/degauss.log. Degauss never writes its own request URLs or login data there; a server error text quoted in the log is cut to one line and has its login and developer credential parameters replaced by "[redacted]". Degauss allows 10 seconds to establish each connection and 60 seconds for an ordinary API request. An image transfer receives 60 to 300 seconds according to its size and the account's reported speed. Retryable failures receive up to three attempts, and the whole operation remains cancellable while waiting.

Downloaded pictures go under media/screenscraper/ beside the gamelist and use content-based names. Degauss inspects each gamelist once before network work and performs at most one replacement per scrape run, after validating the complete proposed XML with its normal reader. Before changing an existing gamelist it writes one timestamped gamelist.xml.degauss-scraper-*.bak copy beside it. Backups are never overwritten or removed, so they can be deleted manually after the result has been checked. Existing comments, attributes, unknown fields and unrelated entries are preserved. A malformed or ambiguous gamelist is reported and left byte-for-byte unchanged. After a failed gamelist write, Degauss removes a picture created by that run only when the current gamelist can be parsed and proves the file is unreferenced. If that cannot be established safely, the content-named file is retained for manual review.

The account password is stored as plain text in screenscraper.toml beside settings.toml, because FAT and exFAT cards do not provide private Unix file permissions. Degauss asks for confirmation before saving it, masks it on screen, never puts it in logs or process arguments, and provides Clear saved login. External USB and network storage need no special scraper setting: the same resolved system folders used by the browser determine where each gamelist and media directory are written.

Choose Default Image in Scrape All Systems to set the global artwork type: Screenshot, Box Art (2D), or Box Art (3D). A system, folder or single-game scraper instead offers System Image, which applies to that entire system. Its default, Use Global, follows Default Image. For example, choose 2D box art globally and Screenshot for Arcade. Scrape All and manual-match previews respect each system's choice. Favourites display the artwork of their original games, so they do not need a separate scraper preference.

Changing the image type does not replace existing pictures under Missing Only. Choose Images: Replace existing when replacing already downloaded artwork. If the chosen type is unavailable, Degauss reports missing media instead of silently selecting another type. Artwork Pack systems remain excluded from scraping.

Advanced settings can be edited directly in the same screenscraper.toml. They are optional; omitting them keeps the defaults shown here:

# Omit region to use the account's preferred region.
region = "us"
language = "en"
hash_limit_mib = 64
max_media_mib = 32
media_type = "ss"

[system_media_types]
Arcade = "box-2D"

[system_ids]
"ExactDegaussSystemId" = 123

hash_limit_mib controls the largest ordinary ROM Degauss will hash (1–4096 MiB); larger and wrapper/disc files use title matching. max_media_mib limits one downloaded picture (1–256 MiB). media_type is the ScreenScraper media type, with ss meaning gameplay screenshot. The optional system_media_types table overrides it for individual Degauss system IDs, matched case-insensitively. Removing an entry restores the global type. Existing custom media types remain supported in the file. A system_ids entry maps a Degauss system ID, matched case-insensitively, to a positive ScreenScraper platform ID. It is intended only for a missing or deliberately overridden platform mapping; an invalid or ambiguous override can associate the wrong game, so verify both IDs before using it.

Scraping with Libretro

Open the same Scrape This Game, Scrape This Folder, Scrape This System or Scrape All Systems screen and change Scraping Source to Libretro. No account is required. ScreenScraper remains the default and its saved login and artwork choices are kept when switching sources.

Libretro supplies Screenshot, Box Art and Title Screen choices. The existing Images and Metadata policies, manual match selection, progress, cancellation, XML backups and list refresh apply to both sources. Artwork Pack systems remain excluded. Downloaded pictures go into media/libretro beside the system's gamelist; no ROM, Artwork Pack or previously downloaded picture is overwritten.

The relevant public Libretro database is downloaded only when an explicit scrape or manual search needs it, then reused from cache/libretro beside Degauss's settings. No database or image download runs at startup or during normal browsing. An invalid cached database is reported as an error; it is not silently replaced. To refresh a database, exit Degauss, remove only its .rdb file from that cache and scrape again.

Ordinary ROMs use bounded CRC32, MD5 and SHA-1 matching, including renamed files. Libretro hashing is limited to 64 MiB or the configured smaller limit. Disc/container/launcher files use names, not the hash of an MRA, MGL, CHD, CUE or ZIP wrapper. Uncertain regions/revisions require manual selection. Supported systems are mapped explicitly to their own database, rather than guessed from display labels. Unsupported or unmatched games remain playable. This does not add disc-serial or CHD parsing. Serial-only database records are not game matches; supported disc games still use their database titles.

Only supplied metadata fields are written. Hash-only database records can provide their metadata without inventing a title or artwork. Missing artwork is reported separately from network, timeout, HTTP, database and image errors. Thumbnail names use the confirmed database title and Libretro's character/URL rules; short-name artwork is tried only when that name identifies one database entry. See the Libretro thumbnail conventions.

Libretro databases are credited to their contributors and licensed under CC BY-SA 4.0. Artwork has separate rights belonging to its creators; see Libretro thumbnail credits. Databases and artwork are fetched on request, not bundled with Degauss. The independent RDB reader uses MIT-licensed MessagePack crates, not RetroArch's scanner or thumbnail-downloader code.

Where the gamelist goes

One gamelist.xml at the top of each folder a system uses.

Paths inside it are relative to that folder, and subfolders are covered by the same file. Most systems use a single folder under /media/fat/games:

System	Gamelist
Commodore 64	`/media/fat/games/C64/gamelist.xml`
SNES	`/media/fat/games/SNES/gamelist.xml`
PlayStation	`/media/fat/games/PSX/gamelist.xml`
Amiga	`/media/fat/games/Amiga/gamelist.xml`
Neo Geo	`/media/fat/games/NEOGEO/gamelist.xml`

Some sit outside that folder, and some are spread over several. Every folder gets its own gamelist, and the system is still shown as one:

System	Gamelist
Arcade	`/media/fat/_Arcade/gamelist.xml`
PC (DOS)	`/media/fat/games/AO486/gamelist.xml` `/media/fat/_DOS Games/gamelist.xml`
Genesis	`/media/fat/games/MegaDrive/gamelist.xml` `/media/fat/games/Genesis/gamelist.xml`
Neo Geo CD	`/media/fat/games/NeoGeo-CD/gamelist.xml` `/media/fat/games/NEOGEO/gamelist.xml`
SG-1000	`/media/fat/games/SG1000/gamelist.xml` `/media/fat/games/Coleco/gamelist.xml` `/media/fat/games/SMS/gamelist.xml`

Systems that share a folder share its gamelist: Neo Geo and Neo Geo MVS both read /media/fat/games/NEOGEO.

/media/fat/Scripts/.config/degauss/degauss --list-systems prints where every system resolved on your own card, which is the answer for that card.

Every system and the folders it reads

System	Folders holding its gamelist
3DO	`/media/fat/games/3DO`
Adventure Vision	`/media/fat/games/AVision`
Amiga	`/media/fat/games/Amiga`
Amiga CD32	`/media/fat/games/AmigaCD32`
Amstrad CPC	`/media/fat/games/Amstrad`
Amstrad PCW	`/media/fat/games/Amstrad PCW`
Apogee BK-01	`/media/fat/games/APOGEE`
Apple I	`/media/fat/games/Apple-I`
Apple IIe	`/media/fat/games/Apple-II`
Apple IIGS	`/media/fat/games/Apple-IIgs`
Apple Lisa	`/media/fat/games/LISA`
Arcade	`/media/fat/_Arcade`
Arcadia 2001	`/media/fat/games/Arcadia`
Arduboy	`/media/fat/games/Arduboy`
Atari 2600	`/media/fat/games/ATARI7800` `/media/fat/games/Atari2600`
Atari 5200	`/media/fat/games/ATARI5200`
Atari 7800	`/media/fat/games/ATARI7800`
Atari 800XL	`/media/fat/games/ATARI800`
Atari Lynx	`/media/fat/games/AtariLynx`
Atom	`/media/fat/games/AcornAtom`
Audio	`/media/fat/games/MegaVGMDrive`
Bally Astrocade	`/media/fat/games/Astrocade`
BBC Micro/Master	`/media/fat/games/BBCMicro`
BK0011M	`/media/fat/games/BK0011M`
Casio PV-1000	`/media/fat/games/Casio_PV-1000`
Casio PV-2000	`/media/fat/games/Casio_PV-2000`
CD-i	`/media/fat/games/CD-i`
Channel F	`/media/fat/games/ChannelF`
CHIP-8	`/media/fat/games/Chip8`
ColecoVision	`/media/fat/games/Coleco`
Commodore 16	`/media/fat/games/C16`
Commodore 64	`/media/fat/games/C64`
Commodore PET 2001	`/media/fat/games/PET2001`
Commodore VIC-20	`/media/fat/games/VIC20`
EDSAC	`/media/fat/games/EDSAC`
Electron	`/media/fat/games/AcornElectron`
Famicom Disk System	`/media/fat/games/NES` `/media/fat/games/FDS`
Galaksija	`/media/fat/games/Galaksija`
Gamate	`/media/fat/games/Gamate`
Game & Watch	`/media/fat/games/GameNWatch` `/media/fat/games/Game and Watch`
Game Gear	`/media/fat/games/SMS` `/media/fat/games/GameGear`
Game Gear (2 Player)	`/media/fat/games/GameGear2P`
Gameboy	`/media/fat/games/GAMEBOY`
Gameboy (2 Player)	`/media/fat/games/GAMEBOY2P`
Gameboy Advance	`/media/fat/games/GBA`
Gameboy Advance (2 Player)	`/media/fat/games/GBA2P`
Gameboy Color	`/media/fat/games/GAMEBOY` `/media/fat/games/GBC`
Genesis	`/media/fat/games/MegaDrive` `/media/fat/games/Genesis`
Genesis 32X	`/media/fat/games/S32X`
Groovy	`/media/fat/games/Groovy`
Intellivision	`/media/fat/games/Intellivision`
Interact	`/media/fat/games/Interact`
Jaguar	`/media/fat/games/Jaguar`
Jaguar CD	`/media/fat/games/Jaguar`
Jupiter Ace	`/media/fat/games/Jupiter`
Laser 350/500/700	`/media/fat/games/Laser`
Lynx 48/96K	`/media/fat/games/Lynx48`
M5	`/media/fat/games/Sord M5`
Macintosh Plus	`/media/fat/games/MACPLUS`
Magnavox Odyssey2	`/media/fat/games/ODYSSEY2`
Master System	`/media/fat/games/SMS`
Mattel Aquarius	`/media/fat/games/AQUARIUS`
Mega Duck	`/media/fat/games/GAMEBOY` `/media/fat/games/MegaDuck`
MSX	`/media/fat/games/MSX`
MSX1	`/media/fat/games/MSX1`
MultiComp	`/media/fat/games/MultiComp`
Neo Geo	`/media/fat/games/NEOGEO`
Neo Geo CD	`/media/fat/games/NeoGeo-CD` `/media/fat/games/NEOGEO`
Neo Geo MVS	`/media/fat/games/NEOGEO`
Neo Geo Pocket	`/media/fat/games/NGP`
Neo Geo Pocket Color	`/media/fat/games/NGPC`
NES	`/media/fat/games/NES`
NES Music	`/media/fat/games/NES`
Nintendo 64	`/media/fat/games/N64`
OpenBOR	`/media/fat/games/OpenBOR`
Orao	`/media/fat/games/ORAO`
Oric	`/media/fat/games/Oric`
PC (DOS)	`/media/fat/games/AO486` `/media/fat/_DOS Games`
PC/XT	`/media/fat/games/PCXT`
PDP-1	`/media/fat/games/PDP1`
PICO-8	`/media/fat/games/PICO-8`
Playstation	`/media/fat/games/PSX`
PMD 85-2A	`/media/fat/games/PMD85`
Pocket Challenge V2	`/media/fat/games/WonderSwan` `/media/fat/games/PocketChallengeV2`
Pokemon Mini	`/media/fat/games/PokemonMini`
RX-78 Gundam	`/media/fat/games/RX78`
SAM Coupe	`/media/fat/games/SAMCOUPE`
Saturn	`/media/fat/games/Saturn`
Sega CD	`/media/fat/games/MegaCD`
SG-1000	`/media/fat/games/SG1000` `/media/fat/games/Coleco` `/media/fat/games/SMS`
Sinclair QL	`/media/fat/games/QL`
SNES	`/media/fat/games/SNES`
SNES Music	`/media/fat/games/SNES`
Specialist/MX	`/media/fat/games/SPMX`
Super Gameboy	`/media/fat/games/SGB`
SuperGrafx	`/media/fat/games/TGFX16`
SuperVision	`/media/fat/games/SuperVision`
SV-328	`/media/fat/games/SVI328`
Tandy MC-10	`/media/fat/games/AliceMC10`
Tatung Einstein	`/media/fat/games/TatungEinstein`
TI-99/4A	`/media/fat/games/TI-99_4A`
TRS-80	`/media/fat/games/TRS-80`
TRS-80 CoCo 2	`/media/fat/games/CoCo2`
TS-1500	`/media/fat/games/ZX81`
TS-Config	`/media/fat/games/TSConf`
TurboGrafx-16	`/media/fat/games/TGFX16`
TurboGrafx-16 CD	`/media/fat/games/TGFX16-CD`
Tutor	`/media/fat/games/TomyTutor`
UK101	`/media/fat/games/UK101`
VC4000	`/media/fat/games/VC4000`
Vector-06C	`/media/fat/games/VECTOR06`
Vectrex	`/media/fat/games/VECTREX`
Virtual Boy	`/media/fat/games/VirtualBoy`
VTech CreatiVision	`/media/fat/games/CreatiVision`
WonderSwan	`/media/fat/games/WonderSwan`
WonderSwan Color	`/media/fat/games/WonderSwan` `/media/fat/games/WonderSwanColor`
X68000	`/media/fat/games/X68000`
ZX Spectrum	`/media/fat/games/Spectrum`
ZX Spectrum Next	`/media/fat/games/ZXNext`

Atari 2600 .bin games belong in games/Atari2600. In the shared games/ATARI7800 folder, .bin remains an Atari 7800 format.

System logos are read from the logos folder beside degauss.toml, named after the system. The 89 files in assets/logos/ are copied from lehcimcramtrebor/es-theme-forever (CUSTOMIZE/logos). The marks themselves are the trademarks of their owners, used here only to identify the systems.

System and category images

Degauss reads system and category images from the logos folder beside degauss.toml. In a normal installation this is:

/media/fat/Scripts/.config/degauss/logos/

A system image is named after its system ID, for example C64.png or PSX.jpg.

To give a category a fixed image, name the file exactly after the category:

Arcade.png
Console.png
Handheld.png
Computer.png
Utility.png
Other.png
Favorites.png

If no category image exists, Degauss chooses the logo of one of the systems in that category at random. Lowercase .png and .jpg extensions are supported. Favourites shows its heart when Favorites.png or .jpg is not present. Restart Degauss after adding or replacing a directly named image.

You can also put additional PNG, JPG or JPEG images directly in this same logos folder, using any filename. On Home, press X and choose Change Image directly. On a system such as Computer → Amiga, press X and choose Appearance → Change Image. Then select any shipped or user-added image in the list. Degauss copies the selection into its managed image storage and leaves the source file untouched. Clear Custom Image appears for a category or system that has such a selection; it removes only the managed copy. Categories then return to their normal named image, random system-logo choice, or Favourites heart. Systems return to their normal image named after the system ID.

A system's custom image applies to the system row and remains the fallback for a folder that has no unambiguous game picture. A folder holding one game, or several discs that share one picture, continues to show that game artwork. Clear Custom Image restores the image named after the system ID.

Arcade.png is already included as the default fixed image for the Arcade category.

Tips

Making the gamelists

Degauss's built-in scraper can create and update gamelists directly on MiSTer using ScreenScraper or account-free Libretro. The computer tools below are alternatives for preparing or curating them while the card is mounted in a computer, or through a local or network location.

On a computer, with the card in it. Any scraper written for EmulationStation produces exactly the file Degauss reads.

Skraper is free. It is a .NET application and Windows is the only native build; Linux and macOS go through WINE. Set its output to RecalBox or RetroPie mode, which is the setting that writes gamelist.xml rather than a frontend's own database. It already knows MiSTer's folder names, so you can point it straight at the card or at a share.
MiSTer Companion includes ZapScraper for Windows, Linux and macOS. Select Recalbox Compatible, then point it at the inserted MiSTer card or a local or network MiSTer location. It writes the gamelist.xml and media files Degauss reads, with support for consoles, handhelds, Arcade and AmigaVision.
Skyscraper is a C++ command line scraper, Linux first, and the one RetroPie uses. It caches everything it fetches and builds the gamelists from that cache, so changing your mind about the artwork costs nothing the second time.

With an AI, over ssh. This is what I do, and it is far and away the best for me. Put an ssh key on the MiSTer, point an AI coding agent at it, and ask. It reads the card as it is, works out which systems are there, matches names against what it finds, writes a gamelist.xml per folder, finds collections containing the images you need, and comes back with what it could not resolve instead of quietly skipping it (and almost always can have a good guess at it!).

The part AI is best at is also managing it all. A gamelist goes stale the moment you add a game, and an agent can be told to look at what changed and only touch that, so keeping the lists current after adding games is super quick.

Working with an agent

Put an ssh key on the MiSTer, point a coding agent at it, get the IP address for the agent, and tell the agent what you want. There is nothing to install and nothing in Degauss to configure. Any agent that can hold an ssh session will do. I use Claude Code.

The one rule that makes it safe: it looks, it tells you what it found, you decide, then it acts. Never let it write to the card on its own initiative.

For the complete review-first workflow, read Managing Degauss artwork with an AI coding agent, or download the complete artwork agent kit with its scripts, tests and requirements.

Everything else your agent can work out or ask you about. To save you both the first hour, paste this into it at the start:

You are working on a MiSTer card for the Degauss frontend, over ssh.

https://github.com/giancarloerra/Degauss is the address to get the original README and code if needed.

Before you change anything on the card, tell me what you found and wait.

- Back up any gamelist.xml before you write it, next to the original.
- After writing one, read it back: check it still parses, and that every
  picture it names is really on the card.
- Re-read the card before telling me anything about it. Whatever you read
  earlier may have changed since.
- If you cannot find the right picture for a game, leave it without one.
  Never use a picture of a different game.
- Before telling me something is missing, search everything rather than the
  name you expected, and tell me what you searched.

Degauss reads gamelist.xml files straight from the card. Its built-in scraper
can write them only when the user explicitly starts a scrape; do not edit
them while that progress screen is active.

Start from Degauss's own audit rather than forming your own view of the card:

  /media/fat/Scripts/degauss.sh --audit

That prints one line per system with how many games it found and how many
have artwork, then lists the problems underneath. Also useful:
--report --system <id> to expand one system, --list-systems when a system
is missing, --dry-run-launch when a game will not start.

Before editing a gamelist:
- Entries are either flat, or a parent holding the details with children
  pointing at it. A child inherits field by field, and its own value wins.
- Artwork is read as image, then screenshot, then thumbnail, and paths are
  relative to the folder the gamelist is in.
- Degauss checks whether each named picture exists when it reads the system
  list. You still have to check that it is artwork for the correct game.
- Degauss caches what it found. Its built-in scraper refreshes every system
  it changed; after an external edit, rebuild from the menu.

The one thing that catches everyone

Scrapers sometimes file a game under a different game's name. They group by their own database record, so an arcade original and its clones can end up sharing one entry, and the title you see is whichever one the scraper chose. The game is not missing. It is sitting under a name you would never look for, which is much harder to spot than an empty row.

If you hit it, ask your agent to detach that entry rather than rename it. Renaming fixes the title and leaves the wrong description, publisher and year behind it. Detached and left without a name, Degauss simply shows the filename as it is on the card, which is usually clearer anyway.

It is worth asking your agent to check the whole card for this once.

After any change

Rebuild the cache from the Degauss menu, or just the changed system with X Actions → Library → Rebuild This System List while inside it. Artwork is not stored in the persistent system-list index, so new pictures are read from the card when their rows are shown. Favourites are shared with MiSTer's own _@Favorites folder, so an agent can add one and the stock menu will agree with it, and vice versa.

Keeping the card in order (additional bonus!)

The same thing works for the card itself. After every update_all I have an agent go over it and tell me what it found: cores that arrived or vanished, games with no artwork, artwork with no game, folders that ended up in the wrong place, gamelists that no longer match what is on the card, and anything a core needs that is missing. It reports; I decide; it executes.

Troubleshooting and FAQ

Why does a core appear in MiSTer's menu but not in Degauss?

Degauss's game library uses per-system definitions to recognise game folders, file formats and launch settings. It is not a direct copy of MiSTer's core menu, so an installed core may not yet have a dedicated game-library section.

To access the installed core directly:

Set Options → Library → Show Cores → On.
Return to Home and open Cores.
Choose the appropriate category and core.

For example, Atari ST is available through Cores → Computer → AtariST. Load games through the core's usual MiSTer OSD. This provides access without leaving Degauss, but does not add an indexed game list or artwork section. Those require a system definition. Rebuilding the library or enabling Show Systems with No Games cannot add a missing definition.

How can I rebuild just one system instead of the whole library?

Enter the affected system, for example Console → NES.
Press X and open Actions → Library → Rebuild This System List.
Let indexing finish, then close the completion report.

Only that system's game folders are read. Starting from a subfolder still rebuilds the containing system, not just that folder. B Cancel stops an active rebuild. Use Options → Library → Rebuild All System Lists only when the whole library needs updating. See External storage support for indexing and storage details.

Can I put a system in a different Home folder?

Yes, organise shortcuts in personal Home folders without moving game files or changing MiSTer's categories:

Highlight the system, game, library folder or saved collection.
Press X and choose Add to Home in Actions.
Choose an existing personal folder or New Personal Folder, then name it.

The addition appears immediately. Edit Home and Edit Home Folder let you change order, visibility, names, images and personal-folder placement; save those editor changes with Save Changes. Personal folders can contain other personal folders up to three levels. The original system remains in its standard category unless separately hidden. See Personal Home for all shortcut and editing controls.

An Artwork Pack assigns the wrong picture to a game. How can I correct it?

Select the affected game while its system uses Artwork Pack data.
Open X Actions → Game → Artwork Pack Match.
Preview the suggested titles, or use Search Pack... to find the right one.
Press A to apply its artwork and metadata, or B to leave unchanged.

The choice is saved in Degauss, not the pack, and the launch target stays unchanged. Automatic Match removes your manual choice. See Correct a missing or wrong Pack match for update behaviour and matching details.

Network games are missing when Degauss starts

Return to the category or system browser to check for storage that mounted late. Existing lists are reused; new or moved sources ask before indexing. To require that share before startup instead, add its actual mountpoint to wait_for_mounts in degauss-user.toml. See External storage support for examples.

What MiSTer hardware has Degauss been reported working on?

Degauss has been reported working on:

MiSTer Pi
the original DE10-Nano
QMTech
Multisystem2
SS1

Can an AI coding agent manage my Degauss artwork?

Yes. An agent with SSH access can audit the gamelists and artwork already on the MiSTer, identify genuine gaps, and prepare reviewed changes without replacing Degauss's own scraper. It should report what it found and wait for approval before writing to the card.

Read Managing Degauss artwork with an AI coding agent, or download the complete artwork agent kit with its scripts, tests, requirements and licence.

Can an AI coding agent maintain my MiSTer after Update All?

Yes. Start with the completed run's exact changes, including files delivered inside archives. Check affected cores, launchers, ROM requirements, Linux state and artwork; preserve manual content and perform only approved repairs. The same-run artwork pass is part of completion, not a separate optional follow-up.

Read Managing MiSTer with AI after Update All and copy its generic management instruction template into a separate local management folder. The guide links the existing SSH and artwork instructions, explains safe writes and validation, and includes a copyable agent brief. It does not grant permission to run Update All, reboot, download games or rebuild lists.

I installed an Artwork Pack, but its artwork is not showing

Degauss checks an installed Artwork Pack when its system is opened, not by scanning every pack at startup.

Check that Options → Appearance → Artwork is On.
Enter the affected system. If Degauss finds an unprepared pack, choose Prepare when asked.
Options → Library → Automatic Data Source → Artwork Pack First makes Artwork Packs the global preference for systems still set to Automatic. Gamelist First is the default and uses a root gamelist.xml when one is present.
To select a pack for only one system, highlight that system or open it, press X, then choose Library → Game Data Source → Artwork Pack and select the detected location.

An explicit per-system Gamelist or Artwork Pack choice always overrides the global Automatic preference. Packs installed normally through Update All are found below docs/<System>/Artwork on the SD card or USB storage.

Degauss stays on “Starting Degauss frontend...”

The first start reads the game library and creates its index, so it can take longer than later starts. If the indexing screen appears, let it finish.

If Degauss never reaches that screen:

For the normal automatic installation, check that the active /media/fat/MiSTer.ini contains this under [MiSTer]:
```
main=degauss/MiSTer_Degauss
```
Run this from a terminal or SSH:
```
/media/fat/Scripts/.config/degauss/degauss --check-install
```
It reports missing, incomplete or invalid installation files.

If Degauss is intentionally launched from Scripts instead of replacing the stock frontend, the main= line is not required. That mode requires fb_terminal=1 under [Menu] in MiSTer.ini.

Why does Update All warn that Degauss replaces MiSTer firmware with a fork?

This warning is expected when turning Degauss On under Update All → Settings → Frontends. A fork here means Degauss's separately maintained build of MiSTer Main. Update All is not asking to create a GitHub fork or account.

The warning's word “replace” refers to which Main binary starts. Select Yes if you want Degauss to start automatically. This is the recommended setup for almost all users and enables Degauss's full frontend integration: Degauss starts on boot, returns after leaving a game, and provides the System → Frontend command while a game is running. Then choose SAVE and EXIT and RUN UPDATE ALL. Update All installs /media/fat/degauss/MiSTer_Degauss, leaves the official /media/fat/MiSTer binary in place, and selects Degauss by adding this to MiSTer.ini:

main=degauss/MiSTer_Degauss

To return to the official Main binary, choose Update All → Settings → Frontends → Stock MiSTer UI and save the change. Update All removes the Degauss main= selection.

What should I preserve when using custom or alternate INI profiles?

Update All's Degauss option updates /media/fat/MiSTer.ini; it does not synchronize custom or alternate INI profiles. If you replace your INI file or switch profiles, keep this setting in the existing [MiSTer] section of each profile where Degauss should start automatically:

main=degauss/MiSTer_Degauss

With RetroAchievements, also preserve the RA-specific Main selection. Update All's RA option sets main=MiSTer_RA under [RA_*]. To keep Degauss's Frontend menu and saved shortcut in RA games, select main=degauss/MiSTer_RA_Degauss in that existing section instead, following the RA setup instructions. Preserve its other settings and any intentional per-core Main overrides.

How do I install Degauss on an SS1 currently using Console Mode?

Console Mode uses its own main= setting in the SS1's main and alternate video profiles. Degauss's Update All option changes /media/fat/MiSTer.ini, so use the Main profile for Degauss:

In Console Mode, open Settings → System → System Config, select Main, and leave it selected for Degauss. The same selection is available from OSD → Video / INI → Select INI.
Back up /media/fat/MiSTer.ini.
If you normally use an SS1 profile such as MiSTer_RGHV.ini, MiSTer_RGsB.ini, MiSTer_SVID.ini or MiSTer_YPbP.ini, copy that profile over /media/fat/MiSTer.ini. This keeps its output settings while using the Main profile.
In Update All, turn Degauss On, choose SAVE, then EXIT and RUN UPDATE ALL.
Check that /media/fat/MiSTer.ini now contains this under [MiSTer]:
```
main=degauss/MiSTer_Degauss
```
Before rebooting, confirm OSD → Video / INI → Select INI still shows Main.

Current Update All replaces Console Mode's existing main= value, so it does not need to be removed first. For a manual Degauss installation, replace that value yourself instead of adding a second main= line.

Degauss appears over HDMI but not on an analog CRT

Seeing MiSTer's OSD on a CRT does not necessarily mean that its Linux framebuffer is routed there. This is especially relevant when using an SS1's analog output.

For CRT and HDMI together, back up the active MiSTer.ini and update its existing [Menu] section:

[Menu]
fb_terminal=1
vga_scaler=0
degauss_native_analog=1
video_mode=8

With Degauss's bundled Main and Menu, the CRT shows the native interface and HDMI scales up the same image to 1080p60. Replace the old [Menu] video_mode line and keep the other settings; do not add a second [Menu] section. The native analog option is off by default.

The optional degauss_analog_video_mode can preserve a compatible progressive CRT timing, but timings with zero sync widths are rejected. Leave it unset initially. See the complete dual-display example and CRT-timing limitations.

If you instead use vga_scaler=1, both outputs use the scaler. That route needs a 15 kHz video_mode supported by the CRT; this common mode can be used as a starting point:

video_mode=640,54,56,106,224,16,0,28,13764

That timing is not universal. With vga_scaler=1, both connected displays must support the same scaler timing.

Coloured vertical stripes appear over S-Video or composite

At a 352-pixel Menu timing, the Y/C encoder does not receive enough samples per colour-carrier cycle. Use a 13.5 MHz output and double only the framebuffer width:

[Menu]
fb_terminal=1
vga_scaler=1
video_mode=704,24,62,68,240,4,3,15,13500
fb_hscale=2

Degauss still renders at 352×240 while the encoder runs at 13.5 MHz. This is the validated NTSC setup. A PAL timing is not supplied because it has not yet been validated on the target display path.

Update All enabled Degauss, but its files are missing

Turning Degauss On and downloading its files are separate steps. In Update All, choose SAVE, then EXIT and RUN UPDATE ALL, and let the update complete.

Afterwards, run:

/media/fat/Scripts/.config/degauss/degauss --check-install

If that command is missing or reports an incomplete installation, run Update All again. If it still fails, keep update_all.log and /media/fat/Scripts/.config/downloader/downloader.log for support.

Can Degauss reuse artwork from Zaparoo Frontend or Console Mode?

Usually, yes. Degauss can reuse the same pictures when each system's game folder contains a gamelist.xml that points to them. It reads artwork listed as <image>, <screenshot> or <thumbnail>, so there is no need to download it again.

Leave Game Data Source on Automatic, or select it manually:

Highlight the system and press X.
Open Library → Game Data Source.
Choose Gamelist.

Artwork stored only inside Zaparoo's database or Console Mode's central image folder is not automatically shared. If there is no usable gamelist.xml, keep or restore one beside the games; otherwise use Degauss's scraper or a MiSTer Artwork Pack.

Can I add or customise Degauss's scanline and shadow-mask effects?

Open Options → Display → Video Effects to choose Off, an included mask, or a general MiSTer video preset with its required files installed. Core-specific and incomplete presets are not offered. To change a mask, copy its .txt file under a new name and edit the copy. You can also use another MiSTer-compatible shadow-mask .txt file. Place it in /media/fat/Scripts/.config/degauss/masks/, then reopen Display and select the new name. MiSTer's Shadow Mask guide explains the format and links to an editor.

To make a full video preset, create /media/fat/Presets/Degauss/ if needed, copy an installed MiSTer .ini preset there, give the copy your own name, and edit it. Reopen Display and it appears as Custom/Your Name. A preset can combine MiSTer's horizontal, vertical and scanline filters, gamma and shadow masks. Referenced filter, gamma and mask files must already be installed in MiSTer's /media/fat/filters/, /media/fat/gamma/ and /media/fat/shadow_masks/ folders. Presets with missing components are not listed; Main reports an error if a selected file is malformed. The standard MiSTer preset format documents the keys and example combinations.

The mask files are not general-purpose shaders. All Video Effects choices affect Degauss on HDMI and scaled analog output while it is open, not games.

Why aren't physical discs launching automatically?

Auto-run Physical Discs does not install disc support. It requires MiSTer_Degauss, an installed physical-disc provider and its MGL launchers, and the provider-specific main= section in the active MiSTer INI. Keep Degauss as the menu's Main. Follow the physical-disc setup, including the provider and disc format requirements for MD+ and SNES MSU-1.

If the same disc plays through the provider's manual launcher but not automatically, record the exact MGL selected and the game title. Save /tmp/degauss.log after the failed automatic attempt, before restarting, using the instructions below. Manual playback does not test automatic identification.

My problem is not listed here

Reproduce the problem once, then save Degauss's log before restarting Degauss or rebooting MiSTer:

cp /tmp/degauss.log /media/fat/degauss.log

Degauss starts a fresh /tmp/degauss.log on every launch, and /tmp is cleared when MiSTer is power-cycled. Join the Degauss Discord channel and send the saved log to me in a DM, together with the Degauss version, the steps that caused the problem and a photo of any message shown on screen.

The command line (CLI)

Degauss is a normal program, so it can be run over SSH without taking the screen. That is worth having for two things: finding out what it makes of a card, and seeing what a change looks like without standing in front of the machine.

/media/fat/Scripts/.config/degauss/degauss --help

--version (or -V) prints the installed Degauss version and exits.

--config and --systems default to degauss.toml and systems.toml beside the binary, which is where they live, so the flags are only needed to point somewhere else. degauss.sh passes them explicitly.

Checking a card

Flag	What it answers
`--audit`	Every system, one line each: games found, artwork bound, folders and any selected Artwork Pack health problem. A Gamelist system with a `gamelist.xml` but no artwork bound, a usable Pack that resolves no pictures, or a system with no games is listed again underneath as a problem, as is an archive, or a member of one, that was skipped, with its reason. A whole card checked without opening a hundred systems by hand.
`--list-systems`	Which systems this card actually has, and where each one resolved. The answer to "why is my system missing".
`--check-install`	The installation itself, including every saved Artwork Pack root and every pack state file written beside a system cache, read under the source the settings choose for that system now: an Automatic acceptance or decline, an explicit Artwork Pack choice's preparation, or a state kept behind a later Gamelist choice, a prepared state with how many games were left without pack data. What is present, missing, broken or left half-migrated. The first thing to run when something looks wrong.
`--report`	One system in detail, with `--system <id>`. It identifies Gamelist or Artwork Pack; for a Pack it also reports the selected root, health and the first game's local match method, a match that fails on an MGL names the file the MGL asked for and the folder it was looked for in, or the set name no games folder was found for, and a descriptor left out of the mapping is counted under its reason. Under Automatic it also says what the pack decision stands at: prepared and current, changed, unavailable, declined, or a candidate not yet asked about. A skipped archive or member is listed as `unreadable` with its reason.
`--dry-run-launch`	The MGL that would be written to start a game, printed instead of run. The answer to "why does this game not start".

Seeing it without the screen

--render <file.bmp> draws one frame to an image instead of the framebuffer, which works while the frontend is running. --screen, --layout, --system, --select and --find choose what that frame shows. --layout accepts details, tiled, list, carousel, multi-list and gallery. An explicit --layout is temporary and takes precedence over saved global and custom views; without it, render, bench and selftest use Details. A Details frame follows the Details Style saved in settings.toml; there is no separate flag for it. This headless facility is useful for inspection and diagnostics; it is separate from capturing the live MiSTer framebuffer.

--screen options shows the Options categories. Add --options-page navigation|shortcuts|appearance|library|display|developer to render a settings page directly. --screen advanced remains a direct alias for the Developer page. --screen actions shows Actions, with the existing --screen context spelling retained as an alias. --screen information shows Game Information for the playable game chosen with --system and --select. --screen scripts opens the Scripts browser under the configured menu_root.

degauss --system PSX --layout tiled --render /tmp/shot.bmp --geometry 352x240

Measuring it

--bench <frames> scrolls a folder in memory and reports frame times, decode cost and cache behaviour. It never touches the framebuffer, so it is safe to run while the frontend is up. Run it twice and read the second: the first pays for a cold card.

--import-favorites <file> writes a favourite per line of a list, in MiSTer's own format, for moving a collection over in one go.

Building it yourself

Every release carries a ready binary, so building is optional.

The dependency tree is pure Rust, so a cross build needs nothing but rustup: no Docker, no C cross-compiler, no arm-linux-gnueabihf-gcc. Rust's own linker and its self-contained musl do the work, and .cargo/config.toml already selects them.

rustup target add armv7-unknown-linux-musleabihf
./scripts/build-arm.sh

That writes the binary and everything beside it into deploy/Scripts, ready to copy onto the card. It builds on Linux, macOS and Windows alike.

The MiSTer package script refuses to build unless the application credentials issued to Degauss are supplied at compile time. Authorized maintainers can put them in an untracked screenscraper-developer.toml at the repository root:

developer_id = "your_developer_id"
developer_password = "your_developer_password"

The same two values can instead be supplied as DEGAUSS_SCREENSCRAPER_DEVID and DEGAUSS_SCREENSCRAPER_DEVPASSWORD, or the file can be selected with DEGAUSS_SCREENSCRAPER_CREDENTIAL_FILE. The values are embedded in the executable; the credentials file is never copied into deploy/.

The repository ignores both that file and the local screenscraper.toml account file. The scraper invokes curl for verified HTTPS; normal browsing and every other feature remain in the static Rust binary.

MiSTer_Degauss is built from its own repository, which carries the script that does it. That one is C++ and does need a cross-compiler.

Licence

Degauss is under PolyForm Noncommercial 1.0.0. See LICENSE.

The rmp and rmpv MessagePack crates use the MIT licence, included with the executable.

MiSTer_Degauss, shipped alongside it, is a separate program: a fork of MiSTer Main under GPLv3, with its source at giancarloerra/Degauss-Main.

Four typefaces are baked into the binary:

DejaVu Sans, under the Bitstream Vera and Arev licences (text). The original is unmodified; size variants have distinct family names.
Px437 DOS/V re. JPN12, from The Ultimate Oldschool PC Font Pack, © 2016-2020 VileR, under CC BY-SA 4.0 (text). The original is unmodified; size variants are derived from it for crisp list text.
Roboto Condensed Bold v2.138, © Google, under the Apache License 2.0 (text). The original is unmodified; size variants have distinct family names.
Tamzen 6x12 Bold, © 2011 Suraj N. Kurapati, derived from Tamsyn © 2010 Scott Fial, free to use, copy, modify and distribute (text). The original is unmodified; size variants are derived from it.

Names are drawn in the Latin, Greek and Cyrillic alphabets, with the accents and marks of each. A name in Japanese or Chinese draws as a gap: neither typeface has those characters.

Name		Name	Last commit message	Last commit date
.cargo		.cargo
.github		.github
assets		assets
build		build
deploy/Scripts		deploy/Scripts
docs		docs
scripts		scripts
src		src
support		support
tests/fixtures		tests/fixtures
tools/artwork-agent		tools/artwork-agent
ui		ui
.coderabbit.yaml		.coderabbit.yaml
.gitattributes		.gitattributes
.gitignore		.gitignore
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
README.md		README.md
build.rs		build.rs
degauss.toml		degauss.toml

Latest commit

History

Folders and files

Repository files navigation

Feature request or bug report? Star this repository as well to support it ⭐️