ZapScript
ZapScript is a small scripting language written to the storage of Zaparoo tokens. It tells Zaparoo what to do when a token is scanned. Through regular use you won't need to write much yourself, but you can use it to customize launching or add scripted actions. The Zaparoo App is the easiest way to write ZapScript to tokens. If you write ZapScript by hand, read Syntax first.
Write your first card
Most cards only need the name of a game. The Zaparoo App writes that for you when you pick a game from your library, and the Web UI does the same from a browser. When you want a card to do something else, write ZapScript by hand in the App's Custom write or ZapScript editor:
- Start with a launch.
@Genesis/Sonic the Hedgehoglaunches a game by system and title;**launch.random:SNESpicks one at random. - Add more commands with
||between them.**delay:1000||@SNES/Super Mario Worldwaits a second first. - Tune a command with
?arguments.@N64/GoldenEye 007?launcher=80MHzNintendo64picks a specific launcher.
That covers most cards. Syntax explains the rest: escaping, quoting, when conditions, and expressions.
Quick reference
| Command | Description |
|---|---|
launch | Launch media from a path or identifier |
launch.title | Launch by title ID with explicit syntax |
launch.system | Launch a system/emulator |
launch.random | Launch a random game |
launch.search | Search indexed media and launch the first result |
launch.last | Launch a recently played game |
input.keyboard | Simulate keyboard input |
input.text | Type a string of literal text |
input.gamepad | Simulate gamepad input |
input.coinp1 to input.coinp4 | Insert coins for players 1 to 4 |
http.get | Make an HTTP GET request |
http.post | Make an HTTP POST request |
playlist.play | Load and play a playlist |
playlist.load | Load a playlist without playing |
playlist.open | Open playlist picker menu |
playlist.stop | Stop and clear playlist |
playlist.pause | Pause playlist |
playlist.next | Next playlist item |
playlist.previous | Previous playlist item |
playlist.goto | Jump to playlist position |
stop | Stop current media |
profile | Switch to a device profile |
profile.clear | Return to the shared profile |
playtime.extend | Grant extra playtime with an administrator's card |
echo | Log a message |
execute | Run a host command |
delay | Pause script execution |
control | Send a control action to the active media's launcher |
screenshot | Capture the current platform display |
write | Write ZapScript to the next token scanned |
mister.ini | Load MiSTer ini file |
mister.core | Launch MiSTer core |
mister.script | Run MiSTer script |
mister.mgl | Execute MGL content |
mister.wallpaper | Set or unset MiSTer menu wallpaper |
Command categories
- Launch: Commands for launching games, systems, and media
- Input: Commands for simulating keyboard and gamepad input
- HTTP: Commands for making HTTP requests
- Playlist: Commands for managing playlists
- Utilities: Utility commands (stop, profile switching, playtime extension, delay, echo, execute, control, screenshot)
- MiSTer: Commands specific to the MiSTer platform
Syntax
The syntax of ZapScript is designed to be human-readable and writeable, with minimal complexity and focused on fitting as much information as possible on the limited storage available on NFC tags and QR codes.
See Syntax for a detailed explanation of all the different parts of ZapScript syntax, Expressions for dynamic values, and Zap Links for scripts hosted at a URL.
Examples
Launch a game
@Genesis/Sonic the Hedgehog
Or with the explicit command:
**launch:PCEngine/Another Game
Launch a game with a delay
**delay:1000||@SNES/Super Mario World
Send an HTTP request and launch a random game
**http.get:https://api.example.com/hello||**launch.random:Genesis
Launch different content based on platform
Genesis/Game.md?when=[[platform == "mister"]]||PCEngine/Game.pce?when=[[platform != "mister"]]
Use expressions for dynamic paths
SNES/games-[[platform]]/Super Mario World.sfc