@sharpee/plugins 1.0.0 → 1.0.8

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../repos/sharpee/packages/plugins/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugins/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sharpee/plugins",
-  "version": "1.0.0",
+  "version": "1.0.8",
   "description": "Plugin contracts for Sharpee engine turn-cycle extensibility",
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -12,8 +12,8 @@
     }
   },
   "dependencies": {
-    "@sharpee/core": "^1.0.0",
-    "@sharpee/world-model": "^1.0.0"
+    "@sharpee/core": "^1.0.8",
+    "@sharpee/world-model": "^1.0.8"
   },
   "keywords": [
     "interactive-fiction",

package/plugin-registry.d.ts

@@ -1,12 +1,32 @@
 import { TurnPlugin } from './turn-plugin';
+/**
+ * Holds the turn plugins for a running game and hands them to the engine in
+ * priority order each turn (ADR-120). The engine owns the single registry;
+ * stories add behaviour through the plugin packages (NPC, scheduler, state
+ * machine) rather than implementing {@link TurnPlugin} directly.
+ */
 export declare class PluginRegistry {
     private plugins;
+    /** Register a plugin. Throws if a plugin with the same id is already registered. */
     register(plugin: TurnPlugin): void;
+    /** Remove a plugin by id; a no-op if no such plugin is registered. */
     unregister(id: string): void;
+    /** Remove all registered plugins. */
     clear(): void;
+    /** All registered plugins, sorted by descending priority (turn run order). */
     getAll(): TurnPlugin[];
+    /** Look up a single plugin by id, or `undefined` if absent. */
     getById(id: string): TurnPlugin | undefined;
+    /**
+     * Collect each plugin's {@link TurnPlugin.getState} result, keyed by plugin id,
+     * for inclusion in a save. Plugins without `getState` are omitted.
+     */
     getStates(): Record<string, unknown>;
+    /**
+     * Restore plugin state from a prior {@link PluginRegistry.getStates} result on
+     * load, calling each matching plugin's {@link TurnPlugin.setState}. Entries
+     * with no registered plugin (or no `setState`) are skipped.
+     */
     setStates(states: Record<string, unknown>): void;
 }
 //# sourceMappingURL=plugin-registry.d.ts.map

package/plugin-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-registry.d.ts","sourceRoot":"","sources":["../../../../../repos/sharpee/packages/plugins/src/plugin-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAsC;IAErD,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAOlC,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI5B,KAAK,IAAI,IAAI;IAIb,MAAM,IAAI,UAAU,EAAE;IAMtB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI3C,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAUpC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAQjD"}
+{"version":3,"file":"plugin-registry.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugins/src/plugin-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAsC;IAErD,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAOlC,sEAAsE;IACtE,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI5B,qCAAqC;IACrC,KAAK,IAAI,IAAI;IAIb,8EAA8E;IAC9E,MAAM,IAAI,UAAU,EAAE;IAMtB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI3C;;;OAGG;IACH,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAUpC;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAQjD"}

package/plugin-registry.js

@@ -1,26 +1,41 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PluginRegistry = void 0;
+/**
+ * Holds the turn plugins for a running game and hands them to the engine in
+ * priority order each turn (ADR-120). The engine owns the single registry;
+ * stories add behaviour through the plugin packages (NPC, scheduler, state
+ * machine) rather than implementing {@link TurnPlugin} directly.
+ */
 class PluginRegistry {
     plugins = new Map();
+    /** Register a plugin. Throws if a plugin with the same id is already registered. */
     register(plugin) {
         if (this.plugins.has(plugin.id)) {
             throw new Error(`Plugin already registered: ${plugin.id}`);
         }
         this.plugins.set(plugin.id, plugin);
     }
+    /** Remove a plugin by id; a no-op if no such plugin is registered. */
     unregister(id) {
         this.plugins.delete(id);
     }
+    /** Remove all registered plugins. */
     clear() {
         this.plugins.clear();
     }
+    /** All registered plugins, sorted by descending priority (turn run order). */
     getAll() {
         return Array.from(this.plugins.values()).sort((a, b) => b.priority - a.priority);
     }
+    /** Look up a single plugin by id, or `undefined` if absent. */
     getById(id) {
         return this.plugins.get(id);
     }
+    /**
+     * Collect each plugin's {@link TurnPlugin.getState} result, keyed by plugin id,
+     * for inclusion in a save. Plugins without `getState` are omitted.
+     */
     getStates() {
         const states = {};
         for (const plugin of this.plugins.values()) {
@@ -30,6 +45,11 @@ class PluginRegistry {
         }
         return states;
     }
+    /**
+     * Restore plugin state from a prior {@link PluginRegistry.getStates} result on
+     * load, calling each matching plugin's {@link TurnPlugin.setState}. Entries
+     * with no registered plugin (or no `setState`) are skipped.
+     */
     setStates(states) {
         for (const [id, state] of Object.entries(states)) {
             const plugin = this.plugins.get(id);

package/plugin-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-registry.js","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugins/src/plugin-registry.ts"],"names":[],"mappings":";;;AAEA,MAAa,cAAc;IACjB,OAAO,GAA4B,IAAI,GAAG,EAAE,CAAC;IAErD,QAAQ,CAAC,MAAkB;QACzB,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,8BAA8B,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,UAAU,CAAC,EAAU;QACnB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC;IAED,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,MAAM;QACJ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAC3C,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAClC,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,EAAU;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED,SAAS;QACP,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAC3C,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACpB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;YACxC,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,SAAS,CAAC,MAA+B;QACvC,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACjD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACpC,IAAI,MAAM,EAAE,QAAQ,EAAE,CAAC;gBACrB,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;CACF;AA9CD,wCA8CC"}
+{"version":3,"file":"plugin-registry.js","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugins/src/plugin-registry.ts"],"names":[],"mappings":";;;AAEA;;;;;GAKG;AACH,MAAa,cAAc;IACjB,OAAO,GAA4B,IAAI,GAAG,EAAE,CAAC;IAErD,oFAAoF;IACpF,QAAQ,CAAC,MAAkB;QACzB,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,8BAA8B,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,sEAAsE;IACtE,UAAU,CAAC,EAAU;QACnB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC;IAED,qCAAqC;IACrC,KAAK;QACH,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED,8EAA8E;IAC9E,MAAM;QACJ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAC3C,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAClC,CAAC;IACJ,CAAC;IAED,+DAA+D;IAC/D,OAAO,CAAC,EAAU;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC;IAED;;;OAGG;IACH,SAAS;QACP,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAC3C,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACpB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC;YACxC,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;OAIG;IACH,SAAS,CAAC,MAA+B;QACvC,KAAK,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACjD,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACpC,IAAI,MAAM,EAAE,QAAQ,EAAE,CAAC;gBACrB,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;CACF;AA5DD,wCA4DC"}

package/turn-plugin-context.d.ts

@@ -1,18 +1,34 @@
-import { EntityId, SeededRandom, ISemanticEvent } from "../core/index";
-import { WorldModel } from "../world-model/index";
+import { EntityId, SeededRandom, ISemanticEvent } from '@sharpee/core';
+import { WorldModel } from '@sharpee/world-model';
+/** Summary of the player action that just completed, passed to each plugin. */
 export interface TurnPluginActionResult {
+    /** The action's id (the verb that ran). */
     actionId: string;
+    /** Whether the action succeeded. Plugins only run after successful actions. */
     success: boolean;
+    /** The action's direct-object entity, when it had one. */
     targetId?: EntityId;
+    /** Arbitrary data the action chose to share, keyed by the action. */
     sharedData?: Record<string, unknown>;
 }
+/** Read-only turn context the engine passes to each plugin's onAfterAction. */
 export interface TurnPluginContext {
+    /** The live world model. */
     world: WorldModel;
+    /** The current turn number. */
     turn: number;
+    /** The player entity id. */
     playerId: EntityId;
+    /** The player's current location id. */
     playerLocation: EntityId;
+    /**
+     * The engine's seeded RNG. Use this instead of `Math.random` so turns stay
+     * deterministic and replayable.
+     */
     random: SeededRandom;
+    /** The action that just completed this turn. */
     actionResult?: TurnPluginActionResult;
+    /** The semantic events the action emitted this turn. */
     actionEvents?: ISemanticEvent[];
 }
 //# sourceMappingURL=turn-plugin-context.d.ts.map

package/turn-plugin-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"turn-plugin-context.d.ts","sourceRoot":"","sources":["../../../../../repos/sharpee/packages/plugins/src/turn-plugin-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,cAAc,EAAE,QAAQ,CAAC;IACzB,MAAM,EAAE,YAAY,CAAC;IACrB,YAAY,CAAC,EAAE,sBAAsB,CAAC;IACtC,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;CACjC"}
+{"version":3,"file":"turn-plugin-context.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugins/src/turn-plugin-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,+EAA+E;AAC/E,MAAM,WAAW,sBAAsB;IACrC,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,QAAQ,EAAE,QAAQ,CAAC;IACnB,wCAAwC;IACxC,cAAc,EAAE,QAAQ,CAAC;IACzB;;;OAGG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB,gDAAgD;IAChD,YAAY,CAAC,EAAE,sBAAsB,CAAC;IACtC,wDAAwD;IACxD,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;CACjC"}

package/turn-plugin.d.ts

@@ -1,10 +1,28 @@
-import { ISemanticEvent } from "../core/index";
+import { ISemanticEvent } from '@sharpee/core';
 import { TurnPluginContext } from './turn-plugin-context';
+/**
+ * A turn-cycle plugin: code that runs once after each successful player action
+ * to contribute additional world changes and events (ADR-120).
+ *
+ * The engine invokes every registered plugin's {@link TurnPlugin.onAfterAction}
+ * in descending {@link TurnPlugin.priority} order (NPC behaviour at 100, state
+ * machines at 75, the scheduler at 50). Plugins do not run for meta-commands or
+ * for failed actions.
+ */
 export interface TurnPlugin {
+    /** Unique plugin identifier. Registering two plugins with the same id throws. */
     id: string;
+    /** Run order within a turn; higher priority runs first. */
     priority: number;
+    /**
+     * Called once per successful player action. Return the semantic events the
+     * plugin produces; the engine merges a non-empty array into the turn's event
+     * stream. Return an empty array to contribute nothing.
+     */
     onAfterAction(context: TurnPluginContext): ISemanticEvent[];
+    /** Optional: return serializable state to persist when the game is saved. */
     getState?(): unknown;
+    /** Optional: restore previously-saved state when the game is loaded. */
     setState?(state: unknown): void;
 }
 //# sourceMappingURL=turn-plugin.d.ts.map

package/turn-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"turn-plugin.d.ts","sourceRoot":"","sources":["../../../../../repos/sharpee/packages/plugins/src/turn-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1D,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,EAAE,CAAC;IAC5D,QAAQ,CAAC,IAAI,OAAO,CAAC;IACrB,QAAQ,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACjC"}
+{"version":3,"file":"turn-plugin.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugins/src/turn-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1D;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,iFAAiF;IACjF,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,EAAE,CAAC;IAC5D,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,OAAO,CAAC;IACrB,wEAAwE;IACxE,QAAQ,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACjC"}