@crowdedkingdoms/crowdyjs 18.10.0 → 18.12.0-dev.1

package/dist/kit/mirror.d.ts

@@ -0,0 +1,111 @@
+import { type KitChanged, type KitContainer, type KitDelta, type KitHeader } from './protocol.js';
+import type { KitRuntime } from './runtime.js';
+import type { KitStore } from './store.js';
+/**
+ * A hub topic mirrored on the client: it subscribes, asks the hub for a snapshot, then applies
+ * what arrives after the snapshot's `seq`. It asks again when the publishing instance's
+ * `epoch` changes, when a delta topic skips a `seq`, and after the connection reconnects.
+ */
+export declare abstract class TopicMirror<S> implements KitStore<S | undefined> {
+    protected readonly runtime: KitRuntime;
+    readonly nodeType: string;
+    readonly key: string;
+    readonly topic: string;
+    private state;
+    private epoch;
+    private seq;
+    private buffer;
+    private syncing;
+    private stopSub;
+    private offReconnect;
+    private readonly listeners;
+    private readonly eventListeners;
+    private readonly changedListeners;
+    private watching;
+    constructor(runtime: KitRuntime, nodeType: string, key: string, topic: string);
+    /** The state a snapshot's body stands for. */
+    protected abstract fromSnapshot(body: Record<string, unknown>): S;
+    /** The state after one delta, or null when a delta is not this topic's (resync). */
+    protected abstract applyDelta(state: S, delta: KitDelta): S | null;
+    /** Whether a skipped `seq` loses state (a delta topic) or not (snapshot topics). */
+    protected abstract readonly gapsLoseState: boolean;
+    /** Subscribes and takes the first snapshot; resolves with the state. Idempotent. */
+    start(): Promise<S>;
+    /** Stops the subscription; the last state stays readable. */
+    stop(): Promise<void>;
+    /** Takes a fresh snapshot (shared by concurrent callers). */
+    resync(): Promise<S>;
+    get(): S | undefined;
+    subscribe(listener: (value: S | undefined) => void): () => void;
+    /** `event` messages on the topic. */
+    onEvent(listener: (body: Record<string, unknown>, header: KitHeader) => void): () => void;
+    /** `changed` messages on the topic: someone's private state to read again. */
+    onChanged(listener: (changed: KitChanged, header: KitHeader) => void): () => void;
+    /** The epoch and seq the mirror is at; `-1` before its first snapshot. */
+    get position(): {
+        epoch: number;
+        seq: number;
+    };
+    private emit;
+    private onPush;
+    private apply;
+}
+/** A topic whose messages are its hub's whole public state (`snapshot` messages). */
+export declare class HubState<T = Record<string, unknown>> extends TopicMirror<T> {
+    protected readonly gapsLoseState = false;
+    protected fromSnapshot(body: Record<string, unknown>): T;
+    protected applyDelta(): T | null;
+}
+/** A collection's members by id: what a model topic's snapshot and deltas describe. */
+export type KitCollection = ReadonlyMap<number, KitContainer>;
+/**
+ * A topic carrying a collection (`delta` per member; the snapshot's `containers`): the
+ * starters' model topics, such as an area's mobs, NPCs and pets.
+ */
+export declare class CollectionMirror extends TopicMirror<KitCollection> {
+    protected readonly gapsLoseState = true;
+    protected fromSnapshot(body: Record<string, unknown>): KitCollection;
+    protected applyDelta(state: KitCollection, d: KitDelta): KitCollection | null;
+    /** The members, oldest first, of one type or all. */
+    list(typeName?: string): KitContainer[];
+    /** One member by id. */
+    member(id: number): KitContainer | undefined;
+}
+/** How a {@link PrivateState} reads its value and hears that it changed. */
+export interface PrivateStateSource<T> {
+    nodeType: string;
+    key: string;
+    /** The topic whose `changed` messages name this player. */
+    topic: string;
+    /** The `what` (or whats) that concern this value. */
+    what: string | readonly string[];
+    /** Reads the value with a call the hub answers for its caller alone. */
+    read: () => Promise<T>;
+}
+/**
+ * State only its player may read (a hand of cards, an inventory, a pet's bond): read with a
+ * caller-scoped call, read again when the hub's `changed` message names this player, and after
+ * a reconnect. Nothing private is ever on a topic.
+ */
+export declare class PrivateState<T> implements KitStore<T | undefined> {
+    private readonly runtime;
+    private readonly source;
+    private value;
+    private reading;
+    private again;
+    private stopSub;
+    private offReconnect;
+    private readonly listeners;
+    private readonly whats;
+    private watching;
+    constructor(runtime: KitRuntime, source: PrivateStateSource<T>);
+    /** Subscribes and reads the first value. Idempotent. */
+    start(): Promise<T>;
+    stop(): Promise<void>;
+    /** Reads the value again (one read at a time; a request during one runs after it). */
+    refresh(): Promise<T>;
+    get(): T | undefined;
+    subscribe(listener: (value: T | undefined) => void): () => void;
+    private onPush;
+}
+//# sourceMappingURL=mirror.d.ts.map

package/dist/kit/mirror.d.ts.map

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

package/dist/kit/mirror.js

@@ -0,0 +1,295 @@
+import { KIT_SNAPSHOT_METHOD, KitError, splitKitMessage, } from './protocol.js';
+/**
+ * A hub topic mirrored on the client: it subscribes, asks the hub for a snapshot, then applies
+ * what arrives after the snapshot's `seq`. It asks again when the publishing instance's
+ * `epoch` changes, when a delta topic skips a `seq`, and after the connection reconnects.
+ */
+export class TopicMirror {
+    constructor(runtime, nodeType, key, topic) {
+        this.runtime = runtime;
+        this.nodeType = nodeType;
+        this.key = key;
+        this.topic = topic;
+        this.epoch = -1;
+        this.seq = 0;
+        this.buffer = null;
+        this.syncing = null;
+        this.stopSub = null;
+        this.offReconnect = null;
+        this.listeners = new Set();
+        this.eventListeners = new Set();
+        this.changedListeners = new Set();
+        this.watching = null;
+    }
+    /** Subscribes and takes the first snapshot; resolves with the state. Idempotent. */
+    start() {
+        if (!this.watching) {
+            this.watching = (async () => {
+                this.offReconnect = this.runtime.onReconnect(() => void this.resync().catch(() => undefined));
+                this.stopSub = await this.runtime.subscribe(this.nodeType, this.key, this.topic, (p) => this.onPush(p));
+                return this.resync();
+            })().catch((e) => {
+                this.watching = null;
+                throw e;
+            });
+        }
+        return this.watching;
+    }
+    /** Stops the subscription; the last state stays readable. */
+    async stop() {
+        this.offReconnect?.();
+        this.offReconnect = null;
+        const stop = this.stopSub;
+        this.stopSub = null;
+        this.watching = null;
+        await stop?.();
+    }
+    /** Takes a fresh snapshot (shared by concurrent callers). */
+    resync() {
+        if (!this.syncing) {
+            this.buffer = [];
+            this.syncing = (async () => {
+                try {
+                    const reply = await this.runtime.call(this.nodeType, this.key, KIT_SNAPSHOT_METHOD, { topic: this.topic });
+                    const msg = splitKitMessage(reply);
+                    if (!msg)
+                        throw new KitError('bad_request', `${this.nodeType} answered snapshot with something other than a kit message`);
+                    this.epoch = msg.header.epoch;
+                    this.seq = msg.header.seq;
+                    this.state = this.fromSnapshot(msg.body);
+                    const pending = this.buffer ?? [];
+                    this.buffer = null;
+                    this.syncing = null;
+                    for (const m of pending.sort((a, b) => a.header.seq - b.header.seq))
+                        this.apply(m);
+                    this.emit();
+                    return this.state;
+                }
+                catch (e) {
+                    this.buffer = null;
+                    this.syncing = null;
+                    throw e;
+                }
+            })();
+        }
+        return this.syncing;
+    }
+    get() {
+        return this.state;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** `event` messages on the topic. */
+    onEvent(listener) {
+        this.eventListeners.add(listener);
+        return () => this.eventListeners.delete(listener);
+    }
+    /** `changed` messages on the topic: someone's private state to read again. */
+    onChanged(listener) {
+        this.changedListeners.add(listener);
+        return () => this.changedListeners.delete(listener);
+    }
+    /** The epoch and seq the mirror is at; `-1` before its first snapshot. */
+    get position() {
+        return { epoch: this.epoch, seq: this.seq };
+    }
+    emit() {
+        for (const l of [...this.listeners]) {
+            try {
+                l(this.state);
+            }
+            catch {
+                /* a listener's exception is its own */
+            }
+        }
+    }
+    onPush(push) {
+        const msg = splitKitMessage(push.value);
+        if (!msg)
+            return;
+        if (this.buffer) {
+            this.buffer.push(msg);
+            return;
+        }
+        this.apply(msg);
+    }
+    apply({ header, body }) {
+        if (header.epoch !== this.epoch) {
+            if (header.kind === 'snapshot') {
+                this.epoch = header.epoch;
+                this.seq = header.seq;
+                this.state = this.fromSnapshot(body);
+                this.emit();
+            }
+            else {
+                void this.resync().catch(() => undefined);
+            }
+            return;
+        }
+        if (header.seq <= this.seq)
+            return;
+        const gap = header.seq !== this.seq + 1;
+        this.seq = header.seq;
+        switch (header.kind) {
+            case 'snapshot':
+                this.state = this.fromSnapshot(body);
+                this.emit();
+                return;
+            case 'delta': {
+                const next = gap || this.state === undefined ? null : this.applyDelta(this.state, body);
+                if (next === null) {
+                    void this.resync().catch(() => undefined);
+                    return;
+                }
+                this.state = next;
+                this.emit();
+                return;
+            }
+            case 'changed':
+                for (const l of [...this.changedListeners])
+                    l(body, header);
+                break;
+            case 'event':
+                for (const l of [...this.eventListeners])
+                    l(body, header);
+                break;
+        }
+        if (gap && this.gapsLoseState)
+            void this.resync().catch(() => undefined);
+    }
+}
+/** A topic whose messages are its hub's whole public state (`snapshot` messages). */
+export class HubState extends TopicMirror {
+    constructor() {
+        super(...arguments);
+        this.gapsLoseState = false;
+    }
+    fromSnapshot(body) {
+        return body;
+    }
+    applyDelta() {
+        return null;
+    }
+}
+/**
+ * A topic carrying a collection (`delta` per member; the snapshot's `containers`): the
+ * starters' model topics, such as an area's mobs, NPCs and pets.
+ */
+export class CollectionMirror extends TopicMirror {
+    constructor() {
+        super(...arguments);
+        this.gapsLoseState = true;
+    }
+    fromSnapshot(body) {
+        const out = new Map();
+        for (const c of body.containers ?? []) {
+            if (!c.removed)
+                out.set(c.id, { id: c.id, type_name: c.type_name ?? '', props: c.props ?? {} });
+        }
+        return out;
+    }
+    applyDelta(state, d) {
+        if (typeof d.id !== 'number')
+            return null;
+        const next = new Map(state);
+        if (d.removed) {
+            next.delete(d.id);
+        }
+        else {
+            next.set(d.id, { id: d.id, type_name: d.type_name ?? state.get(d.id)?.type_name ?? '', props: d.props ?? {} });
+        }
+        return next;
+    }
+    /** The members, oldest first, of one type or all. */
+    list(typeName) {
+        const all = [...(this.get()?.values() ?? [])].sort((a, b) => a.id - b.id);
+        return typeName ? all.filter((c) => c.type_name === typeName) : all;
+    }
+    /** One member by id. */
+    member(id) {
+        return this.get()?.get(id);
+    }
+}
+/**
+ * State only its player may read (a hand of cards, an inventory, a pet's bond): read with a
+ * caller-scoped call, read again when the hub's `changed` message names this player, and after
+ * a reconnect. Nothing private is ever on a topic.
+ */
+export class PrivateState {
+    constructor(runtime, source) {
+        this.runtime = runtime;
+        this.source = source;
+        this.reading = null;
+        this.again = false;
+        this.stopSub = null;
+        this.offReconnect = null;
+        this.listeners = new Set();
+        this.watching = null;
+        this.whats = new Set(typeof source.what === 'string' ? [source.what] : source.what);
+    }
+    /** Subscribes and reads the first value. Idempotent. */
+    start() {
+        if (!this.watching) {
+            this.watching = (async () => {
+                this.offReconnect = this.runtime.onReconnect(() => void this.refresh().catch(() => undefined));
+                this.stopSub = await this.runtime.subscribe(this.source.nodeType, this.source.key, this.source.topic, (p) => this.onPush(p));
+                return this.refresh();
+            })().catch((e) => {
+                this.watching = null;
+                throw e;
+            });
+        }
+        return this.watching;
+    }
+    async stop() {
+        this.offReconnect?.();
+        this.offReconnect = null;
+        const stop = this.stopSub;
+        this.stopSub = null;
+        this.watching = null;
+        await stop?.();
+    }
+    /** Reads the value again (one read at a time; a request during one runs after it). */
+    refresh() {
+        if (this.reading) {
+            this.again = true;
+            return this.reading;
+        }
+        this.reading = (async () => {
+            try {
+                let v;
+                do {
+                    this.again = false;
+                    v = await this.source.read();
+                } while (this.again);
+                this.value = v;
+                for (const l of [...this.listeners])
+                    l(v);
+                return v;
+            }
+            finally {
+                this.reading = null;
+            }
+        })();
+        return this.reading;
+    }
+    get() {
+        return this.value;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    onPush(push) {
+        const msg = splitKitMessage(push.value);
+        if (!msg || msg.header.kind !== 'changed' || !this.whats.has(msg.body.what))
+            return;
+        const who = Array.isArray(msg.body.who) ? msg.body.who.map(String) : [];
+        void this.runtime.playerId().then((me) => {
+            if (me === null || who.includes(me))
+                void this.refresh().catch(() => undefined);
+        });
+    }
+}

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

@@ -0,0 +1,87 @@
+import { HubState } from '../mirror.js';
+import type { KitRuntime } from '../runtime.js';
+export interface ArenaFighter {
+    player: number;
+    class: string;
+    x: number;
+    z: number;
+    hp: number;
+    max_hp: number;
+    /** What casts spend; it regenerates. */
+    resource: number;
+    statuses: string[];
+    kills: number;
+    deaths: number;
+    /** Down, until the respawn. */
+    down: boolean;
+}
+export interface ArenaShot {
+    ability: string;
+    caster: number;
+    x: number;
+    z: number;
+}
+export interface ArenaBlast {
+    ability: string;
+    caster: number;
+    x: number;
+    z: number;
+    radius: number;
+    /** When it goes off (Unix ms). */
+    at: number;
+}
+/** What the `arena` topic's snapshots carry. */
+export interface ArenaView {
+    phase: 'waiting' | 'running' | 'finished';
+    width: number;
+    depth: number;
+    fighters: ArenaFighter[];
+    projectiles: ArenaShot[];
+    areas: ArenaBlast[];
+    kill_target: number;
+    ends_at: number | null;
+    winner: number | null;
+}
+/** Real-time arenas (the `arena` starter): {@link arena} by key. */
+export declare class ArenasKit {
+    private readonly runtime;
+    private readonly nodeType;
+    private readonly arenas;
+    constructor(runtime: KitRuntime, nodeType?: string);
+    arena(key: string): ArenaMatch;
+}
+/**
+ * One arena: players fight with their class's abilities and the hub referees every hit. A
+ * client reports where its player is ({@link move}, a few times a second) and the hub keeps what
+ * the class's speed allows; casts are checked for cooldown, resource and range, and land as the hub
+ * decides. {@link view} mirrors the `arena` topic (up to five snapshots a second); its `event`
+ * messages (`type`: `cast`, `impact`, `kill`, `respawn`, `violation`, `removed`, `finished`) come
+ * through `view.onEvent`.
+ */
+export declare class ArenaMatch {
+    private readonly runtime;
+    readonly nodeType: string;
+    readonly key: string;
+    readonly view: HubState<ArenaView>;
+    constructor(runtime: KitRuntime, nodeType: string, key: string);
+    watch(): Promise<ArenaView>;
+    unwatch(): Promise<void>;
+    /** Joins as `heroClass` (the starter's are `warrior` and `mage`). @throws {KitError} `bad_request`, `full`, `started`. */
+    join(heroClass: string): Promise<boolean>;
+    leave(): Promise<boolean>;
+    /** The first to join, or a developer. @throws {KitError} `forbidden`, `not_ready` (one fighter), `started`. */
+    start(): Promise<boolean>;
+    /**
+     * Reports where the player is; resolves with the position the hub kept (a move too fast is cut
+     * short, a jump refused). Not sent with an action id: the next report replaces it.
+     * @throws {KitError} `forbidden` (removed for movement the warden refused), `conflict` (down).
+     */
+    move(x: number, z: number): Promise<[number, number]>;
+    /**
+     * Casts `ability` aimed at `(x, z)`; resolves with whether a hit-scan strike hit someone at once
+     * (a projectile or an area lands later, as an `impact` event).
+     * @throws {KitError} `cooldown`, `insufficient` (resource), `out_of_reach`, `not_found` (not the class's).
+     */
+    cast(ability: string, x: number, z: number): Promise<boolean>;
+}
+//# sourceMappingURL=arenas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"arenas.d.ts","sourceRoot":"","sources":["../../../src/kit/modules/arenas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,gDAAgD;AAChD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,UAAU,CAAC;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,WAAW,EAAE,SAAS,EAAE,CAAC;IACzB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,oEAAoE;AACpE,qBAAa,SAAS;IAIlB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJ3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;gBAGrC,OAAO,EAAE,UAAU,EACnB,QAAQ,SAAU;IAGrC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU;CAQ/B;AAED;;;;;;;GAOG;AACH,qBAAa,UAAU;IAInB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM;IALtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,CAAC;gBAGhB,OAAO,EAAE,UAAU,EAC3B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM;IAKtB,KAAK,IAAI,OAAO,CAAC,SAAS,CAAC;IAI3B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,0HAA0H;IAC1H,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIzC,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;IAIzB,+GAA+G;IAC/G,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;IAIzB;;;;OAIG;IACH,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAIrD;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAG9D"}

package/dist/kit/modules/arenas.js

@@ -0,0 +1,66 @@
+import { HubState } from '../mirror.js';
+/** Real-time arenas (the `arena` starter): {@link arena} by key. */
+export class ArenasKit {
+    constructor(runtime, nodeType = 'arena') {
+        this.runtime = runtime;
+        this.nodeType = nodeType;
+        this.arenas = new Map();
+    }
+    arena(key) {
+        let a = this.arenas.get(key);
+        if (!a) {
+            a = new ArenaMatch(this.runtime, this.nodeType, key);
+            this.arenas.set(key, a);
+        }
+        return a;
+    }
+}
+/**
+ * One arena: players fight with their class's abilities and the hub referees every hit. A
+ * client reports where its player is ({@link move}, a few times a second) and the hub keeps what
+ * the class's speed allows; casts are checked for cooldown, resource and range, and land as the hub
+ * decides. {@link view} mirrors the `arena` topic (up to five snapshots a second); its `event`
+ * messages (`type`: `cast`, `impact`, `kill`, `respawn`, `violation`, `removed`, `finished`) come
+ * through `view.onEvent`.
+ */
+export class ArenaMatch {
+    constructor(runtime, nodeType, key) {
+        this.runtime = runtime;
+        this.nodeType = nodeType;
+        this.key = key;
+        this.view = new HubState(runtime, nodeType, key, 'arena');
+    }
+    watch() {
+        return this.view.start();
+    }
+    unwatch() {
+        return this.view.stop();
+    }
+    /** Joins as `heroClass` (the starter's are `warrior` and `mage`). @throws {KitError} `bad_request`, `full`, `started`. */
+    join(heroClass) {
+        return this.runtime.call(this.nodeType, this.key, 'join', { class: heroClass }, { action: true });
+    }
+    leave() {
+        return this.runtime.call(this.nodeType, this.key, 'leave', null, { action: true });
+    }
+    /** The first to join, or a developer. @throws {KitError} `forbidden`, `not_ready` (one fighter), `started`. */
+    start() {
+        return this.runtime.call(this.nodeType, this.key, 'start', null, { action: true });
+    }
+    /**
+     * Reports where the player is; resolves with the position the hub kept (a move too fast is cut
+     * short, a jump refused). Not sent with an action id: the next report replaces it.
+     * @throws {KitError} `forbidden` (removed for movement the warden refused), `conflict` (down).
+     */
+    move(x, z) {
+        return this.runtime.call(this.nodeType, this.key, 'move', { x, z });
+    }
+    /**
+     * Casts `ability` aimed at `(x, z)`; resolves with whether a hit-scan strike hit someone at once
+     * (a projectile or an area lands later, as an `impact` event).
+     * @throws {KitError} `cooldown`, `insufficient` (resource), `out_of_reach`, `not_found` (not the class's).
+     */
+    cast(ability, x, z) {
+        return this.runtime.call(this.nodeType, this.key, 'cast', { ability, x, z }, { action: true });
+    }
+}

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

@@ -0,0 +1,75 @@
+import { HubState } from '../mirror.js';
+import type { KitRuntime } from '../runtime.js';
+export interface EncounterEnemy {
+    id: number;
+    kind: string;
+    x: number;
+    z: number;
+    hp: number;
+    max_hp: number;
+    boss: boolean;
+    /** Ticks until its next step. */
+    wait: number;
+}
+export interface EncounterTower {
+    x: number;
+    z: number;
+    owner: number;
+}
+/** What the `encounter` topic's snapshots carry. */
+export interface EncounterView {
+    phase: 'lobby' | 'running' | 'won' | 'lost';
+    players: number[];
+    width: number;
+    height: number;
+    spawn: [number, number];
+    base: [number, number];
+    base_hp: number;
+    gold: number;
+    /** The wave under way. */
+    wave: number | null;
+    waves: number;
+    /** When the next wave starts, while one counts down (Unix ms). */
+    next_wave_at: number | null;
+    enemies: EncounterEnemy[];
+    towers: EncounterTower[];
+    boss_phase: number;
+    /** Kills by player id (the keys are the ids as text). */
+    kills: Record<string, number>;
+}
+/** Waves, towers and bosses (the `director` starter): {@link encounter} by key. */
+export declare class EncountersKit {
+    private readonly runtime;
+    private readonly nodeType;
+    private readonly encounters;
+    constructor(runtime: KitRuntime, nodeType?: string);
+    encounter(key: string): Encounter;
+}
+/**
+ * One encounter: waves of enemies down a lane to the players' base, towers the players build (a
+ * tower may not cut the lane), strikes on a cooldown, kills that pay gold, and a boss that changes
+ * phase as it weakens. {@link view} mirrors the `encounter` topic: snapshots once a second while it
+ * runs, and `event` messages (`type`: `wave_started`, `wave_cleared`, `boss_phase`, `won`, `lost`)
+ * through `view.onEvent`.
+ */
+export declare class Encounter {
+    private readonly runtime;
+    readonly nodeType: string;
+    readonly key: string;
+    readonly view: HubState<EncounterView>;
+    constructor(runtime: KitRuntime, nodeType: string, key: string);
+    watch(): Promise<EncounterView>;
+    unwatch(): Promise<void>;
+    /** @throws {KitError} `full`. */
+    join(): Promise<boolean>;
+    /** The first to join, or a developer. @throws {KitError} `forbidden`, `started`, `bad_request` (no way to the base). */
+    start(): Promise<boolean>;
+    /**
+     * Builds a tower at `(x, z)`; resolves with the gold left.
+     * @throws {KitError} `blocks_lane`, `insufficient` (gold), `conflict` (taken), `bad_request`, `not_member`.
+     */
+    build(x: number, z: number): Promise<number>;
+    /** Strikes enemy `enemy`; resolves with its hp left. @throws {KitError} `cooldown`, `not_found`, `not_member`. */
+    hit(enemy: number): Promise<number>;
+}
+//# sourceMappingURL=encounters.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"encounters.d.ts","sourceRoot":"","sources":["../../../src/kit/modules/encounters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAEhD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,cAAc;IAC7B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;CACf;AAED,oDAAoD;AACpD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,OAAO,GAAG,SAAS,GAAG,KAAK,GAAG,MAAM,CAAC;IAC5C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxB,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,mFAAmF;AACnF,qBAAa,aAAa;IAItB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAJ3B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgC;gBAGxC,OAAO,EAAE,UAAU,EACnB,QAAQ,SAAa;IAGxC,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS;CAQlC;AAED;;;;;;GAMG;AACH,qBAAa,SAAS;IAIlB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM;IALtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;gBAGpB,OAAO,EAAE,UAAU,EAC3B,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM;IAKtB,KAAK,IAAI,OAAO,CAAC,aAAa,CAAC;IAI/B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIxB,iCAAiC;IACjC,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAIxB,wHAAwH;IACxH,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC;IAIzB;;;OAGG;IACH,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI5C,kHAAkH;IAClH,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAGpC"}