@crowdedkingdoms/crowdyjs 8.0.0 → 8.1.0

package/dist/index.js

@@ -45,12 +45,14 @@
  * or internal tooling, never an untrusted browser.
  */
 /** The published package version. Mirrors `package.json`. */
-export const VERSION = '8.0.0';
+export const VERSION = '8.1.0';
+export { LbCookieStore } from './lb-cookie-store.js';
 export { CrowdyClient, createCrowdyClient, } from './crowdy-client.js';
 export { BrowserLocalStorageTokenStore, SessionStore, } from './session.js';
 export { GraphQLClient, GraphQLTransport, } from './client.js';
 export { RealtimeClient, } from './realtime.js';
 export { WorldClient, ActorClient } from './world.js';
+export { GameKitClient, InventoryKit, NpcsKit, ObjectsKit, inventoryBlueprint, inventoryNames, kitInvoke, kitPolicyJson, lockBlueprint, lockNames, mergeBlueprints, npcBehaviorFunctionName, npcBlueprint, toKitInvokeResult, } from './kit/index.js';
 export { CrowdyError, CrowdyGraphQLError, CrowdyHttpError, CrowdyNetworkError, CrowdyProtocolError, CrowdyRealtimeError, CrowdyTimeoutError, } from './errors.js';
 export { SequenceAllocator, decodeBase64, encodeBase64, generateCrowdyUuid, validateChunkCoordinates, validateCrowdyUuid, } from './utils.js';
 export { UdpErrorCode } from './types.js';

package/dist/kit/blueprints.d.ts

@@ -0,0 +1,259 @@
+import type { FunctionMutationInput, FunctionParamInput, Scalars, SeedContainerInput, SeedContainerTypeInput, SeedEdgeInput, SeedFunctionInput, SeedGameModelInput, SeedPropertyDefInput, UpsertAutomationInput, UpsertAutomationTriggerInput } from '../generated/graphql.js';
+/**
+ * A composable invoke-policy rule tree, mirroring the server's authority
+ * rules (see the Game API "Game Models → Authority" guide). Serialized with
+ * {@link kitPolicyJson} into the `invokePolicyJson` a function carries.
+ */
+export type KitInvokePolicy = {
+    type: 'allow';
+} | {
+    type: 'owner_of_self';
+} | {
+    type: 'is_host';
+} | {
+    type: 'is_current_turn';
+} | {
+    type: 'is_participant';
+} | {
+    type: 'is_automation';
+} | {
+    type: 'tier_feature';
+    feature: string;
+} | {
+    type: 'group_permission';
+    groupId: string;
+    permission?: string;
+} | {
+    type: 'grid_permission';
+    key: string;
+    gridId?: string;
+} | {
+    type: 'condition';
+    expression: string;
+} | {
+    type: 'and';
+    rules: KitInvokePolicy[];
+} | {
+    type: 'or';
+    rules: KitInvokePolicy[];
+} | {
+    type: 'not';
+    rule: KitInvokePolicy;
+};
+/** Serialize a {@link KitInvokePolicy} tree to the wire `invokePolicyJson`. */
+export declare function kitPolicyJson(policy: KitInvokePolicy): string;
+/** An automation spec inside a blueprint (the `appId` is bound at deploy). */
+export type KitAutomationSpec = Omit<UpsertAutomationInput, 'appId'>;
+/** An automation event-trigger spec inside a blueprint. */
+export type KitAutomationTriggerSpec = Omit<UpsertAutomationTriggerInput, 'appId'>;
+/**
+ * A **blueprint**: a self-contained, declarative bundle of game-model
+ * definitions (container types, property defs, functions), optional seed
+ * instances, and optional automations that together implement one game
+ * concept (an inventory system, a lockable object, an NPC archetype).
+ *
+ * Blueprints are plain data — build them with {@link inventoryBlueprint},
+ * {@link lockBlueprint}, {@link npcBlueprint}, or by hand — then load them
+ * into an app with `client.kit(appId).deploy([...])` (requires the app-admin
+ * `manage_apps` permission). Deployment is idempotent: seeding upserts
+ * definitions and `upsertAutomation` keys on the automation name.
+ */
+export interface KitBlueprint {
+    /** A short identifier used in error messages (e.g. `'inventory'`). */
+    name: string;
+    containerTypes?: SeedContainerTypeInput[];
+    propertyDefinitions?: SeedPropertyDefInput[];
+    functions?: SeedFunctionInput[];
+    /** Optional shared/world containers to seed (catalog data, world objects). */
+    containers?: SeedContainerInput[];
+    /** Optional edges between seeded containers (by `tempId`). */
+    edges?: SeedEdgeInput[];
+    /** Server-driven automations to upsert after the seed. */
+    automations?: KitAutomationSpec[];
+    /** Event triggers to attach to the automations. */
+    automationTriggers?: KitAutomationTriggerSpec[];
+}
+/** Convert `PascalCase`/`camelCase` to `snake_case` for derived names. */
+export declare function toSnakeCase(name: string): string;
+/** 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;
+/**
+ * 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;
+} | {
+    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[];
+}
+/** 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;
+/** 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). JSON-encoded at deploy.
+     */
+    selector?: Record<string, unknown>;
+    /**
+     * 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;
+/** The wire payloads {@link mergeBlueprints} produces for one deployment. */
+export interface MergedBlueprints {
+    seedInput: SeedGameModelInput;
+    automations: UpsertAutomationInput[];
+    automationTriggers: UpsertAutomationTriggerInput[];
+}
+/**
+ * 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 declare function mergeBlueprints(appId: Scalars['BigInt']['input'], blueprints: KitBlueprint[], options?: {
+    sessionId?: string;
+}): MergedBlueprints;
+//# sourceMappingURL=blueprints.d.ts.map

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

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