@crowdedkingdoms/crowdyjs 8.2.0 → 8.3.0

package/dist/kit/blueprints.js

@@ -1,643 +0,0 @@
-/** Serialize a {@link KitInvokePolicy} tree to the wire `invokePolicyJson`. */
-export function kitPolicyJson(policy) {
-    return JSON.stringify(policy);
-}
-/** Convert `PascalCase`/`camelCase` to `snake_case` for derived names. */
-export function toSnakeCase(name) {
-    return name
-        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
-        .replace(/[\s-]+/g, '_')
-        .toLowerCase();
-}
-/** 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: '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.',
-            },
-        ],
-    };
-}
-/** Compute the type/function names a lock blueprint (and its runtime helper) uses. */
-export function lockNames(objectTypeName = 'Lockable', keyTypeName) {
-    const snake = toSnakeCase(objectTypeName);
-    return {
-        objectType: objectTypeName,
-        keyType: keyTypeName ?? `${objectTypeName}Key`,
-        openFn: `open_${snake}`,
-        closeFn: `close_${snake}`,
-    };
-}
-function lockAuthorityRule(authority) {
-    switch (authority.kind) {
-        case 'owner':
-            return { type: 'owner_of_self' };
-        case 'key':
-            // Container ownership is not readable from expressions, so the key
-            // mirrors its owner into an `owner_user_id` property; the condition
-            // verifies both the match and the ownership server-side.
-            return {
-                type: 'condition',
-                expression: 'ref($key_id).key_id == self.required_key_id && ref($key_id).owner_user_id == $caller_user_id',
-            };
-        case 'gridPermission':
-            return {
-                type: 'grid_permission',
-                key: authority.key,
-                ...(authority.gridId !== undefined ? { gridId: authority.gridId } : {}),
-            };
-        case 'chunkPermission':
-            // Resolved per-invocation against the grid covering the object's chunk.
-            return {
-                type: 'condition',
-                expression: `has_chunk_permission($caller_user_id, "${authority.key}", self.cx, self.cy, self.cz, "${authority.mode ?? 'first'}")`,
-            };
-        case 'groupPermission':
-            return {
-                type: 'group_permission',
-                groupId: authority.groupId,
-                ...(authority.permission !== undefined
-                    ? { permission: authority.permission }
-                    : {}),
-            };
-        case 'custom':
-            return authority.rule;
-    }
-}
-/**
- * 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 function lockBlueprint(options) {
-    const authorities = Array.isArray(options.authority)
-        ? options.authority
-        : [options.authority];
-    if (authorities.length === 0) {
-        throw new Error('lockBlueprint requires at least one authority source');
-    }
-    const names = lockNames(options.objectTypeName, options.keyTypeName);
-    const usesKey = authorities.some((a) => a.kind === 'key');
-    const usesChunk = authorities.some((a) => a.kind === 'chunkPermission');
-    const rules = authorities.map(lockAuthorityRule);
-    const policy = rules.length === 1 ? rules[0] : { type: 'or', rules };
-    const policyJson = kitPolicyJson(policy);
-    const parameters = usesKey
-        ? [{ name: 'key_id', valueType: 'container_ref', required: true }]
-        : [];
-    const containerTypes = [
-        {
-            typeName: names.objectType,
-            displayName: names.objectType,
-            instantiableBy: 'admin',
-            description: 'A lockable world object operated through gated functions.',
-        },
-    ];
-    const propertyDefinitions = [
-        {
-            containerTypeName: names.objectType,
-            key: 'is_open',
-            valueType: 'bool',
-            defaultValueJson: 'false',
-        },
-    ];
-    if (usesChunk) {
-        // The chunk the object stands in, read by has_chunk_permission().
-        for (const axis of ['cx', 'cy', 'cz']) {
-            propertyDefinitions.push({
-                containerTypeName: names.objectType,
-                key: axis,
-                valueType: 'int',
-                defaultValueJson: '0',
-            });
-        }
-    }
-    if (usesKey) {
-        propertyDefinitions.push({
-            containerTypeName: names.objectType,
-            key: 'required_key_id',
-            valueType: 'string',
-        });
-        containerTypes.push({
-            typeName: names.keyType,
-            displayName: names.keyType,
-            instantiableBy: 'admin',
-            description: 'A key item granting access to matching lockable objects.',
-        });
-        propertyDefinitions.push({ containerTypeName: names.keyType, key: 'key_id', valueType: 'string' }, {
-            containerTypeName: names.keyType,
-            key: 'owner_user_id',
-            valueType: 'int',
-        });
-    }
-    const openMutation = {
-        target: 'self',
-        property: 'is_open',
-        expression: 'true',
-    };
-    const closeMutation = {
-        target: 'self',
-        property: 'is_open',
-        expression: 'false',
-    };
-    return {
-        name: names.objectType,
-        containerTypes,
-        propertyDefinitions,
-        functions: [
-            {
-                name: names.openFn,
-                containerTypeName: names.objectType,
-                returnType: 'bool',
-                parameters,
-                mutations: [openMutation],
-                returnExpression: 'self.is_open',
-                invokePolicyJson: policyJson,
-                description: `Open a ${names.objectType}; the invoke policy decides who may.`,
-            },
-            {
-                name: names.closeFn,
-                containerTypeName: names.objectType,
-                returnType: 'bool',
-                parameters,
-                mutations: [closeMutation],
-                returnExpression: 'self.is_open',
-                invokePolicyJson: policyJson,
-                description: `Close a ${names.objectType}; same authority as opening.`,
-            },
-        ],
-    };
-}
-/** 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) => kitPolicyJson({
-        type: 'condition',
-        expression: `ref($wallet_id).${walletOwner} == $caller_user_id && ref($wallet_id).${currency} >= ${priceExpr}`,
-    });
-    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'),
-            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'),
-            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,
-    };
-}
-/** 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,
-    };
-}
-/**
- * Merge blueprints into a single `gameModelSeed` payload plus the automation
- * upserts, rejecting duplicate type, property, function, or automation names
- * across blueprints (a duplicate almost always means two blueprints need
- * distinct prefixes/type names).
- */
-export function mergeBlueprints(appId, blueprints, options = {}) {
-    const containerTypes = [];
-    const propertyDefinitions = [];
-    const functions = [];
-    const containers = [];
-    const edges = [];
-    const automations = [];
-    const automationTriggers = [];
-    const seenTypes = new Map();
-    const seenProps = new Map();
-    const seenFunctions = new Map();
-    const seenAutomations = new Map();
-    const seenTempIds = new Map();
-    const claim = (seen, key, blueprintName, kind) => {
-        const existing = seen.get(key);
-        if (existing !== undefined) {
-            throw new Error(`Blueprint '${blueprintName}' redefines ${kind} '${key}' already defined by blueprint '${existing}'`);
-        }
-        seen.set(key, blueprintName);
-    };
-    for (const blueprint of blueprints) {
-        for (const type of blueprint.containerTypes ?? []) {
-            claim(seenTypes, type.typeName, blueprint.name, 'container type');
-            containerTypes.push(type);
-        }
-        for (const prop of blueprint.propertyDefinitions ?? []) {
-            claim(seenProps, `${prop.containerTypeName}.${prop.key}`, blueprint.name, 'property');
-            propertyDefinitions.push(prop);
-        }
-        for (const fn of blueprint.functions ?? []) {
-            claim(seenFunctions, fn.name, blueprint.name, 'function');
-            functions.push(fn);
-        }
-        for (const container of blueprint.containers ?? []) {
-            claim(seenTempIds, container.tempId, blueprint.name, 'container tempId');
-            containers.push(container);
-        }
-        edges.push(...(blueprint.edges ?? []));
-        for (const automation of blueprint.automations ?? []) {
-            claim(seenAutomations, automation.name, blueprint.name, 'automation');
-            automations.push({ ...automation, appId });
-        }
-        for (const trigger of blueprint.automationTriggers ?? []) {
-            automationTriggers.push({ ...trigger, appId });
-        }
-    }
-    const seedInput = {
-        appId,
-        ...(options.sessionId !== undefined ? { sessionId: options.sessionId } : {}),
-        ...(containerTypes.length ? { containerTypes } : {}),
-        ...(propertyDefinitions.length ? { propertyDefinitions } : {}),
-        ...(functions.length ? { functions } : {}),
-        ...(containers.length ? { containers } : {}),
-        ...(edges.length ? { edges } : {}),
-    };
-    return { seedInput, automations, automationTriggers };
-}