@crowdedkingdoms/crowdyjs 8.7.0 → 8.8.0

package/dist/kit/matchmaking.d.ts

@@ -0,0 +1,57 @@
+import type { Scalars } from '../generated/graphql.js';
+import type { EngineDetector } from './engine.js';
+/** Options for {@link MatchmakingKit}. */
+export interface MatchmakingKitOptions {
+    /** The matchmaking module name. Defaults to `'matchmaking'`. */
+    moduleName?: string;
+}
+/** Your queue status: where you are queued and any live proposal. */
+export interface KitQueueStatus {
+    queuedIn: string | null;
+    proposal: {
+        proposalId: string;
+        mode: string;
+        players: string[];
+        accepted: string[];
+        handedOff: boolean;
+    } | null;
+    queueDepth: number;
+    rating: number;
+}
+/**
+ * Runtime helpers for the matchmaking engine (Wave 2): rating-bucketed
+ * queues with widening windows, party blocks, and accept-gated proposals
+ * that hand off to the match layer over compute events. After everyone
+ * accepts, resolve the created match with `kit.matches.findByProposal`.
+ *
+ * Obtained via `client.kit(appId).matchmaking`.
+ */
+export declare class MatchmakingKit {
+    private readonly engines;
+    private readonly moduleName;
+    constructor(_appId: Scalars['BigInt']['input'], engines: EngineDetector, options?: MatchmakingKitOptions);
+    /** Is the matchmaking engine deployed + enabled (cached per session)? */
+    engineAvailable(): Promise<boolean>;
+    /**
+     * Join a queue (optionally with a party block that must match together,
+     * and an explicit rating for games that keep rating on the progression
+     * layer).
+     */
+    queueJoin(input?: {
+        mode?: string;
+        rating?: number;
+        party?: string[];
+    }): Promise<Record<string, unknown>>;
+    /** Leave your queue (all modes, or one with `mode`). */
+    queueLeave(mode?: string): Promise<Record<string, unknown>>;
+    /** Your queue/proposal status. */
+    queueStatus(mode?: string): Promise<KitQueueStatus>;
+    /** Accept a proposal; when everyone has, the match handoff fires. */
+    accept(proposalId: string): Promise<Record<string, unknown>>;
+    /** Report the decided result (Elo-lite rating update + proposal close). */
+    reportResult(proposalId: string, winnerUserId: string): Promise<Record<string, unknown>>;
+    /** Engine totals (queues/proposals/rated players). */
+    status(): Promise<Record<string, unknown>>;
+    private invoke;
+}
+//# sourceMappingURL=matchmaking.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"matchmaking.d.ts","sourceRoot":"","sources":["../../src/kit/matchmaking.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE;QACR,UAAU,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,SAAS,EAAE,OAAO,CAAC;KACpB,GAAG,IAAI,CAAC;IACT,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,qBAAa,cAAc;IAKvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAGlC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjB,OAAO,EAAE,cAAc,EACxC,OAAO,GAAE,qBAA0B;IAKrC,yEAAyE;IACzE,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAInC;;;;OAIG;IACG,SAAS,CAAC,KAAK,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAO;IAIhF,wDAAwD;IAClD,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM;IAI9B,kCAAkC;IAC5B,WAAW,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAUzD,qEAAqE;IAC/D,MAAM,CAAC,UAAU,EAAE,MAAM;IAI/B,2EAA2E;IACrE,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;IAI3D,sDAAsD;IAChD,MAAM;YAIE,MAAM;CAOrB"}

package/dist/kit/matchmaking.js

@@ -0,0 +1,59 @@
+/**
+ * Runtime helpers for the matchmaking engine (Wave 2): rating-bucketed
+ * queues with widening windows, party blocks, and accept-gated proposals
+ * that hand off to the match layer over compute events. After everyone
+ * accepts, resolve the created match with `kit.matches.findByProposal`.
+ *
+ * Obtained via `client.kit(appId).matchmaking`.
+ */
+export class MatchmakingKit {
+    constructor(_appId, engines, options = {}) {
+        this.engines = engines;
+        this.moduleName = options.moduleName ?? 'matchmaking';
+    }
+    /** Is the matchmaking engine deployed + enabled (cached per session)? */
+    engineAvailable() {
+        return this.engines.has(this.moduleName);
+    }
+    /**
+     * Join a queue (optionally with a party block that must match together,
+     * and an explicit rating for games that keep rating on the progression
+     * layer).
+     */
+    async queueJoin(input = {}) {
+        return this.invoke('queue_join', input);
+    }
+    /** Leave your queue (all modes, or one with `mode`). */
+    async queueLeave(mode) {
+        return this.invoke('queue_leave', mode ? { mode } : {});
+    }
+    /** Your queue/proposal status. */
+    async queueStatus(mode) {
+        const body = await this.invoke('queue_status', mode ? { mode } : {});
+        return {
+            queuedIn: body.queuedIn != null ? String(body.queuedIn) : null,
+            proposal: body.proposal ?? null,
+            queueDepth: Number(body.queueDepth ?? 0),
+            rating: Number(body.rating ?? 0),
+        };
+    }
+    /** Accept a proposal; when everyone has, the match handoff fires. */
+    async accept(proposalId) {
+        return this.invoke('accept', { proposalId });
+    }
+    /** Report the decided result (Elo-lite rating update + proposal close). */
+    async reportResult(proposalId, winnerUserId) {
+        return this.invoke('report_result', { proposalId, winnerUserId });
+    }
+    /** Engine totals (queues/proposals/rated players). */
+    async status() {
+        return this.invoke('status', {});
+    }
+    async invoke(exportName, params) {
+        const result = await this.engines.invoke(this.moduleName, exportName, params);
+        if (!result.success) {
+            throw new Error(`matchmaking.${exportName} failed: ${result.reason ?? 'unknown'}`);
+        }
+        return result.body;
+    }
+}

package/dist/kit/minigames.d.ts

@@ -0,0 +1,30 @@
+import type { Scalars } from '../generated/graphql.js';
+import type { EngineDetector, EngineInvokeResult } from './engine.js';
+/** Options for {@link MinigamesKit}. */
+export interface MinigamesKitOptions {
+    /** Default module when calls omit one (e.g. your scaffolded game). */
+    defaultModuleName?: string;
+}
+/**
+ * A thin invoke wrapper for invoke-loop minigames (the Wave 2 `minigame`
+ * scaffold pattern): synchronous `play` RPCs with server-bound caller
+ * identity, server-held secrets, and per-caller records. Every method
+ * resolves the engine envelope — denials come back as
+ * `{success: false, reason}` rather than throwing.
+ *
+ * Obtained via `client.kit(appId).minigames`.
+ */
+export declare class MinigamesKit {
+    private readonly engines;
+    private readonly defaultModuleName?;
+    constructor(_appId: Scalars['BigInt']['input'], engines: EngineDetector, options?: MinigamesKitOptions);
+    /** Is a minigame module deployed + enabled (cached per session)? */
+    engineAvailable(moduleName?: string): Promise<boolean>;
+    /** One round: invoke the game's `play` export with your move. */
+    play(params: Record<string, unknown>, moduleName?: string): Promise<EngineInvokeResult>;
+    /** Your per-caller record. */
+    record(moduleName?: string): Promise<EngineInvokeResult>;
+    /** Any other export the game defines (typed result envelope). */
+    invoke(exportName: string, params?: Record<string, unknown>, moduleName?: string): Promise<EngineInvokeResult>;
+}
+//# sourceMappingURL=minigames.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"minigames.d.ts","sourceRoot":"","sources":["../../src/kit/minigames.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtE,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAY;IAKrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJ1B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAS;gBAG1C,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjB,OAAO,EAAE,cAAc,EACxC,OAAO,GAAE,mBAAwB;IAKnC,oEAAoE;IACpE,eAAe,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMtD,iEAAiE;IAC3D,IAAI,CACR,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,kBAAkB,CAAC;IAI9B,8BAA8B;IACxB,MAAM,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAI9D,iEAAiE;IAC3D,MAAM,CACV,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,kBAAkB,CAAC;CAO/B"}

package/dist/kit/minigames.js

@@ -0,0 +1,38 @@
+/**
+ * A thin invoke wrapper for invoke-loop minigames (the Wave 2 `minigame`
+ * scaffold pattern): synchronous `play` RPCs with server-bound caller
+ * identity, server-held secrets, and per-caller records. Every method
+ * resolves the engine envelope — denials come back as
+ * `{success: false, reason}` rather than throwing.
+ *
+ * Obtained via `client.kit(appId).minigames`.
+ */
+export class MinigamesKit {
+    constructor(_appId, engines, options = {}) {
+        this.engines = engines;
+        this.defaultModuleName = options.defaultModuleName;
+    }
+    /** Is a minigame module deployed + enabled (cached per session)? */
+    engineAvailable(moduleName) {
+        const name = moduleName ?? this.defaultModuleName;
+        if (!name)
+            return Promise.resolve(false);
+        return this.engines.has(name);
+    }
+    /** One round: invoke the game's `play` export with your move. */
+    async play(params, moduleName) {
+        return this.invoke('play', params, moduleName);
+    }
+    /** Your per-caller record. */
+    async record(moduleName) {
+        return this.invoke('record', {}, moduleName);
+    }
+    /** Any other export the game defines (typed result envelope). */
+    async invoke(exportName, params = {}, moduleName) {
+        const name = moduleName ?? this.defaultModuleName;
+        if (!name) {
+            return { success: false, reason: 'no minigame module configured', body: {} };
+        }
+        return this.engines.invoke(name, exportName, params);
+    }
+}

package/dist/kit/quests.d.ts

@@ -87,6 +87,63 @@ export declare class QuestsKit {
     }>;
     /** List a player's quest progress rows. */
     mine(ownerUserId: Scalars['BigInt']['input']): Promise<KitQuestProgress[]>;
+    /**
+     * STUDIO (admin) — define an ordered tutorial chain as quest defs. Steps
+     * are plain quests whose `questId` encodes the chain + index
+     * (`"<chain>:<i>"`), so no new server surface is involved: the sequencing
+     * is a read-side convention enforced by {@link tutorial} /
+     * {@link acceptNextTutorialStep} (a step is `locked` until every earlier
+     * step completes).
+     */
+    defineTutorial(input: {
+        /** Chain id (one app can ship several tutorials). Defaults to `'ftue'`. */
+        chain?: string;
+        steps: Array<{
+            displayName: string;
+            targetCount?: number;
+            rewardItemId?: string;
+            rewardQty?: number;
+            rewardGold?: number;
+        }>;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }[]>;
+    /** One tutorial step joined with the player's progress. */
+    /**
+     * A player's view of a tutorial chain: steps in order, each `locked`
+     * (an earlier step is incomplete), `active` (the first incomplete step),
+     * or `complete`. The client shows/drives only the `active` step; the
+     * trusted advance authority is unchanged (players still cannot complete
+     * their own quests).
+     */
+    tutorial(ownerUserId: Scalars['BigInt']['input'], chain?: string): Promise<Array<{
+        stepIndex: number;
+        def: KitQuestDef;
+        progress: KitQuestProgress | null;
+        status: 'locked' | 'active' | 'complete';
+    }>>;
+    /**
+     * Ensure the player's ACTIVE tutorial step has a progress row (accepting
+     * it when missing) and return the step. Returns null when the chain is
+     * complete. Calling this for a locked step is impossible by construction —
+     * it always targets the first incomplete step.
+     */
+    acceptNextTutorialStep(ownerUserId: Scalars['BigInt']['input'], chain?: string, options?: {
+        sessionId?: string;
+    }): Promise<{
+        stepIndex: number;
+        def: KitQuestDef;
+        progress: KitQuestProgress | null;
+        status: "locked" | "active" | "complete";
+    } | null>;
     /** Read one progress row. */
     state(progressId: string): Promise<KitQuestProgress>;
     /**

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

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

package/dist/kit/quests.js

@@ -106,6 +106,78 @@ export class QuestsKit {
         const mine = containers.filter((c) => c.ownerUserId != null && String(c.ownerUserId) === String(ownerUserId));
         return Promise.all(mine.map((c) => this.state(c.containerId)));
     }
+    // -- FTUE / tutorial step sequencing (Wave 2) -----------------------------
+    /**
+     * STUDIO (admin) — define an ordered tutorial chain as quest defs. Steps
+     * are plain quests whose `questId` encodes the chain + index
+     * (`"<chain>:<i>"`), so no new server surface is involved: the sequencing
+     * is a read-side convention enforced by {@link tutorial} /
+     * {@link acceptNextTutorialStep} (a step is `locked` until every earlier
+     * step completes).
+     */
+    async defineTutorial(input) {
+        const chain = input.chain ?? 'ftue';
+        const created = [];
+        for (const [index, step] of input.steps.entries()) {
+            created.push(await this.defineQuest({
+                questId: `${chain}:${index}`,
+                displayName: step.displayName,
+                targetCount: step.targetCount ?? 1,
+                rewardItemId: step.rewardItemId,
+                rewardQty: step.rewardQty,
+                rewardGold: step.rewardGold,
+            }));
+        }
+        return created;
+    }
+    /** One tutorial step joined with the player's progress. */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars -- documented shape
+    /**
+     * A player's view of a tutorial chain: steps in order, each `locked`
+     * (an earlier step is incomplete), `active` (the first incomplete step),
+     * or `complete`. The client shows/drives only the `active` step; the
+     * trusted advance authority is unchanged (players still cannot complete
+     * their own quests).
+     */
+    async tutorial(ownerUserId, chain = 'ftue') {
+        const prefix = `${chain}:`;
+        const defs = (await this.catalog())
+            .filter((def) => def.questId.startsWith(prefix))
+            .map((def) => ({ def, stepIndex: Number(def.questId.slice(prefix.length)) }))
+            .filter(({ stepIndex }) => Number.isFinite(stepIndex))
+            .sort((a, b) => a.stepIndex - b.stepIndex);
+        const progressRows = await this.mine(ownerUserId);
+        let blocked = false;
+        return defs.map(({ def, stepIndex }) => {
+            const progress = progressRows.find((p) => p.questId === def.questId) ?? null;
+            const complete = progress?.completed === true;
+            const status = complete
+                ? 'complete'
+                : blocked
+                    ? 'locked'
+                    : 'active';
+            if (!complete)
+                blocked = true;
+            return { stepIndex, def, progress, status };
+        });
+    }
+    /**
+     * Ensure the player's ACTIVE tutorial step has a progress row (accepting
+     * it when missing) and return the step. Returns null when the chain is
+     * complete. Calling this for a locked step is impossible by construction —
+     * it always targets the first incomplete step.
+     */
+    async acceptNextTutorialStep(ownerUserId, chain = 'ftue', options = {}) {
+        const steps = await this.tutorial(ownerUserId, chain);
+        const active = steps.find((step) => step.status === 'active');
+        if (!active)
+            return null;
+        if (active.progress)
+            return active;
+        await this.accept(ownerUserId, active.def.containerId, options);
+        const refreshed = await this.tutorial(ownerUserId, chain);
+        return refreshed.find((step) => step.stepIndex === active.stepIndex) ?? null;
+    }
     /** Read one progress row. */
     async state(progressId) {
         const container = await this.gameModel.container({

package/dist/kit/wire.d.ts

@@ -60,6 +60,12 @@ export declare function engineLanes(): Record<string, (state: EnginePose) => boo
 export declare const EVENT_CONTACT_DAMAGE = 77;
 /** Weather/season transition from a world engine (kit-sim weather). */
 export declare const EVENT_WEATHER = 90;
+/** Turn changed (kit-play turns; match engines). */
+export declare const EVENT_TURN = 91;
+/** Score / match summary (kit-play score). */
+export declare const EVENT_SCORE = 92;
+/** Match proposal (matchmaking → matches handoff). */
+export declare const EVENT_PROPOSAL = 93;
 /** Split an engine server-event payload into its type + JSON body. */
 export declare function parseEngineEvent(bytes: Uint8Array): {
     eventType: number;
@@ -84,4 +90,35 @@ export interface WeatherEvent {
 }
 /** Parse a weather event; null when the payload is another type. */
 export declare function parseWeatherEvent(bytes: Uint8Array): WeatherEvent | null;
+/** A parsed type-91 turn-changed event (match engines). */
+export interface TurnEvent {
+    actorId: string;
+    round: number;
+    turnInRound: number;
+    body: Record<string, unknown>;
+}
+/** Parse a turn event; null when the payload is another type. */
+export declare function parseTurnEvent(bytes: Uint8Array): TurnEvent | null;
+/** A parsed type-92 score/summary event (match engines). */
+export interface ScoreEvent {
+    /** Per-actor standings when present. */
+    standings: Array<{
+        actorId: string;
+        score: number;
+        rank: number;
+    }>;
+    winnerId: string | null;
+    body: Record<string, unknown>;
+}
+/** Parse a score event; null when the payload is another type. */
+export declare function parseScoreEvent(bytes: Uint8Array): ScoreEvent | null;
+/** A parsed type-93 match-proposal event (matchmaking handoff). */
+export interface ProposalEvent {
+    proposalId: string;
+    mode: string;
+    players: string[];
+    body: Record<string, unknown>;
+}
+/** Parse a proposal event; null when the payload is another type. */
+export declare function parseProposalEvent(bytes: Uint8Array): ProposalEvent | null;
 //# sourceMappingURL=wire.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../src/kit/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,eAAO,MAAM,UAAU,KAAK,CAAC;AAE7B,4EAA4E;AAC5E,eAAO,MAAM,aAAa,IAAS,CAAC;AACpC,eAAO,MAAM,QAAQ,IAAS,CAAC;AAC/B,eAAO,MAAM,QAAQ,IAAS,CAAC;AAC/B,eAAO,MAAM,cAAc,IAAS,CAAC;AAErC,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,gDAAgD;AAChD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAiBtE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAqBrE;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAI3D;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,UAAU,CAAC,UAAU,CAiBlD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,CAM5E;AAMD,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,uEAAuE;AACvE,eAAO,MAAM,aAAa,KAAK,CAAC;AAEhC,sEAAsE;AACtE,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,UAAU,GAChB;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,IAAI,CAY7D;AAED,6CAA6C;AAC7C,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,kBAAkB,GAAG,IAAI,CAS/E;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,YAAY,GAAG,IAAI,CASxE"}
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../src/kit/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,eAAO,MAAM,UAAU,KAAK,CAAC;AAE7B,4EAA4E;AAC5E,eAAO,MAAM,aAAa,IAAS,CAAC;AACpC,eAAO,MAAM,QAAQ,IAAS,CAAC;AAC/B,eAAO,MAAM,QAAQ,IAAS,CAAC;AAC/B,eAAO,MAAM,cAAc,IAAS,CAAC;AAErC,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,gDAAgD;AAChD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAiBtE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAqBrE;AAED,sEAAsE;AACtE,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAI3D;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,UAAU,CAAC,UAAU,CAiBlD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,CAM5E;AAMD,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,uEAAuE;AACvE,eAAO,MAAM,aAAa,KAAK,CAAC;AAChC,oDAAoD;AACpD,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,8CAA8C;AAC9C,eAAO,MAAM,WAAW,KAAK,CAAC;AAC9B,sDAAsD;AACtD,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC,sEAAsE;AACtE,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,UAAU,GAChB;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,GAAG,IAAI,CAY7D;AAED,6CAA6C;AAC7C,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,2EAA2E;AAC3E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,kBAAkB,GAAG,IAAI,CAS/E;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,oEAAoE;AACpE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,YAAY,GAAG,IAAI,CASxE;AAED,2DAA2D;AAC3D,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,IAAI,CASlE;AAED,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,wCAAwC;IACxC,SAAS,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,kEAAkE;AAClE,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAepE;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B;AAED,qEAAqE;AACrE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,aAAa,GAAG,IAAI,CAW1E"}

package/dist/kit/wire.js

@@ -114,6 +114,12 @@ export function engineLanes() {
 export const EVENT_CONTACT_DAMAGE = 77;
 /** Weather/season transition from a world engine (kit-sim weather). */
 export const EVENT_WEATHER = 90;
+/** Turn changed (kit-play turns; match engines). */
+export const EVENT_TURN = 91;
+/** Score / match summary (kit-play score). */
+export const EVENT_SCORE = 92;
+/** Match proposal (matchmaking → matches handoff). */
+export const EVENT_PROPOSAL = 93;
 /** Split an engine server-event payload into its type + JSON body. */
 export function parseEngineEvent(bytes) {
     if (bytes.length < 2)
@@ -154,3 +160,47 @@ export function parseWeatherEvent(bytes) {
         body: parsed.body,
     };
 }
+/** Parse a turn event; null when the payload is another type. */
+export function parseTurnEvent(bytes) {
+    const parsed = parseEngineEvent(bytes);
+    if (!parsed || parsed.eventType !== EVENT_TURN)
+        return null;
+    return {
+        actorId: String(parsed.body.actorId ?? ''),
+        round: Number(parsed.body.round ?? 0),
+        turnInRound: Number(parsed.body.turnInRound ?? 0),
+        body: parsed.body,
+    };
+}
+/** Parse a score event; null when the payload is another type. */
+export function parseScoreEvent(bytes) {
+    const parsed = parseEngineEvent(bytes);
+    if (!parsed || parsed.eventType !== EVENT_SCORE)
+        return null;
+    const standings = Array.isArray(parsed.body.standings)
+        ? parsed.body.standings.map((s) => ({
+            actorId: String(s.actorId ?? ''),
+            score: Number(s.score ?? 0),
+            rank: Number(s.rank ?? 0),
+        }))
+        : [];
+    return {
+        standings,
+        winnerId: parsed.body.winnerId != null ? String(parsed.body.winnerId) : null,
+        body: parsed.body,
+    };
+}
+/** Parse a proposal event; null when the payload is another type. */
+export function parseProposalEvent(bytes) {
+    const parsed = parseEngineEvent(bytes);
+    if (!parsed || parsed.eventType !== EVENT_PROPOSAL)
+        return null;
+    return {
+        proposalId: String(parsed.body.proposalId ?? ''),
+        mode: String(parsed.body.mode ?? ''),
+        players: Array.isArray(parsed.body.players)
+            ? parsed.body.players.map(String)
+            : [],
+        body: parsed.body,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowdedkingdoms/crowdyjs",
-  "version": "8.7.0",
+  "version": "8.8.0",
   "description": "Client SDK for Crowded Kingdoms GraphQL API with UDP proxy support",
   "type": "module",
   "main": "dist/index.js",