@crowdedkingdoms/crowdyjs 18.10.0 → 18.11.0-dev.1

package/dist/kit/modules/npcs.js

@@ -0,0 +1,102 @@
+import { CollectionMirror } from '../mirror.js';
+import { shardKey } from '../protocol.js';
+/**
+ * The world's areas of mobs, NPCs and pets (the `npc-mobs` starter): one hub per area,
+ * keyed by its centre chunk, so a client finds the hub for where it stands
+ * ({@link areaAt}) without asking.
+ */
+export class NpcsKit {
+    constructor(runtime, options = {}) {
+        this.runtime = runtime;
+        this.areas = new Map();
+        this.nodeType = options.nodeType ?? 'npcs';
+        this.size = Math.max(1, options.areaSize ?? 8);
+    }
+    /** The key of the area holding chunk `(chunkX, chunkZ)`. */
+    keyAt(chunkX, chunkZ) {
+        return shardKey(chunkX, chunkZ, this.size);
+    }
+    /** The area holding chunk `(chunkX, chunkZ)`. */
+    areaAt(chunkX, chunkZ) {
+        return this.area(this.keyAt(chunkX, chunkZ));
+    }
+    /** The area with key `key` (`"<x>,<z>"`, its centre chunk). */
+    area(key) {
+        let a = this.areas.get(key);
+        if (!a) {
+            a = new NpcArea(this.runtime, this.nodeType, key);
+            this.areas.set(key, a);
+        }
+        return a;
+    }
+}
+/**
+ * One area: its mobs, NPCs and pets mirrored from the `area` topic ({@link members}), hits
+ * on mobs (the hub decides reach, cooldown and damage), NPC talk, and the player's pets.
+ * The hub also shows its actors through the realtime tier (`kitActorCodec`).
+ */
+export class NpcArea {
+    constructor(runtime, nodeType, key) {
+        this.runtime = runtime;
+        this.nodeType = nodeType;
+        this.key = key;
+        this.members = new CollectionMirror(runtime, nodeType, key, 'area');
+    }
+    /** Mirrors the area. */
+    async watch() {
+        await this.members.start();
+    }
+    unwatch() {
+        return this.members.stop();
+    }
+    mobs() {
+        return this.members.list('Mob');
+    }
+    npcs() {
+        return this.members.list('Npc');
+    }
+    pets() {
+        return this.members.list('Pet');
+    }
+    /**
+     * Hits mob `mob`; resolves with its hp after the hit.
+     * @throws {KitError} `not_in_area`, `out_of_reach`, `cooldown`, `down`, `not_found`.
+     */
+    attack(mob) {
+        return this.runtime.call(this.nodeType, this.key, 'attack', { mob }, { action: true });
+    }
+    /** What NPC `npc` says, with its public properties. */
+    talk(npc) {
+        return this.runtime.call(this.nodeType, this.key, 'talk', { npc });
+    }
+    /**
+     * Adopts a pet where the player stands; resolves with its id.
+     * @throws {KitError} `not_in_area`, `limit` (pets a player), `full`, `bad_request`.
+     */
+    adopt(species, name) {
+        return this.runtime.call(this.nodeType, this.key, 'adopt', { species, name }, { action: true });
+    }
+    rename(pet, name) {
+        return this.pet('rename', pet, name);
+    }
+    /** The pet follows its owner (and its bond grows). */
+    summon(pet) {
+        return this.pet('summon', pet);
+    }
+    /** The pet stays where it is. */
+    dismiss(pet) {
+        return this.pet('dismiss', pet);
+    }
+    /** The pet is gone. */
+    release(pet) {
+        return this.pet('release', pet);
+    }
+    /** The player's pets in this area, with their bond. */
+    myPets() {
+        return this.runtime.call(this.nodeType, this.key, 'pets');
+    }
+    pet(method, pet, name) {
+        const args = name === undefined ? { pet } : { pet, name };
+        return this.runtime.call(this.nodeType, this.key, method, args, { action: true });
+    }
+}

package/dist/kit/modules/presence.d.ts

@@ -0,0 +1,81 @@
+import type { UdpAPI } from '../../domains/udp.js';
+import { type EmoteEvent } from '../wire.js';
+/** A chunk, in chunk coordinates. */
+export interface KitChunk {
+    x: number;
+    y: number;
+    z: number;
+}
+/** How a spectator stays where the world's messages reach them. */
+export interface SpectateOptions {
+    /** The spectator's actor uuid (32 characters), as with `udp.sendActorUpdate`. */
+    uuid: string;
+    /** Where to watch from: a chunk inside the app's world grid. */
+    chunk: KitChunk;
+    /** How often to say so, in milliseconds. Default 2 000. */
+    intervalMs?: number;
+    /** The actor state to send (base64); empty by default, which registers without a body. */
+    state?: string;
+    /** Replication distance, 0-8. Default 8. */
+    distance?: number;
+}
+/**
+ * Spectating: the realtime tier delivers what happens near an actor only while that actor is
+ * live, so a viewer with no avatar of its own (a spectator, a kill-cam, a second screen) sends
+ * a small actor update every couple of seconds from a chunk inside the app's world grid.
+ * Outside the grid the update is refused and delivery stops.
+ */
+export declare class SpectateKit {
+    private readonly appId;
+    private readonly udp;
+    constructor(appId: string, udp: UdpAPI | undefined);
+    /** Starts the heartbeat; returns the handle that moves or stops it. */
+    observe(options: SpectateOptions): SpectatorHeartbeat;
+}
+/** A running spectator heartbeat. */
+export declare class SpectatorHeartbeat {
+    private readonly appId;
+    private readonly udp;
+    private readonly options;
+    private chunk;
+    private timer;
+    private lastError;
+    constructor(appId: string, udp: UdpAPI, options: SpectateOptions);
+    private beat;
+    /** Watches from another chunk from the next beat on (sent at once). */
+    moveTo(chunk: KitChunk): void;
+    /** The last send's error, or null when it went out. */
+    get error(): unknown;
+    stop(): void;
+}
+/** One emote to send. */
+export interface EmoteSend {
+    /** The sending actor's uuid (32 characters). */
+    uuid: string;
+    /** The chunk the sender stands in. */
+    chunk: KitChunk;
+    /** The emote's name, as the game knows it: `wave`, `cheer`, ... */
+    emote: string;
+    /** The actor it is aimed at, if any. */
+    targetUuid?: string;
+    /** Replication distance, 0-8. Default 2. */
+    distance?: number;
+}
+/**
+ * Emotes: a client event (type {@link EVENT_EMOTE}) with a JSON body `{ emote, targetUuid }`,
+ * replicated to the players near the sender. A kit convention, so players on CrowdyJS,
+ * CrowdyCPP and CrowdyPy see each other's; no hub is involved.
+ */
+export declare class EmotesKit {
+    private readonly appId;
+    private readonly udp;
+    constructor(appId: string, udp: UdpAPI | undefined);
+    /** Sends an emote; `true` when it was accepted for sending. */
+    send(emote: EmoteSend): Promise<boolean>;
+    /** An emote from a `clientEvent` notification, or null when it is another event. */
+    parse(notification: {
+        eventType: number;
+        state: string;
+    }): EmoteEvent | null;
+}
+//# sourceMappingURL=presence.d.ts.map

package/dist/kit/modules/presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../../../src/kit/modules/presence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EAAgC,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAE3E,qCAAqC;AACrC,MAAM,WAAW,QAAQ;IACvB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAID,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,KAAK,EAAE,QAAQ,CAAC;IAChB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0FAA0F;IAC1F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,qBAAa,WAAW;IAEpB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBADH,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GAAG,SAAS;IAG1C,uEAAuE;IACvE,OAAO,CAAC,OAAO,EAAE,eAAe,GAAG,kBAAkB;CAItD;AAED,qCAAqC;AACrC,qBAAa,kBAAkB;IAM3B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,KAAK,CAAwC;IACrD,OAAO,CAAC,SAAS,CAAiB;gBAGf,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,eAAe;IAO3C,OAAO,CAAC,IAAI;IAiBZ,uEAAuE;IACvE,MAAM,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAK7B,uDAAuD;IACvD,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,IAAI,IAAI,IAAI;CAIb;AAED,yBAAyB;AACzB,MAAM,WAAW,SAAS;IACxB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,KAAK,EAAE,QAAQ,CAAC;IAChB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,SAAS;IAElB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBADH,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,GAAG,SAAS;IAG1C,+DAA+D;IAC/D,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IAaxC,oFAAoF;IACpF,KAAK,CAAC,YAAY,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,UAAU,GAAG,IAAI;CAS7E"}

package/dist/kit/modules/presence.js

@@ -0,0 +1,99 @@
+import { decodeBase64, encodeBase64 } from '../../utils.js';
+import { EVENT_EMOTE, parseEmoteEvent } from '../wire.js';
+const chunkInput = (c) => ({ x: String(Math.trunc(c.x)), y: String(Math.trunc(c.y)), z: String(Math.trunc(c.z)) });
+/**
+ * Spectating: the realtime tier delivers what happens near an actor only while that actor is
+ * live, so a viewer with no avatar of its own (a spectator, a kill-cam, a second screen) sends
+ * a small actor update every couple of seconds from a chunk inside the app's world grid.
+ * Outside the grid the update is refused and delivery stops.
+ */
+export class SpectateKit {
+    constructor(appId, udp) {
+        this.appId = appId;
+        this.udp = udp;
+    }
+    /** Starts the heartbeat; returns the handle that moves or stops it. */
+    observe(options) {
+        if (!this.udp)
+            throw new Error('the kit has no udp client to spectate with');
+        return new SpectatorHeartbeat(this.appId, this.udp, options);
+    }
+}
+/** A running spectator heartbeat. */
+export class SpectatorHeartbeat {
+    constructor(appId, udp, options) {
+        this.appId = appId;
+        this.udp = udp;
+        this.options = options;
+        this.lastError = null;
+        this.chunk = options.chunk;
+        this.beat();
+        this.timer = setInterval(() => this.beat(), Math.max(250, options.intervalMs ?? 2000));
+    }
+    beat() {
+        this.udp
+            .sendActorUpdate({
+            appId: this.appId,
+            uuid: this.options.uuid,
+            chunk: chunkInput(this.chunk),
+            state: this.options.state ?? '',
+            distance: this.options.distance ?? 8,
+        })
+            .then(() => {
+            this.lastError = null;
+        })
+            .catch((e) => {
+            this.lastError = e;
+        });
+    }
+    /** Watches from another chunk from the next beat on (sent at once). */
+    moveTo(chunk) {
+        this.chunk = chunk;
+        this.beat();
+    }
+    /** The last send's error, or null when it went out. */
+    get error() {
+        return this.lastError;
+    }
+    stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+}
+/**
+ * Emotes: a client event (type {@link EVENT_EMOTE}) with a JSON body `{ emote, targetUuid }`,
+ * replicated to the players near the sender. A kit convention, so players on CrowdyJS,
+ * CrowdyCPP and CrowdyPy see each other's; no hub is involved.
+ */
+export class EmotesKit {
+    constructor(appId, udp) {
+        this.appId = appId;
+        this.udp = udp;
+    }
+    /** Sends an emote; `true` when it was accepted for sending. */
+    send(emote) {
+        if (!this.udp)
+            return Promise.reject(new Error('the kit has no udp client to send emotes with'));
+        const body = JSON.stringify({ emote: emote.emote, targetUuid: emote.targetUuid ?? null });
+        return this.udp.sendClientEvent({
+            appId: this.appId,
+            uuid: emote.uuid,
+            chunk: chunkInput(emote.chunk),
+            eventType: EVENT_EMOTE,
+            state: encodeBase64(new TextEncoder().encode(body)),
+            distance: emote.distance ?? 2,
+        });
+    }
+    /** An emote from a `clientEvent` notification, or null when it is another event. */
+    parse(notification) {
+        if (notification.eventType !== EVENT_EMOTE)
+            return null;
+        const state = decodeBase64(notification.state);
+        const bytes = new Uint8Array(2 + state.length);
+        bytes[0] = EVENT_EMOTE & 0xff;
+        bytes[1] = EVENT_EMOTE >> 8;
+        bytes.set(state, 2);
+        return parseEmoteEvent(bytes);
+    }
+}

package/dist/kit/modules/sessions.d.ts

@@ -0,0 +1,91 @@
+import { HubState } from '../mirror.js';
+import type { KitRuntime } from '../runtime.js';
+export type SessionPhase = 'lobby' | 'playing' | 'finished';
+export interface SessionConfig {
+    min_players: number;
+    max_players: number;
+    turn_ms: number;
+    target_score: number;
+    max_rounds: number;
+    /** A lobby nobody joins closes after this long. */
+    lobby_idle_ms: number;
+}
+export interface SessionMove {
+    player: number;
+    round: number;
+    /** null when the player ran out of time. */
+    points: number | null;
+}
+/** A session as everyone sees it: what `state` answers and the `session` topic carries. */
+export interface SessionState {
+    config: SessionConfig;
+    phase: SessionPhase;
+    /** Only these players may join, when set (a matchmaker's reservation). */
+    reserved: number[];
+    players: number[];
+    ready: number[];
+    connected: number[];
+    host: number | null;
+    turn: number;
+    round: number;
+    /** Scores by player id (the keys are the ids as text). */
+    scores: Record<string, number>;
+    winner: number | null;
+    moves: SessionMove[];
+}
+/** Where the session hubs are: type `session`, one per session key, in the starter pack. */
+export interface SessionsKitOptions {
+    nodeType?: string;
+}
+/** Game sessions (the `session` starter): {@link open} one by its key. */
+export declare class SessionsKit {
+    private readonly runtime;
+    private readonly sessions;
+    private readonly nodeType;
+    constructor(runtime: KitRuntime, options?: SessionsKitOptions);
+    /** The session with key `key` (a matchmaker's `matched.session`, or one a game names). */
+    open(key: string): GameSessionHandle;
+}
+/** Whose turn it is in `state`, while it plays. */
+export declare function sessionTurn(state: SessionState | undefined): number | null;
+/**
+ * One session from lobby to result: join, ready up, the host starts, players act in turn
+ * under a time limit, and the hub keeps the score and names the winner. {@link state} mirrors
+ * the `session` topic; every change is a snapshot on it.
+ */
+export declare class GameSessionHandle {
+    private readonly runtime;
+    readonly nodeType: string;
+    readonly key: string;
+    /** The `session` topic: the whole session. {@link watch} starts it. */
+    readonly state: HubState<SessionState>;
+    constructor(runtime: KitRuntime, nodeType: string, key: string);
+    /** Mirrors the session; resolves with it. */
+    watch(): Promise<SessionState>;
+    unwatch(): Promise<void>;
+    /** Whose turn it is, as the mirror last saw it. */
+    currentTurn(): number | null;
+    /** Whether it is the player's turn, as the mirror last saw it. */
+    isMyTurn(): Promise<boolean>;
+    /** @throws {KitError} `started`, `reserved`, `full`. */
+    join(): Promise<boolean>;
+    leave(): Promise<boolean>;
+    /** @throws {KitError} `not_member` (join the lobby first). */
+    ready(ready?: boolean): Promise<boolean>;
+    /**
+     * Starts the session (the host, once everyone is ready).
+     * @throws {KitError} `forbidden` (not the host), `not_ready`, `too_few_players`, `started`.
+     */
+    startGame(): Promise<boolean>;
+    /**
+     * Plays the player's move (the starter's is `{ points }`, 0 to 3); resolves with whether play
+     * goes on. Sent with an action id: a move resent after a lost reply is played once.
+     * @throws {KitError} `not_your_turn`, `invalid_move` (the game's rule).
+     */
+    act<A extends object = {
+        points: number;
+    }>(action: A): Promise<boolean>;
+    /** Changes the config: the host in the lobby, or a developer. */
+    configure(config: Partial<SessionConfig>): Promise<boolean>;
+}
+//# sourceMappingURL=sessions.d.ts.map

package/dist/kit/modules/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../../src/kit/modules/sessions.ts"],"names":[],"mappings":"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"}

package/dist/kit/modules/sessions.js

@@ -0,0 +1,84 @@
+import { HubState } from '../mirror.js';
+/** Game sessions (the `session` starter): {@link open} one by its key. */
+export class SessionsKit {
+    constructor(runtime, options = {}) {
+        this.runtime = runtime;
+        this.sessions = new Map();
+        this.nodeType = options.nodeType ?? 'session';
+    }
+    /** The session with key `key` (a matchmaker's `matched.session`, or one a game names). */
+    open(key) {
+        let s = this.sessions.get(key);
+        if (!s) {
+            s = new GameSessionHandle(this.runtime, this.nodeType, key);
+            this.sessions.set(key, s);
+        }
+        return s;
+    }
+}
+/** Whose turn it is in `state`, while it plays. */
+export function sessionTurn(state) {
+    if (!state || state.phase !== 'playing')
+        return null;
+    return state.players[state.turn] ?? null;
+}
+/**
+ * One session from lobby to result: join, ready up, the host starts, players act in turn
+ * under a time limit, and the hub keeps the score and names the winner. {@link state} mirrors
+ * the `session` topic; every change is a snapshot on it.
+ */
+export class GameSessionHandle {
+    constructor(runtime, nodeType, key) {
+        this.runtime = runtime;
+        this.nodeType = nodeType;
+        this.key = key;
+        this.state = new HubState(runtime, nodeType, key, 'session');
+    }
+    /** Mirrors the session; resolves with it. */
+    watch() {
+        return this.state.start();
+    }
+    unwatch() {
+        return this.state.stop();
+    }
+    /** Whose turn it is, as the mirror last saw it. */
+    currentTurn() {
+        return sessionTurn(this.state.get());
+    }
+    /** Whether it is the player's turn, as the mirror last saw it. */
+    async isMyTurn() {
+        const me = await this.runtime.playerId();
+        const turn = this.currentTurn();
+        return me !== null && turn !== null && String(turn) === me;
+    }
+    /** @throws {KitError} `started`, `reserved`, `full`. */
+    join() {
+        return this.runtime.call(this.nodeType, this.key, 'join', null, { action: true });
+    }
+    leave() {
+        return this.runtime.call(this.nodeType, this.key, 'leave', null, { action: true });
+    }
+    /** @throws {KitError} `not_member` (join the lobby first). */
+    ready(ready = true) {
+        return this.runtime.call(this.nodeType, this.key, 'ready', { ready }, { action: true });
+    }
+    /**
+     * Starts the session (the host, once everyone is ready).
+     * @throws {KitError} `forbidden` (not the host), `not_ready`, `too_few_players`, `started`.
+     */
+    startGame() {
+        return this.runtime.call(this.nodeType, this.key, 'start', null, { action: true });
+    }
+    /**
+     * Plays the player's move (the starter's is `{ points }`, 0 to 3); resolves with whether play
+     * goes on. Sent with an action id: a move resent after a lost reply is played once.
+     * @throws {KitError} `not_your_turn`, `invalid_move` (the game's rule).
+     */
+    act(action) {
+        return this.runtime.call(this.nodeType, this.key, 'act', action, { action: true });
+    }
+    /** Changes the config: the host in the lobby, or a developer. */
+    configure(config) {
+        return this.runtime.call(this.nodeType, this.key, 'configure', config, { action: true });
+    }
+}

package/dist/kit/modules/world.d.ts

@@ -0,0 +1,69 @@
+import { CollectionMirror, HubState } from '../mirror.js';
+import type { KitRuntime } from '../runtime.js';
+/** What the `world` topic carries: the world's conditions now. */
+export interface WorldConditions {
+    /** 0 at midnight, 0.5 at noon. */
+    time_of_day: number;
+    night: boolean;
+    /** `clear`, `rain`, `storm` or `fog` in the starter. */
+    weather: string;
+    /** The active liveops events' modifiers; where events overlap they multiply. */
+    modifiers: Record<string, number>;
+}
+/** A resource node, as `state` lists it. */
+export interface WorldResourceNode {
+    id: number;
+    amount: number;
+    /** When it grows back (Unix ms), while it is empty. */
+    regrow_at: number | null;
+}
+/** A liveops event: between `start_ms` and `end_ms` its modifiers apply. */
+export interface WorldLiveopsEvent {
+    name: string;
+    start_ms: number;
+    end_ms: number;
+    modifiers?: Record<string, number>;
+}
+/** What the world hub's `state` answers. */
+export interface WorldView {
+    conditions: WorldConditions;
+    /** Game time since the world began, advanced only while it runs. */
+    clock_ms: number;
+    nodes: WorldResourceNode[];
+    events: WorldLiveopsEvent[];
+    /** Players in the app. */
+    online: number;
+}
+/** Where the world hub is: the root hub, `world` with an empty key, in the starter pack. */
+export interface WorldKitOptions {
+    nodeType?: string;
+    key?: string;
+}
+/**
+ * The root world hub (the `world-tick` starter): its clock, weather and liveops modifiers as a
+ * mirrored {@link conditions} topic, its resource nodes as a mirrored {@link nodes} collection,
+ * harvesting, and for developers the liveops schedule. The root hub takes 50 calls a second for
+ * the whole app, so read it from the mirrors (`conditions.start()`), not by polling `state`.
+ */
+export declare class WorldKit {
+    private readonly runtime;
+    /** The `world` topic: conditions now. `start()` it to keep it current. */
+    readonly conditions: HubState<WorldConditions>;
+    /** The `nodes` topic: each resource node's `amount` and `regrow_at`, by node id. */
+    readonly nodes: CollectionMirror;
+    private readonly nodeType;
+    private readonly key;
+    constructor(runtime: KitRuntime, options?: WorldKitOptions);
+    /** Everything the world shows: conditions, clock, nodes, events, players online. */
+    state(): Promise<WorldView>;
+    /**
+     * Takes one from resource node `node`; resolves with what it holds now.
+     * @throws {KitError} `cooldown`, `empty` (it grows back), `not_found`.
+     */
+    harvest(node: number): Promise<number>;
+    /** Schedules (or replaces) a liveops event. Developers only (a developer kit). */
+    schedule(event: WorldLiveopsEvent): Promise<boolean>;
+    /** Cancels a liveops event; resolves with whether there was one. Developers only. */
+    cancel(name: string): Promise<boolean>;
+}
+//# sourceMappingURL=world.d.ts.map

package/dist/kit/modules/world.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world.d.ts","sourceRoot":"","sources":["../../../src/kit/modules/world.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,kEAAkE;AAClE,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED,4CAA4C;AAC5C,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,eAAe,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,4FAA4F;AAC5F,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;GAKG;AACH,qBAAa,QAAQ;IASjB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAR1B,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;IAC/C,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;gBAGV,OAAO,EAAE,UAAU,EACpC,OAAO,GAAE,eAAoB;IAQ/B,oFAAoF;IACpF,KAAK,IAAI,OAAO,CAAC,SAAS,CAAC;IAI3B;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAItC,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IAIpD,qFAAqF;IACrF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAGvC"}

package/dist/kit/modules/world.js

@@ -0,0 +1,35 @@
+import { CollectionMirror, HubState } from '../mirror.js';
+/**
+ * The root world hub (the `world-tick` starter): its clock, weather and liveops modifiers as a
+ * mirrored {@link conditions} topic, its resource nodes as a mirrored {@link nodes} collection,
+ * harvesting, and for developers the liveops schedule. The root hub takes 50 calls a second for
+ * the whole app, so read it from the mirrors (`conditions.start()`), not by polling `state`.
+ */
+export class WorldKit {
+    constructor(runtime, options = {}) {
+        this.runtime = runtime;
+        this.nodeType = options.nodeType ?? 'world';
+        this.key = options.key ?? '';
+        this.conditions = new HubState(runtime, this.nodeType, this.key, 'world');
+        this.nodes = new CollectionMirror(runtime, this.nodeType, this.key, 'nodes');
+    }
+    /** Everything the world shows: conditions, clock, nodes, events, players online. */
+    state() {
+        return this.runtime.call(this.nodeType, this.key, 'state');
+    }
+    /**
+     * Takes one from resource node `node`; resolves with what it holds now.
+     * @throws {KitError} `cooldown`, `empty` (it grows back), `not_found`.
+     */
+    harvest(node) {
+        return this.runtime.call(this.nodeType, this.key, 'harvest', { node }, { action: true });
+    }
+    /** Schedules (or replaces) a liveops event. Developers only (a developer kit). */
+    schedule(event) {
+        return this.runtime.call(this.nodeType, this.key, 'schedule', event, { action: true });
+    }
+    /** Cancels a liveops event; resolves with whether there was one. Developers only. */
+    cancel(name) {
+        return this.runtime.call(this.nodeType, this.key, 'cancel', { name }, { action: true });
+    }
+}