0xDocs 0x.limo

Docs / Scripting

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:

bash
0x script capabilities          # or: 0x script capabilities --json

The 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

jsonc
// 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) and Host.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.MessagePosted needs chat. World events (World.BlockBroken, BlockPlaced, Interact, Touched, ItemPickedUp) and the fishing events reach a package only with world or regions, and only inside its regions.

#Errors

  • A call outside your grants throws CapabilityError before anything happens. Its capability field names what was missing, and its message reads x1: 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 Error whose message starts with x1:, for example x1: rate limited (10 ui calls a second per player). Calls that return a promise reject with the same errors.
ts
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:

BudgetDefaultMaximum
slice_ms: one handler, task or continuation5 ms20 ms
slice_steps: VM steps per slice500,0002,000,000
entry_ms: one call from the host into the VM50 ms200 ms
cpu_ms_per_tick: main-thread time per tick, averaged over 1 s2 ms8 ms
memory_mb: JS heap1664
calls_per_s: host calls100400
events_per_s: events in200800
tasks: pending tasks1,0004,000
kv_bytes: data store size4 MiB16 MiB
kv_keys_per_store1,0004,000
bus_per_s: bus publishes520

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

CapabilityUnlocksGrant parametersWho may hold it
chatPlayer.SendMessage, Chat.MessagePostednonecommunity
chat.broadcastChat.Broadcastper_min 1-6by hand, sensitive
kickPlayer.Kicknoneoperator only
kvDataStorenone (size via budgets)community
messagingMessagingnonecommunity
teleportTeleport.TeleportAsync, Player.TeleportAsyncdestinations?community, sensitive
worldWorld.GetBlock/SetBlock/Spawn, Player.GetPositionnone (bounded by regions)community, sensitive
itemsItems.GetAsyncnonecommunity
inventoryInventorybases, gives_per_min, max_countcommunity, sensitive
economyEconomyper_payout, per_player_day, per_daycommunity, sensitive
regionsRegions, region eventsrequestcommunity
commandsCommands.Registernames, aliasescommunity
uiUikinds, sounds, particlescommunity
fishingFishing events and hook changesnone (bounded by regions)community
environmentEnvironment.GetAsyncnone (bounded by regions)community

#chat

Talk to one player, and hear the world's chat.

APIArgumentsReturns
player.SendMessage(text)text: plain text, cut at 512 charactersnothing
Chat.MessagePostedevent (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.
ts
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.

APIArgumentsReturns
Chat.Broadcast(text)text: plain text, cut at 256 characters, shown as [<experience>] textnothing
  • Parameters: per_min: broadcasts a minute, 1-6 (default 6 when you ask without it).
  • Also needs chat: ask for both; the call checks chat first, then the host checks chat.broadcast.
  • Errors: rate limited (<per_min> broadcasts a minute).
ts
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.

APIArgumentsReturns
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 bytesthe value (or {value, version}), undefined when absent
store.SetAsync(key, value)value: JSON, at most 64 KiBthe new version
store.UpdateAsync(key, transform)transform(old, version) returns the new value or undefined to leave itthe 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 their UserId), not allowed: kv_read / kv_write (another experience's store without its grant).
ts
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.

APIArgumentsReturns
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 (with retry_after_ms).
ts
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).

APIArgumentsReturns
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 samethe 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.
ts
const r = await Teleport.TeleportAsync(p, "gem-catcher", { from: "pond" });

#world

Read and change blocks, spawn, and read positions, inside your granted regions only.

APIArgumentsReturns
World.GetBlock(x, y, z)block coordinates in a region with readthe block id ("water")
World.SetBlock(x, y, z, block)a region with build; block: a block idnothing
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, rabbitnothing
player.GetPosition()the player is inside one of your regions{x, y, z, world}
  • Limits: SetBlock 200 a second; Spawn 60 a minute.
  • Errors: outside your regions (build) (or read, 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).
ts
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.

ts
const owned = await Items.GetAsync(p);

#inventory

Give, take and list your own sealed items in the player's world inventory. Full guide: Inventory.

APIArgumentsReturns
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 itemsthe ItemRefs taken
Inventory.ListAsync(player) / HeldAsync(player)ItemRef[] / the main-hand ItemRef or undefined
Inventory.ItemUsedevent (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_min 1-600 (default 120), max_count 1-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.
ts
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.

APIArgumentsReturns
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, duplicate or frozen. Days are UTC days. The same key never 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.
ts
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.

APIArgumentsReturns
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 / PlayerLeftevents (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}. id comes from the world's catalogue (0x script capabilities lists them, for example lago-pond in earth); rights are some of read (events, positions), build (SetBlock), spawn (default read); why is up to 200 characters for the reviewer.
  • Bounds: granted regions bound world, fishing, environment and Ui.Particles, and filter world events.
  • Errors: region <id> is not granted to this experience.
ts
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.

APIArgumentsReturns
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 of names: also /<name> when no other plugin or package holds it).
  • Limits: a player runs at most 5 commands a second. help and fund are 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.
ts
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.

APIGrant kindNotes
Ui.ActionBar(player, text)actionbar120 characters
Ui.Title(player, title, subtitle?)title1 a second per player
Ui.Sound(player, key, volume?, pitch?)soundkey from your sounds
Ui.Particles(kind, at, count)particleskind from your particles, inside your regions, count at most 64, 20 calls a second
Ui.Sidebar(player, title, lines)sidebarup to 12 lines; [] removes it
Ui.Panel(player, panel) / Ui.ShowAsync(player, panel) / Ui.ClosePanel(player)panelresolves 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?)toastinfo, success, warn, error
Ui.Hud(player, hud | null)hudtitle, up to 6 lines, a 0..1 progress bar
  • Parameters: kinds: some of actionbar, 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>.
ts
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.

APIArgumentsNotes
Fishing.Cast / Bite / Reelevents (hook); Reel: (hook, hadBite)hook has Player, Position, Rod, Depth?, ReactionMs? (Reel)
hook.SetWait(minTicks, maxTicks)whole ticks, 1 ≤ min ≤ max ≤ 6000Cast 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.
ts
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.

APIArgumentsReturns
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.
ts
const c = await Environment.GetAsync(hook.Position);
if (c.waterTempC < 12) Ui.ActionBar(hook.Player, "Cold water: trout bite");