@crowdedkingdoms/crowdyjs 8.2.0 → 8.3.0

package/dist/kit/blueprints/guild.js

@@ -0,0 +1,50 @@
+import { composeBlueprints } from './core.js';
+import { inventoryBlueprint, inventoryNames } from './inventory.js';
+import { lockBlueprint, lockNames } from './locks.js';
+/** Compute the type/function names a guild blueprint (and kit.social.guild) uses. */
+export function guildNames(typePrefix = 'Guild') {
+    const locks = lockNames(`${typePrefix}Hall`);
+    const bank = inventoryNames(`${typePrefix}Bank`);
+    return {
+        hallType: locks.objectType,
+        openHallFn: locks.openFn,
+        closeHallFn: locks.closeFn,
+        bankTypePrefix: `${typePrefix}Bank`,
+        bankInventoryType: bank.inventoryType,
+        bankStackType: bank.stackType,
+    };
+}
+/**
+ * Composite blueprint for a **guild's shared assets** — a demonstration of
+ * blueprint composition: a `GuildHall` lockable whose open/close is gated on
+ * membership of the guild team (`group_permission`), plus a prefixed
+ * guild-bank inventory (`GuildBankInventory` / `GuildBankItemStack`) for
+ * shared storage. The guild itself is a **team** (`kit.social.guild`), its
+ * chat a **channel**, and its territory a grid group-grant
+ * (`kit.social.guild.claimTerritory`) — no new model surface needed for
+ * those.
+ *
+ * Runtime counterparts: `client.kit(appId).social.guild` (team/chat/territory),
+ * `kit.objectsFor(guildNames().hallType)` (the hall), and
+ * `client.kit(appId, { inventory: { typePrefix: guildNames().bankTypePrefix } })
+ * .inventory` (the bank).
+ */
+export function guildBlueprint(options) {
+    const { typePrefix = 'Guild', guildGroupId, hallPermission, bank = true } = options;
+    if (!guildGroupId) {
+        throw new Error('guildBlueprint requires guildGroupId — create the guild team first, then deploy');
+    }
+    const hall = lockBlueprint({
+        objectTypeName: `${typePrefix}Hall`,
+        authority: {
+            kind: 'groupPermission',
+            groupId: guildGroupId,
+            ...(hallPermission !== undefined ? { permission: hallPermission } : {}),
+        },
+    });
+    const blueprints = [hall];
+    if (bank) {
+        blueprints.push(inventoryBlueprint({ typePrefix: `${typePrefix}Bank` }));
+    }
+    return composeBlueprints(typePrefix.toLowerCase(), blueprints);
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Blueprint builders for the Game Kit, one module per game concept, re-exported
+ * here as a stable barrel (import paths from `kit/index.js` and the package
+ * root are unchanged as builders are added).
+ */
+export { andPolicies, composeBlueprints, featureGate, kitPolicyJson, mergeBlueprints, ownerEquals, ownerEqualsCaller, ownerMirrorProperty, toSnakeCase, trustedAuthorityFields, type KitAutomationSpec, type KitAutomationTriggerSpec, type KitBlueprint, type KitInvokePolicy, type KitOwnerIdKind, type KitSelectorSpec, type KitTrustedAuthority, type MergedBlueprints, type SelectorPermissionPredicate, } from './core.js';
+export { combatBlueprint, combatNames, type CombatBlueprintOptions, type CombatNames, } from './combat.js';
+export { decksBlueprint, decksNames, type DecksBlueprintOptions, type DecksNames, } from './decks.js';
+export { economyBlueprint, economyCurrencyFn, economyNames, type EconomyBlueprintOptions, type EconomyNames, } from './economy.js';
+export { guildBlueprint, guildNames, type GuildBlueprintOptions, type GuildNames, } from './guild.js';
+export { inventoryBlueprint, inventoryNames, type InventoryBlueprintOptions, type InventoryNames, } from './inventory.js';
+export { leaderboardsBlueprint, leaderboardsNames, type LeaderboardsBlueprintOptions, type LeaderboardsNames, } from './leaderboards.js';
+export { lootBlueprint, lootNames, lootRollFn, type LootBlueprintOptions, type LootDropSpec, type LootEntrySpec, type LootNames, type LootTableSpec, } from './loot.js';
+export { lockBlueprint, lockNames, type LockAuthority, type LockBlueprintOptions, type LockNames, } from './locks.js';
+export { questsBlueprint, questsNames, type QuestAdvanceSpec, type QuestsBlueprintOptions, type QuestsNames, } from './quests.js';
+export { progressionBlueprint, progressionNames, type ProgressionBlueprintOptions, type ProgressionNames, } from './progression.js';
+export { plotBlueprint, plotNames, type PlotBlueprintOptions, type PlotNames, } from './plots.js';
+export { matchesBlueprint, matchesNames, type MatchesBlueprintOptions, type MatchesNames, } from './matches.js';
+export { npcBehaviorFunctionName, npcBlueprint, type NpcBehaviorSpec, type NpcBehaviorTrigger, type NpcBlueprintOptions, } from './npcs.js';
+export { worldsimBlueprint, worldsimNames, type WorldsimBlueprintOptions, type WorldsimNames, } from './worldsim.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/kit/blueprints/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,eAAe,EACf,WAAW,EACX,iBAAiB,EACjB,mBAAmB,EACnB,WAAW,EACX,sBAAsB,EACtB,KAAK,iBAAiB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,2BAA2B,GACjC,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,eAAe,EACf,WAAW,EACX,KAAK,sBAAsB,EAC3B,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,cAAc,EACd,UAAU,EACV,KAAK,qBAAqB,EAC1B,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,KAAK,uBAAuB,EAC5B,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,cAAc,EACd,UAAU,EACV,KAAK,qBAAqB,EAC1B,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,KAAK,yBAAyB,EAC9B,KAAK,cAAc,GACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,KAAK,4BAA4B,EACjC,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,aAAa,EACb,SAAS,EACT,UAAU,EACV,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,aAAa,GACnB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,aAAa,EACb,SAAS,EACT,KAAK,aAAa,EAClB,KAAK,oBAAoB,EACzB,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,2BAA2B,EAChC,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,aAAa,EACb,SAAS,EACT,KAAK,oBAAoB,EACzB,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,KAAK,uBAAuB,EAC5B,KAAK,YAAY,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,uBAAuB,EACvB,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,iBAAiB,EACjB,aAAa,EACb,KAAK,wBAAwB,EAC7B,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC"}

package/dist/kit/blueprints/index.js

@@ -0,0 +1,20 @@
+/**
+ * Blueprint builders for the Game Kit, one module per game concept, re-exported
+ * here as a stable barrel (import paths from `kit/index.js` and the package
+ * root are unchanged as builders are added).
+ */
+export { andPolicies, composeBlueprints, featureGate, kitPolicyJson, mergeBlueprints, ownerEquals, ownerEqualsCaller, ownerMirrorProperty, toSnakeCase, trustedAuthorityFields, } from './core.js';
+export { combatBlueprint, combatNames, } from './combat.js';
+export { decksBlueprint, decksNames, } from './decks.js';
+export { economyBlueprint, economyCurrencyFn, economyNames, } from './economy.js';
+export { guildBlueprint, guildNames, } from './guild.js';
+export { inventoryBlueprint, inventoryNames, } from './inventory.js';
+export { leaderboardsBlueprint, leaderboardsNames, } from './leaderboards.js';
+export { lootBlueprint, lootNames, lootRollFn, } from './loot.js';
+export { lockBlueprint, lockNames, } from './locks.js';
+export { questsBlueprint, questsNames, } from './quests.js';
+export { progressionBlueprint, progressionNames, } from './progression.js';
+export { plotBlueprint, plotNames, } from './plots.js';
+export { matchesBlueprint, matchesNames, } from './matches.js';
+export { npcBehaviorFunctionName, npcBlueprint, } from './npcs.js';
+export { worldsimBlueprint, worldsimNames, } from './worldsim.js';

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

@@ -0,0 +1,38 @@
+import { type KitBlueprint } from './core.js';
+/** Options for {@link inventoryBlueprint}. */
+export interface InventoryBlueprintOptions {
+    /**
+     * Prefix applied to the container type names (e.g. `'Bank'` →
+     * `BankInventory` / `BankItemStack`) and, snake-cased, to the function
+     * names (`bank_grant_stack`, …). Lets several independent inventory systems
+     * coexist in one app. Defaults to none.
+     */
+    typePrefix?: string;
+    /** Default `max_slots` on new inventories. Defaults to 24. */
+    maxSlots?: number;
+    /** Exclusive upper bound for stack `slot` indexes. Defaults to 64. */
+    slotCount?: number;
+}
+/** Names derived by {@link inventoryBlueprint} for a given prefix. */
+export interface InventoryNames {
+    inventoryType: string;
+    stackType: string;
+    grantFn: string;
+    consumeFn: string;
+    moveFn: string;
+    transferFn: string;
+    containsEdge: string;
+}
+/** Compute the type/function names an inventory blueprint (and its runtime helper) uses. */
+export declare function inventoryNames(typePrefix?: string): InventoryNames;
+/**
+ * Blueprint for a server-authoritative **inventory**: a per-player
+ * `Inventory` container plus `ItemStack` containers (`item_id`, `quantity`,
+ * `slot`), and owner-gated functions to grant, consume, move, and transfer
+ * stacks. Quantity guards live in the invoke policies, so an untrusted client
+ * can never overdraw or touch another player's items.
+ *
+ * Runtime counterpart: `client.kit(appId).inventory`.
+ */
+export declare function inventoryBlueprint(options?: InventoryBlueprintOptions): KitBlueprint;
+//# sourceMappingURL=inventory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inventory.d.ts","sourceRoot":"","sources":["../../../src/kit/blueprints/inventory.ts"],"names":[],"mappings":"AACA,OAAO,EAA8B,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAE1E,8CAA8C;AAC9C,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,sEAAsE;AACtE,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,UAAU,SAAK,GAAG,cAAc,CAW9D;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,GAAE,yBAA8B,GACtC,YAAY,CAyId"}

package/dist/kit/blueprints/inventory.js

@@ -0,0 +1,157 @@
+import { kitPolicyJson, toSnakeCase } from './core.js';
+/** Compute the type/function names an inventory blueprint (and its runtime helper) uses. */
+export function inventoryNames(typePrefix = '') {
+    const fnPrefix = typePrefix ? `${toSnakeCase(typePrefix)}_` : '';
+    return {
+        inventoryType: `${typePrefix}Inventory`,
+        stackType: `${typePrefix}ItemStack`,
+        grantFn: `${fnPrefix}grant_stack`,
+        consumeFn: `${fnPrefix}consume_stack`,
+        moveFn: `${fnPrefix}move_stack`,
+        transferFn: `${fnPrefix}transfer_stack`,
+        containsEdge: 'inventory_contains',
+    };
+}
+/**
+ * Blueprint for a server-authoritative **inventory**: a per-player
+ * `Inventory` container plus `ItemStack` containers (`item_id`, `quantity`,
+ * `slot`), and owner-gated functions to grant, consume, move, and transfer
+ * stacks. Quantity guards live in the invoke policies, so an untrusted client
+ * can never overdraw or touch another player's items.
+ *
+ * Runtime counterpart: `client.kit(appId).inventory`.
+ */
+export function inventoryBlueprint(options = {}) {
+    const { typePrefix = '', maxSlots = 24, slotCount = 64 } = options;
+    const names = inventoryNames(typePrefix);
+    const ownerOnly = kitPolicyJson({ type: 'owner_of_self' });
+    return {
+        name: names.inventoryType,
+        containerTypes: [
+            {
+                typeName: names.inventoryType,
+                displayName: names.inventoryType,
+                instantiableBy: 'member',
+                description: 'A bag of item stacks owned by one player.',
+            },
+            {
+                typeName: names.stackType,
+                displayName: names.stackType,
+                instantiableBy: 'member',
+                description: 'One stack of a single item type in an inventory slot.',
+            },
+        ],
+        propertyDefinitions: [
+            {
+                containerTypeName: names.inventoryType,
+                key: 'max_slots',
+                valueType: 'int',
+                defaultValueJson: String(maxSlots),
+            },
+            { containerTypeName: names.stackType, key: 'item_id', valueType: 'string' },
+            {
+                containerTypeName: names.stackType,
+                key: 'owner_user_id',
+                valueType: 'int',
+                defaultValueJson: '0',
+                description: "Mirror of the stack owner's user id (kit convention), read by cross-container guards such as the economy trade/market functions.",
+            },
+            {
+                containerTypeName: names.stackType,
+                key: 'quantity',
+                valueType: 'int',
+                defaultValueJson: '0',
+            },
+            {
+                containerTypeName: names.stackType,
+                key: 'slot',
+                valueType: 'int',
+                defaultValueJson: '0',
+            },
+        ],
+        functions: [
+            {
+                name: names.grantFn,
+                containerTypeName: names.stackType,
+                returnType: 'int',
+                parameters: [{ name: 'amount', valueType: 'int', required: true }],
+                mutations: [
+                    {
+                        target: 'self',
+                        property: 'quantity',
+                        expression: 'self.quantity + max(0, $amount)',
+                    },
+                ],
+                returnExpression: 'self.quantity',
+                invokePolicyJson: ownerOnly,
+                description: 'Add items to a stack the caller owns.',
+            },
+            {
+                name: names.consumeFn,
+                containerTypeName: names.stackType,
+                returnType: 'int',
+                parameters: [{ name: 'amount', valueType: 'int', required: true }],
+                mutations: [
+                    { target: 'self', property: 'quantity', expression: 'self.quantity - $amount' },
+                ],
+                returnExpression: 'self.quantity',
+                invokePolicyJson: kitPolicyJson({
+                    type: 'and',
+                    rules: [
+                        { type: 'owner_of_self' },
+                        {
+                            type: 'condition',
+                            expression: '$amount > 0 && self.quantity >= $amount',
+                        },
+                    ],
+                }),
+                description: 'Spend items from a stack; refuses to overdraw.',
+            },
+            {
+                name: names.moveFn,
+                containerTypeName: names.stackType,
+                returnType: 'int',
+                parameters: [{ name: 'to_slot', valueType: 'int', required: true }],
+                mutations: [
+                    {
+                        target: 'self',
+                        property: 'slot',
+                        expression: `clamp($to_slot, 0, ${slotCount - 1})`,
+                    },
+                ],
+                returnExpression: 'self.slot',
+                invokePolicyJson: ownerOnly,
+                description: 'Move a stack to another slot.',
+            },
+            {
+                name: names.transferFn,
+                containerTypeName: names.stackType,
+                returnType: 'int',
+                parameters: [
+                    { name: 'to_id', valueType: 'container_ref', required: true },
+                    { name: 'amount', valueType: 'int', required: true },
+                ],
+                mutations: [
+                    { target: 'self', property: 'quantity', expression: 'self.quantity - $amount' },
+                    {
+                        target: 'ref($to_id)',
+                        property: 'quantity',
+                        expression: 'ref($to_id).quantity + $amount',
+                    },
+                ],
+                returnExpression: 'self.quantity',
+                invokePolicyJson: kitPolicyJson({
+                    type: 'and',
+                    rules: [
+                        { type: 'owner_of_self' },
+                        {
+                            type: 'condition',
+                            expression: '$amount > 0 && self.quantity >= $amount && ref($to_id).item_id == self.item_id',
+                        },
+                    ],
+                }),
+                description: 'Atomically move items between two stacks of the same item type.',
+            },
+        ],
+    };
+}

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

@@ -0,0 +1,49 @@
+import { type KitBlueprint, type KitOwnerIdKind, type KitTrustedAuthority } from './core.js';
+/** Options for {@link leaderboardsBlueprint}. */
+export interface LeaderboardsBlueprintOptions {
+    /** Prefix for the type/function names. Defaults to none. */
+    typePrefix?: string;
+    /**
+     * Who may submit scores: `'host'` (the elected host referees; default),
+     * `'server'` (app admins / studio backend), or `'automation'` (e.g. an
+     * event automation on the match layer's `end_match`).
+     */
+    submitAuthority?: KitTrustedAuthority;
+    /**
+     * When true (default), submitting keeps the best score
+     * (`max(self.score, $points)`); when false, submissions overwrite.
+     */
+    keepBest?: boolean;
+    /**
+     * When set, adds a cron automation that rolls the season: bumps `season`
+     * and resets `score`/`rank` on EVERY entry (e.g. `'0 0 1 * *'` for
+     * monthly seasons).
+     */
+    seasonCron?: string;
+    /** Owner-mirror typing (see the kit convention). Defaults to `'int'`. */
+    ownerIdKind?: KitOwnerIdKind;
+}
+/** Names derived by {@link leaderboardsBlueprint} for a given prefix. */
+export interface LeaderboardsNames {
+    entryType: string;
+    submitFn: string;
+    rollSeasonFn: string;
+    seasonAutomation: string;
+}
+/** Compute the type/function names a leaderboards blueprint (and its runtime helper) uses. */
+export declare function leaderboardsNames(typePrefix?: string): LeaderboardsNames;
+/**
+ * Blueprint for **leaderboards**: per-player `LeaderboardEntry` rows keyed
+ * by a `board_id`, written only through the trusted `submit_score`
+ * (host-refereed by default — configure `submitAuthority`), with optional
+ * cron **season rolls**.
+ *
+ * Ranking is honest about the platform: container lists have no server-side
+ * ORDER BY, so `kit.leaderboards.top()` fetches a board's entries and sorts
+ * client-side — fine for the few hundred entries a per-app board holds.
+ * Automation selectors' `pick: highest` covers server-side top-1 needs.
+ *
+ * Runtime counterpart: `client.kit(appId).leaderboards`.
+ */
+export declare function leaderboardsBlueprint(options?: LeaderboardsBlueprintOptions): KitBlueprint;
+//# sourceMappingURL=leaderboards.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"leaderboards.d.ts","sourceRoot":"","sources":["../../../src/kit/blueprints/leaderboards.ts"],"names":[],"mappings":"AAIA,OAAO,EAML,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACzB,MAAM,WAAW,CAAC;AAEnB,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,eAAe,CAAC,EAAE,mBAAmB,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,WAAW,CAAC,EAAE,cAAc,CAAC;CAC9B;AAED,yEAAyE;AACzE,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,UAAU,SAAK,GAAG,iBAAiB,CAQpE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,GAAE,4BAAiC,GACzC,YAAY,CAiHd"}

package/dist/kit/blueprints/leaderboards.js

@@ -0,0 +1,126 @@
+import { kitPolicyJson, ownerMirrorProperty, toSnakeCase, trustedAuthorityFields, } from './core.js';
+/** Compute the type/function names a leaderboards blueprint (and its runtime helper) uses. */
+export function leaderboardsNames(typePrefix = '') {
+    const fnPrefix = typePrefix ? `${toSnakeCase(typePrefix)}_` : '';
+    return {
+        entryType: `${typePrefix}LeaderboardEntry`,
+        submitFn: `${fnPrefix}submit_score`,
+        rollSeasonFn: `${fnPrefix}roll_season`,
+        seasonAutomation: `${fnPrefix.replace(/_/g, '-')}season-roll`,
+    };
+}
+/**
+ * Blueprint for **leaderboards**: per-player `LeaderboardEntry` rows keyed
+ * by a `board_id`, written only through the trusted `submit_score`
+ * (host-refereed by default — configure `submitAuthority`), with optional
+ * cron **season rolls**.
+ *
+ * Ranking is honest about the platform: container lists have no server-side
+ * ORDER BY, so `kit.leaderboards.top()` fetches a board's entries and sorts
+ * client-side — fine for the few hundred entries a per-app board holds.
+ * Automation selectors' `pick: highest` covers server-side top-1 needs.
+ *
+ * Runtime counterpart: `client.kit(appId).leaderboards`.
+ */
+export function leaderboardsBlueprint(options = {}) {
+    const { typePrefix = '', submitAuthority = 'host', keepBest = true, seasonCron, ownerIdKind: kind = 'int', } = options;
+    const names = leaderboardsNames(typePrefix);
+    const propertyDefinitions = [
+        ownerMirrorProperty(names.entryType, kind),
+        {
+            containerTypeName: names.entryType,
+            key: 'board_id',
+            valueType: 'string',
+            defaultValueJson: '""',
+            description: "Which leaderboard this entry belongs to (e.g. 'weekly_kills').",
+        },
+        {
+            containerTypeName: names.entryType,
+            key: 'score',
+            valueType: 'int',
+            defaultValueJson: '0',
+            description: 'The ranked score, written only through submit_score.',
+        },
+        {
+            containerTypeName: names.entryType,
+            key: 'season',
+            valueType: 'int',
+            defaultValueJson: '1',
+            description: 'Season counter, bumped by the season-roll automation.',
+        },
+        {
+            containerTypeName: names.entryType,
+            key: 'rank',
+            valueType: 'int',
+            defaultValueJson: '0',
+            description: 'Optional stamped rank (0 = unstamped; ranking is client-side by default).',
+        },
+    ];
+    const functions = [
+        {
+            name: names.submitFn,
+            containerTypeName: names.entryType,
+            returnType: 'int',
+            parameters: [
+                {
+                    name: 'points',
+                    valueType: 'int',
+                    required: true,
+                    description: 'The score to submit.',
+                },
+            ],
+            mutations: [
+                {
+                    target: 'self',
+                    property: 'score',
+                    expression: keepBest ? 'max(self.score, $points)' : '$points',
+                },
+            ],
+            returnExpression: 'self.score',
+            ...trustedAuthorityFields(submitAuthority),
+            description: `Trusted score submission (${keepBest ? 'keeps the best score' : 'overwrites'}); never a plain player call.`,
+        },
+    ];
+    const automations = [];
+    if (seasonCron !== undefined) {
+        functions.push({
+            name: names.rollSeasonFn,
+            containerTypeName: names.entryType,
+            returnType: 'int',
+            mutations: [
+                { target: 'self', property: 'season', expression: 'self.season + 1' },
+                { target: 'self', property: 'score', expression: '0' },
+                { target: 'self', property: 'rank', expression: '0' },
+            ],
+            returnExpression: 'self.season',
+            invokePolicyJson: kitPolicyJson({ type: 'is_automation' }),
+            autonomousInvocable: true,
+            description: 'Season roll (automation-only): bumps the season and resets scores.',
+        });
+        automations.push({
+            name: names.seasonAutomation,
+            functionName: names.rollSeasonFn,
+            targetMode: 'type',
+            targetTypeName: names.entryType,
+            triggerType: 'schedule',
+            scheduleKind: 'cron',
+            cronExpr: seasonCron,
+            maxTargets: 500,
+            description: 'Rolls every leaderboard entry into the next season on the cron.',
+        });
+    }
+    return {
+        name: names.entryType,
+        containerTypes: [
+            {
+                typeName: names.entryType,
+                displayName: names.entryType,
+                instantiableBy: 'member',
+                description: "One player's entry on one leaderboard (score writable only via submit_score).",
+            },
+        ],
+        propertyDefinitions,
+        functions,
+        ...(automations.length ? { automations } : {}),
+    };
+}

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

@@ -0,0 +1,82 @@
+import { type KitBlueprint, type KitInvokePolicy } from './core.js';
+/**
+ * The authority source that may operate a lockable object. Several may be
+ * combined (any one grants access — they are OR'd):
+ *
+ * - `owner` — only the container's owner (`owner_of_self`); "only the owner
+ *   of this chest can open it".
+ * - `key` — the caller must own a matching key item; "if a player has key 1
+ *   they can open door 1". Adds a required `key_id` (`container_ref`) param.
+ * - `gridPermission` — the caller must hold a runtime grid permission; ties
+ *   the object to a world region ("movement permission on chunk X opens the
+ *   doors in it").
+ * - `groupPermission` — the caller must be in a team/group (optionally with a
+ *   specific group permission).
+ * - `custom` — any hand-written {@link KitInvokePolicy} rule.
+ */
+export type LockAuthority = {
+    kind: 'owner';
+} | {
+    kind: 'key';
+} | {
+    kind: 'gridPermission';
+    key: string;
+    gridId?: string;
+} | {
+    /**
+     * The caller must hold the runtime permission on the grid covering the
+     * chunk the OBJECT stands in (`cx`/`cy`/`cz` int properties, seeded via
+     * `ObjectsKit.create({ chunk })`). No hand-pinned grid id — one function
+     * serves every such object in the world. `mode` picks the covering grid
+     * when several overlap: 'first' (enforcement parity, default) |
+     * 'smallest' (innermost plot) | 'largest'. Requires game-api v0.13.12+.
+     */
+    kind: 'chunkPermission';
+    key: string;
+    mode?: 'first' | 'smallest' | 'largest';
+} | {
+    kind: 'groupPermission';
+    groupId: string;
+    permission?: string;
+} | {
+    kind: 'custom';
+    rule: KitInvokePolicy;
+};
+/** Options for {@link lockBlueprint}. */
+export interface LockBlueprintOptions {
+    /**
+     * Container type name for the lockable object (`Door`, `Chest`, `Gate`, …).
+     * Also drives the function names (`open_door` / `close_door`). Defaults to
+     * `'Lockable'`.
+     */
+    objectTypeName?: string;
+    /** Key item type name (only used with a `key` authority). Defaults to `<objectTypeName>Key`. */
+    keyTypeName?: string;
+    /** One or more authority sources; any one grants access. */
+    authority: LockAuthority | LockAuthority[];
+    /**
+     * Extra policy rule AND'ed on top of the OR'd authorities — e.g.
+     * `featureGate('vip')` for members-only doors regardless of keys.
+     */
+    policyExtra?: KitInvokePolicy;
+}
+/** Names derived by {@link lockBlueprint} for a given object type. */
+export interface LockNames {
+    objectType: string;
+    keyType: string;
+    openFn: string;
+    closeFn: string;
+}
+/** Compute the type/function names a lock blueprint (and its runtime helper) uses. */
+export declare function lockNames(objectTypeName?: string, keyTypeName?: string): LockNames;
+/**
+ * Blueprint for a **lockable game object** (door, chest, gate, switch) whose
+ * `open`/`close` functions are gated by a configurable authority source:
+ * ownership, a key item the caller must hold, a runtime grid permission, a
+ * team/group permission, or any custom policy rule. Multiple authorities are
+ * OR'd, so "the owner, or anyone with the right key" is one blueprint.
+ *
+ * Runtime counterpart: `client.kit(appId).objects`.
+ */
+export declare function lockBlueprint(options: LockBlueprintOptions): KitBlueprint;
+//# sourceMappingURL=locks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"locks.d.ts","sourceRoot":"","sources":["../../../src/kit/blueprints/locks.ts"],"names":[],"mappings":"AAMA,OAAO,EAIL,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GACf;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACxD;IACE;;;;;;;OAOG;IACH,IAAI,EAAE,iBAAiB,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;CACzC,GACD;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC;AAE9C,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gGAAgG;IAChG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,SAAS,EAAE,aAAa,GAAG,aAAa,EAAE,CAAC;IAC3C;;;OAGG;IACH,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED,sEAAsE;AACtE,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sFAAsF;AACtF,wBAAgB,SAAS,CACvB,cAAc,SAAa,EAC3B,WAAW,CAAC,EAAE,MAAM,GACnB,SAAS,CAQX;AAwCD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,YAAY,CA6GzE"}