Zaparoo Core
Zaparoo Core is the service that runs on your MiSTer, PC, handheld, or media device. It sits in the background, watches for scans from readers, reads the ZapScript from matching tokens, and launches the right game, app, script, or media file for that platform.
Core is the part of Zaparoo you install on the device that has access to your media library and launchers. The Zaparoo App, Web UI, command line tools, readers, and custom integrations all connect to or are managed by Core.
What Core does
Core coordinates the main Zaparoo system:
- Manages reader connections for NFC readers, barcode scanners, optical drives, MQTT, file readers, and other supported reader types.
- Reads token data from NFC tags, NFC toys, QR codes, barcodes, optical discs, and mapped sources.
- Applies mappings and runs ZapScript for launches, input actions, playlists, and other commands.
- Builds and searches the local media database so scans can match games, apps, videos, scripts, and other launchable files.
- Starts, monitors, and controls media through built-in or custom launchers.
- Publishes the Core API, a local JSON-RPC API used by the app, web UI, CLI, and integrations.
Installing and controlling Core
Start with the platform guides for installation steps. Each platform has its own paths, startup behavior, launchers, and reader notes.
After Core is installed, you can control it through:
- The Zaparoo App on iOS or Android.
- The embedded Web UI at
http://<device-ip>:7497/app/. - The terminal UI, when available for your platform.
- The command line, when supported by your platform.
- The Core API for custom tools and integrations.
Most Core settings live in config.toml. See the configuration reference for file locations, option names, and examples.
Media database and scraping
Core keeps a rebuildable media database so the app, Web UI, TUI, and ZapScript can search for games and other launchable media. Update it after adding files, installing games in a supported launcher, or changing launcher paths. Scraping is a separate step that imports local metadata and artwork into those indexed records.
The media database and scraper guide explains how to update all systems or selected systems, run scrapers, and recover a damaged media database without deleting favorites, history, mappings, or launcher overrides.
Maintenance and troubleshooting
Use these starting points for Core maintenance tasks:
| Task | Start here |
|---|---|
| Reload settings, mappings, or launchers | Reload Core from the TUI or command line |
| Restart or manage the Core service | Platform command-line flags and your platform guide |
| Find, view, or export logs | TUI logs and the log path in your platform guide |
| Update the media database or run a scraper | Media database and scraper guide |
Edit config.toml | Configuration reference |
| Recover a corrupt media database | Database recovery |
| Update or uninstall Core | Your platform guide; uninstall steps are platform-specific |
Direct uninstall instructions are available for Linux, SteamOS, Bazzite, ChimeraOS, Windows, and RePlayOS.
Features and customization
Core includes user-configurable features for larger setups and custom workflows. The features section covers mappings, playlists, play controls, hooks, publishers, launcher controls, custom launchers, systems, and tags.
If you are setting up hardware, start with the readers and tokens sections first. If you already have a reader working and want to control what a scan does, start with ZapScript.
Source and license
Zaparoo Core is free and open source under the GPLv3 license. The source code and releases are hosted in the Zaparoo Core GitHub repository.