Concepts

A few pieces of jargon recur across these docs — worth pinning down up front so the rest of the pages read cleanly.

Bot

A single connection to the Pixel Worlds game server. Each bot owns:

• its auth state (PlayFab session, sclfrst JWT, device ID),
• a world snapshot (current tile grid, entities, collectables, AI),
• an outbound packet queue (the scheduler drains it onto the TCP socket while respecting per-packet pacing),
• a runtime (the mlua Luau VM, started fresh per script).

Bots are created from the dashboard or via the HTTP API. Once created, they persist across app restarts — Seraph re-auths and reconnects automatically.

State machine:

[Created] → connecting → authenticating → MenuReady
                                         ↓ (warp)
                                       InWorld
                                         ↓ (leave / kick / disconnect)
                                       MenuReady
                                         ↓ (disconnect)
                                       Disconnected
                                         ↑ (connect)

Script

Lua source executed against either a single bot (panel-launched) or every connected bot in parallel (Scripts-page launch). Scripts run in their own Luau VM with a curated set of bindings; they can spawn background coroutines, call HTTP, read JSON, and store scoped state.

Each script has a scope key — (client_id, script_id) — that identifies it for stop / status / console-clear calls. The same script_id can run independently on multiple bots; they don't share VM state.

Module

A namespace of Lua bindings the runtime injects at script start. The most common ones:

Module	What it covers
bot	Per-bot client handle: connect, warp, walk, hit, place, chat.
world	Live world snapshot: tile grid, paths, NPCs, entities.
inventory	Backpack reads + writes (drop / trash / equip / wear).
info	Static catalogs — block database, recipe pool, achievement defs.
task	Cooperative scheduling — wait, spawn, cancellation hooks.
http	Outbound HTTPS — GET / POST / form / multipart, JSON helpers.
json	Encode + decode.
regex	PCRE-like matching.
storage	Persistent KV scoped per bot, survives restarts.
console	Append / clear / read the script's own log buffer.

The full set lives under API Reference.

Method

A function exposed to Lua via the runtime. Methods are listed under API Reference, auto-extracted from src/seraph/*.rs at build time. The reference is the single source of truth — if a method isn't there, the running binary doesn't expose it.

Job

A running script instance, identified by (client_id, script_id). The Jobs view + the /api/jobs endpoint report every live job across every bot. Useful for "what's running where" dashboards.

Edge relay

Server-side hop Seraph uses when PlayFab anti-fraud has flagged your local IP. The bot fetches an XChaCha20-Poly1305-encrypted relay URL from the licensing server, routes the auth HTTPS calls through it, then drops the relay — the actual game socket connects direct. See /api/edge/relay notes (you don't have to call it manually; the bot does this automatically when needed).

Lease

Locally-cached, Ed25519-signed proof that your license is valid. The client verifies the signature against an embedded public key, so even if the licensing server is down (or compromised), an existing lease keeps working through its grace window. This means Seraph stays usable for ~24 hours of offline operation before re-auth is forced.

Snapshot

Read-only flattening of a bot's full state at one instant — current world, position, status, inventory, gems, byte-coins, fishing state, proxy assignment, and more. The dashboard subscribes to snapshots over the SSE event stream; scripts get them synchronously via methods like bot:snapshot().