@crowdedkingdoms/crowdyjs 8.2.0 → 8.3.0

package/dist/kit/blueprints/quests.js

@@ -0,0 +1,284 @@
+import { kitPolicyJson, ownerEqualsCaller, ownerMirrorProperty, toSnakeCase, trustedAuthorityFields, } from './core.js';
+/** Compute the type/function names a quests blueprint (and its runtime helper) uses. */
+export function questsNames(typePrefix = '') {
+    const fnPrefix = typePrefix ? `${toSnakeCase(typePrefix)}_` : '';
+    return {
+        defType: `${typePrefix}QuestDef`,
+        progressType: `${typePrefix}QuestProgress`,
+        advanceFn: `${fnPrefix}advance_quest`,
+        claimFn: `${fnPrefix}claim_reward`,
+        resetFn: `${fnPrefix}reset_daily`,
+        dailyResetAutomation: `${fnPrefix.replace(/_/g, '-')}daily-quest-reset`,
+    };
+}
+/**
+ * Blueprint for **quests**: an admin `QuestDef` catalog (objective count +
+ * reward spec + daily flag) and per-player `QuestProgress` rows. Progress
+ * advances through trusted calls or event automations on your gameplay
+ * functions; `claim_reward` marks the progress claimed AND grants the item
+ * and currency rewards through `container_ref` params in ONE transaction
+ * (composing with the inventory stack and economy wallet types); a **cron
+ * automation** resets daily quests at midnight.
+ *
+ * Runtime counterpart: `client.kit(appId).quests`.
+ */
+export function questsBlueprint(options = {}) {
+    const { typePrefix = '', advanceAuthority = 'server', currencyProperty = 'gold', dailyResetCron = '0 0 * * *', advanceOn = [], ownerIdKind: kind = 'int', } = options;
+    const names = questsNames(typePrefix);
+    const propertyDefinitions = [
+        {
+            containerTypeName: names.defType,
+            key: 'quest_id',
+            valueType: 'string',
+            description: 'Stable quest identifier.',
+        },
+        {
+            containerTypeName: names.defType,
+            key: 'target_count',
+            valueType: 'int',
+            defaultValueJson: '1',
+            description: 'Objective count required to complete.',
+        },
+        {
+            containerTypeName: names.defType,
+            key: 'reward_item_id',
+            valueType: 'string',
+            defaultValueJson: '""',
+            description: 'Item reward (empty for currency-only quests).',
+        },
+        {
+            containerTypeName: names.defType,
+            key: 'reward_qty',
+            valueType: 'int',
+            defaultValueJson: '0',
+            description: 'Item reward quantity.',
+        },
+        {
+            containerTypeName: names.defType,
+            key: 'reward_gold',
+            valueType: 'int',
+            defaultValueJson: '0',
+            description: `Currency reward paid into the '${currencyProperty}' wallet property.`,
+        },
+        {
+            containerTypeName: names.defType,
+            key: 'repeatable',
+            valueType: 'bool',
+            defaultValueJson: 'false',
+            description: 'Whether a player may accept the quest again after claiming.',
+        },
+        {
+            containerTypeName: names.defType,
+            key: 'daily',
+            valueType: 'bool',
+            defaultValueJson: 'false',
+            description: 'Whether progress resets on the daily cron.',
+        },
+        ownerMirrorProperty(names.progressType, kind),
+        {
+            containerTypeName: names.progressType,
+            key: 'quest_id',
+            valueType: 'string',
+            defaultValueJson: '""',
+            description: 'The quest this row tracks.',
+        },
+        {
+            containerTypeName: names.progressType,
+            key: 'count',
+            valueType: 'int',
+            defaultValueJson: '0',
+            description: 'Objective progress, clamped to target.',
+        },
+        {
+            containerTypeName: names.progressType,
+            key: 'target',
+            valueType: 'int',
+            defaultValueJson: '1',
+            description: 'Objective count copied from the def at accept time.',
+        },
+        {
+            containerTypeName: names.progressType,
+            key: 'completed',
+            valueType: 'bool',
+            defaultValueJson: 'false',
+            description: 'True once count reaches target.',
+        },
+        {
+            containerTypeName: names.progressType,
+            key: 'claimed',
+            valueType: 'bool',
+            defaultValueJson: 'false',
+            description: 'True once the reward was granted (single-claim guard).',
+        },
+        {
+            containerTypeName: names.progressType,
+            key: 'daily',
+            valueType: 'bool',
+            defaultValueJson: 'false',
+            description: 'Mirrors the def; selects rows for the daily reset automation.',
+        },
+    ];
+    const functions = [
+        {
+            name: names.advanceFn,
+            containerTypeName: names.progressType,
+            returnType: 'int',
+            parameters: [
+                {
+                    name: 'amount',
+                    valueType: 'int',
+                    required: true,
+                    description: 'Progress to add (negative values are ignored; clamped to target).',
+                },
+            ],
+            mutations: [
+                {
+                    target: 'self',
+                    property: 'count',
+                    expression: 'min(self.target, self.count + max(0, $amount))',
+                },
+                {
+                    target: 'self',
+                    property: 'completed',
+                    expression: 'self.count >= self.target',
+                },
+            ],
+            returnExpression: 'self.count',
+            ...trustedAuthorityFields(advanceAuthority),
+            // Event automations must be able to run it regardless of authority.
+            ...(advanceOn.length ? { autonomousInvocable: true } : {}),
+            description: 'Trusted quest progress bump (clamped to the target); completion flips server-side in the same transaction.',
+        },
+        {
+            name: names.claimFn,
+            containerTypeName: names.progressType,
+            returnType: 'int',
+            parameters: [
+                {
+                    name: 'def_id',
+                    valueType: 'container_ref',
+                    required: true,
+                    description: 'The QuestDef holding the reward spec (must match quest_id).',
+                },
+                {
+                    name: 'to_stack_id',
+                    valueType: 'container_ref',
+                    required: true,
+                    description: 'A caller-owned stack receiving the item reward (item grant is 0 when the item id does not match, e.g. currency-only quests).',
+                },
+                {
+                    name: 'wallet_id',
+                    valueType: 'container_ref',
+                    required: true,
+                    description: "The caller's wallet receiving the currency reward.",
+                },
+            ],
+            mutations: [
+                { target: 'self', property: 'claimed', expression: 'true' },
+                {
+                    target: 'ref($to_stack_id)',
+                    property: 'quantity',
+                    expression: 'ref($to_stack_id).quantity + if(ref($to_stack_id).item_id == ref($def_id).reward_item_id, ref($def_id).reward_qty, 0)',
+                },
+                {
+                    target: 'ref($wallet_id)',
+                    property: currencyProperty,
+                    expression: `ref($wallet_id).${currencyProperty} + ref($def_id).reward_gold`,
+                },
+            ],
+            returnExpression: `ref($wallet_id).${currencyProperty}`,
+            invokePolicyJson: kitPolicyJson({
+                type: 'condition',
+                expression: [
+                    ownerEqualsCaller('self.owner_user_id', kind),
+                    'self.count >= self.target',
+                    'not(self.claimed)',
+                    'ref($def_id).quest_id == self.quest_id',
+                    ownerEqualsCaller('ref($wallet_id).owner_user_id', kind),
+                    ownerEqualsCaller('ref($to_stack_id).owner_user_id', kind),
+                ].join(' && '),
+            }),
+            description: 'Turn in a completed quest: the claimed flag, item grant, and currency grant commit atomically — no double-claims, no client-chosen rewards.',
+        },
+        {
+            name: names.resetFn,
+            containerTypeName: names.progressType,
+            returnType: 'bool',
+            mutations: [
+                { target: 'self', property: 'count', expression: '0' },
+                { target: 'self', property: 'completed', expression: 'false' },
+                { target: 'self', property: 'claimed', expression: 'false' },
+            ],
+            returnExpression: 'self.completed',
+            invokePolicyJson: kitPolicyJson({ type: 'is_automation' }),
+            autonomousInvocable: true,
+            description: 'Server-driven daily quest reset (automation-only).',
+        },
+    ];
+    const automations = [
+        {
+            name: names.dailyResetAutomation,
+            functionName: names.resetFn,
+            targetMode: 'type',
+            targetTypeName: names.progressType,
+            triggerType: 'schedule',
+            scheduleKind: 'cron',
+            cronExpr: dailyResetCron,
+            maxTargets: 500,
+            selectorJson: JSON.stringify({
+                selfWhere: [{ key: 'daily', op: '==', value: true }],
+            }),
+            description: 'Resets daily quest progress on the cron schedule.',
+        },
+    ];
+    const automationTriggers = [];
+    for (const spec of advanceOn) {
+        automations.push({
+            name: spec.name,
+            functionName: names.advanceFn,
+            targetMode: 'type',
+            targetTypeName: names.progressType,
+            triggerType: 'event',
+            maxTargets: spec.maxTargets ?? 8,
+            selectorJson: JSON.stringify({
+                selfWhere: [
+                    { key: 'quest_id', op: '==', value: spec.questId },
+                    { key: 'completed', op: '==', value: false },
+                ],
+            }),
+            paramsJson: JSON.stringify({ amount: spec.amount ?? 1 }),
+            description: `Advances '${spec.questId}' progress when the gameplay event fires.`,
+        });
+        automationTriggers.push({
+            automationName: spec.name,
+            onEvent: spec.onEvent,
+            ...(spec.functionName !== undefined ? { functionName: spec.functionName } : {}),
+            ...(spec.containerTypeName !== undefined
+                ? { containerTypeName: spec.containerTypeName }
+                : {}),
+            ...(spec.propertyKey !== undefined ? { propertyKey: spec.propertyKey } : {}),
+            ...(spec.debounceMs !== undefined ? { debounceMs: spec.debounceMs } : {}),
+        });
+    }
+    return {
+        name: names.progressType,
+        containerTypes: [
+            {
+                typeName: names.defType,
+                displayName: names.defType,
+                instantiableBy: 'admin',
+                description: 'Studio quest catalog row (objective, rewards, daily flag).',
+            },
+            {
+                typeName: names.progressType,
+                displayName: names.progressType,
+                instantiableBy: 'member',
+                description: "A player's progress toward one quest.",
+            },
+        ],
+        propertyDefinitions,
+        functions,
+        automations,
+        automationTriggers,
+    };
+}

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

@@ -0,0 +1,84 @@
+import { type KitBlueprint, type KitOwnerIdKind } from './core.js';
+/** Options for {@link worldsimBlueprint}. */
+export interface WorldsimBlueprintOptions {
+    /** Prefix for the type/function names. Defaults to none. */
+    typePrefix?: string;
+    /**
+     * Day/night + weather: an interval automation advances `time_of_day`
+     * (wrapping at `hoursPerDay`, bumping `day`), optionally re-rolls the
+     * weather, and emits a **spatial notification** at the world anchor chunk
+     * so nearby clients update the sky without polling. Set `false` to omit.
+     * Defaults to a 60s tick, 24-hour days, weather on.
+     */
+    time?: {
+        intervalMs?: number;
+        hoursPerDay?: number;
+        weather?: boolean;
+        /** Replication radius of the time-changed ping (chunks, 0-8). Defaults to 8. */
+        notifyDistance?: number;
+    } | false;
+    /**
+     * Resource-node regeneration: an interval automation raises `amount`
+     * toward `max_amount` on depleted nodes; players `gather_node` into a
+     * matching stack. Set `false` to omit. Defaults to a 60s tick.
+     */
+    nodes?: {
+        intervalMs?: number;
+    } | false;
+    /**
+     * Crop growth: an interval automation advances `stage` toward
+     * `max_stage`; owners `harvest` grown crops into a matching stack. Set
+     * `false` to omit. Defaults to a 60s tick.
+     */
+    crops?: {
+        intervalMs?: number;
+    } | false;
+    /**
+     * Wave spawner counters: an interval automation bumps `wave` and grows
+     * `next_wave_size` — the actual entity spawning stays host-side on the
+     * replication plane (the BWF hybrid). Off by default.
+     */
+    waves?: {
+        intervalMs?: number;
+        growth?: number;
+    };
+    /** Owner-mirror typing (see the kit convention). Defaults to `'int'`. */
+    ownerIdKind?: KitOwnerIdKind;
+}
+/** Names derived by {@link worldsimBlueprint} for a given prefix. */
+export interface WorldsimNames {
+    worldStateType: string;
+    nodeType: string;
+    cropType: string;
+    spawnerType: string;
+    advanceTimeFn: string;
+    setWeatherFn: string;
+    regenNodeFn: string;
+    gatherNodeFn: string;
+    growCropFn: string;
+    harvestFn: string;
+    spawnWaveFn: string;
+    clockAutomation: string;
+    regenAutomation: string;
+    growthAutomation: string;
+    waveAutomation: string;
+}
+/** Compute the type/function names a worldsim blueprint (and its runtime helper) uses. */
+export declare function worldsimNames(typePrefix?: string): WorldsimNames;
+/**
+ * Blueprint for **world simulation**: day/night + weather (`WorldState`
+ * singleton), regenerating `ResourceNode`s, growing `Crop`s / production
+ * jobs, and `WaveSpawner` counters — all driven by interval automations that
+ * run with **no client online** (the automations simulation tier: seconds,
+ * never per-frame).
+ *
+ * The world clock emits a **spatial notification** at the world anchor chunk
+ * each tick, so nearby clients update the sky push-style instead of polling;
+ * everything else is pull-on-demand (or wire your own notify-to-pull pings).
+ * Wave spawners only advance counters — actual entity spawning belongs on
+ * the replication plane under host authority (the BWF hybrid).
+ *
+ * Runtime counterpart: `client.kit(appId).worldsim`.
+ */
+export declare function worldsimBlueprint(options?: WorldsimBlueprintOptions): KitBlueprint;
+//# sourceMappingURL=worldsim.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worldsim.d.ts","sourceRoot":"","sources":["../../../src/kit/blueprints/worldsim.ts"],"names":[],"mappings":"AAIA,OAAO,EAML,KAAK,YAAY,EACjB,KAAK,cAAc,EACpB,MAAM,WAAW,CAAC;AAEnB,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,IAAI,CAAC,EACD;QACE,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,gFAAgF;QAChF,cAAc,CAAC,EAAE,MAAM,CAAC;KACzB,GACD,KAAK,CAAC;IACV;;;;OAIG;IACH,KAAK,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,CAAC;IACxC;;;;OAIG;IACH,KAAK,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,KAAK,CAAC;IACxC;;;;OAIG;IACH,KAAK,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,yEAAyE;IACzE,WAAW,CAAC,EAAE,cAAc,CAAC;CAC9B;AAED,qEAAqE;AACrE,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,UAAU,SAAK,GAAG,aAAa,CAoB5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,YAAY,CAmdd"}