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:
- Upload.
0x script publish(orx1-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. - Automated review. Within a minute, 0x checks the package and runs it in a sandbox.
- 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.
- 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:
{
"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."
}| Field | What it is |
|---|---|
id | Your experience's id: 2-40 of a-z 0-9 -. The first upload claims it for your account. |
version | Semver MAJOR.MINOR.PATCH. Versions are immutable, and each upload must be higher than the last. |
api | 1, the @x1/script major version. |
scripts | Script name to entry file. Each becomes one ES module, dist/<name>.js. |
targets | The worlds you ask to be installed in. |
capabilities | What the scripts need, with parameters. See Capabilities. |
budgets | Optional. 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.
| Capability | Allows | Parameters |
|---|---|---|
chat | Player.SendMessage, Chat.MessagePosted | none |
chat.broadcast | Chat.Broadcast (reviewers grant it only by hand) | per_min (1-6) |
kv | DataStore | none |
messaging | Messaging | none |
teleport | Teleport, Player.TeleportAsync | destinations? |
world | World.GetBlock/SetBlock/Spawn inside your regions | none |
items | Items.GetAsync | none |
inventory | Inventory: your own sealed items | bases, gives_per_min, max_count |
economy | Economy: SCRIP payouts from your funded wallet | per_payout, per_player_day, per_day (all required) |
regions | Regions; bounds world and region events | request: [{id, rights: [read, build, spawn], why}], ids from the world's catalogue |
commands | Commands.Register under /x1 <id> | names, aliases |
ui | Ui | kinds, sounds, particles |
fishing | Fishing | none |
environment | Environment.GetAsync | none |
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
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.0Or, with the 0x CLI (0.1.7 or newer: curl -fsSL https://0x.limo/sdk/install.sh | sh updates it), in one step:
0x login
0x script publish --notes "First release"
0x script status lago-fishing@1.0.0x1-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:
- Build. Builds each script with the pinned compiler (esbuild 0.28.2).
- Bundle. Writes
dist/package.jsonwith the manifest, the compiled modules and every source file the compiler read. - 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.
| Command | What 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 capabilities | What 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
| Check | Fails when |
|---|---|
| Forbidden constructs | eval, the Function constructor, import(), WebAssembly, fetch or require, prototype tampering, or setTimeout with a string |
| Imports | A module imports anything but @x1/script. Bundle your dependencies. |
| Capability over-reach | Code calls an API of a capability the manifest doesn't ask for |
| Source scan | The platform's malware and abuse rules find something serious |
| Reproducible build | A module isn't byte-for-byte what its sources compile to with the pinned compiler |
| Smoke run | In 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. |
| Guests | The 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:
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/submitor with0x 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.
| Status | Meaning |
|---|---|
uploaded, reviewing | The automated review is pending or running |
review_failed | Fix it and upload a new version |
pending_approval | Waiting for a 0x reviewer |
approved | Installed in a world; it runs there |
rejected | See the review issue for why |
superseded | A newer version was uploaded or approved |
withdrawn | You withdrew it |
