@crowdedkingdoms/crowdyjs 8.0.1 → 8.2.0

package/dist/kit/inventory.d.ts

@@ -0,0 +1,111 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars } from '../generated/graphql.js';
+import { type KitInvokeResult } from './shared.js';
+/** Options for {@link InventoryKit}. Must match the deployed blueprint's options. */
+export interface InventoryKitOptions {
+    /** The `typePrefix` the inventory blueprint was deployed with. */
+    typePrefix?: string;
+}
+/** A parsed view of one item stack. */
+export interface KitItemStack {
+    containerId: string;
+    displayName: string;
+    ownerUserId: string | null;
+    itemId: string;
+    quantity: number;
+    slot: number;
+}
+/**
+ * Runtime helpers for the {@link inventoryBlueprint} conventions: find or
+ * create the player's inventory, list stacks, and mutate them through the
+ * owner-gated model functions. All state lives server-side; every mutation is
+ * authority-checked and atomic.
+ *
+ * Obtained via `client.kit(appId).inventory`.
+ */
+export declare class InventoryKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly names;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: InventoryKitOptions);
+    /**
+     * Find the caller's inventory container, creating it when absent. The
+     * server assigns ownership to the caller (the type is member-instantiable
+     * and `ownerUserId` is omitted on create).
+     *
+     * @param ownerUserId - The calling player's user id (a decimal string, e.g.
+     *   from `client.users.me()`), used to recognize an existing inventory.
+     */
+    ensure(ownerUserId: Scalars['BigInt']['input'], options?: {
+        displayName?: string;
+        sessionId?: string;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /**
+     * List a player's item stacks with parsed properties (`itemId`, `quantity`,
+     * `slot`). Fetches each stack's visible state in parallel.
+     */
+    stacks(ownerUserId: Scalars['BigInt']['input']): Promise<KitItemStack[]>;
+    /**
+     * Create a new stack owned by the caller (server-assigned ownership).
+     * Use {@link grant} afterwards for authority-checked increments; the initial
+     * quantity here is a seed value on a container the caller owns anyway.
+     */
+    createStack(input: {
+        itemId: string;
+        quantity?: number;
+        slot?: number;
+        displayName?: string;
+        sessionId?: string;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /** Add items to a stack the caller owns. Resolves with the new quantity. */
+    grant(stackId: string, amount: number): Promise<KitInvokeResult<number>>;
+    /**
+     * Spend items from a stack the caller owns. The server refuses to overdraw
+     * (`success: false`, nothing written). Resolves with the new quantity.
+     */
+    consume(stackId: string, amount: number): Promise<KitInvokeResult<number>>;
+    /** Move a stack to another slot. Resolves with the new (clamped) slot. */
+    move(stackId: string, toSlot: number): Promise<KitInvokeResult<number>>;
+    /**
+     * Atomically move items between two stacks of the same item type — both
+     * writes commit or neither does. The caller must own the source stack.
+     * Resolves with the source stack's remaining quantity.
+     */
+    transfer(fromStackId: string, toStackId: string, amount: number): Promise<KitInvokeResult<number>>;
+    /**
+     * Record that a stack belongs to an inventory with an
+     * `inventory_contains` edge, so {@link contents} can read the whole bag in
+     * one traversal.
+     */
+    linkStack(inventoryId: string, stackId: string): Promise<{
+        __typename?: "GmEdge";
+        edgeId: string;
+        fromContainerId: string;
+        toContainerId: string;
+        relationshipType: string;
+        weight: number | null;
+    }>;
+    /** Read every stack linked to an inventory (via `inventory_contains` edges). */
+    contents(inventoryId: string): Promise<KitItemStack[]>;
+}
+//# sourceMappingURL=inventory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inventory.d.ts","sourceRoot":"","sources":["../../src/kit/inventory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEvD,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,qBAAa,YAAY;IAIrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;gBAGpB,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACxC,OAAO,GAAE,mBAAwB;IAKnC;;;;;;;OAOG;IACG,MAAM,CACV,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACvC,OAAO,GAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;;;;;;;;;;;IAmB5D;;;OAGG;IACG,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IA2B9E;;;;OAIG;IACG,WAAW,CAAC,KAAK,EAAE;QACvB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;;;;;;;;;;;IAcD,4EAA4E;IACtE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAS9E;;;OAGG;IACG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAShF,0EAA0E;IACpE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAS7E;;;;OAIG;IACG,QAAQ,CACZ,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IASnC;;;;OAIG;IACG,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;;;;;;;;IASpD,gFAAgF;IAC1E,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;CA4B7D"}

package/dist/kit/inventory.js

@@ -0,0 +1,158 @@
+import { inventoryNames } from './blueprints.js';
+import { kitContainerProperties, kitInvoke, } from './shared.js';
+/**
+ * Runtime helpers for the {@link inventoryBlueprint} conventions: find or
+ * create the player's inventory, list stacks, and mutate them through the
+ * owner-gated model functions. All state lives server-side; every mutation is
+ * authority-checked and atomic.
+ *
+ * Obtained via `client.kit(appId).inventory`.
+ */
+export class InventoryKit {
+    constructor(appId, gameModel, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.names = inventoryNames(options.typePrefix ?? '');
+    }
+    /**
+     * Find the caller's inventory container, creating it when absent. The
+     * server assigns ownership to the caller (the type is member-instantiable
+     * and `ownerUserId` is omitted on create).
+     *
+     * @param ownerUserId - The calling player's user id (a decimal string, e.g.
+     *   from `client.users.me()`), used to recognize an existing inventory.
+     */
+    async ensure(ownerUserId, options = {}) {
+        const existing = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.inventoryType,
+            ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
+        });
+        const mine = existing.find((c) => c.ownerUserId != null && String(c.ownerUserId) === String(ownerUserId));
+        if (mine)
+            return mine;
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.inventoryType,
+            displayName: options.displayName ?? `Inventory ${ownerUserId}`,
+            ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
+        });
+    }
+    /**
+     * List a player's item stacks with parsed properties (`itemId`, `quantity`,
+     * `slot`). Fetches each stack's visible state in parallel.
+     */
+    async stacks(ownerUserId) {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.stackType,
+        });
+        const mine = containers.filter((c) => c.ownerUserId != null && String(c.ownerUserId) === String(ownerUserId));
+        return Promise.all(mine.map(async (c) => {
+            const props = await kitContainerProperties(this.gameModel, String(this.appId), c.containerId);
+            return {
+                containerId: c.containerId,
+                displayName: c.displayName,
+                ownerUserId: c.ownerUserId != null ? String(c.ownerUserId) : null,
+                itemId: String(props.item_id ?? ''),
+                quantity: Number(props.quantity ?? 0),
+                slot: Number(props.slot ?? 0),
+            };
+        }));
+    }
+    /**
+     * Create a new stack owned by the caller (server-assigned ownership).
+     * Use {@link grant} afterwards for authority-checked increments; the initial
+     * quantity here is a seed value on a container the caller owns anyway.
+     */
+    async createStack(input) {
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.stackType,
+            displayName: input.displayName ?? `Stack ${input.itemId}`,
+            ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+            properties: [
+                { key: 'item_id', valueType: 'string', valueJson: JSON.stringify(input.itemId) },
+                { key: 'quantity', valueType: 'int', valueJson: String(input.quantity ?? 0) },
+                { key: 'slot', valueType: 'int', valueJson: String(input.slot ?? 0) },
+            ],
+        });
+    }
+    /** Add items to a stack the caller owns. Resolves with the new quantity. */
+    async grant(stackId, amount) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.grantFn,
+            selfContainerId: stackId,
+            params: { amount },
+        });
+    }
+    /**
+     * Spend items from a stack the caller owns. The server refuses to overdraw
+     * (`success: false`, nothing written). Resolves with the new quantity.
+     */
+    async consume(stackId, amount) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.consumeFn,
+            selfContainerId: stackId,
+            params: { amount },
+        });
+    }
+    /** Move a stack to another slot. Resolves with the new (clamped) slot. */
+    async move(stackId, toSlot) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.moveFn,
+            selfContainerId: stackId,
+            params: { to_slot: toSlot },
+        });
+    }
+    /**
+     * Atomically move items between two stacks of the same item type — both
+     * writes commit or neither does. The caller must own the source stack.
+     * Resolves with the source stack's remaining quantity.
+     */
+    async transfer(fromStackId, toStackId, amount) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.transferFn,
+            selfContainerId: fromStackId,
+            params: { to_id: toStackId, amount },
+        });
+    }
+    /**
+     * Record that a stack belongs to an inventory with an
+     * `inventory_contains` edge, so {@link contents} can read the whole bag in
+     * one traversal.
+     */
+    async linkStack(inventoryId, stackId) {
+        return this.gameModel.addEdge({
+            appId: this.appId,
+            fromContainerId: inventoryId,
+            toContainerId: stackId,
+            relationshipType: this.names.containsEdge,
+        });
+    }
+    /** Read every stack linked to an inventory (via `inventory_contains` edges). */
+    async contents(inventoryId) {
+        const result = await this.gameModel.traverse({
+            appId: this.appId,
+            rootId: inventoryId,
+            relationshipType: this.names.containsEdge,
+            depth: 1,
+        });
+        const stacks = result.nodes.filter((n) => n.typeName === this.names.stackType);
+        return Promise.all(stacks.map(async (c) => {
+            const props = await kitContainerProperties(this.gameModel, String(this.appId), c.containerId);
+            return {
+                containerId: c.containerId,
+                displayName: c.displayName,
+                ownerUserId: c.ownerUserId != null ? String(c.ownerUserId) : null,
+                itemId: String(props.item_id ?? ''),
+                quantity: Number(props.quantity ?? 0),
+                slot: Number(props.slot ?? 0),
+            };
+        }));
+    }
+}

package/dist/kit/kit.d.ts

@@ -0,0 +1,101 @@
+import type { GameAppsAPI } from '../domains/gameApps.js';
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { GameModelSeedMutation, GameModelUpsertAutomationMutation, GameModelUpsertAutomationTriggerMutation, Scalars } from '../generated/graphql.js';
+import { type KitBlueprint } from './blueprints.js';
+import { InventoryKit, type InventoryKitOptions } from './inventory.js';
+import { NpcsKit, type NpcsKitOptions } from './npcs.js';
+import { ObjectsKit, type ObjectsKitOptions } from './objects.js';
+import { PlotsKit, type PlotsKitOptions } from './plots.js';
+/** Options for {@link GameKitClient}, configuring the runtime helpers to match your deployed blueprints. */
+export interface GameKitOptions {
+    inventory?: InventoryKitOptions;
+    objects?: ObjectsKitOptions;
+    npcs?: NpcsKitOptions;
+    plots?: PlotsKitOptions;
+}
+/** The result of {@link GameKitClient.deploy}: the seed outcome plus each automation/trigger upserted. */
+export interface KitDeployResult {
+    seed: GameModelSeedMutation['gameModelSeed'];
+    automations: GameModelUpsertAutomationMutation['gameModelUpsertAutomation'][];
+    automationTriggers: GameModelUpsertAutomationTriggerMutation['gameModelUpsertAutomationTrigger'][];
+    /** Non-fatal static-analysis warnings from the seed. */
+    warnings: string[];
+}
+/**
+ * App-scoped **Game Kit** facade returned by `client.kit(appId)` — high-level
+ * building blocks that map traditional game concepts (inventory, lockable
+ * objects with custom permissions, NPCs) onto the Game Model + Automations
+ * API. Everything composes `client.gameModel`; no new server surface.
+ *
+ * Two phases, matching the platform's model:
+ *
+ * 1. **Studio (admin) loads the rules** — {@link deploy} takes declarative
+ *    {@link KitBlueprint}s (built with `inventoryBlueprint`, `lockBlueprint`,
+ *    `npcBlueprint`, or by hand) and seeds the container types, property
+ *    schemas, policy-gated functions, and automations into the app in one
+ *    idempotent pass. Requires the app-admin `manage_apps` permission — run
+ *    it from a trusted admin context, never the shipped game client.
+ * 2. **The game client plays** — {@link inventory}, {@link objects}, and
+ *    {@link npcs} wrap the runtime calls (create/read containers, invoke the
+ *    gated functions) assuming the blueprint conventions. Authorization is
+ *    enforced server-side on every call.
+ *
+ * See the docs guides "Game API → Modeling game concepts" and
+ * "CrowdyJS → Game Kit".
+ *
+ * @example
+ * ```ts
+ * // Studio setup (admin token):
+ * const kit = admin.kit(appId);
+ * await kit.deploy([
+ *   inventoryBlueprint(),
+ *   lockBlueprint({ objectTypeName: 'Door', authority: { kind: 'key' } }),
+ * ]);
+ *
+ * // Game client (player token):
+ * const kit = game.kit(appId);
+ * const bag = await kit.inventory.ensure(me.userId);
+ * const result = await kit.objects.open(doorId, { keyId });
+ * if (!result.success) showLockedMessage(result.errorMessage);
+ * ```
+ */
+export declare class GameKitClient {
+    private readonly appId;
+    private readonly gameModel;
+    /** Inventory helpers (per-player bags and item stacks). */
+    readonly inventory: InventoryKit;
+    /** Lockable-object helpers (doors/chests/gates with custom permissions). */
+    readonly objects: ObjectsKit;
+    /** NPC helpers (spawn/read instances, manage the automations behind them). */
+    readonly npcs: NpcsKit;
+    /** Plot helpers (buy/rent land with transactional, enforced grid grants). */
+    readonly plots: PlotsKit;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, gameApps: GameAppsAPI, options?: GameKitOptions);
+    /**
+     * Helpers for an additional lockable object type deployed under a different
+     * type name (e.g. both `Door` and `Chest` lock blueprints in one app).
+     */
+    objectsFor(objectTypeName: string, keyTypeName?: string): ObjectsKit;
+    /**
+     * **Studio (admin)** — load blueprints into the app: one transactional
+     * `gameModelSeed` for the definitions (and any seed containers/edges),
+     * followed by an `upsertAutomation` per automation and an
+     * `upsertAutomationTrigger` per event trigger. Idempotent: definitions
+     * upsert on their names, automations key on the automation name.
+     *
+     * Requires the app-admin `manage_apps` permission.
+     *
+     * @param blueprints - The blueprints to deploy. Duplicate type/function/
+     *   automation names across blueprints throw before anything is sent.
+     * @param options - `sessionId` scopes any seed containers to a session.
+     * @returns A {@link KitDeployResult} with the seed counts, the upserted
+     *   automations/triggers, and any non-fatal seed `warnings`.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN` (`requiredPermission ===
+     *   'manage_apps'`) without app-admin, or `BAD_USER_INPUT` for definitions
+     *   that fail to compile.
+     */
+    deploy(blueprints: KitBlueprint | KitBlueprint[], options?: {
+        sessionId?: string;
+    }): Promise<KitDeployResult>;
+}
+//# sourceMappingURL=kit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"kit.d.ts","sourceRoot":"","sources":["../../src/kit/kit.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EACV,qBAAqB,EACrB,iCAAiC,EACjC,wCAAwC,EACxC,OAAO,EACR,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,EAAE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAE5D,4GAA4G;AAC5G,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,mBAAmB,CAAC;IAChC,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED,0GAA0G;AAC1G,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,qBAAqB,CAAC,eAAe,CAAC,CAAC;IAC7C,WAAW,EAAE,iCAAiC,CAAC,2BAA2B,CAAC,EAAE,CAAC;IAC9E,kBAAkB,EAAE,wCAAwC,CAAC,kCAAkC,CAAC,EAAE,CAAC;IACnG,wDAAwD;IACxD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,aAAa;IAWtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAX5B,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;gBAGN,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACxC,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,cAAmB;IAQ9B;;;OAGG;IACH,UAAU,CAAC,cAAc,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU;IAOpE;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CACV,UAAU,EAAE,YAAY,GAAG,YAAY,EAAE,EACzC,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACnC,OAAO,CAAC,eAAe,CAAC;CAsB5B"}

package/dist/kit/kit.js

@@ -0,0 +1,100 @@
+import { mergeBlueprints } from './blueprints.js';
+import { InventoryKit } from './inventory.js';
+import { NpcsKit } from './npcs.js';
+import { ObjectsKit } from './objects.js';
+import { PlotsKit } from './plots.js';
+/**
+ * App-scoped **Game Kit** facade returned by `client.kit(appId)` — high-level
+ * building blocks that map traditional game concepts (inventory, lockable
+ * objects with custom permissions, NPCs) onto the Game Model + Automations
+ * API. Everything composes `client.gameModel`; no new server surface.
+ *
+ * Two phases, matching the platform's model:
+ *
+ * 1. **Studio (admin) loads the rules** — {@link deploy} takes declarative
+ *    {@link KitBlueprint}s (built with `inventoryBlueprint`, `lockBlueprint`,
+ *    `npcBlueprint`, or by hand) and seeds the container types, property
+ *    schemas, policy-gated functions, and automations into the app in one
+ *    idempotent pass. Requires the app-admin `manage_apps` permission — run
+ *    it from a trusted admin context, never the shipped game client.
+ * 2. **The game client plays** — {@link inventory}, {@link objects}, and
+ *    {@link npcs} wrap the runtime calls (create/read containers, invoke the
+ *    gated functions) assuming the blueprint conventions. Authorization is
+ *    enforced server-side on every call.
+ *
+ * See the docs guides "Game API → Modeling game concepts" and
+ * "CrowdyJS → Game Kit".
+ *
+ * @example
+ * ```ts
+ * // Studio setup (admin token):
+ * const kit = admin.kit(appId);
+ * await kit.deploy([
+ *   inventoryBlueprint(),
+ *   lockBlueprint({ objectTypeName: 'Door', authority: { kind: 'key' } }),
+ * ]);
+ *
+ * // Game client (player token):
+ * const kit = game.kit(appId);
+ * const bag = await kit.inventory.ensure(me.userId);
+ * const result = await kit.objects.open(doorId, { keyId });
+ * if (!result.success) showLockedMessage(result.errorMessage);
+ * ```
+ */
+export class GameKitClient {
+    constructor(appId, gameModel, gameApps, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        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.plots = new PlotsKit(appId, gameModel, gameApps, options.plots);
+    }
+    /**
+     * Helpers for an additional lockable object type deployed under a different
+     * type name (e.g. both `Door` and `Chest` lock blueprints in one app).
+     */
+    objectsFor(objectTypeName, keyTypeName) {
+        return new ObjectsKit(this.appId, this.gameModel, {
+            objectTypeName,
+            keyTypeName,
+        });
+    }
+    /**
+     * **Studio (admin)** — load blueprints into the app: one transactional
+     * `gameModelSeed` for the definitions (and any seed containers/edges),
+     * followed by an `upsertAutomation` per automation and an
+     * `upsertAutomationTrigger` per event trigger. Idempotent: definitions
+     * upsert on their names, automations key on the automation name.
+     *
+     * Requires the app-admin `manage_apps` permission.
+     *
+     * @param blueprints - The blueprints to deploy. Duplicate type/function/
+     *   automation names across blueprints throw before anything is sent.
+     * @param options - `sessionId` scopes any seed containers to a session.
+     * @returns A {@link KitDeployResult} with the seed counts, the upserted
+     *   automations/triggers, and any non-fatal seed `warnings`.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN` (`requiredPermission ===
+     *   'manage_apps'`) without app-admin, or `BAD_USER_INPUT` for definitions
+     *   that fail to compile.
+     */
+    async deploy(blueprints, options = {}) {
+        const list = Array.isArray(blueprints) ? blueprints : [blueprints];
+        const merged = mergeBlueprints(this.appId, list, options);
+        const seed = await this.gameModel.seed(merged.seedInput);
+        const automations = [];
+        for (const automation of merged.automations) {
+            automations.push(await this.gameModel.upsertAutomation(automation));
+        }
+        const automationTriggers = [];
+        for (const trigger of merged.automationTriggers) {
+            automationTriggers.push(await this.gameModel.upsertAutomationTrigger(trigger));
+        }
+        return {
+            seed,
+            automations,
+            automationTriggers,
+            warnings: [...(seed.warnings ?? [])],
+        };
+    }
+}

package/dist/kit/npcs.d.ts

@@ -0,0 +1,182 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars, SeedPropertyInput } from '../generated/graphql.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;
+}
+/** A parsed view of one live NPC. */
+export interface KitNpc {
+    containerId: string;
+    displayName: string;
+    role: string;
+    x: number;
+    y: number;
+    z: number;
+    behaviorState: string;
+    health: number;
+    /** All visible properties, including any extras your blueprint added. */
+    properties: Record<string, unknown>;
+}
+/**
+ * Runtime helpers for the {@link npcBlueprint} conventions: spawn NPC
+ * instances, read their server-driven state, and manage/monitor the
+ * automations behind them. Behaviors run in the API server — clients only
+ * re-read state (or listen for model-driven notifications) and render.
+ *
+ * Spawning and the automation management/monitoring calls are studio/admin
+ * operations (`manage_apps`); reads are player-safe.
+ *
+ * Obtained via `client.kit(appId).npcs`.
+ */
+export declare class NpcsKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly typeName;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: NpcsKitOptions);
+    /** Spawn a live NPC instance (admin — the type is admin-instantiable). */
+    spawn(input: {
+        displayName: string;
+        role?: string;
+        position?: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        properties?: SeedPropertyInput[];
+        sessionId?: string;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /**
+     * List live NPCs with parsed state, optionally filtered by `role`. Fetches
+     * each NPC's visible properties in parallel — fine for the bounded NPC
+     * populations automations are designed around.
+     */
+    list(options?: {
+        role?: string;
+        sessionId?: string;
+    }): Promise<KitNpc[]>;
+    /** Read one NPC's current server-side state. */
+    state(npcId: string): Promise<KitNpc>;
+    /** Run one of the NPC automations immediately (admin; useful for testing). */
+    runNow(automationName: string): Promise<{
+        __typename?: "GmAutomationRun";
+        runId: string;
+        appId: string;
+        automationId: string;
+        automationName: string;
+        triggerSource: string;
+        parentRunId: string | null;
+        cascadeDepth: number;
+        startedAt: string;
+        finishedAt: string | null;
+        durationUs: number;
+        targets: number;
+        invocations: number;
+        mutations: number;
+        fnCalls: number;
+        gasUsed: number;
+        success: boolean;
+        errorMessage: string | null;
+        circuitAction: string | null;
+        computeUnits: number;
+    }>;
+    /**
+     * Pause or resume an NPC automation (admin). Re-enabling also resets a
+     * tripped failure circuit.
+     */
+    setEnabled(automationName: string, enabled: boolean): Promise<{
+        __typename?: "GmAutomation";
+        automationId: string;
+        appId: string;
+        name: string;
+        description: string | null;
+        enabled: boolean;
+        functionName: string;
+        targetMode: string;
+        selfContainerId: string | null;
+        targetTypeName: string | null;
+        sessionId: string | null;
+        paramsJson: string;
+        selectorJson: string | null;
+        runAsUserId: string | null;
+        triggerType: string;
+        scheduleKind: string | null;
+        intervalMs: number | null;
+        cronExpr: string | null;
+        maxTargets: number;
+        maxFnDepth: number | null;
+        gasLimit: number | null;
+        runTimeoutMs: number | null;
+        maxRunsPerMinute: number;
+        failureThreshold: number;
+        cooldownMs: number;
+        circuitState: string;
+        consecutiveFailures: number;
+        pausedUntil: string | null;
+        lastError: string | null;
+        lastRunAt: string | null;
+        nextRunAt: string | null;
+    }>;
+    /** Aggregate "what are my NPCs doing" stats over a recent window (admin). */
+    stats(windowMinutes?: number): Promise<{
+        __typename?: "GmAutomationStats";
+        windowMinutes: number;
+        totalRuns: number;
+        failedRuns: number;
+        failureRatePct: number;
+        runsPerMinute: number;
+        totalInvocations: number;
+        totalMutations: number;
+        totalComputeUnits: number;
+        avgDurationUs: number;
+        byAutomation: Array<{
+            __typename?: "GmAutomationStat";
+            automationName: string;
+            runs: number;
+            failures: number;
+            invocations: number;
+            computeUnits: number;
+            avgDurationUs: number;
+            circuitState: string;
+        }>;
+    }>;
+    /** Recent automation run history, newest first (admin). */
+    runs(options?: {
+        automationName?: string;
+        success?: boolean;
+        limit?: number;
+    }): Promise<{
+        __typename?: "GmAutomationRun";
+        runId: string;
+        appId: string;
+        automationId: string;
+        automationName: string;
+        triggerSource: string;
+        parentRunId: string | null;
+        cascadeDepth: number;
+        startedAt: string;
+        finishedAt: string | null;
+        durationUs: number;
+        targets: number;
+        invocations: number;
+        mutations: number;
+        fnCalls: number;
+        gasUsed: number;
+        success: boolean;
+        errorMessage: string | null;
+        circuitAction: string | null;
+        computeUnits: number;
+    }[]>;
+    private toNpc;
+}
+//# sourceMappingURL=npcs.d.ts.map

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

@@ -0,0 +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+B+2gc,CAAC;;;;;;;;;;IAxBl5gc,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"}