Settings tab
In one line: every option in the app, on one scrolling page, saved instantly to
hdfg.cfg.
There is no OK or Apply button — changes take effect and are written as you make
them. Everything lives in a single file, hdfg.cfg, next to the app. If you
ever want to start clean, back that file up and delete it; the app recreates it
with defaults on the next launch.
The Open config file button at the bottom opens it in your text editor.
This page walks the settings in the order they appear.
The top of the page. It scrolls a long way further — emulator options, the NextSync HTTP bridge, the Retro toggles and the diagnostics are all below.
Check for ZX Next Unite updates at startup on Github (on by default) —
looks at the GitHub releases page and offers to download a newer version (or
suggests git pull if you run from source). The result is written to the SD
Card tab's log window. There are matching update-check toggles for CSpect
and MAME further down.
Application language — the language of the app's buttons, labels,
checkboxes and tooltips. Seven choices, each shown in its own language:
English, Español, Português, Polski, Русский, Čeština
and Français. Changing it re-translates the interface immediately — no
restart — and the choice is saved to hdfg.cfg (ui_language).
On the very first start the app looks at your operating system's language: if it is one of the seven, the interface starts in it right away (otherwise English) and a 15-second note in the bottom-left corner — written in that language — tells you it did so and points you here. This happens once; whatever you pick afterwards always wins.
A few things intentionally stay in English:
- Tab titles and dropdown option values — they double as identifiers inside the app.
- Text generated while the app runs — log messages, dialogs and most toasts.
Found a translation that reads oddly? The catalogues are plain
English-to-translation tables in
zxnu_i18n.py —
corrections are one-line changes and pull requests are very welcome.
| Setting | What it does |
|---|---|
| Desktop Theme | Automatic (follows your OS), White mode, Dark mode, High contrast (black) or Custom. Automatic is the safe choice — it keeps the explorer colours readable on both light and dark desktops. |
| Local file explorers & App Text Colors | A row of colour pickers for each item type in the file explorers — Up Directory row, directory name, directory type, file name, extension, size — plus the general app text colour. Pick Custom as the theme to make these stick. |
| Retro log font size | Text size in the 🎮 Retro pygame log windows. |
| Background image | Which background image the app uses, or Random for a different one each launch. |
| Background image opacity (%) | How strongly it shows through. Turn it down if it distracts from the file lists. |
| Setting | What it does |
|---|---|
| SD Card - Warn when an image is nearly full | Warns before a transfer that would fill the disk image. |
| Do not prompt for confirmation on deletion | Skips the "are you sure?" dialog. Convenient, and exactly as dangerous as it sounds. |
| Send deleted files to the Recycle Bin (local file explorers) (on) | Deletions in the local explorers go to the system Recycle Bin / Trash and can be restored. Deletions inside a disk image are always permanent. Needs the optional Send2Trash package — the toggle is greyed out without it. |
| Setting | What it does |
|---|---|
| Perform pre-availability check on Downloads (ZXDB & zxArt) | Tests that a download link actually works before offering it. Slower searches, fewer dead links. |
| Enable multi API endpoints search | A search typed into GetIt, ZXDB or zxArt also queries the other two, feeding the Unite! tab. |
| Enable search autocompletion | Title suggestions as you type in the search boxes. |
| Gallery search sort ordering preference | How merged Unite! results are ranked: GetIt first class (default, Next-native software on top), Mixed, or Classic (arrival order). |
These apply to every gallery pane — GetIt, ZXDB, zxArt, itch.io, Favorites and Unite!.
| Setting | Options |
|---|---|
| Gallery animation | On hover (default), Timed, or None |
| Gallery rows per page (min) | How many rows to fill before paginating |
| Gallery items per row | 2, 4 (default), or 8 |
| Gallery image size | Small, Medium (default), or Large |
| Gallery slideshow pause time | How long the full-screen viewer holds each screenshot |
| Setting | What it does |
|---|---|
| NextSync — when a sent file or directory exists locally | What happens when the Next pushes a file back (.sync5 -send) that you already have: Prompt (default), Overwrite or Ignore. |
| NextSync HTTP bridge | Republishes a running Remote Explorer session as HTTP routes, so a browser, curl, or another Next running .http can drive the connected Next's SD card. Needs the optional flask package. |
| Port | The bridge's port — 80 by default. |
| Max connections | Concurrent requests allowed, 1 by default (recommended: extra requests wait their turn rather than being refused). |
| Require bearer token | Adds a shared-secret gate. |
⚠️ The bridge is a LAN-only file server. It is unencrypted, and unauthenticated unless you enable the token — anyone who can reach the port can list, download, upload, rename and delete files on the connected Next. Run it only on a network you trust and never expose the port to the internet.Ticking Require bearer token mints a random 64-character token (editable, with a Generate button, saved to
hdfg.cfg). The bridge then answers only requests carrying it in theZXNEXTUNITE-BRIDGE-TOKENheader and returns HTTP 401 to everything else. It is a gate against casual access, not encryption — the token travels in clear text too. For real protection over an untrusted link, tunnel it through a VPN or SSH port-forward. Details: HTTP bridge → Security.
| Setting | What it does |
|---|---|
| MAME ROM / system | Which Spectrum Next system MAME should boot |
| MAME default launch parameters | Extra command-line options appended at launch |
| Check for MAME updates at startup | As with the app's own update check |
| Launch Mame with Flatpak (Linux) | Run MAME through Flatpak instead of a native binary |
| Flatpak rom path | Where the Flatpak sandbox should look for ROMs |
| CSpect default launch parameters | Extra command-line options for CSpect |
| Check for CSpect updates at startup | As above |
| Disable 'No emulators detected' message at startup | Silences the startup notice if you don't use emulators |
The per-launch dropdowns — screen size, sound, joystick and so on — live on the SD Card Utility tab next to the launch buttons, not here.
| Setting | What it does |
|---|---|
| Unite! — Invaders background animation (on) | An animated Space Invaders scene behind the Unite! tab in Retro mode |
| NextSync — starfield log animation (on) | The twinkling $/£/€ starfield behind the NextSync retro log |
| Alien Floyd's — animated background on all tabs | Live animation behind every tab — see Alien Floyd's |
| Alien Floyd's — show the full-window tab | Adds the playable game tab |
| Show the itch.io tab (on) | Show or hide the itch.io tab. Only meaningful when itch-dl is installed. |
All of these need pygame-ce; without it the toggles are greyed out with an
install hint.
Enable crash log file generation — writes zx-next-unite-crash.log
alongside the app, capturing low-level crashes that the normal log can't. Off by
default; turn it on if you're reporting a crash.
The always-on diagnostic log, zx-next-unite.log, needs no setting — it is
always being written, rotating at about 1 MB across 3 files. Attach it to bug
reports.
See also: User Manual · Installation for the optional packages several of these settings depend on.