0xDocs 0x.limo

Docs / Scripting

Regions: the map areas your experience may act in

Partly live

The regions capability: granted map regions, their events, and the bounds they put on World calls.

#Regions: the map areas your experience may act in

Capability regions. Typings: Regions, Region (packages/script/v1/regions.d.ts).

ts
import { Regions } from "@x1/script";

const lake = Regions.Get("lago-di-gusana")!;
lake.PlayerEntered.Connect((p) => p.SendMessage("Welcome to the lake"));
lake.PlayerLeft.Connect((p) => { /* ... */ });
print(lake.GetPlayers().length, lake.Contains(await player.GetPosition()), lake.Water);

#Where regions come from

Operators draw regions per world in the console (Worlds › Script economy › Regions): boxes of blocks, with the water inside them. Your manifest asks for regions by id under capabilities.regions.request. The approver grants a subset, each with rights:

  • read: events and positions;
  • build: World.SetBlock;
  • spawn: World.Spawn.

Your sandbox sees only the regions it was granted, with the box as approved. A later change to the catalogue reaches you only at your next approval.

#What regions bound

  • World.GetBlock, SetBlock and Spawn work only inside a region with the matching right.
  • Player.GetPosition works only for players inside one of your regions.
  • World events (BlockBroken, BlockPlaced, Interact, the fishing hook) reach your sandbox only when they happen inside your regions.
  • Ui.Particles draws only inside your regions.

#Enter and leave

The host checks every online player's block position once a second:

  • PlayerEntered and PlayerLeft fire on the changes;
  • a sandbox that starts gets PlayerEntered for everyone already inside;
  • a player who leaves the server gets PlayerLeft.

GetPlayers() is who is inside as of that last check, so it is at most 1 s old. Boxes are inclusive and in one Minecraft world (Region.World).