@crowdedkingdoms/crowdyjs 8.6.0 → 8.7.0

package/dist/kit/kit.js

@@ -2,12 +2,15 @@ import { mergeBlueprints } from './blueprints/index.js';
 import { CombatKit } from './combat.js';
 import { DecksKit } from './decks.js';
 import { EconomyKit } from './economy.js';
+import { EngineDetector } from './engine.js';
 import { FeaturesKit } from './features.js';
 import { InventoryKit } from './inventory.js';
 import { LeaderboardsKit } from './leaderboards.js';
 import { LootKit } from './loot.js';
+import { MobsKit } from './mobs.js';
 import { NpcsKit } from './npcs.js';
 import { ObjectsKit } from './objects.js';
+import { PetsKit } from './pets.js';
 import { PlotsKit } from './plots.js';
 import { MatchesKit } from './matches.js';
 import { ProgressionKit } from './progression.js';
@@ -56,18 +59,21 @@ export class GameKitClient {
     constructor(appId, gameModel, gameApps, options = {}, domains = {}) {
         this.appId = appId;
         this.gameModel = gameModel;
+        this.engines = new EngineDetector(String(appId), domains.compute);
         this.inventory = new InventoryKit(appId, gameModel, options.inventory);
         this.objects = new ObjectsKit(appId, gameModel, options.objects);
-        this.npcs = new NpcsKit(appId, gameModel, options.npcs);
+        this.npcs = new NpcsKit(appId, gameModel, options.npcs, this.engines);
         this.plots = new PlotsKit(appId, gameModel, gameApps, options.plots);
         this.economy = new EconomyKit(appId, gameModel, options.economy);
         this.progression = new ProgressionKit(appId, gameModel, options.progression);
         this.loot = new LootKit(appId, gameModel, options.loot);
         this.quests = new QuestsKit(appId, gameModel, options.quests);
-        this.combat = new CombatKit(appId, gameModel, options.combat);
+        this.combat = new CombatKit(appId, gameModel, options.combat, this.engines);
         this.matches = new MatchesKit(appId, gameModel, domains.channels, domains.udp, options.matches);
         this.decks = new DecksKit(appId, gameModel, options.decks);
-        this.worldsim = new WorldsimKit(appId, gameModel, options.worldsim);
+        this.worldsim = new WorldsimKit(appId, gameModel, options.worldsim, this.engines);
+        this.mobs = new MobsKit(appId, gameModel, this.engines, options.mobs);
+        this.pets = new PetsKit(appId, gameModel, this.engines, options.pets);
         this.social = new SocialKit(appId, domains.teams, domains.channels, domains.udp, gameApps, options.social);
         this.leaderboards = new LeaderboardsKit(appId, gameModel, options.leaderboards);
         this.features = new FeaturesKit(appId, gameModel);

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

@@ -0,0 +1,87 @@
+/**
+ * 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;
+/** 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;
+//# 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":"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"}