@crowdedkingdoms/crowdyjs 8.2.0 → 8.3.0

package/dist/kit/worldsim.d.ts

@@ -0,0 +1,225 @@
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { Scalars, SeedPropertyInput } from '../generated/graphql.js';
+import { type KitInvokeResult } from './shared.js';
+/** Options for {@link WorldsimKit}. Must match the deployed worldsim blueprint. */
+export interface WorldsimKitOptions {
+    /** The `typePrefix` the worldsim blueprint was deployed with. */
+    typePrefix?: string;
+}
+/** A parsed view of the world clock/weather state. */
+export interface KitWorldState {
+    containerId: string;
+    timeOfDay: number;
+    day: number;
+    weather: string;
+}
+/** A parsed view of one resource node. */
+export interface KitResourceNode {
+    containerId: string;
+    displayName: string;
+    nodeId: string;
+    resourceItemId: string;
+    amount: number;
+    maxAmount: number;
+    regenRate: number;
+    x: number;
+    y: number;
+    z: number;
+}
+/** A parsed view of one crop / production job. */
+export interface KitCrop {
+    containerId: string;
+    displayName: string;
+    ownerUserId: string | null;
+    stage: number;
+    maxStage: number;
+    outputItemId: string;
+    outputQty: number;
+    ready: boolean;
+}
+/** A parsed view of one wave spawner. */
+export interface KitWaveSpawner {
+    containerId: string;
+    displayName: string;
+    wave: number;
+    nextWaveSize: number;
+}
+/**
+ * Runtime helpers for the {@link worldsimBlueprint} conventions: the world
+ * clock/weather singleton, regenerating resource nodes players gather from,
+ * crops that mature server-side, and wave counters the host reads. The
+ * simulation itself runs in automations — these helpers create/read state
+ * and drive the player-facing functions.
+ *
+ * Obtained via `client.kit(appId).worldsim`.
+ */
+export declare class WorldsimKit {
+    private readonly appId;
+    private readonly gameModel;
+    private readonly names;
+    constructor(appId: Scalars['BigInt']['input'], gameModel: GameModelAPI, options?: WorldsimKitOptions);
+    /**
+     * Find-or-create the WorldState singleton (admin). `anchorChunk` is where
+     * the clock's spatial time-changed ping is emitted.
+     */
+    ensureWorld(options?: {
+        anchorChunk?: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        displayName?: string;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /** Read the world clock/weather state. */
+    worldState(): Promise<KitWorldState>;
+    /** Force the weather (app admins only — the policy denies everyone else). */
+    setWeather(weather: string): Promise<KitInvokeResult<string>>;
+    /** Create a resource node (admin). */
+    createNode(input: {
+        displayName: string;
+        nodeId: string;
+        resourceItemId: string;
+        amount?: number;
+        maxAmount?: number;
+        regenRate?: number;
+        position?: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        properties?: SeedPropertyInput[];
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /** List resource nodes with parsed state. */
+    nodes(): Promise<KitResourceNode[]>;
+    /**
+     * Gather from a node into a caller-owned stack of the node's resource;
+     * the node decrement and the grant commit atomically. Resolves with the
+     * node's remaining amount.
+     */
+    gather(input: {
+        nodeId: string;
+        amount: number;
+        toStackId: string;
+    }): Promise<KitInvokeResult<number>>;
+    /** Plant a crop / start a production job (member). */
+    plant(input: {
+        ownerUserId: Scalars['BigInt']['input'];
+        outputItemId: string;
+        outputQty?: number;
+        maxStage?: number;
+        displayName?: string;
+        sessionId?: string;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /** List a player's crops (all crops when `ownerUserId` is null). */
+    crops(ownerUserId: Scalars['BigInt']['input'] | null): Promise<KitCrop[]>;
+    /**
+     * Harvest a grown crop into a caller-owned stack of the output item;
+     * resets the stage for regrowth. Resolves with the yield quantity.
+     */
+    harvest(cropId: string, toStackId: string): Promise<KitInvokeResult<number>>;
+    /** Create a wave spawner (admin; blueprint deployed with `waves`). */
+    createSpawner(input: {
+        displayName: string;
+        nextWaveSize?: number;
+    }): Promise<{
+        __typename?: "GmContainer";
+        containerId: string;
+        appId: string;
+        sessionId: string | null;
+        typeName: string;
+        displayName: string;
+        description: string | null;
+        ownerUserId: string | null;
+        metadataJson: string;
+    }>;
+    /** List wave spawners (the host reads these to spawn entities). */
+    spawners(): Promise<KitWaveSpawner[]>;
+    /** Run one of the worldsim automations immediately (admin; for testing). */
+    runNow(automationName: string): Promise<{
+        __typename?: "GmAutomationRun";
+        runId: string;
+        appId: string;
+        automationId: string;
+        automationName: string;
+        triggerSource: string;
+        parentRunId: string | null;
+        cascadeDepth: number;
+        startedAt: string;
+        finishedAt: string | null;
+        durationUs: number;
+        targets: number;
+        invocations: number;
+        mutations: number;
+        fnCalls: number;
+        gasUsed: number;
+        success: boolean;
+        errorMessage: string | null;
+        circuitAction: string | null;
+        computeUnits: number;
+    }>;
+    /** Pause or resume one of the worldsim automations (admin). */
+    setEnabled(automationName: string, enabled: boolean): Promise<{
+        __typename?: "GmAutomation";
+        automationId: string;
+        appId: string;
+        name: string;
+        description: string | null;
+        enabled: boolean;
+        functionName: string;
+        targetMode: string;
+        selfContainerId: string | null;
+        targetTypeName: string | null;
+        sessionId: string | null;
+        paramsJson: string;
+        selectorJson: string | null;
+        runAsUserId: string | null;
+        triggerType: string;
+        scheduleKind: string | null;
+        intervalMs: number | null;
+        cronExpr: string | null;
+        maxTargets: number;
+        maxFnDepth: number | null;
+        gasLimit: number | null;
+        runTimeoutMs: number | null;
+        maxRunsPerMinute: number;
+        failureThreshold: number;
+        cooldownMs: number;
+        circuitState: string;
+        consecutiveFailures: number;
+        pausedUntil: string | null;
+        lastError: string | null;
+        lastRunAt: string | null;
+        nextRunAt: string | null;
+    }>;
+}
+//# sourceMappingURL=worldsim.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"worldsim.d.ts","sourceRoot":"","sources":["../../src/kit/worldsim.ts"],"names":[],"mappings":"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"}

package/dist/kit/worldsim.js

@@ -0,0 +1,231 @@
+import { worldsimNames } from './blueprints/index.js';
+import { kitContainerProperties, kitInvoke, } from './shared.js';
+/**
+ * Runtime helpers for the {@link worldsimBlueprint} conventions: the world
+ * clock/weather singleton, regenerating resource nodes players gather from,
+ * crops that mature server-side, and wave counters the host reads. The
+ * simulation itself runs in automations — these helpers create/read state
+ * and drive the player-facing functions.
+ *
+ * Obtained via `client.kit(appId).worldsim`.
+ */
+export class WorldsimKit {
+    constructor(appId, gameModel, options = {}) {
+        this.appId = appId;
+        this.gameModel = gameModel;
+        this.names = worldsimNames(options.typePrefix ?? '');
+    }
+    /**
+     * Find-or-create the WorldState singleton (admin). `anchorChunk` is where
+     * the clock's spatial time-changed ping is emitted.
+     */
+    async ensureWorld(options = {}) {
+        const existing = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.worldStateType,
+        });
+        if (existing.length > 0)
+            return existing[0];
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.worldStateType,
+            displayName: options.displayName ?? 'World',
+            properties: options.anchorChunk
+                ? [
+                    { key: 'cx', valueType: 'int', valueJson: String(options.anchorChunk.x) },
+                    { key: 'cy', valueType: 'int', valueJson: String(options.anchorChunk.y) },
+                    { key: 'cz', valueType: 'int', valueJson: String(options.anchorChunk.z) },
+                ]
+                : [],
+        });
+    }
+    /** Read the world clock/weather state. */
+    async worldState() {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.worldStateType,
+        });
+        if (containers.length === 0) {
+            throw new Error(`No ${this.names.worldStateType} exists yet — run kit.worldsim.ensureWorld() as admin`);
+        }
+        const props = await kitContainerProperties(this.gameModel, String(this.appId), containers[0].containerId);
+        return {
+            containerId: containers[0].containerId,
+            timeOfDay: Number(props.time_of_day ?? 0),
+            day: Number(props.day ?? 0),
+            weather: String(props.weather ?? 'clear'),
+        };
+    }
+    /** Force the weather (app admins only — the policy denies everyone else). */
+    async setWeather(weather) {
+        const state = await this.worldState();
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.setWeatherFn,
+            selfContainerId: state.containerId,
+            params: { weather },
+        });
+    }
+    /** Create a resource node (admin). */
+    async createNode(input) {
+        const maxAmount = input.maxAmount ?? 100;
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.nodeType,
+            displayName: input.displayName,
+            properties: [
+                { key: 'node_id', valueType: 'string', valueJson: JSON.stringify(input.nodeId) },
+                {
+                    key: 'resource_item_id',
+                    valueType: 'string',
+                    valueJson: JSON.stringify(input.resourceItemId),
+                },
+                { key: 'amount', valueType: 'int', valueJson: String(input.amount ?? maxAmount) },
+                { key: 'max_amount', valueType: 'int', valueJson: String(maxAmount) },
+                { key: 'regen_rate', valueType: 'int', valueJson: String(input.regenRate ?? 1) },
+                ...(input.position
+                    ? [
+                        { key: 'x', valueType: 'float', valueJson: String(input.position.x) },
+                        { key: 'y', valueType: 'float', valueJson: String(input.position.y) },
+                        { key: 'z', valueType: 'float', valueJson: String(input.position.z) },
+                    ]
+                    : []),
+                ...(input.properties ?? []),
+            ],
+        });
+    }
+    /** List resource nodes with parsed state. */
+    async nodes() {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.nodeType,
+        });
+        return Promise.all(containers.map(async (c) => {
+            const props = await kitContainerProperties(this.gameModel, String(this.appId), c.containerId);
+            return {
+                containerId: c.containerId,
+                displayName: c.displayName,
+                nodeId: String(props.node_id ?? ''),
+                resourceItemId: String(props.resource_item_id ?? ''),
+                amount: Number(props.amount ?? 0),
+                maxAmount: Number(props.max_amount ?? 0),
+                regenRate: Number(props.regen_rate ?? 0),
+                x: Number(props.x ?? 0),
+                y: Number(props.y ?? 0),
+                z: Number(props.z ?? 0),
+            };
+        }));
+    }
+    /**
+     * Gather from a node into a caller-owned stack of the node's resource;
+     * the node decrement and the grant commit atomically. Resolves with the
+     * node's remaining amount.
+     */
+    async gather(input) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.gatherNodeFn,
+            selfContainerId: input.nodeId,
+            params: { amount: input.amount, to_stack_id: input.toStackId },
+        });
+    }
+    /** Plant a crop / start a production job (member). */
+    async plant(input) {
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.cropType,
+            displayName: input.displayName ?? `Crop ${input.outputItemId}`,
+            ...(input.sessionId !== undefined ? { sessionId: input.sessionId } : {}),
+            properties: [
+                { key: 'owner_user_id', valueType: 'int', valueJson: String(input.ownerUserId) },
+                {
+                    key: 'output_item_id',
+                    valueType: 'string',
+                    valueJson: JSON.stringify(input.outputItemId),
+                },
+                { key: 'output_qty', valueType: 'int', valueJson: String(input.outputQty ?? 1) },
+                { key: 'max_stage', valueType: 'int', valueJson: String(input.maxStage ?? 3) },
+            ],
+        });
+    }
+    /** List a player's crops (all crops when `ownerUserId` is null). */
+    async crops(ownerUserId) {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.cropType,
+        });
+        const filtered = ownerUserId === null
+            ? containers
+            : containers.filter((c) => c.ownerUserId != null && String(c.ownerUserId) === String(ownerUserId));
+        return Promise.all(filtered.map(async (c) => {
+            const props = await kitContainerProperties(this.gameModel, String(this.appId), c.containerId);
+            const stage = Number(props.stage ?? 0);
+            const maxStage = Number(props.max_stage ?? 0);
+            return {
+                containerId: c.containerId,
+                displayName: c.displayName,
+                ownerUserId: c.ownerUserId != null ? String(c.ownerUserId) : null,
+                stage,
+                maxStage,
+                outputItemId: String(props.output_item_id ?? ''),
+                outputQty: Number(props.output_qty ?? 0),
+                ready: maxStage > 0 && stage >= maxStage,
+            };
+        }));
+    }
+    /**
+     * Harvest a grown crop into a caller-owned stack of the output item;
+     * resets the stage for regrowth. Resolves with the yield quantity.
+     */
+    async harvest(cropId, toStackId) {
+        return kitInvoke(this.gameModel, {
+            appId: String(this.appId),
+            functionName: this.names.harvestFn,
+            selfContainerId: cropId,
+            params: { to_stack_id: toStackId },
+        });
+    }
+    /** Create a wave spawner (admin; blueprint deployed with `waves`). */
+    async createSpawner(input) {
+        return this.gameModel.createContainer({
+            appId: this.appId,
+            typeName: this.names.spawnerType,
+            displayName: input.displayName,
+            properties: [
+                {
+                    key: 'next_wave_size',
+                    valueType: 'int',
+                    valueJson: String(input.nextWaveSize ?? 5),
+                },
+            ],
+        });
+    }
+    /** List wave spawners (the host reads these to spawn entities). */
+    async spawners() {
+        const containers = await this.gameModel.containers({
+            appId: this.appId,
+            typeName: this.names.spawnerType,
+        });
+        return Promise.all(containers.map(async (c) => {
+            const props = await kitContainerProperties(this.gameModel, String(this.appId), c.containerId);
+            return {
+                containerId: c.containerId,
+                displayName: c.displayName,
+                wave: Number(props.wave ?? 0),
+                nextWaveSize: Number(props.next_wave_size ?? 0),
+            };
+        }));
+    }
+    /** Run one of the worldsim automations immediately (admin; for testing). */
+    async runNow(automationName) {
+        return this.gameModel.runAutomation({ appId: this.appId, name: automationName });
+    }
+    /** Pause or resume one of the worldsim automations (admin). */
+    async setEnabled(automationName, enabled) {
+        return this.gameModel.setAutomationEnabled({
+            appId: this.appId,
+            name: automationName,
+            enabled,
+        });
+    }
+}

package/package.json

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