@crowdedkingdoms/crowdyjs 8.0.1 → 8.2.0

package/dist/kit/npcs.js

@@ -0,0 +1,106 @@
+import { kitContainerProperties } from './shared.js';
+/**
+ * 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 class NpcsKit {
+    constructor(appId, gameModel, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.typeName = options.typeName ?? 'Npc';
+    }
+    /** Spawn a live NPC instance (admin — the type is admin-instantiable). */
+    async spawn(input) {
+        const properties = [
+            ...(input.role !== undefined
+                ? [{ key: 'role', valueType: 'string', valueJson: JSON.stringify(input.role) }]
+                : []),
+            ...(input.position
+                ? [
+                    { key: 'x', valueType: 'float', valueJson: String(input.position.x) },
+                    { key: 'y', valueType: 'float', valueJson: String(input.position.y) },
+                    { key: 'z', valueType: 'float', valueJson: String(input.position.z) },
+                ]
+                : []),
+            ...(input.properties ?? []),
+        ];
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.typeName,
+            displayName: input.displayName,
+            ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+            ...(properties.length ? { properties } : {}),
+        });
+    }
+    /**
+     * 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.
+     */
+    async list(options = {}) {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.typeName,
+            ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
+        });
+        const npcs = await Promise.all(containers.map((c) => this.toNpc(c.containerId, c.displayName)));
+        return options.role !== undefined
+            ? npcs.filter((n) => n.role === options.role)
+            : npcs;
+    }
+    /** Read one NPC's current server-side state. */
+    async state(npcId) {
+        const container = await this.gameModel.container({
+            appId: this.appId,
+            containerId: npcId,
+        });
+        return this.toNpc(container.containerId, container.displayName);
+    }
+    /** Run one of the NPC automations immediately (admin; useful for testing). */
+    async runNow(automationName) {
+        return this.gameModel.runAutomation({ appId: this.appId, name: automationName });
+    }
+    /**
+     * Pause or resume an NPC automation (admin). Re-enabling also resets a
+     * tripped failure circuit.
+     */
+    async setEnabled(automationName, enabled) {
+        return this.gameModel.setAutomationEnabled({
+            appId: this.appId,
+            name: automationName,
+            enabled,
+        });
+    }
+    /** Aggregate "what are my NPCs doing" stats over a recent window (admin). */
+    async stats(windowMinutes) {
+        return this.gameModel.automationStats({
+            appId: this.appId,
+            ...(windowMinutes !== undefined ? { windowMinutes } : {}),
+        });
+    }
+    /** Recent automation run history, newest first (admin). */
+    async runs(options = {}) {
+        return this.gameModel.automationRuns({ appId: this.appId, ...options });
+    }
+    async toNpc(containerId, displayName) {
+        const props = await kitContainerProperties(this.gameModel, String(this.appId), containerId);
+        return {
+            containerId,
+            displayName,
+            role: String(props.role ?? ''),
+            x: Number(props.x ?? 0),
+            y: Number(props.y ?? 0),
+            z: Number(props.z ?? 0),
+            behaviorState: String(props.behavior_state ?? ''),
+            health: Number(props.health ?? 0),
+            properties: props,
+        };
+    }
+}

package/dist/kit/objects.d.ts

@@ -0,0 +1,116 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars, SeedPropertyInput } from '../generated/graphql.js';
+import { type KitInvokeResult } from './shared.js';
+/** Options for {@link ObjectsKit}. Must match the deployed lock blueprint. */
+export interface ObjectsKitOptions {
+    /** The `objectTypeName` the lock blueprint was deployed with. Defaults to `'Lockable'`. */
+    objectTypeName?: string;
+    /** The `keyTypeName` the lock blueprint was deployed with. */
+    keyTypeName?: string;
+}
+/**
+ * Runtime helpers for the {@link lockBlueprint} conventions: instantiate
+ * lockable world objects, grant key items, and operate the objects through
+ * their authority-gated `open`/`close` functions. Authorization is decided
+ * entirely server-side; a denied attempt resolves with `success: false`.
+ *
+ * Obtained via `client.kit(appId).objects` (or `client.kit(appId)
+ * .objectsFor('Door')` for a non-default type name).
+ */
+export declare class ObjectsKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly names;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: ObjectsKitOptions);
+    /**
+     * Instantiate a lockable object (admin/studio call — the type is
+     * admin-instantiable). For key-gated objects set `requiredKeyId` to the key
+     * id that opens it; for owner-gated objects set `ownerUserId`; for
+     * chunk-permission-gated objects set `chunk` to where the object stands
+     * (feeds the `has_chunk_permission` policy).
+     */
+    create(input: {
+        displayName: string;
+        requiredKeyId?: string;
+        ownerUserId?: Scalars['BigInt']['input'];
+        /** The chunk the object occupies (chunkPermission authority). */
+        chunk?: {
+            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;
+    }>;
+    /**
+     * Grant a player a key item (admin/studio call). Creates a key container
+     * owned by the player, with the owner mirrored into the `owner_user_id`
+     * property that the key condition policy reads.
+     */
+    grantKey(input: {
+        keyId: string;
+        toUserId: Scalars['BigInt']['input'];
+        displayName?: string;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /** List the key items a player holds. */
+    keysOf(userId: Scalars['BigInt']['input']): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }[]>;
+    /**
+     * Try to open an object. Pass `keyId` (the **container id** of a key the
+     * caller holds) when the object is key-gated; owner/grid/group authorities
+     * need no params. A denial is not an exception — check `success`.
+     */
+    open(objectId: string, options?: {
+        keyId?: string;
+    }): Promise<KitInvokeResult<boolean>>;
+    /** Try to close an object; same authority as {@link open}. */
+    close(objectId: string, options?: {
+        keyId?: string;
+    }): Promise<KitInvokeResult<boolean>>;
+    /** Read whether an object is currently open. */
+    isOpen(objectId: string): Promise<boolean>;
+    /** List all objects of this lockable type. */
+    list(options?: {
+        sessionId?: string;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }[]>;
+}
+//# sourceMappingURL=objects.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"objects.d.ts","sourceRoot":"","sources":["../../src/kit/objects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE1E,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,2FAA2F;IAC3F,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,qBAAa,UAAU;IAInB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;gBAGf,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACxC,OAAO,GAAE,iBAAsB;IAKjC;;;;;;OAMG;IACG,MAAM,CAAC,KAAK,EAAE;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,WAAW,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;QACzC,iEAAiE;QACjE,KAAK,CAAC,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC5C,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;QACjC,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;;;;;;;;;;;IA+BD;;;;OAIG;IACG,QAAQ,CAAC,KAAK,EAAE;QACpB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;QACrC,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB;;;;;;;;;;;IAiBD,yCAAyC;IACnC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC;;;;;;;;;;;IAU/C;;;;OAIG;IACG,IAAI,CACR,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAC/B,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IASpC,8DAA8D;IACxD,KAAK,CACT,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAC/B,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IASpC,gDAAgD;IAC1C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAShD,8CAA8C;IACxC,IAAI,CAAC,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;;;;;;;;;;;CAOhD"}

package/dist/kit/objects.js

@@ -0,0 +1,119 @@
+import { lockNames } from './blueprints.js';
+import { kitContainerProperties, kitInvoke, } from './shared.js';
+/**
+ * Runtime helpers for the {@link lockBlueprint} conventions: instantiate
+ * lockable world objects, grant key items, and operate the objects through
+ * their authority-gated `open`/`close` functions. Authorization is decided
+ * entirely server-side; a denied attempt resolves with `success: false`.
+ *
+ * Obtained via `client.kit(appId).objects` (or `client.kit(appId)
+ * .objectsFor('Door')` for a non-default type name).
+ */
+export class ObjectsKit {
+    constructor(appId, gameModel, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.names = lockNames(options.objectTypeName, options.keyTypeName);
+    }
+    /**
+     * Instantiate a lockable object (admin/studio call — the type is
+     * admin-instantiable). For key-gated objects set `requiredKeyId` to the key
+     * id that opens it; for owner-gated objects set `ownerUserId`; for
+     * chunk-permission-gated objects set `chunk` to where the object stands
+     * (feeds the `has_chunk_permission` policy).
+     */
+    async create(input) {
+        const properties = [
+            { key: 'is_open', valueType: 'bool', valueJson: 'false' },
+            ...(input.requiredKeyId !== undefined
+                ? [
+                    {
+                        key: 'required_key_id',
+                        valueType: 'string',
+                        valueJson: JSON.stringify(input.requiredKeyId),
+                    },
+                ]
+                : []),
+            ...(input.chunk
+                ? [
+                    { key: 'cx', valueType: 'int', valueJson: String(input.chunk.x) },
+                    { key: 'cy', valueType: 'int', valueJson: String(input.chunk.y) },
+                    { key: 'cz', valueType: 'int', valueJson: String(input.chunk.z) },
+                ]
+                : []),
+            ...(input.properties ?? []),
+        ];
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.objectType,
+            displayName: input.displayName,
+            ...(input.ownerUserId !== undefined ? { ownerUserId: input.ownerUserId } : {}),
+            ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+            properties,
+        });
+    }
+    /**
+     * Grant a player a key item (admin/studio call). Creates a key container
+     * owned by the player, with the owner mirrored into the `owner_user_id`
+     * property that the key condition policy reads.
+     */
+    async grantKey(input) {
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.keyType,
+            displayName: input.displayName ?? `Key ${input.keyId}`,
+            ownerUserId: input.toUserId,
+            properties: [
+                { key: 'key_id', valueType: 'string', valueJson: JSON.stringify(input.keyId) },
+                {
+                    key: 'owner_user_id',
+                    valueType: 'int',
+                    valueJson: String(input.toUserId),
+                },
+            ],
+        });
+    }
+    /** List the key items a player holds. */
+    async keysOf(userId) {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.keyType,
+        });
+        return containers.filter((c) => c.ownerUserId != null && String(c.ownerUserId) === String(userId));
+    }
+    /**
+     * Try to open an object. Pass `keyId` (the **container id** of a key the
+     * caller holds) when the object is key-gated; owner/grid/group authorities
+     * need no params. A denial is not an exception — check `success`.
+     */
+    async open(objectId, options = {}) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.openFn,
+            selfContainerId: objectId,
+            params: options.keyId !== undefined ? { key_id: options.keyId } : {},
+        });
+    }
+    /** Try to close an object; same authority as {@link open}. */
+    async close(objectId, options = {}) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.closeFn,
+            selfContainerId: objectId,
+            params: options.keyId !== undefined ? { key_id: options.keyId } : {},
+        });
+    }
+    /** Read whether an object is currently open. */
+    async isOpen(objectId) {
+        const props = await kitContainerProperties(this.gameModel, String(this.appId), objectId);
+        return props.is_open === true;
+    }
+    /** List all objects of this lockable type. */
+    async list(options = {}) {
+        return this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.objectType,
+            ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
+        });
+    }
+}

package/dist/kit/plots.d.ts

@@ -0,0 +1,81 @@
+import type { GameAppsAPI } from '../domains/gameApps.js';
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars, SeedPropertyInput } from '../generated/graphql.js';
+import { type KitInvokeResult } from './shared.js';
+/** Options for {@link PlotsKit}. Must match the deployed plot blueprint. */
+export interface PlotsKitOptions {
+    /** The `typeName` the plot blueprint was deployed with. Defaults to `'Plot'`. */
+    typeName?: string;
+}
+/** A parsed view of one plot. */
+export interface KitPlot {
+    containerId: string;
+    displayName: string;
+    gridId: number;
+    price: number;
+    /** 0 when unowned. */
+    ownerUserId: number;
+    rentPrice?: number;
+    rentTtlSeconds?: number;
+}
+/**
+ * Runtime helpers for the {@link plotBlueprint} conventions: list/create
+ * plots and drive the buy/rent/evict functions whose permission effects grant
+ * or revoke real, replication-enforced grid permissions transactionally with
+ * the currency mutation. Authorization (wallet ownership, price, plot
+ * ownership) is enforced server-side — a denial resolves with
+ * `success: false`, never an exception.
+ *
+ * Obtained via `client.kit(appId).plots`.
+ */
+export declare class PlotsKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly gameApps;
+    private readonly names;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, gameApps: GameAppsAPI, options?: PlotsKitOptions);
+    /**
+     * Instantiate a plot over an existing grid (admin — the type is
+     * admin-instantiable). Create the grid first (`client.gameApps.createGrid`)
+     * and pass its id here.
+     */
+    create(input: {
+        displayName: string;
+        gridId: Scalars['BigInt']['input'];
+        price: number;
+        rentPrice?: number;
+        rentTtlSeconds?: 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 plots with parsed state (grid, price, current owner). */
+    list(): Promise<KitPlot[]>;
+    /**
+     * Buy a plot: spends the price from the caller's wallet AND grants the
+     * blueprint's grid permissions in one transaction. Resolves with the
+     * wallet's remaining balance.
+     */
+    buy(plotId: string, walletId: string): Promise<KitInvokeResult<number>>;
+    /**
+     * Rent a plot (blueprint deployed with `rentable: true`): like {@link buy}
+     * but the grant expires after the plot's `rent_ttl_seconds`.
+     */
+    rent(plotId: string, walletId: string): Promise<KitInvokeResult<number>>;
+    /** Revoke a user's permissions on a plot (plot owner or app admin). */
+    evict(plotId: string, targetUserId: Scalars['BigInt']['input']): Promise<KitInvokeResult>;
+    /**
+     * A user's effective permission keys on a plot's grid (for HUD display —
+     * enforcement happens server-side regardless).
+     */
+    accessOf(userId: Scalars['BigInt']['input'], gridId: Scalars['BigInt']['input']): Promise<string[]>;
+}
+//# sourceMappingURL=plots.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plots.d.ts","sourceRoot":"","sources":["../../src/kit/plots.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE1E,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,4EAA4E;AAC5E,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,iCAAiC;AACjC,MAAM,WAAW,OAAO;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,qBAAa,QAAQ;IAIjB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAL3B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;gBAGf,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EACjC,SAAS,EAAE,YAAY,EACvB,QAAQ,EAAE,WAAW,EACtC,OAAO,GAAE,eAAoB;IAK/B;;;;OAIG;IACG,MAAM,CAAC,KAAK,EAAE;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;QACnC,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;KAClC;;;;;;;;;;;IA0BD,iEAAiE;IAC3D,IAAI,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IA2BhC;;;;OAIG;IACG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAS7E;;;OAGG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;IAS9E,uEAAuE;IACjE,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC;IAS/F;;;OAGG;IACG,QAAQ,CACZ,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EAClC,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,GACjC,OAAO,CAAC,MAAM,EAAE,CAAC;CAQrB"}

package/dist/kit/plots.js

@@ -0,0 +1,113 @@
+import { plotNames } from './blueprints.js';
+import { kitContainerProperties, kitInvoke, } from './shared.js';
+/**
+ * Runtime helpers for the {@link plotBlueprint} conventions: list/create
+ * plots and drive the buy/rent/evict functions whose permission effects grant
+ * or revoke real, replication-enforced grid permissions transactionally with
+ * the currency mutation. Authorization (wallet ownership, price, plot
+ * ownership) is enforced server-side — a denial resolves with
+ * `success: false`, never an exception.
+ *
+ * Obtained via `client.kit(appId).plots`.
+ */
+export class PlotsKit {
+    constructor(appId, gameModel, gameApps, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.gameApps = gameApps;
+        this.names = plotNames(options.typeName);
+    }
+    /**
+     * Instantiate a plot over an existing grid (admin — the type is
+     * admin-instantiable). Create the grid first (`client.gameApps.createGrid`)
+     * and pass its id here.
+     */
+    async create(input) {
+        const properties = [
+            { key: 'grid_id', valueType: 'int', valueJson: String(input.gridId) },
+            { key: 'price', valueType: 'int', valueJson: String(input.price) },
+            ...(input.rentPrice !== undefined
+                ? [{ key: 'rent_price', valueType: 'int', valueJson: String(input.rentPrice) }]
+                : []),
+            ...(input.rentTtlSeconds !== undefined
+                ? [
+                    {
+                        key: 'rent_ttl_seconds',
+                        valueType: 'int',
+                        valueJson: String(input.rentTtlSeconds),
+                    },
+                ]
+                : []),
+            ...(input.properties ?? []),
+        ];
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.plotType,
+            displayName: input.displayName,
+            properties,
+        });
+    }
+    /** List plots with parsed state (grid, price, current owner). */
+    async list() {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.plotType,
+        });
+        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,
+                gridId: Number(props.grid_id ?? 0),
+                price: Number(props.price ?? 0),
+                ownerUserId: Number(props.owner_user_id ?? 0),
+                ...(props.rent_price !== undefined ? { rentPrice: Number(props.rent_price) } : {}),
+                ...(props.rent_ttl_seconds !== undefined
+                    ? { rentTtlSeconds: Number(props.rent_ttl_seconds) }
+                    : {}),
+            };
+        }));
+    }
+    /**
+     * Buy a plot: spends the price from the caller's wallet AND grants the
+     * blueprint's grid permissions in one transaction. Resolves with the
+     * wallet's remaining balance.
+     */
+    async buy(plotId, walletId) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.buyFn,
+            selfContainerId: plotId,
+            params: { wallet_id: walletId },
+        });
+    }
+    /**
+     * Rent a plot (blueprint deployed with `rentable: true`): like {@link buy}
+     * but the grant expires after the plot's `rent_ttl_seconds`.
+     */
+    async rent(plotId, walletId) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.rentFn,
+            selfContainerId: plotId,
+            params: { wallet_id: walletId },
+        });
+    }
+    /** Revoke a user's permissions on a plot (plot owner or app admin). */
+    async evict(plotId, targetUserId) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.evictFn,
+            selfContainerId: plotId,
+            params: { target_user_id: Number(targetUserId) },
+        });
+    }
+    /**
+     * A user's effective permission keys on a plot's grid (for HUD display —
+     * enforcement happens server-side regardless).
+     */
+    async accessOf(userId, gridId) {
+        const res = await this.gameApps.userPermissions(String(this.appId), String(gridId), String(userId));
+        return [...res.permissionKeys];
+    }
+}

package/dist/kit/shared.d.ts

@@ -0,0 +1,32 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { GameModelInvokeMutation } from '../generated/graphql.js';
+/** The raw server result of a `gameModelInvoke` call. */
+export type RawInvokeResult = GameModelInvokeMutation['gameModelInvoke'];
+/**
+ * A kit invoke outcome: the server's authority/evaluation verdict plus the
+ * parsed return value. Authority denials and expression errors are **not**
+ * exceptions — check {@link success}.
+ */
+export interface KitInvokeResult<T = unknown> {
+    /** `false` when the invoke policy denied the caller or the logic errored (rolled back). */
+    success: boolean;
+    /** The parsed `returnValueJson`, when present and `success` is true. */
+    returnValue?: T;
+    /** The server's error message when `success` is false. */
+    errorMessage?: string;
+    /** The full server result (event id, applied mutations, …). */
+    raw: RawInvokeResult;
+}
+/** Wrap a raw invoke result, parsing the JSON return value. */
+export declare function toKitInvokeResult<T>(raw: RawInvokeResult): KitInvokeResult<T>;
+/** Invoke a model function and wrap the result. */
+export declare function kitInvoke<T = unknown>(gameModel: GameModelAPI, input: {
+    appId: string;
+    functionName: string;
+    selfContainerId: string;
+    params?: Record<string, unknown>;
+    sessionId?: string;
+}): Promise<KitInvokeResult<T>>;
+/** Read a container's visible properties as a parsed object. */
+export declare function kitContainerProperties(gameModel: GameModelAPI, appId: string, containerId: string): Promise<Record<string, unknown>>;
+//# sourceMappingURL=shared.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/kit/shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEvE,yDAAyD;AACzD,MAAM,MAAM,eAAe,GAAG,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;AAEzE;;;;GAIG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,2FAA2F;IAC3F,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,WAAW,CAAC,EAAE,CAAC,CAAC;IAChB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,GAAG,EAAE,eAAe,CAAC;CACtB;AAED,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,GAAG,EAAE,eAAe,GAAG,eAAe,CAAC,CAAC,CAAC,CAe7E;AAED,mDAAmD;AACnD,wBAAsB,SAAS,CAAC,CAAC,GAAG,OAAO,EACzC,SAAS,EAAE,YAAY,EACvB,KAAK,EAAE;IACL,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACA,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAS7B;AAED,gEAAgE;AAChE,wBAAsB,sBAAsB,CAC1C,SAAS,EAAE,YAAY,EACvB,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAOlC"}

package/dist/kit/shared.js

@@ -0,0 +1,39 @@
+/** Wrap a raw invoke result, parsing the JSON return value. */
+export function toKitInvokeResult(raw) {
+    let returnValue;
+    if (raw.success && raw.returnValueJson != null) {
+        try {
+            returnValue = JSON.parse(raw.returnValueJson);
+        }
+        catch {
+            returnValue = undefined;
+        }
+    }
+    return {
+        success: raw.success,
+        returnValue,
+        errorMessage: raw.errorMessage ?? undefined,
+        raw,
+    };
+}
+/** Invoke a model function and wrap the result. */
+export async function kitInvoke(gameModel, input) {
+    const raw = await gameModel.invoke({
+        appId: input.appId,
+        functionName: input.functionName,
+        selfContainerId: input.selfContainerId,
+        paramsJson: JSON.stringify(input.params ?? {}),
+        ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+    });
+    return toKitInvokeResult(raw);
+}
+/** Read a container's visible properties as a parsed object. */
+export async function kitContainerProperties(gameModel, appId, containerId) {
+    const state = await gameModel.containerState({ appId, containerId });
+    try {
+        return JSON.parse(state.propertiesJson);
+    }
+    catch {
+        return {};
+    }
+}

package/package.json

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