@crowdedkingdoms/crowdyjs 8.2.0 → 8.3.0

package/dist/kit/blueprints/matches.js

@@ -0,0 +1,246 @@
+import { kitPolicyJson, ownerMirrorProperty, toSnakeCase, trustedAuthorityFields, } from './core.js';
+/** Compute the type/function names a matches blueprint (and its runtime helper) uses. */
+export function matchesNames(typePrefix = '') {
+    const fnPrefix = typePrefix ? `${toSnakeCase(typePrefix)}_` : '';
+    return {
+        metaType: `${typePrefix}MatchMeta`,
+        scoreType: `${typePrefix}Score`,
+        startFn: `${fnPrefix}start_match`,
+        advanceRoundFn: `${fnPrefix}advance_round`,
+        scoreFn: `${fnPrefix}score_points`,
+        endFn: `${fnPrefix}end_match`,
+        turnTickFn: `${fnPrefix}turn_tick`,
+        turnTickAutomation: `${fnPrefix.replace(/_/g, '-')}match-turn-tick`,
+    };
+}
+/** The channel ping every lifecycle function emits post-commit (notify-to-pull). */
+function matchChangedNotification() {
+    return {
+        kind: 'channel',
+        args: [
+            { name: 'channel_id', expression: 'self.channel_id' },
+            { name: 'payload', expression: '"match_changed"' },
+        ],
+    };
+}
+/**
+ * Blueprint for **matches** (lobbies, rounds, turns, scoring) — the
+ * session-layer wrapper every session game needs. Sessions ARE the match
+ * primitive (participants + current turn); this adds a session-scoped
+ * `MatchMeta` (lobby state, round, winner, notification channel) and
+ * per-player `Score` rows.
+ *
+ * Lifecycle functions (`start_match` / `advance_round` / `end_match`) are
+ * creator-or-host gated and declare a **channel notification** — Buddy pings
+ * every channel member post-commit with `"match_changed"`, and clients
+ * re-pull the meta (the notify-to-pull pattern; `kit.matches.onMatchChanged`
+ * wraps the subscription). Turn order itself uses the platform's
+ * `gameModelSetSessionTurn` (the runtime helper calls it — turn authority is
+ * enforced by the service, not an expression).
+ *
+ * End-of-match hooks: attach an event automation to `end_match`
+ * (`function_invoked`) to submit leaderboard scores or adjust ratings.
+ *
+ * Runtime counterpart: `client.kit(appId).matches`.
+ */
+export function matchesBlueprint(options = {}) {
+    const { typePrefix = '', scoreAuthority = 'host', turnTick, ownerIdKind: kind = 'int', } = options;
+    const names = matchesNames(typePrefix);
+    const creatorOrHost = (stateCondition) => {
+        const rules = [
+            {
+                type: 'or',
+                rules: [
+                    { type: 'is_host' },
+                    { type: 'condition', expression: 'self.creator_user_id == $caller_user_id' },
+                ],
+            },
+            { type: 'condition', expression: stateCondition },
+        ];
+        return kitPolicyJson({ type: 'and', rules });
+    };
+    const propertyDefinitions = [
+        {
+            containerTypeName: names.metaType,
+            key: 'creator_user_id',
+            valueType: 'int',
+            defaultValueJson: '0',
+            description: 'The user who created the match (may start/advance/end it).',
+        },
+        {
+            containerTypeName: names.metaType,
+            key: 'mode',
+            valueType: 'string',
+            defaultValueJson: '""',
+            description: "App-defined mode label (e.g. 'ranked', 'ffa').",
+        },
+        {
+            containerTypeName: names.metaType,
+            key: 'state',
+            valueType: 'string',
+            defaultValueJson: '"lobby"',
+            description: "Match lifecycle: 'lobby' | 'active' | 'finished'.",
+        },
+        {
+            containerTypeName: names.metaType,
+            key: 'round',
+            valueType: 'int',
+            defaultValueJson: '0',
+            description: 'Current round (0 in the lobby).',
+        },
+        {
+            containerTypeName: names.metaType,
+            key: 'max_players',
+            valueType: 'int',
+            defaultValueJson: '0',
+            description: 'Advertised player cap (0 = unlimited).',
+        },
+        {
+            containerTypeName: names.metaType,
+            key: 'winner_user_id',
+            valueType: 'int',
+            defaultValueJson: '0',
+            description: 'Set by end_match (0 while unresolved).',
+        },
+        {
+            containerTypeName: names.metaType,
+            key: 'channel_id',
+            valueType: 'int',
+            defaultValueJson: '0',
+            description: 'The per-match channel lifecycle notifications ping (notify-to-pull).',
+        },
+        ...(turnTick
+            ? [
+                {
+                    containerTypeName: names.metaType,
+                    key: 'tick_count',
+                    valueType: 'int',
+                    defaultValueJson: '0',
+                    description: 'Monotonic counter bumped by the turn-tick automation (the wall-clock-free timer).',
+                },
+            ]
+            : []),
+        ownerMirrorProperty(names.scoreType, kind),
+        {
+            containerTypeName: names.scoreType,
+            key: 'points',
+            valueType: 'int',
+            defaultValueJson: '0',
+            description: "One player's score in the match.",
+        },
+    ];
+    const functions = [
+        {
+            name: names.startFn,
+            containerTypeName: names.metaType,
+            returnType: 'string',
+            mutations: [
+                { target: 'self', property: 'state', expression: '"active"' },
+                { target: 'self', property: 'round', expression: '1' },
+            ],
+            returnExpression: 'self.state',
+            invokePolicyJson: creatorOrHost('self.state == "lobby"'),
+            notifications: [matchChangedNotification()],
+            description: 'Start the match (creator or host): lobby → active, round 1; pings the match channel post-commit.',
+        },
+        {
+            name: names.advanceRoundFn,
+            containerTypeName: names.metaType,
+            returnType: 'int',
+            mutations: [{ target: 'self', property: 'round', expression: 'self.round + 1' }],
+            returnExpression: 'self.round',
+            invokePolicyJson: creatorOrHost('self.state == "active"'),
+            notifications: [matchChangedNotification()],
+            description: 'Advance to the next round (creator or host); pings the match channel post-commit.',
+        },
+        {
+            name: names.endFn,
+            containerTypeName: names.metaType,
+            returnType: 'string',
+            parameters: [
+                {
+                    name: 'winner_user_id',
+                    valueType: 'int',
+                    required: true,
+                    description: 'The winning user (0 for a draw).',
+                },
+            ],
+            mutations: [
+                { target: 'self', property: 'state', expression: '"finished"' },
+                { target: 'self', property: 'winner_user_id', expression: '$winner_user_id' },
+            ],
+            returnExpression: 'self.state',
+            invokePolicyJson: creatorOrHost('self.state == "active"'),
+            notifications: [matchChangedNotification()],
+            description: 'Finish the match and record the winner (creator or host); attach an event automation to this function for rating/leaderboard hooks.',
+        },
+        {
+            name: names.scoreFn,
+            containerTypeName: names.scoreType,
+            returnType: 'int',
+            parameters: [
+                {
+                    name: 'points',
+                    valueType: 'int',
+                    required: true,
+                    description: 'Signed points to add.',
+                },
+            ],
+            mutations: [
+                { target: 'self', property: 'points', expression: 'self.points + $points' },
+            ],
+            returnExpression: 'self.points',
+            ...trustedAuthorityFields(scoreAuthority),
+            description: "Add points to a player's Score row — trusted (host-refereed by default).",
+        },
+    ];
+    const automations = [];
+    if (turnTick) {
+        functions.push({
+            name: names.turnTickFn,
+            containerTypeName: names.metaType,
+            returnType: 'int',
+            mutations: [
+                { target: 'self', property: 'tick_count', expression: 'self.tick_count + 1' },
+            ],
+            returnExpression: 'self.tick_count',
+            invokePolicyJson: kitPolicyJson({ type: 'is_automation' }),
+            autonomousInvocable: true,
+            description: 'Server-driven timer tick for active matches (counters instead of wall clocks — expressions have no now()).',
+        });
+        automations.push({
+            name: names.turnTickAutomation,
+            functionName: names.turnTickFn,
+            targetMode: 'type',
+            targetTypeName: names.metaType,
+            triggerType: 'schedule',
+            scheduleKind: 'interval',
+            intervalMs: turnTick.intervalMs,
+            maxTargets: 64,
+            selectorJson: JSON.stringify({
+                selfWhere: [{ key: 'state', op: '==', value: 'active' }],
+            }),
+            description: 'Bumps tick_count on active matches (turn-timeout timer source).',
+        });
+    }
+    return {
+        name: names.metaType,
+        containerTypes: [
+            {
+                typeName: names.metaType,
+                displayName: names.metaType,
+                instantiableBy: 'member',
+                description: 'Session-scoped match record: lobby state, round, winner, notification channel.',
+            },
+            {
+                typeName: names.scoreType,
+                displayName: names.scoreType,
+                instantiableBy: 'member',
+                description: "One player's session-scoped score row.",
+            },
+        ],
+        propertyDefinitions,
+        functions,
+        ...(automations.length ? { automations } : {}),
+    };
+}

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

@@ -0,0 +1,71 @@
+import type { FunctionMutationInput, FunctionParamInput, Scalars, SeedPropertyDefInput } from '../../generated/graphql.js';
+import { type KitBlueprint, type KitSelectorSpec } from './core.js';
+/** A trigger for an NPC behavior: a schedule (interval or cron) or a model event. */
+export type NpcBehaviorTrigger = {
+    intervalMs: number;
+} | {
+    cronExpr: string;
+} | {
+    onEvent: 'function_invoked' | 'property_changed' | 'container_created';
+    functionName?: string;
+    containerTypeName?: string;
+    propertyKey?: string;
+    debounceMs?: number;
+};
+/** One server-driven NPC behavior: a model function plus the automation that drives it. */
+export interface NpcBehaviorSpec {
+    /**
+     * Automation name (unique per app), e.g. `'npc-wander'`. Also derives the
+     * default function name (`npc_wander`).
+     */
+    name: string;
+    /** Entry-point function name. Defaults to the snake-cased behavior name. */
+    functionName?: string;
+    /** The property writes the behavior performs each tick. */
+    mutations: FunctionMutationInput[];
+    /** Typed parameters (bind them from a selector or static `paramsJson`). */
+    parameters?: FunctionParamInput[];
+    /** What makes the behavior run. */
+    trigger: NpcBehaviorTrigger;
+    /**
+     * Selector choosing/filtering targets and binding params (see the Game API
+     * "Autonomous Processes → Selectors" guide), including grid-permission
+     * predicates ({@link KitSelectorSpec}). JSON-encoded at deploy.
+     */
+    selector?: KitSelectorSpec;
+    /**
+     * Convenience: only NPCs whose `role` property equals this act (adds a
+     * `selfWhere` filter when no explicit `selector` is given).
+     */
+    role?: string;
+    /** Fan-out cap per run. Defaults to 8. */
+    maxTargets?: number;
+    /** Static params merged into every call. */
+    params?: Record<string, unknown>;
+    /** Identity the automation acts as; omit for a trusted server caller. */
+    runAsUserId?: Scalars['BigInt']['input'];
+}
+/** Options for {@link npcBlueprint}. */
+export interface NpcBlueprintOptions {
+    /** NPC container type name. Defaults to `'Npc'`. */
+    typeName?: string;
+    /**
+     * Extra property definitions beyond the defaults (`role`, `x`, `y`, `z`,
+     * `behavior_state`, `health`). `containerTypeName` is filled in.
+     */
+    extraProperties?: Omit<SeedPropertyDefInput, 'containerTypeName'>[];
+    /** The server-driven behaviors this NPC archetype has. */
+    behaviors: NpcBehaviorSpec[];
+}
+/** Compute the function/automation names an NPC behavior deploys under. */
+export declare function npcBehaviorFunctionName(behavior: NpcBehaviorSpec): string;
+/**
+ * Blueprint for an **NPC archetype**: an admin-instantiable container type
+ * holding the NPC's durable state, one `autonomousInvocable` model function
+ * per behavior (gated `is_automation` so players cannot puppet them), and the
+ * automations + event triggers that drive those behaviors on the server.
+ *
+ * Runtime counterpart: `client.kit(appId).npcs`.
+ */
+export declare function npcBlueprint(options: NpcBlueprintOptions): KitBlueprint;
+//# sourceMappingURL=npcs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"npcs.d.ts","sourceRoot":"","sources":["../../../src/kit/blueprints/npcs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,kBAAkB,EAClB,OAAO,EAEP,oBAAoB,EACrB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,WAAW,CAAC;AAEnB,qFAAqF;AACrF,MAAM,MAAM,kBAAkB,GAC1B;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GACtB;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GACpB;IACE,OAAO,EAAE,kBAAkB,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEN,2FAA2F;AAC3F,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,SAAS,EAAE,qBAAqB,EAAE,CAAC;IACnC,2EAA2E;IAC3E,UAAU,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAClC,mCAAmC;IACnC,OAAO,EAAE,kBAAkB,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,yEAAyE;IACzE,WAAW,CAAC,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC;CAC1C;AAED,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,eAAe,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,mBAAmB,CAAC,EAAE,CAAC;IACpE,0DAA0D;IAC1D,SAAS,EAAE,eAAe,EAAE,CAAC;CAC9B;AAED,2EAA2E;AAC3E,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,CAEzE;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAmHvE"}

package/dist/kit/blueprints/npcs.js

@@ -0,0 +1,122 @@
+import { kitPolicyJson, toSnakeCase, } from './core.js';
+/** Compute the function/automation names an NPC behavior deploys under. */
+export function npcBehaviorFunctionName(behavior) {
+    return behavior.functionName ?? toSnakeCase(behavior.name);
+}
+/**
+ * Blueprint for an **NPC archetype**: an admin-instantiable container type
+ * holding the NPC's durable state, one `autonomousInvocable` model function
+ * per behavior (gated `is_automation` so players cannot puppet them), and the
+ * automations + event triggers that drive those behaviors on the server.
+ *
+ * Runtime counterpart: `client.kit(appId).npcs`.
+ */
+export function npcBlueprint(options) {
+    const typeName = options.typeName ?? 'Npc';
+    if (options.behaviors.length === 0) {
+        throw new Error('npcBlueprint requires at least one behavior');
+    }
+    const propertyDefinitions = [
+        {
+            containerTypeName: typeName,
+            key: 'role',
+            valueType: 'string',
+            defaultValueJson: '""',
+        },
+        { containerTypeName: typeName, key: 'x', valueType: 'float', defaultValueJson: '0' },
+        { containerTypeName: typeName, key: 'y', valueType: 'float', defaultValueJson: '0' },
+        { containerTypeName: typeName, key: 'z', valueType: 'float', defaultValueJson: '0' },
+        {
+            containerTypeName: typeName,
+            key: 'behavior_state',
+            valueType: 'string',
+            defaultValueJson: '"idle"',
+        },
+        {
+            containerTypeName: typeName,
+            key: 'health',
+            valueType: 'int',
+            defaultValueJson: '100',
+        },
+        ...(options.extraProperties ?? []).map((p) => ({
+            ...p,
+            containerTypeName: typeName,
+        })),
+    ];
+    const functions = [];
+    const automations = [];
+    const automationTriggers = [];
+    for (const behavior of options.behaviors) {
+        const functionName = npcBehaviorFunctionName(behavior);
+        functions.push({
+            name: functionName,
+            containerTypeName: typeName,
+            parameters: behavior.parameters,
+            mutations: behavior.mutations,
+            invokePolicyJson: kitPolicyJson({ type: 'is_automation' }),
+            autonomousInvocable: true,
+            description: `Server-driven NPC behavior for the '${behavior.name}' automation.`,
+        });
+        const selector = behavior.selector ??
+            (behavior.role !== undefined
+                ? { selfWhere: [{ key: 'role', op: '==', value: behavior.role }] }
+                : undefined);
+        const automation = {
+            name: behavior.name,
+            functionName,
+            targetMode: 'type',
+            targetTypeName: typeName,
+            maxTargets: behavior.maxTargets ?? 8,
+            ...(selector ? { selectorJson: JSON.stringify(selector) } : {}),
+            ...(behavior.params ? { paramsJson: JSON.stringify(behavior.params) } : {}),
+            ...(behavior.runAsUserId !== undefined
+                ? { runAsUserId: behavior.runAsUserId }
+                : {}),
+        };
+        if ('intervalMs' in behavior.trigger) {
+            automation.triggerType = 'schedule';
+            automation.scheduleKind = 'interval';
+            automation.intervalMs = behavior.trigger.intervalMs;
+        }
+        else if ('cronExpr' in behavior.trigger) {
+            automation.triggerType = 'schedule';
+            automation.scheduleKind = 'cron';
+            automation.cronExpr = behavior.trigger.cronExpr;
+        }
+        else {
+            automation.triggerType = 'event';
+            automationTriggers.push({
+                automationName: behavior.name,
+                onEvent: behavior.trigger.onEvent,
+                ...(behavior.trigger.functionName !== undefined
+                    ? { functionName: behavior.trigger.functionName }
+                    : {}),
+                ...(behavior.trigger.containerTypeName !== undefined
+                    ? { containerTypeName: behavior.trigger.containerTypeName }
+                    : {}),
+                ...(behavior.trigger.propertyKey !== undefined
+                    ? { propertyKey: behavior.trigger.propertyKey }
+                    : {}),
+                ...(behavior.trigger.debounceMs !== undefined
+                    ? { debounceMs: behavior.trigger.debounceMs }
+                    : {}),
+            });
+        }
+        automations.push(automation);
+    }
+    return {
+        name: typeName,
+        containerTypes: [
+            {
+                typeName,
+                displayName: typeName,
+                instantiableBy: 'admin',
+                description: 'A server-driven non-player character.',
+            },
+        ],
+        propertyDefinitions,
+        functions,
+        automations,
+        automationTriggers,
+    };
+}

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

@@ -0,0 +1,54 @@
+import { type KitBlueprint, type KitInvokePolicy } from './core.js';
+/** Options for {@link plotBlueprint}. */
+export interface PlotBlueprintOptions {
+    /** Plot container type name. Defaults to `'Plot'`. */
+    typeName?: string;
+    /**
+     * Runtime permission keys buying/renting grants on the plot's grid.
+     * Defaults to `['access', 'update_voxel_data']`.
+     */
+    permissionKeys?: string[];
+    /** Currency property on the wallet container. Defaults to `'gold'`. */
+    currencyProperty?: string;
+    /**
+     * Property on the wallet container mirroring its owner's user id (the
+     * standard kit convention, since expressions can't read container
+     * ownership). Defaults to `'owner_user_id'`.
+     */
+    walletOwnerProperty?: string;
+    /**
+     * Also generate `rent_plot`: a TTL grant priced by the plot's `rent_price`
+     * property, expiring after `rent_ttl_seconds`. Defaults to false.
+     */
+    rentable?: boolean;
+    /**
+     * Extra policy rule AND'ed into `buy_plot` — e.g.
+     * `featureGate('land_owner')` to sell land only to a paid tier.
+     */
+    buyPolicyExtra?: KitInvokePolicy;
+    /** Extra policy rule AND'ed into `rent_plot`. */
+    rentPolicyExtra?: KitInvokePolicy;
+}
+/** Names derived by {@link plotBlueprint} for a given plot type. */
+export interface PlotNames {
+    plotType: string;
+    buyFn: string;
+    rentFn: string;
+    evictFn: string;
+}
+/** Compute the type/function names a plot blueprint (and its runtime helper) uses. */
+export declare function plotNames(typeName?: string): PlotNames;
+/**
+ * Blueprint for **sellable/rentable land**: a `Plot` container mapping a world
+ * [grid](../../domains/gameApps.js) to a price, whose `buy`/`rent` functions
+ * consume currency AND grant runtime grid permissions in one transaction (via
+ * permission effects) — the canonical read+write permission loop. Buying sets
+ * the plot's `owner_user_id`; renting grants with a TTL; `evict` revokes.
+ * The grants are enforced by the replication layer on movement/voxel writes
+ * immediately at commit. Requires game-api v0.13.11+ (effects) — pair with
+ * chunk-permission locks (v0.13.12+) for doors that honor the purchase.
+ *
+ * Runtime counterpart: `client.kit(appId).plots`.
+ */
+export declare function plotBlueprint(options?: PlotBlueprintOptions): KitBlueprint;
+//# sourceMappingURL=plots.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"plots.d.ts","sourceRoot":"","sources":["../../../src/kit/blueprints/plots.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,WAAW,CAAC;AAEnB,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,cAAc,CAAC,EAAE,eAAe,CAAC;IACjC,iDAAiD;IACjD,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED,oEAAoE;AACpE,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,QAAQ,SAAS,GAAG,SAAS,CAQtD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,YAAY,CAyI9E"}

package/dist/kit/blueprints/plots.js

@@ -0,0 +1,146 @@
+import { andPolicies, kitPolicyJson, toSnakeCase, } from './core.js';
+/** Compute the type/function names a plot blueprint (and its runtime helper) uses. */
+export function plotNames(typeName = 'Plot') {
+    const snake = toSnakeCase(typeName);
+    return {
+        plotType: typeName,
+        buyFn: `buy_${snake}`,
+        rentFn: `rent_${snake}`,
+        evictFn: `evict_${snake}`,
+    };
+}
+/**
+ * Blueprint for **sellable/rentable land**: a `Plot` container mapping a world
+ * [grid](../../domains/gameApps.js) to a price, whose `buy`/`rent` functions
+ * consume currency AND grant runtime grid permissions in one transaction (via
+ * permission effects) — the canonical read+write permission loop. Buying sets
+ * the plot's `owner_user_id`; renting grants with a TTL; `evict` revokes.
+ * The grants are enforced by the replication layer on movement/voxel writes
+ * immediately at commit. Requires game-api v0.13.11+ (effects) — pair with
+ * chunk-permission locks (v0.13.12+) for doors that honor the purchase.
+ *
+ * Runtime counterpart: `client.kit(appId).plots`.
+ */
+export function plotBlueprint(options = {}) {
+    const names = plotNames(options.typeName);
+    const keys = options.permissionKeys ?? ['access', 'update_voxel_data'];
+    const currency = options.currencyProperty ?? 'gold';
+    const walletOwner = options.walletOwnerProperty ?? 'owner_user_id';
+    const rentable = options.rentable ?? false;
+    const walletParam = [
+        { name: 'wallet_id', valueType: 'container_ref', required: true },
+    ];
+    const walletGuard = (priceExpr, extra) => kitPolicyJson(andPolicies({
+        type: 'condition',
+        expression: `ref($wallet_id).${walletOwner} == $caller_user_id && ref($wallet_id).${currency} >= ${priceExpr}`,
+    }, extra));
+    const propertyDefinitions = [
+        { containerTypeName: names.plotType, key: 'grid_id', valueType: 'int' },
+        { containerTypeName: names.plotType, key: 'price', valueType: 'int', defaultValueJson: '0' },
+        {
+            containerTypeName: names.plotType,
+            key: 'owner_user_id',
+            valueType: 'int',
+            defaultValueJson: '0',
+        },
+    ];
+    if (rentable) {
+        propertyDefinitions.push({
+            containerTypeName: names.plotType,
+            key: 'rent_price',
+            valueType: 'int',
+            defaultValueJson: '0',
+        }, {
+            containerTypeName: names.plotType,
+            key: 'rent_ttl_seconds',
+            valueType: 'int',
+            defaultValueJson: '86400',
+        });
+    }
+    const functions = [
+        {
+            name: names.buyFn,
+            containerTypeName: names.plotType,
+            returnType: 'int',
+            parameters: walletParam,
+            mutations: [
+                {
+                    target: 'ref($wallet_id)',
+                    property: currency,
+                    expression: `ref($wallet_id).${currency} - self.price`,
+                },
+                { target: 'self', property: 'owner_user_id', expression: '$caller_user_id' },
+            ],
+            permissionEffects: [
+                {
+                    action: 'grant',
+                    permissionKeys: keys,
+                    userExpression: '$caller_user_id',
+                    gridIdExpression: 'self.grid_id',
+                },
+            ],
+            returnExpression: `ref($wallet_id).${currency}`,
+            invokePolicyJson: walletGuard('self.price', options.buyPolicyExtra),
+            description: 'Buy this plot: spend the price AND receive grid permissions atomically.',
+        },
+        {
+            name: names.evictFn,
+            containerTypeName: names.plotType,
+            parameters: [{ name: 'target_user_id', valueType: 'int', required: true }],
+            mutations: [],
+            permissionEffects: [
+                {
+                    action: 'revoke',
+                    permissionKeys: keys,
+                    userExpression: '$target_user_id',
+                    gridIdExpression: 'self.grid_id',
+                },
+            ],
+            invokePolicyJson: kitPolicyJson({
+                type: 'condition',
+                expression: 'self.owner_user_id == $caller_user_id',
+            }),
+            description: "Revoke a user's permissions on this plot (owner-gated; admins bypass).",
+        },
+    ];
+    if (rentable) {
+        functions.push({
+            name: names.rentFn,
+            containerTypeName: names.plotType,
+            returnType: 'int',
+            parameters: walletParam,
+            mutations: [
+                {
+                    target: 'ref($wallet_id)',
+                    property: currency,
+                    expression: `ref($wallet_id).${currency} - self.rent_price`,
+                },
+            ],
+            permissionEffects: [
+                {
+                    action: 'grant',
+                    permissionKeys: keys,
+                    userExpression: '$caller_user_id',
+                    gridIdExpression: 'self.grid_id',
+                    ttlSecondsExpression: 'self.rent_ttl_seconds',
+                },
+            ],
+            returnExpression: `ref($wallet_id).${currency}`,
+            invokePolicyJson: walletGuard('self.rent_price', options.rentPolicyExtra),
+            description: 'Rent this plot: spend the rent AND receive an expiring grid grant atomically.',
+        });
+    }
+    return {
+        name: names.plotType,
+        containerTypes: [
+            {
+                typeName: names.plotType,
+                displayName: names.plotType,
+                instantiableBy: 'admin',
+                description: 'A sellable/rentable plot of land mapped to a world grid.',
+            },
+        ],
+        propertyDefinitions,
+        functions,
+    };
+}