0xDocs 0x.limo

Docs / Scripting

Publishing scripts to worlds

Package 0x scripts with x1.json, upload them with 0x script publish or the developer portal, pass the automated review and 0x's approval, and run in a world such as OG Earth in your own sandbox.

Live since 2026-10-23

Publishing is open on 0x.limo: @x1/script 0.2.0 and the 0x CLI 0.1.7 (0x script) are in the 0x registry, and approved packages run in OG Earth in their own sandboxes.

A package is your experience: TypeScript scripts plus a manifest, x1.json, that says which worlds it wants to run in and what it needs from them. Each version you upload goes through four steps:

  1. Upload. 0x script publish (or x1-script pack --sign + x1-script submit, or the developer portal) builds your scripts with the pinned compiler, adds your sources, signs the bundle and uploads it.
  2. Automated review. Within a minute, 0x checks the package and runs it in a sandbox.
  3. Approval. A 0x reviewer reads the report and your code, and approves the version for a world. The reviewer may grant less than you asked for.
  4. Live. The world's host loads your scripts in their own sandbox within about 10 seconds, without a server restart.

#The manifest

The manifest keeps its name x1.json for now (it is read by @x1/script); a 0x.json name is planned.

x1.json, at the root of your project:

json
{
  "id": "lago-fishing",
  "name": "Lago fishing",
  "version": "1.0.0",
  "api": 1,
  "scripts": { "main": "src/main.ts" },
  "targets": ["earth"],
  "capabilities": {
    "kv": {},
    "inventory": { "bases": ["fishing_rod", "cod"], "gives_per_min": 60 },
    "economy": { "per_payout": 200, "per_player_day": 1000, "per_day": 10000 },
    "regions": { "request": [{ "id": "lago-pond", "rights": ["read"], "why": "the fishing spot" }] },
    "commands": { "names": ["sell", "log"] },
    "ui": { "kinds": ["actionbar", "panel"] },
    "fishing": {}
  },
  "budgets": { "memory_mb": 16 },
  "description": "Fish the lake; a fishmonger pays SCRIP from the game's wallet."
}
FieldWhat it is
idYour experience's id: 2-40 of a-z 0-9 -. The first upload claims it for your account.
versionSemver MAJOR.MINOR.PATCH. Versions are immutable, and each upload must be higher than the last.
api1, the @x1/script major version.
scriptsScript name to entry file. Each becomes one ES module, dist/<name>.js.
targetsThe worlds you ask to be installed in.
capabilitiesWhat the scripts need, with parameters. See Capabilities.
budgetsOptional. At most 4 times the community defaults. See Budgets.

#Capabilities

Every call that touches the world or players needs a capability. A call outside your grants throws CapabilityError. 0x script capabilities lists them, with the worlds and their regions.

CapabilityAllowsParameters
chatPlayer.SendMessage, Chat.MessagePostednone
chat.broadcastChat.Broadcast (reviewers grant it only by hand)per_min (1-6)
kvDataStorenone
messagingMessagingnone
teleportTeleport, Player.TeleportAsyncdestinations?
worldWorld.GetBlock/SetBlock/Spawn inside your regionsnone
itemsItems.GetAsyncnone
inventoryInventory: your own sealed itemsbases, gives_per_min, max_count
economyEconomy: SCRIP payouts from your funded walletper_payout, per_player_day, per_day (all required)
regionsRegions; bounds world and region eventsrequest: [{id, rights: [read, build, spawn], why}], ids from the world's catalogue
commandsCommands.Register under /x1 <id>names, aliases
uiUikinds, sounds, particles
fishingFishingnone
environmentEnvironment.GetAsyncnone

Every call, parameter, limit and error is in the Capabilities reference. Several capabilities also have a guide: Inventory, Economy, Regions, Commands, UI, Fishing and Environment. Sandboxes explains budgets and what stops a sandbox.

Ask only for what you use. The review flags capabilities you never call, and fails code that calls APIs you didn't ask for.

#Budgets

Community sandboxes get 5 ms and 500,000 steps per handler, 16 MiB of JS heap, 2 ms of server time per tick, 100 host calls a second and 1,000 pending tasks. Your manifest can ask for more under budgets (slice_ms, slice_steps, entry_ms, memory_mb, cpu_ms_per_tick, events_per_s, calls_per_s, tasks, kv_bytes, kv_keys_per_store, bus_per_s), up to 4 times each default. A sandbox that keeps overrunning is stopped. Other sandboxes and the world are never affected.

#Publish

bash
echo "@x1:registry=https://0x.limo/npm/" >> .npmrc
npm i -D @x1/script
npx x1-script pack . --sign
npx x1-script submit . --api https://api.0x.limo --token "$X1_TOKEN" --notes "First release"
npx x1-script status lago-fishing@1.0.0

Or, with the 0x CLI (0.1.7 or newer: curl -fsSL https://0x.limo/sdk/install.sh | sh updates it), in one step:

bash
0x login
0x script publish --notes "First release"
0x script status lago-fishing@1.0.0

x1-script submit signs in with --token, X1_TOKEN (X1_BACKEND for the API), or the login in ~/.config/0x1/x1-cli.json. @x1/script 0.2.0 doesn't read the ZEROX_* names or ~/.config/0x/ yet, so pass --token if you only have a newer 0x login.

Publish tokens. 0x login saves a publish token (0xpub_…). To publish from CI, or from a machine where you can't run the device sign-in, make one at api.0x.limo/dev/tokens (Developer › Tokens): sign in, name it, copy it (it is shown once). Then 0x login --token <token>, or set it as ZEROX_TOKEN in CI. The same page lists your tokens (created, last used) and revokes them. A publish token can upload hosted sites, store listings and script packages for you, and nothing else: it can't sign in, spend or make more tokens.

0x script publish [dir] (or x1-script pack --sign + x1-script submit) does three things:

  1. Build. Builds each script with the pinned compiler (esbuild 0.28.2).
  2. Bundle. Writes dist/package.json with the manifest, the compiled modules and every source file the compiler read.
  3. Sign and upload. Signs the bundle with your key, ~/.config/0x1/script-signing.key (ed25519, created on first use), and uploads it.

After the first signed upload of an experience, every later upload must be signed with the same key, so keep the key safe. --no-sign uploads unsigned, but only for experiences that have never been signed.

CommandWhat it does
0x script publish [dir] [--check] [--notes "..."] [--no-sign]Build, sign and upload. --check type-checks first.
0x script status [id[@version]] [--json]Your packages, or one version's review report and decisions.
0x script withdraw <id>@<version>Withdraw a version that is not decided yet.
0x script capabilitiesWhat you can ask for, and the worlds' regions.

The same commands exist in @x1/script as x1-script pack [--sign], submit, status and withdraw.

#The developer portal

At api.0x.limo/dev/scripts you can sign in, upload a dist/package.json built with x1-script pack --sign, read each version's review, see where it is installed, and withdraw a version.

#The automated review

CheckFails when
Forbidden constructseval, the Function constructor, import(), WebAssembly, fetch or require, prototype tampering, or setTimeout with a string
ImportsA module imports anything but @x1/script. Bundle your dependencies.
Capability over-reachCode calls an API of a capability the manifest doesn't ask for
Source scanThe platform's malware and abuse rules find something serious
Reproducible buildA module isn't byte-for-byte what its sources compile to with the pinned compiler
Smoke runIn a sandbox with your budgets, players join, chat and run your commands for a few seconds. It fails on a crash, a load error, a budget strike, or a host call outside your capabilities.
GuestsThe smoke run's guest, mc-ReviewGuest, is refused a player data store (scope player needs player), even if your code catches the error

Guests. Players without a 0x account join worlds too. Their UserId is mc-<name>, and they have no player data store: DataStore.GetStore(name, { scope: "player", player }) fails for them with scope player needs player. The smoke run includes a guest, mc-ReviewGuest, who joins, chats and runs your commands. If your code opens a player store for them, the review fails (check guest-store), because every guest in a live world would hit the same error. Keep a guest's data in an experience store keyed by their UserId, or skip it for guests:

ts
import { Players, DataStore } from "@x1/script";

const guests = DataStore.GetStore("visits"); // the experience store
Players.PlayerAdded.Connect(async (p) => {
  if (!/^\d+$/.test(p.UserId)) {
    // a guest (mc-<name>): no player store, keep it under their UserId
    const n = ((await guests.GetAsync(p.UserId)) as number | undefined) ?? 0;
    await guests.SetAsync(p.UserId, n + 1);
    return;
  }
  const mine = DataStore.GetStore("visits", { scope: "player", player: p });
  const n = ((await mine.GetAsync("count")) as number | undefined) ?? 0;
  await mine.SetAsync("count", n + 1);
});

Catching the error isn't enough: the review counts the refusal itself. Other errors your scripts log in the smoke run are warnings.

Some checks only warn: suspicious patterns (obfuscated names, decoded payloads, global writes, busy loops), unused capabilities, and dynamic API access.

The review's verdict decides what happens next:

  • fail: the version is review_failed. Fix the problem and upload a new version.
  • pass or warn: the version waits for approval.

An AI review also runs. It is advice for the reviewer. You see its findings only if a reviewer raises one as a review issue.

#Approval, review issues, and after

  • Approval. A reviewer approves a version for one world at a time, with grants that are at most what you asked for. For example, lower payout caps, fewer item bases, or only some of your regions.
  • Review issues. If something must change, the reviewer opens a review issue. A rejection's message is one too. Answer them in /dev/submit or with 0x issues, then upload a new version.
  • Updates. Each update is a new version and is reviewed again. The console shows reviewers the diff of your sources against the version that runs now.
  • Roll back, kill switch, revoke. 0x can roll a world back to an earlier approved version of yours. It can also switch your scripts off everywhere (the kill switch), or revoke the install in a world.
StatusMeaning
uploaded, reviewingThe automated review is pending or running
review_failedFix it and upload a new version
pending_approvalWaiting for a 0x reviewer
approvedInstalled in a world; it runs there
rejectedSee the review issue for why
supersededA newer version was uploaded or approved
withdrawnYou withdrew it