Capabilities reference
Every capability a 0x script package can ask for on 0x.limo: the calls and events it unlocks, its grant parameters, who may hold it, its limits, its errors and an example.
A package asks for capabilities in its manifest (x1.json), and a 0x reviewer grants some or all of them, per world, when approving a version. Every call that touches players, the world, data or money needs one. This page lists every capability the production backend accepts today; 0x script capabilities prints the same list, with the worlds and their regions:
0x script capabilities # or: 0x script capabilities --jsonThe list comes from GET https://api.0x.limo/v1/scriptbus/packages/capabilities, which needs a sign-in (0x login, or a publish token). It answers {capabilities, budgets, limits, worlds}.
#How grants work
// x1.json
{
"id": "lago-fishing", "version": "1.0.0", "api": 1,
"scripts": { "main": "src/main.ts" },
"targets": ["earth"],
"capabilities": {
"chat": {},
"kv": {},
"inventory": { "bases": ["cod", "salmon"], "gives_per_min": 120, "max_count": 16 },
"economy": { "per_payout": 50, "per_player_day": 500, "per_day": 5000 },
"regions": { "request": [{ "id": "lago-pond", "rights": ["read"], "why": "the pond we fish in" }] },
"ui": { "kinds": ["actionbar", "title", "sound", "panel"], "sounds": ["entity.fishing_bobber.splash"] },
"fishing": {}
}
}- Parameters: each capability takes an object,
{}for none. The upload checks and normalizes them; an unknown capability or a bad parameter fails the upload with the field named (capabilities.inventory.bases: ...). - The grant: what the reviewer approves is at most what you asked for, often narrower (lower caps, fewer bases, some of your regions). At run time your sandbox sees it in
Host.capabilities(the names) andHost.Supports(name). - Who may hold it: community capabilities are granted to packages. By hand capabilities (
chat.broadcast) are never part of a plain approval: the reviewer must grant them one by one. Operator capabilities (kick) belong to a world's own scripts only, and a package that asks for one fails the upload. - Sensitive capabilities (money, other players, griefing:
chat.broadcast,kick,teleport,world,inventory,economy) are flagged in the review report, and the reviewer reads the code that uses them. - Over-reach: the review fails a version whose code calls an API of a capability the manifest doesn't ask for, and warns about capabilities it asks for but never calls.
- Events: player events (
Players.PlayerAdded,PlayerRemoving,Teleport.Arrived) reach every sandbox.Chat.MessagePostedneedschat. World events (World.BlockBroken,BlockPlaced,Interact,Touched,ItemPickedUp) and the fishing events reach a package only withworldorregions, and only inside its regions.
#Errors
- A call outside your grants throws
CapabilityErrorbefore anything happens. Itscapabilityfield names what was missing, and its message readsx1: the "economy" capability is not granted to earth/lago-fishing. - A call inside your grants that breaks a grant parameter (a base, a sound, a command name, a region you don't hold) also throws
CapabilityError, with the reason as the message. - Everything else (a rate limit, a bad argument, a player who left) throws a plain
Errorwhose message starts withx1:, for examplex1: rate limited (10 ui calls a second per player). Calls that return a promise reject with the same errors.
import { CapabilityError, Economy, Host } from "@x1/script";
if (!Host.Supports("economy")) warn("no payouts in this world");
try {
await Economy.PayoutAsync(player, 10, "Catch of the day", `catch:${player.UserId}:${day}`);
} catch (e) {
if (e instanceof CapabilityError) warn(`missing ${e.capability}: ${e.message}`);
else warn(String(e)); // x1: rate limited (2 payouts a second)
}#Budgets and package limits
Every sandbox also has budgets, independent of capabilities. You may ask for more in x1.json budgets, up to the maximum:
| Budget | Default | Maximum |
|---|---|---|
slice_ms: one handler, task or continuation | 5 ms | 20 ms |
slice_steps: VM steps per slice | 500,000 | 2,000,000 |
entry_ms: one call from the host into the VM | 50 ms | 200 ms |
cpu_ms_per_tick: main-thread time per tick, averaged over 1 s | 2 ms | 8 ms |
memory_mb: JS heap | 16 | 64 |
calls_per_s: host calls | 100 | 400 |
events_per_s: events in | 200 | 800 |
tasks: pending tasks | 1,000 | 4,000 |
kv_bytes: data store size | 4 MiB | 16 MiB |
kv_keys_per_store | 1,000 | 4,000 |
bus_per_s: bus publishes | 5 | 20 |
A package holds at most 16 scripts and 300 files, 1 MiB per file and 4 MiB in all. What happens past a budget (strikes, throttling, restarts) is in Sandboxes.
#Summary
| Capability | Unlocks | Grant parameters | Who may hold it |
|---|---|---|---|
chat | Player.SendMessage, Chat.MessagePosted | none | community |
chat.broadcast | Chat.Broadcast | per_min 1-6 | by hand, sensitive |
kick | Player.Kick | none | operator only |
kv | DataStore | none (size via budgets) | community |
messaging | Messaging | none | community |
teleport | Teleport.TeleportAsync, Player.TeleportAsync | destinations? | community, sensitive |
world | World.GetBlock/SetBlock/Spawn, Player.GetPosition | none (bounded by regions) | community, sensitive |
items | Items.GetAsync | none | community |
inventory | Inventory | bases, gives_per_min, max_count | community, sensitive |
economy | Economy | per_payout, per_player_day, per_day | community, sensitive |
regions | Regions, region events | request | community |
commands | Commands.Register | names, aliases | community |
ui | Ui | kinds, sounds, particles | community |
fishing | Fishing events and hook changes | none (bounded by regions) | community |
environment | Environment.GetAsync | none (bounded by regions) | community |
#chat
Talk to one player, and hear the world's chat.
| API | Arguments | Returns |
|---|---|---|
player.SendMessage(text) | text: plain text, cut at 512 characters | nothing |
Chat.MessagePosted | event (player, text) |
- Limits: 5 messages a second per player (burst 10). Links in a package's messages are not clickable.
- Errors:
rate limited (5 messages a second per player);player <id> is not in this world.
import { Chat } from "@x1/script";
Chat.MessagePosted.Connect((p, text) => { if (text === "!hi") p.SendMessage(`Hi ${p.DisplayName}`); });#chat.broadcast
One message to everyone in the world. Granted only by hand.
| API | Arguments | Returns |
|---|---|---|
Chat.Broadcast(text) | text: plain text, cut at 256 characters, shown as [<experience>] text | nothing |
- Parameters:
per_min: broadcasts a minute, 1-6 (default 6 when you ask without it). - Also needs
chat: ask for both; the call checkschatfirst, then the host checkschat.broadcast. - Errors:
rate limited (<per_min> broadcasts a minute).
Chat.Broadcast("The fishing contest starts in 5 minutes at the pond");#kick
Player.Kick(reason?). Operator only: a world's own scripts hold it, and a package that asks for it fails the upload with capabilities.kick: only a world's own scripts hold it.
#kv
Your experience's data stores, kept by the platform across restarts and hosts.
| API | Arguments | Returns |
|---|---|---|
DataStore.GetStore(name, {scope?, player?}) | name: 1-64 of A-Z a-z 0-9 _ . - / :; scope: "experience" (default), "publisher" (all your experiences), "player" (one player's, needs a 0x account), "exp:<id>" (another experience that granted you its store) | a DataStore |
store.GetAsync(key) / GetVersionedAsync(key) | key: 1-128 bytes | the value (or {value, version}), undefined when absent |
store.SetAsync(key, value) | value: JSON, at most 64 KiB | the new version |
store.UpdateAsync(key, transform) | transform(old, version) returns the new value or undefined to leave it | the stored value; retried up to 8 times on conflicting writers |
store.RemoveAsync(key) / ListKeysAsync(prefix?) | nothing / the keys |
- Limits: 16 stores, 1,000 keys per store and 4 MiB in all (raise with
budgets.kv_bytes, up to 16 MiB). - Errors:
keys are 1-128 bytes,value over 64 KiB,store full (1000 keys for community sandboxes),at most 16 stores for community sandboxes,data store quota: <used> of <cap> bytes used,scope player needs player(a guest,mc-<name>, has no player store: keep guests' data in the experience store under theirUserId),not allowed: kv_read/kv_write(another experience's store without its grant).
import { DataStore } from "@x1/script";
const best = DataStore.GetStore<number>("best-catch");
await best.UpdateAsync(player.UserId, (old) => Math.max(old ?? 0, weight));#messaging
Publish and subscribe on the 0x script bus.
| API | Arguments | Returns |
|---|---|---|
Messaging.PublishAsync(topic, data) | topic: yours ("scores") or another experience's ("exp:<id>/<topic>", needs its grant); data: JSON, at most 16 KiB | {id, topic} (the resolved exp:<experience>/<topic>) |
Messaging.SubscribeAsync(topic, callback) | callback(message) with {Topic, Data, Sent, Id, From} | a Connection |
- Limits: 5 publishes a second, burst 30 (raise with
budgets.bus_per_s, up to 20). - Errors:
bad topic,message data over 16 KiB,not allowed: publish/subscribe(another experience's topic without its grant),rate limited(withretry_after_ms).
import { Messaging } from "@x1/script";
await Messaging.PublishAsync("catches", { player: p.UserId, fish: "salmon", kg: 2.4 });#teleport
Send a player to another experience with a one-time ticket; the destination's scripts see Teleport.Arrived(player, data, from).
| API | Arguments | Returns |
|---|---|---|
Teleport.TeleportAsync(player, destination, data?) | player: a player with a 0x account; destination: an experience id; data: JSON, at most 16 KiB | {url, ticket} |
player.TeleportAsync(destination, data?) | the same | the same |
- Parameters:
destinations: the experience ids you plan to send players to (at most 32), shown to the reviewer. - Accepted when: the destination is your own experience, or accepts teleports from anyone, from the same publisher, or from experiences it granted
teleport. - Errors:
player: a 0x account id(guests can't be teleported),no such destination,no such player,not allowed: teleport,teleport data over 16 KiB,rate limited.
const r = await Teleport.TeleportAsync(p, "gem-catcher", { from: "pond" });#world
Read and change blocks, spawn, and read positions, inside your granted regions only.
| API | Arguments | Returns |
|---|---|---|
World.GetBlock(x, y, z) | block coordinates in a region with read | the block id ("water") |
World.SetBlock(x, y, z, block) | a region with build; block: a block id | nothing |
World.Spawn(kind, x, y, z) | a region with spawn; kind: item:<id> drops an item, or one of pig, cow, chicken, sheep, villager, armor_stand, rabbit | nothing |
player.GetPosition() | the player is inside one of your regions | {x, y, z, world} |
- Limits:
SetBlock200 a second;Spawn60 a minute. - Errors:
outside your regions (build)(orread,spawn),outside your regions,not a block: <id>,not an item: <id>,cannot spawn <kind>,x, y and z are numbers,rate limited (200 blocks a second),spawn limit reached (60 a minute).
await World.SetBlock(-900, 90, -520, "lantern");#items
Items.GetAsync(player) returns the player's 0x platform inventory (read only) as a JSON array. It is not the world inventory: for that, see inventory.
const owned = await Items.GetAsync(p);#inventory
Give, take and list your own sealed items in the player's world inventory. Full guide: Inventory.
| API | Arguments | Returns |
|---|---|---|
Inventory.GiveAsync(player, item) | item: {base, name?, lore?, tag?, count?}: base from your grant; name 64 chars; lore 8 lines of 64; tag at most 2 KiB of JSON; count 1-64 and at most max_count | {given, dropped} (what didn't fit drops at the player's feet) |
Inventory.TakeAsync(player, slots | filter, max?) | slot numbers (at most 41) or a filter over your own items | the ItemRefs taken |
Inventory.ListAsync(player) / HeldAsync(player) | ItemRef[] / the main-hand ItemRef or undefined | |
Inventory.ItemUsed | event (player, item): a right-click with one of your items |
- Parameters:
bases(required, at most 64; weapons, spawn eggs and operator items are refused),gives_per_min1-600 (default 120),max_count1-64 (default 64). - Errors:
base "<b>" is not in this experience's granted bases,<b> is a weapon: scripts give no weapons in v1,<b> is never given by scripts,count is 1-<n>,tag is at most 2 KiB of JSON,rate limited (gives_per_min <n>),at most 41 slots,player <id> is not in this world.
await Inventory.GiveAsync(p, { base: "cod", name: "Lago cod", tag: { kg: 1.2 } });#economy
Pay SCRIP from your experience's funded wallet, under caps. Scripts never mint money. Full guide: Economy.
| API | Arguments | Returns |
|---|---|---|
Economy.PayoutAsync(player, amount, memo, key) | amount: whole SCRIP, at least 1; memo: at most 80 characters, in the player's history; key: 1-128 printable characters without spaces, the idempotency key | {paid, capped, reason?, balance, tax?, id?} |
Economy.WalletAsync() | {balance, todayPaid, caps, frozen?} |
- Parameters:
per_payout,per_player_day,per_day, all required, whole SCRIP, up to the platform's maxima (the upload names the limit you crossed). - Cut short, not thrown: a payout over a cap or the balance pays less and says why in
reason:per_payout,per_player_day,per_day,wallet,duplicateorfrozen. Days are UTC days. The samekeynever pays twice. - Limits: 2 payouts a second.
- Errors:
rate limited (2 payouts a second),amount is a whole number of SCRIP, at least 1,key is 1-128 printable characters without spaces,player <id> is not in this world.
const r = await Economy.PayoutAsync(p, 25, "Salmon, 2.4 kg", `catch:${hookId}`);
if (r.capped) p.SendMessage(`Paid ${r.paid} (limit: ${r.reason})`);#regions
The map areas your experience may act in. Full guide: Regions.
| API | Arguments | Returns |
|---|---|---|
Regions.All() / Regions.Get(id) | Region[] / a Region or undefined | |
region.Contains(pos) / region.GetPlayers() | boolean / the players inside (at most 1 s old) | |
region.PlayerEntered / PlayerLeft | events (player) |
A Region has Id, World, Min, Max (inclusive block box), Rights and Water ("sea", "fresh", "brackish").
- Parameters:
request: 1-16 of{id, rights, why}.idcomes from the world's catalogue (0x script capabilitieslists them, for examplelago-pondinearth);rightsare some ofread(events, positions),build(SetBlock),spawn(defaultread);whyis up to 200 characters for the reviewer. - Bounds: granted regions bound
world,fishing,environmentandUi.Particles, and filter world events. - Errors:
region <id> is not granted to this experience.
const pond = Regions.Get("lago-pond");
pond?.PlayerEntered.Connect((p) => Ui.ActionBar(p, "Cast here to fish"));#commands
Chat commands under your namespace: /x1 <experience> <name> [args]. Full guide: Commands.
| API | Arguments | Returns |
|---|---|---|
Commands.Register(name, handler, options?) | name: 1-24 of a-z 0-9 - _, in your grant; handler(player, args): up to 16 plain-text args of 100 characters; options: {description?, usage?, who?: "everyone" | "creator" | "operator"} | a Connection |
- Parameters:
names(required, at most 16),aliases(some ofnames: also/<name>when no other plugin or package holds it). - Limits: a player runs at most 5 commands a second.
helpandfundare the host's own. - Errors:
"<name>" is not in this experience's granted names,"<name>" is the host's own,"<name>" is already registered,name is 1-24 of a-z 0-9 - _,who is everyone, creator or operator.
Commands.Register("top", async (p) => p.SendMessage(await topList()), { description: "The best catches" });#ui
What the player sees: action bars, titles, sounds, particles, sidebars, panels, toasts and the HUD. Text is always plain. Full guide: UI.
| API | Grant kind | Notes |
|---|---|---|
Ui.ActionBar(player, text) | actionbar | 120 characters |
Ui.Title(player, title, subtitle?) | title | 1 a second per player |
Ui.Sound(player, key, volume?, pitch?) | sound | key from your sounds |
Ui.Particles(kind, at, count) | particles | kind from your particles, inside your regions, count at most 64, 20 calls a second |
Ui.Sidebar(player, title, lines) | sidebar | up to 12 lines; [] removes it |
Ui.Panel(player, panel) / Ui.ShowAsync(player, panel) / Ui.ClosePanel(player) | panel | resolves with the button id (or {button, card?, qty?}), undefined when closed or timed out; 2 panels a second per player |
Ui.Toast(player, text, kind?) | toast | info, success, warn, error |
Ui.Hud(player, hud | null) | hud | title, up to 6 lines, a 0..1 progress bar |
- Parameters:
kinds: some ofactionbar,title,sound,particles,sidebar,panel,toast,hud;sounds: vanilla sound keys (at most 64);particles: particle kinds (at most 32). - Limits: 10 UI calls a second per player.
- Errors:
the ui grant has no "<kind>",sound <key> is not in this experience's granted sounds,particle <kind> is not in this experience's granted particles,particles outside this experience's regions,rate limited (10 ui calls a second per player),rate limited (1 title a second per player),rate limited (2 panels a second per player),panel: <what is wrong>.
const pick = await Ui.ShowAsync(p, { id: "shop", title: "Bait shop", cards: [{ id: "worm", title: "Worms", price: 5, qty: { max: 10 } }], buttons: [{ id: "buy", label: "Buy", style: "primary" }] });#fishing
The vanilla fishing hook, inside your regions. Full guide: Fishing and Environment.
| API | Arguments | Notes |
|---|---|---|
Fishing.Cast / Bite / Reel | events (hook); Reel: (hook, hadBite) | hook has Player, Position, Rod, Depth?, ReactionMs? (Reel) |
hook.SetWait(minTicks, maxTicks) | whole ticks, 1 ≤ min ≤ max ≤ 6000 | Cast only |
hook.HoldOff() | Bite only: the hook waits again | |
hook.CancelLoot() | Reel only: no vanilla loot; give your own catch |
- Synchronous only: hook methods change the vanilla event, so they work only in the handler before its first
await. - Errors:
that hook is not being delivered now (hook changes work only in the handler, before its first await),Hook.<method> works only in Fishing.<stage>,SetWait: whole ticks, 1 <= min <= max <= 6000.
Fishing.Cast.Connect((hook) => hook.SetWait(60, 200));
Fishing.Reel.Connect(async (hook, bit) => { if (!bit) return; hook.CancelLoot(); await Inventory.GiveAsync(hook.Player, { base: "salmon" }); });#environment
Real water and weather conditions at a place inside your regions.
| API | Arguments | Returns |
|---|---|---|
Environment.GetAsync(at) | at: a position inside a region with read | {waterTempC, airTempC, windMs, windFromDeg, waveM, salinity, basin, month, localHour, daylight} |
- Errors:
outside your regions,no such world.
const c = await Environment.GetAsync(hook.Position);
if (c.waterTempC < 12) Ui.ActionBar(hook.Player, "Cold water: trout bite");