# Xaya Arcade

> A platform for multiplayer blockchain games on Xaya. Games are playable at arcade.xaya.io, which is curated during its beta; builders rehearse their own on the disposable playground at test-arcade.xaya.io/attach.

## Versions

Everything on this site describes **`@xayaarcade/sdk` 0.18.15**. If the SDK vendored in your game repo is older, read the package's own `CHANGELOG.md` (it ships in the tarball as of 0.9.0, breaking changes marked) before following anything here — the channel API took breaking changes in 0.6.0, 0.7.0 and 0.8.0. Inside a game repo, `npm run sdk:freshness` prints the version you are on and fails if it is behind: it compares against a platform checkout first (`$ARCADE_PLATFORM`, then a sibling `../arcade-platform`) and only falls back to the highest `sdk-v<version>` tag on the `arcade-platform` remote. Prefer the checkout — the tag list is not complete, so a release that was never tagged reads as up to date against it.

## If you were asked to build a game, start here

1. Read the constraints in the next section and say out loud whether the game you were asked for fits. If it does not, say so before writing code — it is the cheapest moment.
2. Load the skill for your architecture: https://arcade.xaya.io/skills/building-channel-games.md for a 2-4 player game (including anything hosted on this Arcade), or https://arcade.xaya.io/skills/building-persistent-games.md for a fully on-chain world. Then read that skill's ARCADE.md or GSP.md in full before designing anything.
3. Follow the opening prompt at https://arcade.xaya.io/docs/ai-agent.md, which is written for exactly this situation, and the walkthrough at https://arcade.xaya.io/docs/quickstart.md.
4. **If a clone fails, stop and say so — do not work around it.** Do NOT reconstruct the judge ABI, the SDK surface or the submission contract from memory: each is a consensus surface, and a guess that compiles still fails. https://arcade.xaya.io/repos lists every repository this site points you at and whether it can be cloned today; #builders at https://discord.gg/FdZWZj4 is where to ask about one.
5. Build and test for free, then dry-run the real submission pipeline on the disposable playground at https://test-arcade.xaya.io/attach — it auto-accepts, so it answers in seconds, and it wipes every Monday 04:10 UTC. Submissions on arcade.xaya.io are closed during the curated phase, so get in touch in #builders with the repository, the same bytes and the four registration values.

There are two architectures here and you must pick one before you write any code. A GAME CHANNEL is two to four named players signing moves off chain, with only open, join, close and dispute touching the chain — this is what the hosted Arcade runs. A PERSISTENT world keeps all state on chain, with every move its own transaction. Routing is decided by where state lives, not by how fast the game plays.

An Arcade game is 2 to 4 seats, React/Next only (the SDK has no supported non-React path today), and ships as a static export with no server of any kind — no API routes, no server actions, no database, no asset backend, no leaderboard service, and no accounts beyond your Xaya p/ name. All shared state is produced by a deterministic wasm judge with no floats, no clock, no network and no file access, whose state output is bounded and whose execution is fuel-capped — which caps how big a world and how long a history you can have. Input is keyboard- or tap-shaped, and every game must be playable by touch: it declares on-screen touch controls (a d-pad and/or action buttons) that the SDK mounts on touch devices, or it declares that it draws its own touch surface and takes the whole frame to draw it in — a game that declares neither is labelled desktop-only on the shelf and a player on a phone cannot start or join a match in it. There is no gamepad support and no key remapping. And a match needs two to four named, funded humans online at the same moment; there is no solo mode, no bot and no matchmaking.

Games are played at /play/<slug>. Submissions are moderated: uploading does not publish, and a human reviews every game before it goes live. The arcade's queue is closed during the curated phase — the playground's /attach is the door that is open.

## Agent skills

- [building-channel-games](https://arcade.xaya.io/skills/building-channel-games.md): For a game two to four people play against each other in real time or in fast turns: moves are signed off chain and only open, join, close and dispute touch the chain. Covers both the hosted Xaya Arcade — write rules and a board UI, upload, no servers of your own — and a standalone channel game you host yourself.
- [building-channel-games/ARCADE.md](https://arcade.xaya.io/skills/building-channel-games/arcade.md): The one file to read if you just want to ship a game: the whole flow from a template clone to an accepted submission.
- [building-channel-games/STANDALONE.md](https://arcade.xaya.io/skills/building-channel-games/standalone.md): Running a channel game without the Arcade: your own referee GSP, relay, session keys and deployment.
- [building-channel-games/WASM.md](https://arcade.xaya.io/skills/building-channel-games/wasm.md): Compiling deterministic C++ rules to a freestanding WebAssembly judge, and authoring the golden traces that prove it.
- [building-channel-games/WAGERING.md](https://arcade.xaya.io/skills/building-channel-games/wagering.md): Putting a WCHI stake on a match: escrow, the payment queue, and paying out N players.
- [building-channel-games/HIDDEN-INFORMATION.md](https://arcade.xaya.io/skills/building-channel-games/hidden-information.md): Every seat holds the full signed state, so nothing in it is secret: where a secret lives instead, and what crosses the wire in its place.
- [building-channel-games/COMMIT-REVEAL.md](https://arcade.xaya.io/skills/building-channel-games/commit-reveal.md): Simultaneous moves on a strictly turn-based protocol, at N seats — the commitment, the reveal window, and the seat that never opens theirs.
- [building-channel-games/PITFALLS.md](https://arcade.xaya.io/skills/building-channel-games/pitfalls.md): The failures this platform actually produces, written so you recognise one in seconds.
- [building-channel-games/EXAMPLES.md](https://arcade.xaya.io/skills/building-channel-games/examples.md): Shipped channel games and what each one is worth reading for.
- [building-persistent-games](https://arcade.xaya.io/skills/building-persistent-games.md): For a game whose state lives fully on chain — a persistent world, an MMO, an economy, or an async game where every move is its own transaction — and for the platform foundation every Xaya game rests on: the GSP, the XayaX Polygon bridge, names, moves and determinism.
- [building-persistent-games/GSP.md](https://arcade.xaya.io/skills/building-persistent-games/gsp.md): Building a GSP on libxayagame: the callbacks you implement, protobuf state, and the build recipe.
- [building-persistent-games/DETERMINISM.md](https://arcade.xaya.io/skills/building-persistent-games/determinism.md): The law every Xaya game obeys — the same ordered moves must produce byte-identical state — and how to prove yours does.
- [building-persistent-games/OPS.md](https://arcade.xaya.io/skills/building-persistent-games/ops.md): The day-2 runbook: WAL growth, ZMQ staleness, resync and genesis height, and a GSP that will not sync.
- [building-persistent-games/FORK-TESTING.md](https://arcade.xaya.io/skills/building-persistent-games/fork-testing.md): Testing against a forked Polygon chain with no real funds, and the traps that come with it.
- [building-persistent-games/PITFALLS.md](https://arcade.xaya.io/skills/building-persistent-games/pitfalls.md): The on-chain and GSP failures that bite hardest, with the symptom first.
- [building-persistent-games/EXAMPLES.md](https://arcade.xaya.io/skills/building-persistent-games/examples.md): Shipped persistent worlds and the foundation repositories both skills rest on.

## Docs

- [Quickstart](https://arcade.xaya.io/docs/quickstart.md): The shortest honest path from nothing to a game on the Arcade — starting with whether your idea fits at all.
- [Driving an AI agent](https://arcade.xaya.io/docs/ai-agent.md): The literal opening prompt to paste at the start of the conversation, one per architecture.
- [Overview](https://arcade.xaya.io/docs/overview.md): What the Xaya Arcade is, how the pieces fit together, and the rules of the road for a game.
- [What you need](https://arcade.xaya.io/docs/requirements.md): The repositories, access, and local tooling required to build an Arcade game.
- [Getting started](https://arcade.xaya.io/docs/getting-started.md): Fork the template, run it locally against the committed SDK, and tour the project.
- [Make it yours](https://arcade.xaya.io/docs/make-it-yours.md): Turn the template into your own game — the full rename surface, one field at a time.
- [The rules blob](https://arcade.xaya.io/docs/rules-blob.md): The wasm judge contract: the arcade_* ABI, the pinned limits, and a reproducible build.
- [The SDK](https://arcade.xaya.io/docs/sdk.md): Build your UI on @xayaarcade/sdk: the adapter, configureApp, debug logging, and vendoring.
- [Testing](https://arcade.xaya.io/docs/testing.md): The determinism ladder, the off-chain channel scenarios, and the blob checks.
- [Submitting your game](https://arcade.xaya.io/docs/submitting.md): What a hand-over is made of — the artifacts, the facts, moderation, and what Accept automates — and where to rehearse it today.

## Repositories

- [arcade-xayaman](https://github.com/xaya/arcade-xayaman): CLONE — The copy-me template for an Arcade game: a working two-to-three player game with its wasm rules blob, its React board UI, the build and bundle scripts, and the offline test ladder. This is where you start. (private during the curated phase)
- [arcade-platform](https://github.com/xaya/arcade-platform): READ — The host game-state processor that runs every Arcade game, the wasm judge that executes your rules blob, the submissions service, and the @xayaarcade/sdk your frontend imports. It is the authority for the judge ABI and every submission limit. (private during the curated phase)
- [arcade-xayaships](https://github.com/xaya/arcade-xayaships): READ — A shipped Arcade game. Read it for the commit-reveal pattern: how to get unpredictability when the judge ABI gives your rules no source of randomness. (private during the curated phase)
- [arcade-xayatrails](https://github.com/xaya/arcade-xayatrails): READ — A shipped Arcade game built and submitted end to end by someone with no prior knowledge of the platform. The closest thing to a worked answer for 'what does a real submission look like'. (private during the curated phase)
- [arcade-dungeonchannel](https://github.com/xaya/arcade-dungeonchannel): READ — A shipped Arcade game: a two-to-four seat hidden-information dungeon crawl. Read it for a one-byte cfg suffix and for the additive arcade_share_weights payout surface, which is how a game splits a multi-seat pot by anything other than winner-takes-all. (private during the curated phase)
- [arcade-vector-sumo](https://github.com/xaya/arcade-vector-sumo): READ — A shipped Arcade game: a two-to-four seat commit/reveal arena with a zero-byte channel cfg (registered with no suffix at all) and on-screen touch controls. It declares no share weights, so its three- and four-seat wagered matches settle winner-takes-all. (private during the curated phase)
- [arcade-taurion-racer](https://github.com/xaya/arcade-taurion-racer): READ — A shipped Arcade game: a two-seat real-time racer whose fixed-point C++ physics, two AI cars and both tracks live in one freestanding rules blob. Read it for a signed setup stage (track and lap count agreed before the race), a seeded channel config (one-byte cfg suffix) and a browser that predicts ahead of the signed state and snaps back to it. (private during the curated phase)
- [xaya-relay](https://github.com/xaya/xaya-relay): CLONE — The message relay two players' browsers use to exchange signed moves off chain. You run one yourself for a standalone channel game; Arcade games use the hosted one. (private during the curated phase)
- [libxayagame (gamechannel/)](https://github.com/xaya/libxayagame): READ — The gamechannel/ directory is the reference implementation of the channel protocol: how a referee validates a state proof, resolves a dispute, and times a channel out.
- [soccer2d](https://github.com/xaya/soccer2d): READ — A real-time two-player channel game — useful for how a fast game hides network latency behind local prediction. (private during the curated phase)
- [xayarts](https://github.com/xaya/xayarts): READ — A channel game with a turn-based structure. (private during the curated phase)
- [xayafpsdemo](https://github.com/xaya/xayafpsdemo): READ — A first-person demo showing the patterns a high-tick-rate game needs on top of a channel. (private during the curated phase)
- [libxayagame](https://github.com/xaya/libxayagame): CLONE — The C++ library every Xaya game-state processor is built on: it feeds you ordered moves and stores your state, and you supply the rules. Also the home of the `mover` example, the smallest complete GSP there is.
- [xayax](https://github.com/xaya/xayax): READ — The bridge that turns Polygon blocks into the move stream your GSP consumes. You run it beside your GSP.
- [taurion_gsp](https://github.com/xaya/taurion_gsp): READ — A large persistent-world GSP: an economy, resources and territory, all fully on chain. The best available answer to 'how big can this get'.
- [tfgsp](https://github.com/xaya/tfgsp): READ — Treat Fighter's GSP — a smaller, more readable persistent game than Taurion, and a good first read.
- [xid](https://github.com/xaya/xid): READ — Identity and authentication built on Xaya names, if your game needs players to prove who they are off chain.
- [xaya (Core)](https://github.com/xaya/xaya): READ — Xaya Core. Its doc/xaya directory holds the live protocol specifications for names, moves and games.
- [xaya/xaya_tutorials](https://github.com/xaya/xaya_tutorials): READ — Superseded. The repository root has been dead since 2019, and the tutorial wiki attached to it predates Polygon, the Arcade and the current SDK. Use this site's docs and agent skills instead — they are verified against the code and rebuilt with it.
- [xaya-arcade](https://github.com/xaya/xaya-arcade): CONSUME — The Arcade website itself: the lobby, the docs you are reading, and the submission form. You use a running instance; you never need to clone it to ship a game. (private during the curated phase)
- [arcade-wager](https://github.com/xaya/arcade-wager): READ — The contract that escrows WCHI stakes for a wagered match and pays out the winner. (private during the curated phase)
- [arcade-fork-testing](https://github.com/xaya/arcade-fork-testing): READ — An operator's own deployment repository: brings up a forked Polygon chain with the whole stack on top, runs the browser end-to-end proofs, and is what runs the public playground. Private, and a builder never needs it. (private during the curated phase)
- [forked-evm-testing](https://github.com/xaya/forked-evm-testing): READ — The minimal forked-chain substrate arcade-fork-testing is built on — fork a real chain locally and spend no real funds.
- [taurion_racer](https://github.com/xaya/taurion_racer): READ — A small game built on Taurion's world — a compact example of building on top of an existing persistent GSP. (private during the curated phase)
- [taurionui](https://github.com/xaya/taurionui): READ — Taurion's game client: a large frontend against a persistent GSP. (private during the curated phase)
- [treatfighter_ui](https://github.com/xaya/treatfighter_ui): READ — Treat Fighter's game client. (private during the curated phase)
- [polygon-contract (XayaAccounts)](https://github.com/xaya/polygon-contract): READ — XayaAccounts: the contract that owns every p/ name and carries every move on chain. The single most important contract in the system.
- [wchi](https://github.com/xaya/wchi): READ — The WCHI token contract — what stakes and name registrations are paid in.
- [delegation-contract](https://github.com/xaya/delegation-contract): READ — Lets a name owner delegate permission to send moves for that name without handing over the name.
- [democrit-evm](https://github.com/xaya/democrit-evm): READ — Atomic trading of in-game assets against WCHI.
- [charon](https://github.com/xaya/charon): READ — Lets a light client reach a game-state processor it does not run itself.
- [eth-utils](https://github.com/xaya/eth-utils): READ — Shared Ethereum/Polygon helpers used across the Xaya contracts.
- [stats-subgraph](https://github.com/xaya/stats-subgraph): READ — A subgraph indexing Xaya activity for stats and dashboards.
- [xaya-mcp-server](https://github.com/xaya/xaya-mcp-server): READ — An MCP server exposing Xaya chain data to AI agents.
- [xaya/xayaman](https://github.com/xaya/xayaman): READ — The frozen pre-split monorepo. Superseded by arcade-xayaman — starting here is a known trap, because it predates the Arcade platform entirely. (private during the curated phase)
- [xaya/polyxayaships](https://github.com/xaya/polyxayaships): READ — The frozen pre-split ships monorepo. Superseded by arcade-xayaships. (private during the curated phase)
- [xaya/xayaships_frontend](https://github.com/xaya/xayaships_frontend): READ — A 2021 Xaya Core-era frontend. Name-collides with arcade-xayaships and is not related to it.
- [xaya/xaya-game-skill](https://github.com/xaya/xaya-game-skill): READ — The previous AI skill, superseded by the two skills in arcade-skills. (private during the curated phase)
- [xaya/xaya_docs](https://github.com/xaya/xaya_docs): READ — Its own README opens by saying the contents are outdated. Use this site's docs, and Xaya Core's own doc/xaya for node internals.
- [xaya/mypp](https://github.com/xaya/mypp): READ — A MariaDB connector wrapper, unrelated to building games.
- [Soccerverse](https://github.com/soccerverse): READ — A persistent football-management world built on Xaya — named here as a class of game rather than a single repository.
- [arcade-skills](https://github.com/xaya/arcade-skills): CLONE/READ — These two skills. Install them as a Claude Code plugin, or clone and copy them into .claude/skills/. (private during the curated phase)

## Optional

- [Hosting & registration](https://arcade.xaya.io/docs/hosting-registration.md): The operator runbook: hosted bundles, the games-host, on-chain registration, and wagering. (operator-only)
- [Operating the platform](https://arcade.xaya.io/docs/operating.md): For operators: the components, bring-up order, and games-host configuration. (operator-only)