@crowdedkingdoms/crowdyjs 8.6.0 → 8.8.0

package/dist/kit/wire.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Engine wire registry — the client mirror of the server's
+ * `crowdy-game-kit-core::wire` (the single source of truth for the actor
+ * pose layout and flag-bit registry used by compute-module game engines).
+ * Parity with the Rust crate is checked by the kit unit suite: any change
+ * here must land in kit-core first.
+ *
+ * 48-byte little-endian pose: pos f32 x3 (0..11), yaw/pitch f32 (12..19),
+ * velocity f32 x3 (20..31), flags u8 (32), held u8 (33), 34-35 reserved,
+ * updated_at f64 ms (36..43), 44-47 reserved. Payloads may append opaque
+ * UTF-8 suffix bytes (engines put the entity's container id there).
+ */
+import type { StateCodec } from '../stores/codec.js';
+export declare const POSE_BYTES = 48;
+/** Flag-bit registry. Bits 0-3 are platform-reserved; games may use 4-7. */
+export declare const FLAG_GROUNDED = 1;
+export declare const FLAG_MOB = 2;
+export declare const FLAG_NPC = 4;
+export declare const FLAG_RESERVED3 = 8;
+/** The decoded engine pose (plus the payload suffix, when present). */
+export interface EnginePose {
+    x: number;
+    y: number;
+    z: number;
+    yaw: number;
+    pitch: number;
+    velX: number;
+    velY: number;
+    velZ: number;
+    flags: number;
+    held: number;
+    updatedAtMs: number;
+    /** UTF-8 payload suffix after the 48-byte pose (container id), if any. */
+    suffix: string | null;
+}
+/** Encode a pose (suffix appended when set). */
+export declare function encodeEnginePose(pose: Partial<EnginePose>): Uint8Array;
+/**
+ * Decode the leading 48 bytes (tolerates longer payloads — the suffix is
+ * extracted). Returns null for short or non-finite payloads.
+ */
+export declare function decodeEnginePose(bytes: Uint8Array): EnginePose | null;
+/** The UTF-8 suffix after the pose (engine container ids), if any. */
+export declare function poseSuffix(bytes: Uint8Array): string | null;
+/**
+ * A {@link StateCodec} for engine poses over the base64 wire form — plug it
+ * into `attachRemoteActors` / `createWorldSession` actor config. Undecodable
+ * payloads yield a zeroed pose with `flags: 0` (they land in the players
+ * lane predicate's care, same as unknown custom states).
+ */
+export declare const enginePoseCodec: StateCodec<EnginePose>;
+/**
+ * Ready-made lane predicates for `createWorldSession` when the world runs
+ * compute-module engines: `players` (no engine flag), `mobs` (FLAG_MOB) and
+ * `npcs` (FLAG_NPC) — what Blocks with Friends hand-wired in its Phase 9
+ * adoption. Spread extra lanes on top as needed.
+ */
+export declare function engineLanes(): Record<string, (state: EnginePose) => boolean>;
+/** Contact damage decided by a mob/combat engine (kit-play referee). */
+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;
+    body: Record<string, unknown>;
+} | null;
+/** A parsed type-77 contact-damage event. */
+export interface ContactDamageEvent {
+    targetUuid: string;
+    damage: number;
+    mobId: string;
+    mobName: string;
+}
+/** Parse a contact-damage event; null when the payload is another type. */
+export declare function parseContactDamage(bytes: Uint8Array): ContactDamageEvent | null;
+/** A parsed type-90 weather transition event. */
+export interface WeatherEvent {
+    weather: string;
+    sinceMs: number;
+    untilMs: number;
+    /** Extra fields engines add (dayPhase, isNight, remainingMs, ...). */
+    body: Record<string, unknown>;
+}
+/** 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

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

package/dist/kit/wire.js

@@ -0,0 +1,206 @@
+/**
+ * Engine wire registry — the client mirror of the server's
+ * `crowdy-game-kit-core::wire` (the single source of truth for the actor
+ * pose layout and flag-bit registry used by compute-module game engines).
+ * Parity with the Rust crate is checked by the kit unit suite: any change
+ * here must land in kit-core first.
+ *
+ * 48-byte little-endian pose: pos f32 x3 (0..11), yaw/pitch f32 (12..19),
+ * velocity f32 x3 (20..31), flags u8 (32), held u8 (33), 34-35 reserved,
+ * updated_at f64 ms (36..43), 44-47 reserved. Payloads may append opaque
+ * UTF-8 suffix bytes (engines put the entity's container id there).
+ */
+import { decodeBase64, encodeBase64 } from '../utils.js';
+export const POSE_BYTES = 48;
+/** Flag-bit registry. Bits 0-3 are platform-reserved; games may use 4-7. */
+export const FLAG_GROUNDED = 0b0001;
+export const FLAG_MOB = 0b0010;
+export const FLAG_NPC = 0b0100;
+export const FLAG_RESERVED3 = 0b1000;
+/** Encode a pose (suffix appended when set). */
+export function encodeEnginePose(pose) {
+    const suffix = pose.suffix != null ? new TextEncoder().encode(pose.suffix) : null;
+    const bytes = new Uint8Array(POSE_BYTES + (suffix?.length ?? 0));
+    const view = new DataView(bytes.buffer);
+    view.setFloat32(0, pose.x ?? 0, true);
+    view.setFloat32(4, pose.y ?? 0, true);
+    view.setFloat32(8, pose.z ?? 0, true);
+    view.setFloat32(12, pose.yaw ?? 0, true);
+    view.setFloat32(16, pose.pitch ?? 0, true);
+    view.setFloat32(20, pose.velX ?? 0, true);
+    view.setFloat32(24, pose.velY ?? 0, true);
+    view.setFloat32(28, pose.velZ ?? 0, true);
+    view.setUint8(32, pose.flags ?? 0);
+    view.setUint8(33, pose.held ?? 0);
+    view.setFloat64(36, pose.updatedAtMs ?? 0, true);
+    if (suffix)
+        bytes.set(suffix, POSE_BYTES);
+    return bytes;
+}
+/**
+ * Decode the leading 48 bytes (tolerates longer payloads — the suffix is
+ * extracted). Returns null for short or non-finite payloads.
+ */
+export function decodeEnginePose(bytes) {
+    if (bytes.length < POSE_BYTES)
+        return null;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const pose = {
+        x: view.getFloat32(0, true),
+        y: view.getFloat32(4, true),
+        z: view.getFloat32(8, true),
+        yaw: view.getFloat32(12, true),
+        pitch: view.getFloat32(16, true),
+        velX: view.getFloat32(20, true),
+        velY: view.getFloat32(24, true),
+        velZ: view.getFloat32(28, true),
+        flags: view.getUint8(32),
+        held: view.getUint8(33),
+        updatedAtMs: view.getFloat64(36, true),
+        suffix: poseSuffix(bytes),
+    };
+    if (!Number.isFinite(pose.x) || !Number.isFinite(pose.y) || !Number.isFinite(pose.z)) {
+        return null;
+    }
+    return pose;
+}
+/** The UTF-8 suffix after the pose (engine container ids), if any. */
+export function poseSuffix(bytes) {
+    if (bytes.length <= POSE_BYTES)
+        return null;
+    const text = new TextDecoder().decode(bytes.subarray(POSE_BYTES)).trim();
+    return text.length > 0 ? text : null;
+}
+/**
+ * A {@link StateCodec} for engine poses over the base64 wire form — plug it
+ * into `attachRemoteActors` / `createWorldSession` actor config. Undecodable
+ * payloads yield a zeroed pose with `flags: 0` (they land in the players
+ * lane predicate's care, same as unknown custom states).
+ */
+export const enginePoseCodec = {
+    encode: (pose) => encodeBase64(encodeEnginePose(pose)),
+    decode: (data) => decodeEnginePose(decodeBase64(data)) ?? {
+        x: 0,
+        y: 0,
+        z: 0,
+        yaw: 0,
+        pitch: 0,
+        velX: 0,
+        velY: 0,
+        velZ: 0,
+        flags: 0,
+        held: 0,
+        updatedAtMs: 0,
+        suffix: null,
+    },
+};
+/**
+ * Ready-made lane predicates for `createWorldSession` when the world runs
+ * compute-module engines: `players` (no engine flag), `mobs` (FLAG_MOB) and
+ * `npcs` (FLAG_NPC) — what Blocks with Friends hand-wired in its Phase 9
+ * adoption. Spread extra lanes on top as needed.
+ */
+export function engineLanes() {
+    return {
+        mobs: (state) => (state.flags & FLAG_MOB) !== 0,
+        npcs: (state) => (state.flags & FLAG_NPC) !== 0,
+        players: (state) => (state.flags & (FLAG_MOB | FLAG_NPC)) === 0,
+    };
+}
+// ---------------------------------------------------------------------------
+// Server-event payloads ([u16 LE event type][state bytes], state = JSON)
+// ---------------------------------------------------------------------------
+/** Contact damage decided by a mob/combat engine (kit-play referee). */
+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)
+        return null;
+    const eventType = bytes[0] | (bytes[1] << 8);
+    let body = {};
+    if (bytes.length > 2) {
+        try {
+            body = JSON.parse(new TextDecoder().decode(bytes.subarray(2)));
+        }
+        catch {
+            return null;
+        }
+    }
+    return { eventType, body };
+}
+/** Parse a contact-damage event; null when the payload is another type. */
+export function parseContactDamage(bytes) {
+    const parsed = parseEngineEvent(bytes);
+    if (!parsed || parsed.eventType !== EVENT_CONTACT_DAMAGE)
+        return null;
+    return {
+        targetUuid: String(parsed.body.targetUuid ?? ''),
+        damage: Number(parsed.body.damage ?? 0),
+        mobId: String(parsed.body.mobId ?? ''),
+        mobName: String(parsed.body.mobName ?? ''),
+    };
+}
+/** Parse a weather event; null when the payload is another type. */
+export function parseWeatherEvent(bytes) {
+    const parsed = parseEngineEvent(bytes);
+    if (!parsed || parsed.eventType !== EVENT_WEATHER)
+        return null;
+    return {
+        weather: String(parsed.body.weather ?? ''),
+        sinceMs: Number(parsed.body.sinceMs ?? 0),
+        untilMs: Number(parsed.body.untilMs ?? 0),
+        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/dist/kit/worldsim.d.ts

@@ -1,10 +1,27 @@
 import type { GameModelAPI } from '../domains/gameModel.js';
 import type { Scalars, SeedPropertyInput } from '../generated/graphql.js';
+import type { EngineDetector } from './engine.js';
 import { type KitInvokeResult } from './shared.js';
+import { type WeatherEvent } from './wire.js';
 /** Options for {@link WorldsimKit}. Must match the deployed worldsim blueprint. */
 export interface WorldsimKitOptions {
     /** The `typePrefix` the worldsim blueprint was deployed with. */
     typePrefix?: string;
+    /**
+     * The compute module serving `forecast` when the app runs a world engine.
+     * Defaults to `'world-engine'`.
+     */
+    moduleName?: string;
+}
+/** A world engine's forecast (current front + day phase). */
+export interface KitForecast {
+    weather: string;
+    /** Day phase in [0, 1) when the engine reports it. */
+    dayPhase?: number;
+    isNight?: boolean;
+    /** Milliseconds until the current front rolls. */
+    remainingMs?: number;
+    body: Record<string, unknown>;
 }
 /** A parsed view of the world clock/weather state. */
 export interface KitWorldState {
@@ -56,8 +73,24 @@ export interface KitWaveSpawner {
 export declare class WorldsimKit {
     private readonly appId;
     private readonly gameModel;
+    private readonly engines?;
     private readonly names;
-    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: WorldsimKitOptions);
+    private readonly moduleName;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: WorldsimKitOptions, engines?: EngineDetector | undefined);
+    /** Is a world compute engine deployed + enabled (cached per session)? */
+    engineAvailable(): Promise<boolean>;
+    /**
+     * The world engine's `forecast` invoke: the current weather front plus
+     * day-phase fields. Late joiners call this once, then track transitions
+     * from the type-90 event stream ({@link parseWeather}).
+     */
+    forecast(): Promise<KitForecast>;
+    /**
+     * Parse a server-event payload as a world-engine weather transition
+     * (type 90), or null when it is another event type. Feed it your world
+     * session's server-event stream.
+     */
+    parseWeather(payload: Uint8Array): WeatherEvent | null;
     /**
      * Find-or-create the WorldState singleton (admin). `anchorChunk` is where
      * the clock's spatial time-changed ping is emitted.

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

@@ -1 +1 @@
-{"version":3,"file":"worldsim.d.ts","sourceRoot":"","sources":["../../src/kit/worldsim.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE1E,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,kDAAkD;AAClD,MAAM,WAAW,OAAO;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,yCAAyC;AACzC,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,qBAAa,WAAW;IAIpB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;gBAGnB,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACxC,OAAO,GAAE,kBAAuB;IAKlC;;;OAGG;IACG,WAAW,CACf,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAO;;;;;;;;;;;IAqB3F,0CAA0C;IACpC,UAAU,IAAI,OAAO,CAAC,aAAa,CAAC;IAuB1C,6EAA6E;IACvE,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAUnE,sCAAsC;IAChC,UAAU,CAAC,KAAK,EAAE;QACtB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC;QACf,cAAc,EAAE,MAAM,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC/C,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;KAClC;;;;;;;;;;;IA4BD,6CAA6C;IACvC,KAAK,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IA4BzC;;;;OAIG;IACG,MAAM,CAAC,KAAK,EAAE;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,EAAE,MAAM,CAAC;KACnB,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IASpC,sDAAsD;IAChD,KAAK,CAAC,KAAK,EAAE;QACjB,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;QACxC,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;;;;;;;;;;;IAmBD,oEAAoE;IAC9D,KAAK,CACT,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,GAAG,IAAI,GAC7C,OAAO,CAAC,OAAO,EAAE,CAAC;IAmCrB;;;OAGG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IASlF,sEAAsE;IAChE,aAAa,CAAC,KAAK,EAAE;QACzB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB;;;;;;;;;;;IAeD,mEAAmE;IAC7D,QAAQ,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAsB3C,4EAA4E;IACtE,MAAM,CAAC,cAAc,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;IAInC,+DAA+D;IACzD,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAO1D"}
+{"version":3,"file":"worldsim.d.ts","sourceRoot":"","sources":["../../src/kit/worldsim.ts"],"names":[],"mappings":"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"}

package/dist/kit/worldsim.js

@@ -1,5 +1,6 @@
 import { worldsimNames } from './blueprints/index.js';
 import { kitContainerProperties, kitInvoke, } from './shared.js';
+import { parseWeatherEvent } from './wire.js';
 /**
  * Runtime helpers for the {@link worldsimBlueprint} conventions: the world
  * clock/weather singleton, regenerating resource nodes players gather from,
@@ -10,10 +11,46 @@ import { kitContainerProperties, kitInvoke, } from './shared.js';
  * Obtained via `client.kit(appId).worldsim`.
  */
 export class WorldsimKit {
-    constructor(appId, gameModel, options = {}) {
+    constructor(appId, gameModel, options = {}, engines) {
         this.appId = appId;
         this.gameModel = gameModel;
+        this.engines = engines;
         this.names = worldsimNames(options.typePrefix ?? '');
+        this.moduleName = options.moduleName ?? 'world-engine';
+    }
+    /** Is a world compute engine deployed + enabled (cached per session)? */
+    engineAvailable() {
+        if (!this.engines)
+            return Promise.resolve(false);
+        return this.engines.has(this.moduleName);
+    }
+    /**
+     * The world engine's `forecast` invoke: the current weather front plus
+     * day-phase fields. Late joiners call this once, then track transitions
+     * from the type-90 event stream ({@link parseWeather}).
+     */
+    async forecast() {
+        const result = this.engines
+            ? await this.engines.invoke(this.moduleName, 'forecast')
+            : { success: false, reason: 'compute domain unavailable', body: {} };
+        if (!result.success) {
+            throw new Error(`forecast unavailable: ${result.reason ?? 'engine missing'}`);
+        }
+        return {
+            weather: String(result.body.weather ?? ''),
+            dayPhase: typeof result.body.dayPhase === 'number' ? result.body.dayPhase : undefined,
+            isNight: typeof result.body.isNight === 'boolean' ? result.body.isNight : undefined,
+            remainingMs: typeof result.body.remainingMs === 'number' ? result.body.remainingMs : undefined,
+            body: result.body,
+        };
+    }
+    /**
+     * Parse a server-event payload as a world-engine weather transition
+     * (type 90), or null when it is another event type. Feed it your world
+     * session's server-event stream.
+     */
+    parseWeather(payload) {
+        return parseWeatherEvent(payload);
     }
     /**
      * Find-or-create the WorldState singleton (admin). `anchorChunk` is where

package/package.json

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