0xDocs 0x.limo

Docs / 0x CLI

0x.config.json

Every key of a game's 0x.config.json (identity, dist, server, listing, csp), what reads it, its rules, and examples; plus swarm-assets.json.

0x.config.json sits at the top of your game folder. The CLI reads it, and it is never uploaded to your site. Every key is optional, but id is what most commands fall back on.

Before the rename to 0x the file was called x1.config.json. A folder that has only x1.config.json still works; when both exist, 0x.config.json wins.

#Example

json
{
  "id": "orb-rush",
  "name": "Orb Rush",
  "tagline": "A 20-player scramble for glowing orbs in a floating arena.",
  "description": "Run, jump and ride launch pads around a floating sky arena…",
  "tags": ["Multiplayer", "Action", "Casual", "3D"],
  "dist": ".",
  "server": { "entry": "server.mjs", "deploy": true },
  "csp": {
    "connect": ["https://api.example.com", "wss://realtime.example.com"],
    "img": ["https://images.example.com"]
  },
  "listing": {
    "age_rating": { "rating": "teen", "descriptors": ["violence"] },
    "play": { "type": "hosted-server" },
    "capsule": "art/capsule.png",
    "screenshots": ["art/shot-1.png", "art/shot-2.png"],
    "trailer": { "url": "https://youtu.be/XXXXXXXXXXX" },
    "release": "full",
    "release_notes": "Two new arenas.",
    "details": { "controls": ["keyboard-mouse", "touch"], "phones": true, "players": { "single": true, "multi": true, "max": 20 }, "languages": ["English"] }
  }
}

#Top-level keys

KeyTypeUsed byMeaning
idstringpublish, deploy-server, server, submitYour game's id. It is the default site name (3–40 a-z 0-9 -), app id for the hosted server, and store listing id (3–64 a-z 0-9 -). Use one id for all three.
namestringpublish, submitThe display name: the site name on creation, and the listing title (1–80 characters)
taglinestringsubmit, universeOne line, at most 200 characters
descriptionstringsubmit, universe1–4000 characters. listing.description overrides it for the store.
tagsstring[]submit, universeAt most 16, each 1–32 characters
diststringdev, publishThe directory to serve and upload, relative to the folder. Default .. Point it at your build output, such as "dist".
sitestringpublishThe hosting site name, if different from id
originstringsubmitFor self-hosted games: the play URL used when no --url, --site or listing.play.url is given
serverobjectpublish, deploy-server, serverSee server
cspobjectpublishThe site security policy declaration. See csp.
mountsobject[]publish --toExternal data trees for the swarm: [{prefix, dir, exclude?, minBytes?}]. A relative dir is resolved against the game directory. They are added to any --mount flags, and a hosted publish ignores them. Not in a published CLI yet. See Mounts.
listingobjectsubmitThe store listing. See listing.
developer, art, accent, appid, freepublish (universe)Fields of the printed universe catalog entry only: developer name, art key ("default"), accent RGB ([120,140,255]), app id, and free (default true). They are not sent to the store.

#server

KeyDefaultMeaning
server.appidApp id of the hosted server (/x1/game/<app>/)
server.entryserver.mjsThe file the host starts
server.deployfalsetrue: 0x publish also deploys the server (like --server)

#csp

This declares what your page needs from outside its own origin. New hosted versions are served with an enforced Content-Security-Policy and a Permissions-Policy. Anything you don't declare is blocked. The declaration is sent with the version (POST /v1/hosting/sites/<site>/versions → csp), and the service validates it. Invalid entries refuse the upload with one problem per line. The upload page's "security policy" section is the same declaration.

KeyTypeExtendsRules
connectorigin[]connect-src (fetch, XHR, WebSocket, EventSource)https:// or wss:// origins
imgorigin[]img-srchttps:// origins
mediaorigin[]media-src (audio, video)https:// origins
fontorigin[]font-srchttps:// origins
scriptorigin[]script-srchttps:// origins
frameorigin[]frame-srchttps:// origins
permissionsstring[]Permissions-PolicyAny of camera, microphone, geolocation, usb, serial, hid, payment
evalbooleanscript-src 'unsafe-eval'Allows eval() and new Function()
inline_stylesbooleanstyle-srcAllows <style> elements created at runtime

Origin rules:

  • an origin only: https://host[:port], with no path, query or user part (a trailing / is dropped);
  • a host name with a domain, not an IP address;
  • a wildcard only as the whole first label: https://*.example.com;
  • at most 20 origins per kind, 64 in all, and 8 KiB for the whole declaration.

Always allowed, without declaring anything:

  • your own origin;
  • connections to the 0x platform hosts (https://api.0x.limo, https://play.0x.limo, wss://play.0x.limo);
  • fullscreen, gamepad and autoplay;
  • inline <script> and <style> that ship in your HTML files (hashed at finalize, up to 64 hashes per version).

After finalizing, 0x publish prints the mode (enforced or report-only), what you declared, the hash counts, and policy warnings. What the policy blocks is reported back to you. See Site security policy on /dev/submit, or GET /v1/hosting/csp-reports.

json
{ "csp": { "connect": ["wss://realtime.example.com"], "script": ["https://cdn.jsdelivr.net"], "permissions": ["microphone"] } }

#listing

0x submit builds the store submission from these keys. Rules for each field: Listing fields.

KeyTypeMeaning
listing.age_ratingstring or {rating, descriptors}"everyone", "teen", "mature", "adults-only". See Age ratings.
listing.playobject{type: "web" | "hosted-server" | "paper", url?, server?: {host, port}, site?, version?}. --site/--site-version/--url/--type override it.
listing.descriptionstringThe store description, if different from description
listing.capsulepathCapsule PNG, at most 1 MiB. Required on the first submission and kept after that if left out.
listing.screenshotspath[]Up to 6 PNG/JPEG files, at most 2 MiB each
listing.trailer{url} or {upload} or falseA YouTube/Vimeo link, an uploaded file name, or false to remove the trailer
listing.releasestring"demo" (a playable demo of an upcoming release) or "full". Left out, the game keeps its stage. --release overrides it.
listing.release_notesstring"What's new" for this version, at most 4000 characters
listing.detailsobjectcontrols, phones, players, languages, download_bytes
listing.sourceobjectThe source declaration, as --source builds it: {kind: "git", url, commit, access} or {kind: "ipfs", cid} or {kind: "torrent", infohash | magnet}, plus build: {file} or an inline recipe

#swarm-assets.json

swarm-assets.json is a separate file next to index.html, so it is uploaded. It chooses which files go into the player swarm. Paths match as globs relative to the site.

json
{ "include": ["**/*.png", "models/**"], "exclude": ["secret/**"] }

When the file is absent, the default policy puts every file of 16 KiB or more in the swarm, except:

json
{
  "include": ["**"],
  "exclude": ["**/*.html", "**/*.htm", "x1/**", "x1-sw.js", "x1.json", "swarm-assets.json", "node_modules/**", ".x1/**",
              "server.mjs", "package.json", "package-lock.json", "0x.config.json"]
}

Pages, small files and the 0x runtime always come from the origin. A paid game's site has no swarm at all.