Publish a web game in 5 minutes
Install the 0x CLI, start from a template or an example, run it locally, publish it on 0x hosting and submit it to the store. Also the no-install web path and multiplayer with a hosted server.
This guide takes you from nothing to a game in the 0x store. It is the canonical version of the older /sdk/first-game.html and /sdk/multiplayer.html pages.
| Step | You run | Time |
|---|---|---|
| 1. Install | curl … | sh | 30 s |
| 2. Get a game | 0x init or an example zip | 30 s |
| 3. Play it locally | 0x dev | 1 min |
| 4. Publish | 0x login, 0x publish | 1 min |
| 5. List it in the store | 0x submit | 2 min |
#1. Install the CLI
You need Node.js 20 or newer.
curl -fsSL https://0x.limo/sdk/install.sh | sh
0x helpThe installer puts 0x in ~/.0x (no sudo needed), adds ~/.0x/bin to your PATH, and points the @0xlimo npm scope at the 0x registry. If you would rather not install, every command also works through npx: npx --registry https://0x.limo/npm/ 0x …. Installer options are listed on the CLI page.
#2. Get a game
You can start from a template:
0x init # lists the templates
0x init canvas my-game # or: three, phaser, babylon
cd my-game| Template | What you get |
|---|---|
three | three.js 3D: a glTF ship and textured ground. three.js is copied into vendor/, so it runs offline. |
phaser | Phaser 3 2D: sprites, arcade physics, arrow keys. Phaser loads from a CDN. |
babylon | Babylon.js 3D: a glTF ship, textured ground and an arc-rotate camera. Babylon loads from a CDN. |
canvas | Vanilla 2D canvas: no engine, no build step, a scrolling world. |
Every template has optional multiplayer: a socket.io server (server.mjs) whose broadcasts go through @0xlimo/net (npm run server).
CDN engines and the site policy
New hosted versions are served with an enforced Content-Security-Policy. If you keep Phaser or Babylon on a CDN, declare it in 0x.config.json (both templates load from https://cdn.jsdelivr.net: "csp": {"script": ["https://cdn.jsdelivr.net"]}), or vendor the engine next to your game. See 0x.config.json csp.
Or you can start from a finished example:
curl -fsSLO https://0x.limo/sdk/examples/neon-drift.zip # a canvas arcade game, single-player
unzip neon-drift.zip -d neon-drift && cd neon-drift| File | What it does |
|---|---|
index.html | The page. Its only 0x line is <script type="module" src="./x1/boot.js" data-entry="./game.js">, which starts the player swarm and then runs your game. |
game.js | The whole game: input, update, draw, and the best score in localStorage. None of it knows about 0x. |
assets/ | Images loaded with plain new Image(). Players get them from each other. |
0x.config.json | Your game's id, name, tagline and tags, plus the store listing (age rating, art). See 0x.config.json. |
art/ | The store capsule (616×353 PNG) and screenshots (1280×720). |
#3. Play it locally
0x dev # http://localhost:51730x dev serves the folder the way 0x will. It runs the 0x runtime, a local tracker and seeder (so the swarm works on your machine too), and a development broadcast service. Edit your code and reload. Add your own loaders as usual: x1/boot.js makes their requests come from the swarm.
#4. Publish
First make the game yours. Open 0x.config.json and change "id". It names your hosted site, your hosted server and your store listing, so pick your own instead of a template's or example's id.
0x login # opens a sign-in page: approve the code
0x publish0x publish: 7 files, 1.4 MiB from /home/you/neon-drift
0x publish: created site my-neon-drift
0x publish: version 1: uploading 7 files, 1.4 MiB (0 already on the service)
0x publish: finalizing (content check, 0x runtime, swarm manifest)
0x publish: 3 files (1.2 MiB) in the swarm
0x publish: security policy enforced; declared nothing ("csp" in 0x.config.json); 0 inline scripts and 0 <style> elements allowed by hash
0x publish: play at https://my-neon-drift-play.0x.limo/sites/my-neon-drift/1/Anyone can open that link right away. Each 0x publish makes a new immutable version (/2/, /3/, …), and old links keep working. If a publish is interrupted, running it again resumes and uploads only what is missing. 0x publish prints a JSON summary on stdout (url, site, version, manifest_sha256, and universe, the launcher catalog entry).
#5. List it in the store
The listing comes from 0x.config.json:
{
"id": "my-neon-drift",
"name": "Neon Drift",
"tagline": "Catch stars, dodge meteors, chase your best score.",
"description": "A tiny neon arcade game. …",
"tags": ["Arcade", "Casual", "Singleplayer"],
"listing": {
"age_rating": "everyone",
"play": { "type": "web" },
"capsule": "art/capsule.png",
"screenshots": ["art/shot-1.png", "art/shot-2.png", "art/shot-3.png"]
}
}Submit the version you just published, using the number 0x publish printed:
0x submit --site my-neon-drift --site-version 10x submit: my-neon-drift v1 is waiting for review (listing 19)
ok fields: title, description, age rating, play target and capsule art present
ok link: HTTP 200
ok hosted: hosted version built (7 files, swarm manifest built)0x submit status # every listing of yours: pending, approved or rejected, with the reviewer's note
0x issues # anything a reviewer raisedWhat review means and how updates work: Developer portal, after you submit. Field rules: Listing fields.
#The web path (no install)
Get a starter, or use your own game. Each starter zip is a complete static site with the 0x runtime already in it:
curl -fsSLO https://0x.limo/sdk/starters/three.zip # or phaser.zip, babylon.zip, canvas.zip unzip three.zip -d my-gameFor your own game, unzip runtime.zip next to your
index.html(it addsx1-sw.jsandx1/). Then change one line:<!-- before --> <script type="module" src="./main.js"></script> <!-- after --> <script type="module" src="./x1/boot.js" data-entry="./main.js"></script>Hosted publishing adds
x1/andx1-sw.jsto every version anyway (and refuses uploads of them), so for 0x hosting the one-line change is all you need.Host it. Open api.0x.limo/hosting/, sign in, enter a site name and drop the folder or
.zip. The page prints the play URL. For self-hosting on any HTTPS static host, see0x publish --to.List it. Use the form at api.0x.limo/dev/submit with your site id and version.
#How players share your game
When you publish, the service builds a swarm manifest. Every file of 16 KiB or more gets a SHA-256 hash and a torrent. The first players load files from 0x. After that, players' browsers hand files to each other over WebRTC while the game is open, and the 0x seeder fills any gaps. Every piece is checked against the manifest's hash before your game sees it, and anything slow or missing comes from the origin as usual. Your code does nothing for this: x1/boot.js installs a service worker that answers your game's ordinary fetch, Image, Audio and loader requests.
- Small files, your HTML and the 0x runtime always come from the origin.
- Players choose in the launcher: On (the default), Private (
?p2p=relay: connections go through the 0x relay, so other players never see their address) or Off (?p2p=0: everything comes from 0x). Your game gets the same files either way. - To see where files came from, run
window.x1swarm.stats()in the console. The live network is at p2p.0x.limo. - To choose what is shared, put a
swarm-assets.jsonnext toindex.html:{"include": ["**/*.png"], "exclude": ["secret/**"]}.
#Multiplayer with a hosted server
Orb Rush is a 20-player three.js arena: an ordinary socket.io server, hosted by 0x, whose updates reach players through the 0x broadcast service.
curl -fsSLO https://0x.limo/sdk/examples/orb-rush.zip
unzip orb-rush.zip -d orb-rush && cd orb-rush
npm install # @0xlimo/net (0x registry, see .npmrc), socket.io, three.js into vendor/
0x dev # terminal 1: http://localhost:5173
npm run server # terminal 2: the game server on :3001Open two tabs, pick two names, and you see each other. Without the server, the page plays solo with the same rules.
How it fits together:
- Broadcasts (
io.emit, andio.to(room).emitfor interest-group rooms) leave your server once, however many players there are. The broadcast service signs each one and fans it out through trees of players over WebRTC. Players check every broadcast against the service's signature. - Unicast (
socket.emit) and everything players send stay on socket.io, unchanged. - A player who cannot reach the service gets broadcasts over socket.io instead.
The server needs two lines:
import { Server } from "socket.io";
import WebSocket from "ws";
import { connectServiceServer, routeSocketIoBroadcasts } from "@0xlimo/net";
const io = new Server(http, { cors: { origin: true } });
const service = await connectServiceServer({ url: process.env.ZEROX_BCAST_SERVER_URL, token: process.env.ZEROX_BCAST_TOKEN, WebSocket });
routeSocketIoBroadcasts(io, { service, playerUrl: process.env.ZEROX_BCAST_PLAYER_URL });
service.on("close", () => process.exit(1)); // the host restarts you with a fresh connectionThe page wraps its socket:
import { connectMeshPlayer, loadBroadcastWasm, x1SocketIo } from "./x1/net/index.js";
const wasm = await loadBroadcastWasm(new URL("./x1/net/wasm/", location.href).href);
const ice = await fetch("./p2p/ice").then((r) => r.json()).catch(() => ({}));
const socket = x1SocketIo(io(SERVER, { path: "/x1/game/my-arena/socket.io" }), {
connect: (j) => connectMeshPlayer({ ...j, wasm, mesh: true, rtcConfig: { iceServers: ice.iceServers } }),
});
socket.on("state", render); // unchanged socket.io handlers#Put it online
0x login # once
0x publish --server # the page, then the server
0x submit --site <id> --site-version 1 # with "play": {"type": "hosted-server"} in 0x.config.json0x publish --server publishes the site and then deploys the server, in that order. The server host only accepts an app id that is one of your hosted sites, so publish the site before (or together with) its server. The server is reachable at https://play.0x.limo/x1/game/<id>/.
Server address from a hosted page
Hosted pages now run on their own origin (<id>-play.0x.limo), but hosted game servers are served from play.0x.limo. The example net.js guesses <page origin>/x1/game/<id>, which does not exist on a site's own origin. Point the page at https://play.0x.limo/x1/game/<id> explicitly, or pass ?server=https://play.0x.limo/x1/game/<id>. 0x publish --server also adds server=<url> to the launcher catalog entry it prints (universe.web.params).
Then manage the server:
0x server status # running, restarts, CPU and memory
0x server logs # your console.log, plus the host's notes (install, start, restarts)
0x server stop | startWhat your server gets:
| Variable | Meaning |
|---|---|
PORT | The port to listen on |
ZEROX_BCAST_SERVER_URL, ZEROX_BCAST_PLAYER_URL, ZEROX_BCAST_TOKEN | The broadcast service, with your app's own token |
ZEROX_PUBLIC_URL, ZEROX_APP, ZEROX_API_URL | Where players reach you, your app id, and the platform API |
The host also sets each of these under its old name, X1_* (for example X1_BCAST_TOKEN), so servers written before the rename to 0x keep working; read ZEROX_* first and fall back to X1_*.
The sandbox and its limits are described in Hosting limits.
#If something goes wrong
| Symptom | Fix |
|---|---|
404 Not Found - GET https://registry.npmjs.org/@0xlimo%2f… | The @0xlimo packages are only on the 0x registry: npm config set @0xlimo:registry https://0x.limo/npm/. The installer does this for you. |
0x: command not found | Open a new shell, or export PATH="$HOME/.0x/bin:$PATH". |
the site name "…" belongs to another developer | Change "id" in 0x.config.json, or use 0x publish --site <name>. |
not signed in | Run 0x login. In CI, set ZEROX_PUBLISH_TOKEN (see tokens in CI). |
upload refused with a list of problems | Each line names a file: a hidden file, a blocked type, or one larger than 64 MiB. See Hosting limits. |
capsule: … required | Point listing.capsule at a PNG of at most 1 MiB. |
Pre-check link fails | Submit with --site and --site-version (a hosted version), or with --url and a public https address. |
| Multiplayer does nothing locally | Run npm install and then npm run server in the game folder, and reload. For a server elsewhere, add ?server=http://host:3001. |
meshtorrent not found | Reinstall the CLI (it brings @x1/meshtorrent), or set ZEROX_MESHTORRENT to a built meshtorrent checkout. |
| Assets still come from the origin | This is expected on the first visit and for files under 16 KiB. Check window.x1swarm.stats(). |
| Something on the page is blocked | Look at Site security policy on /dev/submit and declare the host in "csp". |
