@crowdedkingdoms/crowdyjs 18.10.0 → 18.12.0-dev.1

package/dist/kit/modules/minigames.js

@@ -0,0 +1,55 @@
+import { HubState } from '../mirror.js';
+/** Two-player duels of hidden throws (the `minigame` starter): {@link duel} by table. */
+export class MinigamesKit {
+    constructor(runtime, nodeType = 'minigame') {
+        this.runtime = runtime;
+        this.nodeType = nodeType;
+        this.duels = new Map();
+    }
+    duel(key) {
+        let d = this.duels.get(key);
+        if (!d) {
+            d = new Duel(this.runtime, this.nodeType, key);
+            this.duels.set(key, d);
+        }
+        return d;
+    }
+}
+/**
+ * One duel: the hub keeps each round's throws until both are in (or the round's time runs out),
+ * then reveals them; the first to win a majority of `best_of` rounds wins. The starter's game is
+ * rock, paper, scissors.
+ */
+export class Duel {
+    constructor(runtime, nodeType, key) {
+        this.runtime = runtime;
+        this.nodeType = nodeType;
+        this.key = key;
+        this.view = new HubState(runtime, nodeType, key, 'duel');
+    }
+    watch() {
+        return this.view.start();
+    }
+    unwatch() {
+        return this.view.stop();
+    }
+    /** Takes a seat; resolves with whether this seat started the first round. @throws {KitError} `full`. */
+    join() {
+        return this.runtime.call(this.nodeType, this.key, 'join', null, { action: true });
+    }
+    /** Before the duel starts. @throws {KitError} `started`. */
+    leave() {
+        return this.runtime.call(this.nodeType, this.key, 'leave', null, { action: true });
+    }
+    /**
+     * The caller's hidden throw this round; resolves with whether it completed the round.
+     * @throws {KitError} `conflict` (already in, or no round open), `bad_request` (not a hand), `not_member`.
+     */
+    throw(hand) {
+        return this.runtime.call(this.nodeType, this.key, 'throw', { hand }, { action: true });
+    }
+    /** Once it is over: play again. @throws {KitError} `conflict`, `not_member`. */
+    rematch() {
+        return this.runtime.call(this.nodeType, this.key, 'rematch', null, { action: true });
+    }
+}

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

@@ -0,0 +1,80 @@
+import { CollectionMirror } from '../mirror.js';
+import { type KitContainer } from '../protocol.js';
+import type { KitRuntime } from '../runtime.js';
+/** A pet as its owner reads it: the public view and its bond. */
+export interface KitPetView {
+    id: number;
+    species: string;
+    name: string;
+    x: number;
+    z: number;
+    /** `follow` while summoned, else `stay`. */
+    mode: string;
+    bond: number;
+}
+/** Where the area hubs are: type `npcs`, keyed by area centre chunk, in the starter pack. */
+export interface NpcsKitOptions {
+    nodeType?: string;
+    /** An area's size in chunks, for {@link NpcsKit.areaAt}. Default 8. */
+    areaSize?: number;
+}
+/**
+ * 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 declare class NpcsKit {
+    private readonly runtime;
+    private readonly areas;
+    private readonly nodeType;
+    private readonly size;
+    constructor(runtime: KitRuntime, options?: NpcsKitOptions);
+    /** The key of the area holding chunk `(chunkX, chunkZ)`. */
+    keyAt(chunkX: number, chunkZ: number): string;
+    /** The area holding chunk `(chunkX, chunkZ)`. */
+    areaAt(chunkX: number, chunkZ: number): NpcArea;
+    /** The area with key `key` (`"<x>,<z>"`, its centre chunk). */
+    area(key: string): NpcArea;
+}
+/**
+ * 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 declare class NpcArea {
+    private readonly runtime;
+    readonly nodeType: string;
+    readonly key: string;
+    /** The `area` topic: every member's public properties, by id. */
+    readonly members: CollectionMirror;
+    constructor(runtime: KitRuntime, nodeType: string, key: string);
+    /** Mirrors the area. */
+    watch(): Promise<void>;
+    unwatch(): Promise<void>;
+    mobs(): KitContainer[];
+    npcs(): KitContainer[];
+    pets(): KitContainer[];
+    /**
+     * Hits mob `mob`; resolves with its hp after the hit.
+     * @throws {KitError} `not_in_area`, `out_of_reach`, `cooldown`, `down`, `not_found`.
+     */
+    attack(mob: number): Promise<number>;
+    /** What NPC `npc` says, with its public properties. */
+    talk(npc: number): Promise<Record<string, unknown>>;
+    /**
+     * 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: string, name: string): Promise<number>;
+    rename(pet: number, name: string): Promise<boolean>;
+    /** The pet follows its owner (and its bond grows). */
+    summon(pet: number): Promise<boolean>;
+    /** The pet stays where it is. */
+    dismiss(pet: number): Promise<boolean>;
+    /** The pet is gone. */
+    release(pet: number): Promise<boolean>;
+    /** The player's pets in this area, with their bond. */
+    myPets(): Promise<KitPetView[]>;
+    private pet;
+}
+//# sourceMappingURL=npcs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"npcs.d.ts","sourceRoot":"","sources":["../../../src/kit/modules/npcs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAY,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,iEAAiE;AACjE,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,OAAO;IAMhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA8B;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAGX,OAAO,EAAE,UAAU,EACpC,OAAO,GAAE,cAAmB;IAM9B,4DAA4D;IAC5D,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAI7C,iDAAiD;IACjD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAI/C,+DAA+D;IAC/D,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAQ3B;AAED;;;;GAIG;AACH,qBAAa,OAAO;IAKhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM;IANtB,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;gBAGhB,OAAO,EAAE,UAAU,EAC3B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM;IAKtB,wBAAwB;IAClB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,IAAI,IAAI,YAAY,EAAE;IAItB,IAAI,IAAI,YAAY,EAAE;IAItB,IAAI,IAAI,YAAY,EAAE;IAItB;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIpC,uDAAuD;IACvD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAInD;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAIrD,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAInD,sDAAsD;IACtD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,iCAAiC;IACjC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAItC,uBAAuB;IACvB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAItC,uDAAuD;IACvD,MAAM,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAI/B,OAAO,CAAC,GAAG;CAIZ"}

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/racing.d.ts

@@ -0,0 +1,131 @@
+import { HubState } from '../mirror.js';
+import type { KitRuntime } from '../runtime.js';
+export interface RaceGate {
+    x: number;
+    z: number;
+    radius: number;
+}
+export interface RaceRacer {
+    player: number;
+    x: number;
+    z: number;
+    lap: number;
+    /** The gate the racer must pass next. */
+    next_gate: number;
+    best_lap_ms: number | null;
+    place: number | null;
+    total_ms: number | null;
+    did_not_finish: boolean;
+}
+/** What the `race` topic carries. */
+export interface RaceView {
+    phase: 'lobby' | 'countdown' | 'racing' | 'finished';
+    course_id: string;
+    gates: RaceGate[];
+    laps: number;
+    /** When the race starts (Unix ms), once counting down. */
+    go_at: number | null;
+    /** When the rest's time is up, once the winner is in. */
+    closes_at: number | null;
+    racers: RaceRacer[];
+}
+/** The winner's run: `[ms from the start, x, y, z, yaw]` frames to race against. */
+export interface RaceGhost {
+    player: number;
+    total_ms: number;
+    frames: Array<[number, number, number, number, number]>;
+}
+export interface BallPlayer {
+    player: number;
+    team: 'red' | 'blue';
+    x: number;
+    z: number;
+}
+export interface BallState {
+    x: number;
+    z: number;
+    vx: number;
+    vz: number;
+    holder: number | null;
+    held_since: number;
+    last_touch: number | null;
+}
+/** What the `ball` topic carries. */
+export interface BallView {
+    phase: 'lobby' | 'playing' | 'finished';
+    width: number;
+    depth: number;
+    goal_width: number;
+    ball: BallState;
+    players: BallPlayer[];
+    /** Red's, then blue's. */
+    score: [number, number];
+    ends_at: number | null;
+    winner: 'red' | 'blue' | null;
+}
+/** Races and ball games (the `racing` starter, types `race` and `ball`). */
+export declare class RacingKit {
+    private readonly runtime;
+    private readonly raceType;
+    private readonly ballType;
+    private readonly races;
+    private readonly matches;
+    constructor(runtime: KitRuntime, raceType?: string, ballType?: string);
+    /** The race with key `key`. */
+    race(key: string): Race;
+    /** The ball game with key `key`. */
+    ball(key: string): BallMatch;
+}
+/**
+ * One race: a course of gates passed in order, a countdown, laps and splits, places in finishing
+ * order, and a ghost of the winner's run. A client reports where its racer is ({@link pos}, a few
+ * times a second) and the hub times the positions its movement warden kept. `view.onEvent` hears
+ * `go`, `timing` (with its `stage`: `started`, `checkpoint`, `lap`, `finished`), `violation` and
+ * `finished`.
+ */
+export declare class Race {
+    private readonly runtime;
+    readonly nodeType: string;
+    readonly key: string;
+    readonly view: HubState<RaceView>;
+    constructor(runtime: KitRuntime, nodeType: string, key: string);
+    watch(): Promise<RaceView>;
+    unwatch(): Promise<void>;
+    /** @throws {KitError} `started`, `full`. */
+    join(): Promise<boolean>;
+    leave(): Promise<boolean>;
+    /** Starts the countdown (the first to join, or a developer). @throws {KitError} `forbidden`, `started`. */
+    start(): Promise<boolean>;
+    /** Reports where the racer is; resolves with the position the hub kept. */
+    pos(x: number, z: number): Promise<[number, number]>;
+    /** The winner's run, once there is one. */
+    ghost(): Promise<RaceGhost | null>;
+}
+/**
+ * One ball game: two teams, a ball the hub moves (passes, shots, friction, the side walls),
+ * possession (claim a loose ball near it, or take it from an opponent whose protection is over), a
+ * goal in each end wall. `view.onEvent` hears `claimed`, `passed`, `shot`, `goal`, `violation` and
+ * `finished`.
+ */
+export declare class BallMatch {
+    private readonly runtime;
+    readonly nodeType: string;
+    readonly key: string;
+    readonly view: HubState<BallView>;
+    constructor(runtime: KitRuntime, nodeType: string, key: string);
+    watch(): Promise<BallView>;
+    unwatch(): Promise<void>;
+    /** @throws {KitError} `bad_request` (red or blue), `full`, `started`. */
+    join(team: 'red' | 'blue'): Promise<boolean>;
+    /** @throws {KitError} `forbidden`, `not_ready` (each team needs a player), `started`. */
+    start(): Promise<boolean>;
+    /** Reports where the player is; resolves with the position the hub kept. */
+    pos(x: number, z: number): Promise<[number, number]>;
+    /** Claims the ball. @throws {KitError} `out_of_reach`, `cooldown` (too soon, or its holder's protection), `conflict` (a teammate has it). */
+    claim(): Promise<boolean>;
+    /** Passes to a teammate. @throws {KitError} `conflict` (not the holder), `bad_request` (not a teammate). */
+    pass(to: number | string): Promise<boolean>;
+    /** Shoots toward `(x, z)`. @throws {KitError} `conflict` (not the holder). */
+    shoot(x: number, z: number): Promise<boolean>;
+}
+//# sourceMappingURL=racing.d.ts.map

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

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