0xDocs 0x.limo

Docs / Getting started

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.

StepYou runTime
1. Installcurl … | sh30 s
2. Get a game0x init or an example zip30 s
3. Play it locally0x dev1 min
4. Publish0x login, 0x publish1 min
5. List it in the store0x submit2 min

#1. Install the CLI

You need Node.js 20 or newer.

bash
curl -fsSL https://0x.limo/sdk/install.sh | sh
0x help

The 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:

bash
0x init                       # lists the templates
0x init canvas my-game        # or: three, phaser, babylon
cd my-game
TemplateWhat you get
threethree.js 3D: a glTF ship and textured ground. three.js is copied into vendor/, so it runs offline.
phaserPhaser 3 2D: sprites, arcade physics, arrow keys. Phaser loads from a CDN.
babylonBabylon.js 3D: a glTF ship, textured ground and an arc-rotate camera. Babylon loads from a CDN.
canvasVanilla 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:

bash
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
FileWhat it does
index.htmlThe 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.jsThe 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.jsonYour 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

bash
0x dev                        # http://localhost:5173

0x 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.

bash
0x login                      # opens a sign-in page: approve the code
0x publish
text
0x 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:

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:

bash
0x submit --site my-neon-drift --site-version 1
text
0x 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)
bash
0x submit status              # every listing of yours: pending, approved or rejected, with the reviewer's note
0x issues                     # anything a reviewer raised

What review means and how updates work: Developer portal, after you submit. Field rules: Listing fields.

#The web path (no install)

  1. Get a starter, or use your own game. Each starter zip is a complete static site with the 0x runtime already in it:

    bash
    curl -fsSLO https://0x.limo/sdk/starters/three.zip   # or phaser.zip, babylon.zip, canvas.zip
    unzip three.zip -d my-game

    For your own game, unzip runtime.zip next to your index.html (it adds x1-sw.js and x1/). Then change one line:

    html
    <!-- 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/ and x1-sw.js to every version anyway (and refuses uploads of them), so for 0x hosting the one-line change is all you need.

  2. 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, see 0x publish --to.

  3. 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.json next to index.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.

bash
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 :3001

Open 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, and io.to(room).emit for 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:

js
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 connection

The page wraps its socket:

js
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

bash
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.json

0x 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:

bash
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 | start

What your server gets:

VariableMeaning
PORTThe port to listen on
ZEROX_BCAST_SERVER_URL, ZEROX_BCAST_PLAYER_URL, ZEROX_BCAST_TOKENThe broadcast service, with your app's own token
ZEROX_PUBLIC_URL, ZEROX_APP, ZEROX_API_URLWhere 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

SymptomFix
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 foundOpen a new shell, or export PATH="$HOME/.0x/bin:$PATH".
the site name "…" belongs to another developerChange "id" in 0x.config.json, or use 0x publish --site <name>.
not signed inRun 0x login. In CI, set ZEROX_PUBLISH_TOKEN (see tokens in CI).
upload refused with a list of problemsEach line names a file: a hidden file, a blocked type, or one larger than 64 MiB. See Hosting limits.
capsule: … requiredPoint listing.capsule at a PNG of at most 1 MiB.
Pre-check link failsSubmit with --site and --site-version (a hosted version), or with --url and a public https address.
Multiplayer does nothing locallyRun npm install and then npm run server in the game folder, and reload. For a server elsewhere, add ?server=http://host:3001.
meshtorrent not foundReinstall the CLI (it brings @x1/meshtorrent), or set ZEROX_MESHTORRENT to a built meshtorrent checkout.
Assets still come from the originThis is expected on the first visit and for files under 16 KiB. Check window.x1swarm.stats().
Something on the page is blockedLook at Site security policy on /dev/submit and declare the host in "csp".