# ZapScript Quick Reference

## Syntax

- `**` starts explicit command.
- No prefix means auto-launch by path.
- `@` performs title lookup: `@SNES/Super Metroid`.
- `||` chains commands sequentially; execution stops on error.
- `:` separates command and positional arguments.
- `,` separates positional arguments.
- `?key=value&key2=value2` adds advanced arguments.
- `^` escapes special characters: `^?`, `^,`, `^&`, `^|`, `^n`, `^t`, `^r`.
- Quotes preserve special characters.
- `[[...]]` embeds expression.
- `?when=[[expression]]` conditionally executes command.

Prefer canonical command names below; deprecated aliases remain compatibility-only.

## Launch

```text
**launch:<path>
<path>
@<system>/<title>
**launch.title:<system>/<title>
**launch.system:<system-id>
**launch.random:<system>/<glob>
**launch.search:<system>/<glob>
**launch.last
```

Examples:

```text
@SNES/Super Metroid
**launch:SNES/Super Metroid.sfc
**launch.random:SNES/*metroid*
**launch.search:Genesis/*sonic*
**launch.last
```

Launch changes active media and can trigger launch guard/playtime limits. Ask before live use. A successful request means accepted, not platform-settled. Use paced active-media checks and platform-appropriate settling before dependent control or another lifecycle command.

## Input

```text
**input.keyboard:{f12}
**input.keyboard:{ctrl+c}
**input.gamepad:^^VV<><>BA{start}
**input.text:hello world
**input.coinp1
**input.coinp2
**input.coinp3
**input.coinp4
```

Input is security-sensitive and platform/config dependent. Desktop defaults block dangerous OS shortcuts; configured allow/block lists and input mode apply. Ask before every live input unless user explicitly requested exact sequence.

## Control and utility

```text
**stop
**control:toggle_pause
**control:save_state
**delay:2000
**delay:2s
**delay:media_ready
**echo:message
**screenshot
```

Control action availability depends on active launcher and configured control mappings. `stop` is media-disrupting. For a launch-dependent chain, prefer `**delay:media_ready` before control where supported. Outside a chain, send stop once, wait at multi-second polling intervals for active media to clear, then allow platform-specific settling. Never rapid-fire launch and stop; API state can diverge from device state.

## Execute

```text
**execute:<allowed command and arguments>
```

High risk:

- Requires Core `allow_execute` configuration.
- Core parses argv and runs configured executable directly with 2-second timeout.
- Remote/unsafe token sources can be rejected.
- Can expose device data or mutate operating system.

Never propose or run `execute` without exact command, user authorization, and clear need. Do not use deprecated `shell` or `command` aliases.

## HTTP hooks

```text
**http.get:https://example.com/webhook
**http.post:https://example.com/api,application/json,{"event":"scan"}
```

- URL must be permitted by Core HTTP allowlist.
- Requests run asynchronously with 30-second timeout.
- Command success does not prove remote endpoint completed successfully.
- Query strings and payloads may contain secrets; avoid embedding credentials.
- Ask before sending network requests or data.

## Playlists

```text
**playlist.play:<path-or-json>
**playlist.load:<path-or-json>
**playlist.open:<path-or-json>
**playlist.stop
**playlist.pause
**playlist.next
**playlist.previous
**playlist.goto:5
```

Playlist source can be folder, `.pls`, or supported JSON. Slot/repeat/mode advanced arguments are Core-version dependent; inspect current behavior before composing complex playlist tags. Playlist commands can change media and trigger launch guard.

## Profiles

```text
**profile:<switch-id>
**profile.clear
```

`profile` accepts exactly one profile switch ID; possession of tag is authorization and no PIN is checked on this path. Switch IDs are sensitive. Never log or echo them. Ask before switching/clearing profile.

## MiSTer and MiSTeX

```text
**mister.ini:1
**mister.core:_Console/SNES
**mister.script:update_all.sh
**mister.mgl:<path>
**mister.wallpaper:bg.png
```

Forwarded only on supporting platform. Ignore/error behavior depends on platform command implementation. Script/core actions can be disruptive; ask first.

## Deprecated aliases

Avoid new use of:

```text
input.key
key
coinp1
coinp2
random
shell
command
ini
system
get
```

Use canonical `input.*`, `launch.*`, `execute`, `mister.ini`, and `http.get` forms.

## Safety checklist

Before writing tag or running script:

1. Parse every chained command.
2. Expand effect of launch/control/input/HTTP/execute/profile/MiSTer commands.
3. Check escaping so separators do not change meaning.
4. Remove secrets and unnecessary external calls.
5. Confirm target device and exact action.
6. Obtain approval for user-visible, network, or mutating effects.
7. Pace launch/stop transitions and reconcile active-media state without treating it as definitive platform readiness.