@crowdedkingdoms/crowdyjs 8.6.0 → 8.8.0

package/dist/kit/mobs.d.ts

@@ -0,0 +1,90 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars } from '../generated/graphql.js';
+import type { EngineDetector, EngineInvokeResult } from './engine.js';
+import { type ContactDamageEvent } from './wire.js';
+/** Options for {@link MobsKit}. Must match the deployed mob engine. */
+export interface MobsKitOptions {
+    /** The compute module serving `attack_mob`/`status`. Defaults to `'mob-engine'`. */
+    moduleName?: string;
+    /** The mob-definition container type. Defaults to `'MobDef'`. */
+    defTypeName?: string;
+    /** The mob slot container type. Defaults to `'Mob'`. */
+    slotTypeName?: string;
+}
+/** A parsed mob definition container. */
+export interface KitMobDef {
+    containerId: string;
+    displayName: string;
+    mobId: string;
+    maxHealth: number;
+    damage: number;
+    speed: number;
+    hostile: boolean;
+    spawnTime: string;
+    properties: Record<string, unknown>;
+}
+/** A parsed mob slot container (durable state; live poses ride the mob lane). */
+export interface KitMobSlot {
+    containerId: string;
+    displayName: string;
+    mobId: string;
+    actorUuid: string;
+    health: number;
+    x: number;
+    y: number;
+    z: number;
+    /** health > 0 — the slot is live and being simulated. */
+    alive: boolean;
+    properties: Record<string, unknown>;
+}
+/** The referee's verdict for an accepted/denied attack. */
+export interface KitAttackResult {
+    success: boolean;
+    /** Remaining health after an accepted hit. */
+    health?: number;
+    killed?: boolean;
+    /** The referee's denial reason ("out of range", "mob not live", ...). */
+    reason?: string;
+}
+/**
+ * Runtime helpers for compute-module mob engines (the Wave 1 `mob-engine`
+ * template / BWF's `bwf-mobs`): definition + slot reads off the model, the
+ * refereed `attack_mob` invoke, and the type-77 contact-damage event parser.
+ *
+ * Live mob poses arrive on the actor stream (FLAG_MOB, container-id
+ * suffix) — decode them with `kit/wire`'s {@link engineLanes} +
+ * `enginePoseCodec` in your world session; this kit reads the durable side.
+ *
+ * Obtained via `client.kit(appId).mobs`.
+ */
+export declare class MobsKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly engines;
+    private readonly moduleName;
+    private readonly defTypeName;
+    private readonly slotTypeName;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, engines: EngineDetector, options?: MobsKitOptions);
+    /** Is the mob engine deployed + enabled (cached per session)? */
+    engineAvailable(): Promise<boolean>;
+    /**
+     * Attack a live mob slot through the server referee: presence, range and
+     * damage clamps are validated engine-side before health moves. Denials
+     * resolve with `success: false` and the referee's `reason`.
+     */
+    attack(containerId: string, amount?: number): Promise<KitAttackResult>;
+    /** The engine's `status` snapshot (mob/def counts, tick counter). */
+    status(): Promise<EngineInvokeResult>;
+    /** List mob definitions with parsed stats. */
+    defs(): Promise<KitMobDef[]>;
+    /** List mob slots (durable positions/health; `alive` = health > 0). */
+    slots(): Promise<KitMobSlot[]>;
+    /**
+     * Parse a server-event payload as engine contact damage (type 77), or
+     * null when it is another event type. Feed it your world session's
+     * server-event stream and apply the damage to your own player when
+     * `targetUuid` matches your actor uuid.
+     */
+    parseContactDamage(payload: Uint8Array): ContactDamageEvent | null;
+}
+//# sourceMappingURL=mobs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mobs.d.ts","sourceRoot":"","sources":["../../src/kit/mobs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAExE,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,yCAAyC;AACzC,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,2DAA2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,OAAO;IAMhB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAGnB,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,cAAc,EACxC,OAAO,GAAE,cAAmB;IAO9B,iEAAiE;IACjE,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAInC;;;;OAIG;IACG,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,SAAI,GAAG,OAAO,CAAC,eAAe,CAAC;IAcvE,qEAAqE;IAC/D,MAAM,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAI3C,8CAA8C;IACxC,IAAI,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IA2BlC,uEAAuE;IACjE,KAAK,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IA6BpC;;;;;OAKG;IACH,kBAAkB,CAAC,OAAO,EAAE,UAAU,GAAG,kBAAkB,GAAG,IAAI;CAGnE"}

package/dist/kit/mobs.js

@@ -0,0 +1,98 @@
+import { kitContainerProperties } from './shared.js';
+import { parseContactDamage } from './wire.js';
+/**
+ * Runtime helpers for compute-module mob engines (the Wave 1 `mob-engine`
+ * template / BWF's `bwf-mobs`): definition + slot reads off the model, the
+ * refereed `attack_mob` invoke, and the type-77 contact-damage event parser.
+ *
+ * Live mob poses arrive on the actor stream (FLAG_MOB, container-id
+ * suffix) — decode them with `kit/wire`'s {@link engineLanes} +
+ * `enginePoseCodec` in your world session; this kit reads the durable side.
+ *
+ * Obtained via `client.kit(appId).mobs`.
+ */
+export class MobsKit {
+    constructor(appId, gameModel, engines, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.engines = engines;
+        this.moduleName = options.moduleName ?? 'mob-engine';
+        this.defTypeName = options.defTypeName ?? 'MobDef';
+        this.slotTypeName = options.slotTypeName ?? 'Mob';
+    }
+    /** Is the mob engine deployed + enabled (cached per session)? */
+    engineAvailable() {
+        return this.engines.has(this.moduleName);
+    }
+    /**
+     * Attack a live mob slot through the server referee: presence, range and
+     * damage clamps are validated engine-side before health moves. Denials
+     * resolve with `success: false` and the referee's `reason`.
+     */
+    async attack(containerId, amount = 1) {
+        const result = await this.engines.invoke(this.moduleName, 'attack_mob', { containerId, amount });
+        return {
+            success: result.success,
+            health: typeof result.body.health === 'number' ? result.body.health : undefined,
+            killed: typeof result.body.killed === 'boolean' ? result.body.killed : undefined,
+            reason: result.reason,
+        };
+    }
+    /** The engine's `status` snapshot (mob/def counts, tick counter). */
+    async status() {
+        return this.engines.invoke(this.moduleName, 'status');
+    }
+    /** List mob definitions with parsed stats. */
+    async defs() {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.defTypeName,
+        });
+        return Promise.all(containers.map(async (c) => {
+            const props = await kitContainerProperties(this.gameModel, String(this.appId), c.containerId);
+            return {
+                containerId: c.containerId,
+                displayName: c.displayName,
+                mobId: String(props.mob_id ?? ''),
+                maxHealth: Number(props.max_health ?? 0),
+                damage: Number(props.damage ?? 0),
+                speed: Number(props.speed ?? 0),
+                hostile: props.hostile === true || props.hostile === 'true',
+                spawnTime: String(props.spawn_time ?? 'any'),
+                properties: props,
+            };
+        }));
+    }
+    /** List mob slots (durable positions/health; `alive` = health > 0). */
+    async slots() {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.slotTypeName,
+        });
+        return Promise.all(containers.map(async (c) => {
+            const props = await kitContainerProperties(this.gameModel, String(this.appId), c.containerId);
+            const health = Number(props.health ?? 0);
+            return {
+                containerId: c.containerId,
+                displayName: c.displayName,
+                mobId: String(props.mob_id ?? ''),
+                actorUuid: String(props.actor_uuid ?? ''),
+                health,
+                x: Number(props.x ?? 0),
+                y: Number(props.y ?? 0),
+                z: Number(props.z ?? 0),
+                alive: health > 0,
+                properties: props,
+            };
+        }));
+    }
+    /**
+     * Parse a server-event payload as engine contact damage (type 77), or
+     * null when it is another event type. Feed it your world session's
+     * server-event stream and apply the damage to your own player when
+     * `targetUuid` matches your actor uuid.
+     */
+    parseContactDamage(payload) {
+        return parseContactDamage(payload);
+    }
+}

package/dist/kit/npcs.d.ts

@@ -1,9 +1,26 @@
 import type { GameModelAPI } from '../domains/gameModel.js';
 import type { Scalars, SeedPropertyInput } from '../generated/graphql.js';
+import type { EngineDetector } from './engine.js';
+import type { EnginePose } from './wire.js';
 /** Options for {@link NpcsKit}. Must match the deployed NPC blueprint. */
 export interface NpcsKitOptions {
     /** The `typeName` the NPC blueprint was deployed with. Defaults to `'Npc'`. */
     typeName?: string;
+    /**
+     * The compute module driving NPC movement when the app runs an engine
+     * (smooth FLAG_NPC actor emits instead of property nudges). Defaults to
+     * `'npc-engine'`.
+     */
+    moduleName?: string;
+}
+/**
+ * The minimal shape of a live actor entry {@link overlayLivePoses} reads —
+ * matches the world-session `RemoteActor<EnginePose>` without importing it.
+ */
+export interface LiveNpcPose {
+    uuid: string;
+    state: Pick<EnginePose, 'x' | 'y' | 'z'>;
+    receivedAt: number;
 }
 /** A parsed view of one live NPC. */
 export interface KitNpc {
@@ -32,8 +49,28 @@ export interface KitNpc {
 export declare class NpcsKit {
     private readonly appId;
     private readonly gameModel;
+    private readonly engines?;
     private readonly typeName;
-    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: NpcsKitOptions);
+    private readonly moduleName;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: NpcsKitOptions, engines?: EngineDetector | undefined);
+    /**
+     * Is an NPC compute engine deployed + enabled (cached per session)? When
+     * true, NPCs stream smooth FLAG_NPC actor poses — overlay them with
+     * {@link overlayLivePoses}. When false (model-only deployment), the polled
+     * container positions are all there is, exactly as before.
+     */
+    engineAvailable(): Promise<boolean>;
+    /**
+     * Overlay live engine-driven poses onto a polled NPC snapshot (the
+     * generalized BWF `NpcService.withLivePoses` pattern): each NPC whose
+     * `actor_uuid` has a fresh pose in the npcs actor lane gets its position
+     * replaced; the rest keep their durable container position, so NPCs stand
+     * at their last synced spot instead of disappearing.
+     *
+     * @param npcs - The polled snapshot (from {@link list}).
+     * @param lane - The live actors, e.g. `session.actors.lane('npcs').list()`.
+     */
+    overlayLivePoses(npcs: KitNpc[], lane: LiveNpcPose[]): KitNpc[];
     /** Spawn a live NPC instance (admin — the type is admin-instantiable). */
     spawn(input: {
         displayName: string;

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

@@ -1 +1 @@
-{"version":3,"file":"npcs.d.ts","sourceRoot":"","sources":["../../src/kit/npcs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAG1E,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qCAAqC;AACrC,MAAM,WAAW,MAAM;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,OAAO;IAIhB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAGf,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACxC,OAAO,GAAE,cAAmB;IAK9B,0EAA0E;IACpE,KAAK,CAAC,KAAK,EAAE;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,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;QACjC,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;;;;;;;;;;;IAuBD;;;;OAIG;IACG,IAAI,CAAC,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAclF,gDAAgD;IAC1C,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAQ3C,8EAA8E;IACxE,MAAM,CAAC,cAAc,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;IAInC;;;OAGG;IACG,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAQzD,6EAA6E;IACvE,KAAK,CAAC,aAAa,CAAC,EAAE,MAAM;;;;;;;;;;;;sBA+Bm8ke,CAAC;;;;;;;;;;IAxBt+ke,2DAA2D;IACrD,IAAI,CAAC,OAAO,GAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO;;;;;;;;;;;;;;;;;;;;;;YAIzE,KAAK;CAkBpB"}
+{"version":3,"file":"npcs.d.ts","sourceRoot":"","sources":["../../src/kit/npcs.ts"],"names":[],"mappings":"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"}

package/dist/kit/npcs.js

@@ -11,10 +11,45 @@ import { kitContainerProperties } from './shared.js';
  * Obtained via `client.kit(appId).npcs`.
  */
 export class NpcsKit {
-    constructor(appId, gameModel, options = {}) {
+    constructor(appId, gameModel, options = {}, engines) {
         this.appId = appId;
         this.gameModel = gameModel;
+        this.engines = engines;
         this.typeName = options.typeName ?? 'Npc';
+        this.moduleName = options.moduleName ?? 'npc-engine';
+    }
+    /**
+     * Is an NPC compute engine deployed + enabled (cached per session)? When
+     * true, NPCs stream smooth FLAG_NPC actor poses — overlay them with
+     * {@link overlayLivePoses}. When false (model-only deployment), the polled
+     * container positions are all there is, exactly as before.
+     */
+    engineAvailable() {
+        if (!this.engines)
+            return Promise.resolve(false);
+        return this.engines.has(this.moduleName);
+    }
+    /**
+     * Overlay live engine-driven poses onto a polled NPC snapshot (the
+     * generalized BWF `NpcService.withLivePoses` pattern): each NPC whose
+     * `actor_uuid` has a fresh pose in the npcs actor lane gets its position
+     * replaced; the rest keep their durable container position, so NPCs stand
+     * at their last synced spot instead of disappearing.
+     *
+     * @param npcs - The polled snapshot (from {@link list}).
+     * @param lane - The live actors, e.g. `session.actors.lane('npcs').list()`.
+     */
+    overlayLivePoses(npcs, lane) {
+        if (lane.length === 0)
+            return npcs;
+        const poses = new Map(lane.map((actor) => [actor.uuid, actor]));
+        return npcs.map((npc) => {
+            const uuid = String(npc.properties.actor_uuid ?? '');
+            const live = uuid ? poses.get(uuid) : undefined;
+            if (!live)
+                return npc;
+            return { ...npc, x: live.state.x, y: live.state.y, z: live.state.z };
+        });
     }
     /** Spawn a live NPC instance (admin — the type is admin-instantiable). */
     async spawn(input) {

package/dist/kit/pets.d.ts

@@ -0,0 +1,85 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars, SeedPropertyInput } from '../generated/graphql.js';
+import type { EngineDetector } from './engine.js';
+/** Options for {@link PetsKit}. Must match the deployed npc engine. */
+export interface PetsKitOptions {
+    /** The compute module serving summon/dismiss/rename. Defaults to `'npc-engine'`. */
+    moduleName?: string;
+    /** The pet container type. Defaults to `'Pet'`. */
+    typeName?: string;
+}
+/** A parsed pet container. */
+export interface KitPet {
+    containerId: string;
+    displayName: string;
+    species: string;
+    name: string;
+    ownerUserId: string | null;
+    bond: number;
+    active: boolean;
+    actorUuid: string;
+    x: number;
+    y: number;
+    z: number;
+    properties: Record<string, unknown>;
+}
+/** An engine verdict for a pet invoke. */
+export interface KitPetResult {
+    success: boolean;
+    reason?: string;
+}
+/**
+ * Runtime helpers for engine-driven pets (the Wave 1 npc-engine template):
+ * `Pet` containers hold species/name/owner/bond; the engine walks active
+ * pets after their owner (kit-ai `follow_owner`) and streams FLAG_NPC actor
+ * poses with the pet's container id as the payload suffix — decode the lane
+ * with `kit/wire` and match `pose.suffix` to the container id.
+ *
+ * Obtained via `client.kit(appId).pets`.
+ */
+export declare class PetsKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly engines;
+    private readonly moduleName;
+    private readonly typeName;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, engines: EngineDetector, options?: PetsKitOptions);
+    /** Is the pet-driving npc engine deployed + enabled (cached per session)? */
+    engineAvailable(): Promise<boolean>;
+    /**
+     * Adopt a pet: creates the caller-owned Pet container (active). Member
+     * instantiation defaults the owner to the caller; admin tokens must pass
+     * `ownerUserId` explicitly (the engine validates ownership on every
+     * summon/dismiss/rename).
+     */
+    adopt(input: {
+        species: string;
+        name: string;
+        ownerUserId?: Scalars['BigInt']['input'];
+        position?: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        properties?: SeedPropertyInput[];
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /** List pets (all, or one owner's with `ownerUserId`). */
+    list(ownerUserId?: Scalars['BigInt']['input']): Promise<KitPet[]>;
+    /** Summon your pet: it starts following you (owner-validated engine-side). */
+    summon(containerId: string): Promise<KitPetResult>;
+    /** Dismiss your pet: it stops simulating until summoned again. */
+    dismiss(containerId: string): Promise<KitPetResult>;
+    /** Rename your pet (1-32 chars; owner-validated engine-side). */
+    rename(containerId: string, name: string): Promise<KitPetResult>;
+}
+//# sourceMappingURL=pets.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pets.d.ts","sourceRoot":"","sources":["../../src/kit/pets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,8BAA8B;AAC9B,MAAM,WAAW,MAAM;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,0CAA0C;AAC1C,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,qBAAa,OAAO;IAKhB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAGf,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,cAAc,EACxC,OAAO,GAAE,cAAmB;IAM9B,6EAA6E;IAC7E,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAInC;;;;;OAKG;IACG,KAAK,CAAC,KAAK,EAAE;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;QACzC,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;;;;;;;;;;;IAuBD,0DAA0D;IACpD,IAAI,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAoCvE,8EAA8E;IACxE,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAKxD,kEAAkE;IAC5D,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAKzD,iEAAiE;IAC3D,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;CAOvE"}

package/dist/kit/pets.js

@@ -0,0 +1,96 @@
+import { kitContainerProperties } from './shared.js';
+/**
+ * Runtime helpers for engine-driven pets (the Wave 1 npc-engine template):
+ * `Pet` containers hold species/name/owner/bond; the engine walks active
+ * pets after their owner (kit-ai `follow_owner`) and streams FLAG_NPC actor
+ * poses with the pet's container id as the payload suffix — decode the lane
+ * with `kit/wire` and match `pose.suffix` to the container id.
+ *
+ * Obtained via `client.kit(appId).pets`.
+ */
+export class PetsKit {
+    constructor(appId, gameModel, engines, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.engines = engines;
+        this.moduleName = options.moduleName ?? 'npc-engine';
+        this.typeName = options.typeName ?? 'Pet';
+    }
+    /** Is the pet-driving npc engine deployed + enabled (cached per session)? */
+    engineAvailable() {
+        return this.engines.has(this.moduleName);
+    }
+    /**
+     * Adopt a pet: creates the caller-owned Pet container (active). Member
+     * instantiation defaults the owner to the caller; admin tokens must pass
+     * `ownerUserId` explicitly (the engine validates ownership on every
+     * summon/dismiss/rename).
+     */
+    async adopt(input) {
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.typeName,
+            displayName: input.name,
+            ...(input.ownerUserId !== undefined ? { ownerUserId: input.ownerUserId } : {}),
+            properties: [
+                { key: 'species', valueType: 'string', valueJson: JSON.stringify(input.species) },
+                { key: 'name', valueType: 'string', valueJson: JSON.stringify(input.name) },
+                { key: 'bond', valueType: 'int', valueJson: '0' },
+                { key: 'active', valueType: 'string', valueJson: '"true"' },
+                ...(input.position
+                    ? [
+                        { key: 'x', valueType: 'int', valueJson: String(Math.round(input.position.x)) },
+                        { key: 'y', valueType: 'int', valueJson: String(Math.round(input.position.y)) },
+                        { key: 'z', valueType: 'int', valueJson: String(Math.round(input.position.z)) },
+                    ]
+                    : []),
+                ...(input.properties ?? []),
+            ],
+        });
+    }
+    /** List pets (all, or one owner's with `ownerUserId`). */
+    async list(ownerUserId) {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.typeName,
+        });
+        const filtered = ownerUserId === undefined
+            ? containers
+            : containers.filter((c) => c.ownerUserId != null && String(c.ownerUserId) === String(ownerUserId));
+        return Promise.all(filtered.map(async (c) => {
+            const props = await kitContainerProperties(this.gameModel, String(this.appId), c.containerId);
+            return {
+                containerId: c.containerId,
+                displayName: c.displayName,
+                species: String(props.species ?? ''),
+                name: String(props.name ?? c.displayName),
+                ownerUserId: c.ownerUserId != null ? String(c.ownerUserId) : null,
+                bond: Number(props.bond ?? 0),
+                active: props.active !== 'false' && props.active !== false,
+                actorUuid: String(props.actor_uuid ?? ''),
+                x: Number(props.x ?? 0),
+                y: Number(props.y ?? 0),
+                z: Number(props.z ?? 0),
+                properties: props,
+            };
+        }));
+    }
+    /** Summon your pet: it starts following you (owner-validated engine-side). */
+    async summon(containerId) {
+        const result = await this.engines.invoke(this.moduleName, 'summon', { containerId });
+        return { success: result.success, reason: result.reason };
+    }
+    /** Dismiss your pet: it stops simulating until summoned again. */
+    async dismiss(containerId) {
+        const result = await this.engines.invoke(this.moduleName, 'dismiss', { containerId });
+        return { success: result.success, reason: result.reason };
+    }
+    /** Rename your pet (1-32 chars; owner-validated engine-side). */
+    async rename(containerId, name) {
+        const result = await this.engines.invoke(this.moduleName, 'rename_pet', {
+            containerId,
+            name,
+        });
+        return { success: result.success, reason: result.reason };
+    }
+}

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({