@sharpee/plugin-state-machine 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md ADDED
@@ -0,0 +1,60 @@
1
+ # @sharpee/plugin-state-machine
2
+
3
+ State machine plugin for the Sharpee engine: declarative puzzle and narrative orchestration (ADR-119, ADR-120).
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @sharpee/plugin-state-machine
9
+ ```
10
+
11
+ ## Overview
12
+
13
+ This package implements the `TurnPlugin` contract from `@sharpee/plugins` with declarative, data-driven state machines:
14
+
15
+ - **`StateMachinePlugin`** - Runs at priority 75, after NPCs (100) and before the scheduler (50); evaluates every machine each turn (ADR-119, ADR-120).
16
+ - **`StateMachineDefinition`** - States with transitions, `onEnter`/`onExit` effects, and terminal states.
17
+ - **Triggers** - Transitions fire on an `action`, an `event` (with optional data filter), or a `condition`.
18
+ - **Guards** - Entity, state, location, inventory, composite (`and`/`or`/`not`), and custom predicates gate transitions.
19
+ - **Effects** - Declarative `move`, `remove`, `set_trait`, `set_state`, `message`, `emit_event`, and custom effects run on transitions and state entry/exit.
20
+ - **`StateMachineRegistry`** - Reachable via `getRegistry()`; binds machine roles (`$door`) to entities and serializes machine state for save/load.
21
+
22
+ ## Usage
23
+
24
+ ```typescript
25
+ import { StateMachinePlugin, StateMachineDefinition } from '@sharpee/plugin-state-machine';
26
+
27
+ const smPlugin = new StateMachinePlugin();
28
+ engine.plugins.register(smPlugin);
29
+
30
+ const lock: StateMachineDefinition = {
31
+ id: 'vault-lock',
32
+ initialState: 'locked',
33
+ states: {
34
+ locked: {
35
+ transitions: [
36
+ {
37
+ target: 'open',
38
+ trigger: { type: 'action', actionId: 'unlock', targetEntity: '$door' },
39
+ guard: { type: 'inventory', entityRef: '$key' },
40
+ effects: [{ type: 'set_trait', entityRef: '$door', trait: 'openable', property: 'isOpen', value: true }]
41
+ }
42
+ ]
43
+ },
44
+ open: { terminal: true }
45
+ }
46
+ };
47
+
48
+ // Bind roles to concrete entities and register the machine
49
+ smPlugin.getRegistry().register(lock, { $door: doorId, $key: keyId });
50
+ ```
51
+
52
+ ## Related Packages
53
+
54
+ - [@sharpee/plugins](https://www.npmjs.com/package/@sharpee/plugins) - Turn-plugin contracts
55
+ - [@sharpee/world-model](https://www.npmjs.com/package/@sharpee/world-model) - Entity system the effects and guards operate on
56
+ - [@sharpee/sharpee](https://www.npmjs.com/package/@sharpee/sharpee) - Full platform bundle
57
+
58
+ ## License
59
+
60
+ MIT
@@ -1,8 +1,18 @@
1
1
  /**
2
2
  * Effect Executor - applies state machine effects to the world model.
3
3
  */
4
- import { EntityId, ISemanticEvent } from "../core/index";
5
- import { WorldModel } from "../world-model/index";
4
+ import { EntityId, ISemanticEvent } from '@sharpee/core';
5
+ import { WorldModel } from '@sharpee/world-model';
6
6
  import { Effect, EntityBindings } from './types';
7
+ /**
8
+ * Apply a list of {@link Effect}s to the world in order and collect the semantic
9
+ * events they emit.
10
+ * @param effects The effects to run.
11
+ * @param world The live world model to mutate.
12
+ * @param bindings Role-to-entity bindings used to resolve `$` references.
13
+ * @param playerId The player, passed to custom effects.
14
+ * @param machineId The owning machine's id, tagged onto emitted events.
15
+ * @returns The events produced by the effects.
16
+ */
7
17
  export declare function executeEffects(effects: Effect[], world: WorldModel, bindings: EntityBindings, playerId: EntityId, machineId: string): ISemanticEvent[];
8
18
  //# sourceMappingURL=effect-executor.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"effect-executor.d.ts","sourceRoot":"","sources":["../../../../../repos/sharpee/packages/plugin-state-machine/src/effect-executor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAKjD,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,GAChB,cAAc,EAAE,CASlB"}
1
+ {"version":3,"file":"effect-executor.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugin-state-machine/src/effect-executor.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAKjD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EAAE,EACjB,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,GAChB,cAAc,EAAE,CASlB"}
@@ -6,6 +6,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
6
6
  exports.executeEffects = executeEffects;
7
7
  const guard_evaluator_1 = require("./guard-evaluator");
8
8
  let eventCounter = 0;
9
+ /**
10
+ * Apply a list of {@link Effect}s to the world in order and collect the semantic
11
+ * events they emit.
12
+ * @param effects The effects to run.
13
+ * @param world The live world model to mutate.
14
+ * @param bindings Role-to-entity bindings used to resolve `$` references.
15
+ * @param playerId The player, passed to custom effects.
16
+ * @param machineId The owning machine's id, tagged onto emitted events.
17
+ * @returns The events produced by the effects.
18
+ */
9
19
  function executeEffects(effects, world, bindings, playerId, machineId) {
10
20
  const events = [];
11
21
  for (const effect of effects) {
@@ -1 +1 @@
1
- {"version":3,"file":"effect-executor.js","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugin-state-machine/src/effect-executor.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"effect-executor.js","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugin-state-machine/src/effect-executor.ts"],"names":[],"mappings":"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"}
@@ -1,9 +1,21 @@
1
1
  /**
2
2
  * Guard Evaluator - evaluates guard conditions against world state.
3
3
  */
4
- import { EntityId } from "../core/index";
5
- import { WorldModel } from "../world-model/index";
4
+ import { EntityId } from '@sharpee/core';
5
+ import { WorldModel } from '@sharpee/world-model';
6
6
  import { GuardCondition, EntityBindings } from './types';
7
+ /**
8
+ * Evaluate a {@link GuardCondition} against current world state.
9
+ * @param guard The condition to test.
10
+ * @param world The live world model.
11
+ * @param bindings Role-to-entity bindings used to resolve `$` references.
12
+ * @param playerId The player, used as the default actor for location/inventory guards.
13
+ * @returns true when the condition holds.
14
+ */
7
15
  export declare function evaluateGuard(guard: GuardCondition, world: WorldModel, bindings: EntityBindings, playerId: EntityId): boolean;
16
+ /**
17
+ * Resolve an entity reference: a `$`-prefixed role is looked up in `bindings`
18
+ * (throwing if unbound); any other string is returned as a literal entity id.
19
+ */
8
20
  export declare function resolveRef(ref: string, bindings: EntityBindings): EntityId;
9
21
  //# sourceMappingURL=guard-evaluator.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"guard-evaluator.d.ts","sourceRoot":"","sources":["../../../../../repos/sharpee/packages/plugin-state-machine/src/guard-evaluator.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EACL,cAAc,EACd,cAAc,EACf,MAAM,SAAS,CAAC;AAEjB,wBAAgB,aAAa,CAC3B,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAmBT;AAuCD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,QAAQ,CAS1E"}
1
+ {"version":3,"file":"guard-evaluator.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugin-state-machine/src/guard-evaluator.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EACL,cAAc,EACd,cAAc,EACf,MAAM,SAAS,CAAC;AAEjB;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,cAAc,EACrB,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAmBT;AAuCD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,GAAG,QAAQ,CAS1E"}
@@ -5,6 +5,14 @@
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
6
  exports.evaluateGuard = evaluateGuard;
7
7
  exports.resolveRef = resolveRef;
8
+ /**
9
+ * Evaluate a {@link GuardCondition} against current world state.
10
+ * @param guard The condition to test.
11
+ * @param world The live world model.
12
+ * @param bindings Role-to-entity bindings used to resolve `$` references.
13
+ * @param playerId The player, used as the default actor for location/inventory guards.
14
+ * @returns true when the condition holds.
15
+ */
8
16
  function evaluateGuard(guard, world, bindings, playerId) {
9
17
  switch (guard.type) {
10
18
  case 'entity':
@@ -45,6 +53,10 @@ function evaluateInventoryGuard(guard, world, bindings, playerId) {
45
53
  const entityId = resolveRef(guard.entityRef, bindings);
46
54
  return world.getLocation(entityId) === actorId;
47
55
  }
56
+ /**
57
+ * Resolve an entity reference: a `$`-prefixed role is looked up in `bindings`
58
+ * (throwing if unbound); any other string is returned as a literal entity id.
59
+ */
48
60
  function resolveRef(ref, bindings) {
49
61
  if (ref.startsWith('$')) {
50
62
  const bound = bindings[ref];
@@ -1 +1 @@
1
- {"version":3,"file":"guard-evaluator.js","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugin-state-machine/src/guard-evaluator.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"guard-evaluator.js","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugin-state-machine/src/guard-evaluator.ts"],"names":[],"mappings":"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"}
package/index.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../repos/sharpee/packages/plugin-state-machine/src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugin-state-machine/src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,wBAAwB,CAAC;AACvC,cAAc,yBAAyB,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sharpee/plugin-state-machine",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "State machine plugin for Sharpee engine - declarative puzzle and narrative orchestration (ADR-119, ADR-120)",
5
5
  "main": "./index.js",
6
6
  "types": "./index.d.ts",
@@ -12,9 +12,9 @@
12
12
  }
13
13
  },
14
14
  "dependencies": {
15
- "@sharpee/core": "^1.0.0",
16
- "@sharpee/world-model": "^1.0.0",
17
- "@sharpee/plugins": "^1.0.0"
15
+ "@sharpee/core": "^1.1.0",
16
+ "@sharpee/world-model": "^1.1.0",
17
+ "@sharpee/plugins": "^1.1.0"
18
18
  },
19
19
  "keywords": [
20
20
  "interactive-fiction",
@@ -4,17 +4,31 @@
4
4
  * Priority 75: Runs after NPCs (100) but before scheduler (50).
5
5
  * Evaluates state machine transitions after each successful player action.
6
6
  */
7
- import { ISemanticEvent } from "../core/index";
8
- import { TurnPlugin, TurnPluginContext } from "../plugins/index";
7
+ import { ISemanticEvent } from '@sharpee/core';
8
+ import { TurnPlugin, TurnPluginContext } from '@sharpee/plugins';
9
9
  import { StateMachineRegistry } from './state-machine-runtime';
10
+ /**
11
+ * The {@link TurnPlugin} that drives declarative state machines (ADR-119).
12
+ *
13
+ * Runs at priority 75 — after NPC behaviour (100), before the scheduler (50).
14
+ * Each turn it evaluates every machine in its {@link StateMachineRegistry} and
15
+ * returns the events produced by any transitions that fired. Register the
16
+ * plugin with the engine, then add machines via {@link getRegistry}.
17
+ */
10
18
  export declare class StateMachinePlugin implements TurnPlugin {
19
+ /** Stable plugin id. */
11
20
  id: string;
21
+ /** Run order within a turn (after NPCs, before the scheduler). */
12
22
  priority: number;
13
23
  private registry;
14
24
  constructor();
25
+ /** Evaluate all registered machines for this turn and return their events. */
15
26
  onAfterAction(ctx: TurnPluginContext): ISemanticEvent[];
27
+ /** Serialize all machine instances for saving. */
16
28
  getState(): unknown;
29
+ /** Restore machine instances from a prior {@link getState} result on load. */
17
30
  setState(state: unknown): void;
31
+ /** The registry where stories add and inspect their state machines. */
18
32
  getRegistry(): StateMachineRegistry;
19
33
  }
20
34
  //# sourceMappingURL=state-machine-plugin.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"state-machine-plugin.d.ts","sourceRoot":"","sources":["../../../../../repos/sharpee/packages/plugin-state-machine/src/state-machine-plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAG/D,qBAAa,kBAAmB,YAAW,UAAU;IACnD,EAAE,SAAkC;IACpC,QAAQ,SAAM;IACd,OAAO,CAAC,QAAQ,CAAuB;;IAMvC,aAAa,CAAC,GAAG,EAAE,iBAAiB,GAAG,cAAc,EAAE;IAkBvD,QAAQ,IAAI,OAAO;IAInB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAI9B,WAAW,IAAI,oBAAoB;CAGpC"}
1
+ {"version":3,"file":"state-machine-plugin.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugin-state-machine/src/state-machine-plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAG/D;;;;;;;GAOG;AACH,qBAAa,kBAAmB,YAAW,UAAU;IACnD,wBAAwB;IACxB,EAAE,SAAkC;IACpC,kEAAkE;IAClE,QAAQ,SAAM;IACd,OAAO,CAAC,QAAQ,CAAuB;;IAMvC,8EAA8E;IAC9E,aAAa,CAAC,GAAG,EAAE,iBAAiB,GAAG,cAAc,EAAE;IAkBvD,kDAAkD;IAClD,QAAQ,IAAI,OAAO;IAInB,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAI9B,uEAAuE;IACvE,WAAW,IAAI,oBAAoB;CAGpC"}
@@ -8,13 +8,24 @@
8
8
  Object.defineProperty(exports, "__esModule", { value: true });
9
9
  exports.StateMachinePlugin = void 0;
10
10
  const state_machine_runtime_1 = require("./state-machine-runtime");
11
+ /**
12
+ * The {@link TurnPlugin} that drives declarative state machines (ADR-119).
13
+ *
14
+ * Runs at priority 75 — after NPC behaviour (100), before the scheduler (50).
15
+ * Each turn it evaluates every machine in its {@link StateMachineRegistry} and
16
+ * returns the events produced by any transitions that fired. Register the
17
+ * plugin with the engine, then add machines via {@link getRegistry}.
18
+ */
11
19
  class StateMachinePlugin {
20
+ /** Stable plugin id. */
12
21
  id = 'sharpee.plugin.state-machine';
22
+ /** Run order within a turn (after NPCs, before the scheduler). */
13
23
  priority = 75;
14
24
  registry;
15
25
  constructor() {
16
26
  this.registry = new state_machine_runtime_1.StateMachineRegistry();
17
27
  }
28
+ /** Evaluate all registered machines for this turn and return their events. */
18
29
  onAfterAction(ctx) {
19
30
  const evalCtx = {
20
31
  world: ctx.world,
@@ -31,12 +42,15 @@ class StateMachinePlugin {
31
42
  };
32
43
  return this.registry.evaluate(evalCtx);
33
44
  }
45
+ /** Serialize all machine instances for saving. */
34
46
  getState() {
35
47
  return this.registry.getState();
36
48
  }
49
+ /** Restore machine instances from a prior {@link getState} result on load. */
37
50
  setState(state) {
38
51
  this.registry.setState(state);
39
52
  }
53
+ /** The registry where stories add and inspect their state machines. */
40
54
  getRegistry() {
41
55
  return this.registry;
42
56
  }
@@ -1 +1 @@
1
- {"version":3,"file":"state-machine-plugin.js","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugin-state-machine/src/state-machine-plugin.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAIH,mEAA+D;AAG/D,MAAa,kBAAkB;IAC7B,EAAE,GAAG,8BAA8B,CAAC;IACpC,QAAQ,GAAG,EAAE,CAAC;IACN,QAAQ,CAAuB;IAEvC;QACE,IAAI,CAAC,QAAQ,GAAG,IAAI,4CAAoB,EAAE,CAAC;IAC7C,CAAC;IAED,aAAa,CAAC,GAAsB;QAClC,MAAM,OAAO,GAAsB;YACjC,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,cAAc,EAAE,GAAG,CAAC,cAAc;YAClC,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,QAAQ,EAAE,GAAG,CAAC,YAAY,EAAE,QAAQ;YACpC,cAAc,EAAE,GAAG,CAAC,YAAY,EAAE,QAAQ;YAC1C,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBACxC,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,QAAQ,EAAE,CAAC,CAAC,QAAkC;aAC/C,CAAC,CAAC;SACJ,CAAC;QAEF,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;IAClC,CAAC;IAED,QAAQ,CAAC,KAAc;QACrB,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAkC,CAAC,CAAC;IAC7D,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF;AAtCD,gDAsCC"}
1
+ {"version":3,"file":"state-machine-plugin.js","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugin-state-machine/src/state-machine-plugin.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAIH,mEAA+D;AAG/D;;;;;;;GAOG;AACH,MAAa,kBAAkB;IAC7B,wBAAwB;IACxB,EAAE,GAAG,8BAA8B,CAAC;IACpC,kEAAkE;IAClE,QAAQ,GAAG,EAAE,CAAC;IACN,QAAQ,CAAuB;IAEvC;QACE,IAAI,CAAC,QAAQ,GAAG,IAAI,4CAAoB,EAAE,CAAC;IAC7C,CAAC;IAED,8EAA8E;IAC9E,aAAa,CAAC,GAAsB;QAClC,MAAM,OAAO,GAAsB;YACjC,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,QAAQ,EAAE,GAAG,CAAC,QAAQ;YACtB,cAAc,EAAE,GAAG,CAAC,cAAc;YAClC,IAAI,EAAE,GAAG,CAAC,IAAI;YACd,QAAQ,EAAE,GAAG,CAAC,YAAY,EAAE,QAAQ;YACpC,cAAc,EAAE,GAAG,CAAC,YAAY,EAAE,QAAQ;YAC1C,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;gBACxC,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,QAAQ,EAAE,CAAC,CAAC,QAAkC;aAC/C,CAAC,CAAC;SACJ,CAAC;QAEF,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACzC,CAAC;IAED,kDAAkD;IAClD,QAAQ;QACN,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;IAClC,CAAC;IAED,8EAA8E;IAC9E,QAAQ,CAAC,KAAc;QACrB,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAkC,CAAC,CAAC;IAC7D,CAAC;IAED,uEAAuE;IACvE,WAAW;QACT,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF;AA5CD,gDA4CC"}
@@ -3,19 +3,40 @@
3
3
  *
4
4
  * Manages registered state machines and evaluates transitions each turn.
5
5
  */
6
- import { ISemanticEvent } from "../core/index";
6
+ import { ISemanticEvent } from '@sharpee/core';
7
7
  import { StateMachineDefinition, EntityBindings, EvaluationContext, StateMachineRegistryState } from './types';
8
+ /**
9
+ * Holds the running state machines for a story and advances them each turn
10
+ * (ADR-119). Stories obtain the registry from
11
+ * {@link StateMachinePlugin.getRegistry} and {@link register} their machines.
12
+ */
8
13
  export declare class StateMachineRegistry {
9
14
  private machines;
15
+ /**
16
+ * Register a machine and start it in its initial state.
17
+ * @param definition The machine to add.
18
+ * @param bindings Role-to-entity bindings (e.g. `{ $door: doorId }`).
19
+ * @throws if the id is already registered or the initial state is missing.
20
+ */
10
21
  register(definition: StateMachineDefinition, bindings?: EntityBindings): void;
22
+ /** Remove a machine by id; a no-op if absent. */
11
23
  unregister(id: string): void;
24
+ /** The current state name of a machine, or `undefined` if not registered. */
12
25
  getMachineState(id: string): string | undefined;
26
+ /** The ordered state history of a machine, or `undefined` if not registered. */
13
27
  getMachineHistory(id: string): string[] | undefined;
28
+ /**
29
+ * Evaluate every non-terminal machine for this turn, firing at most one
30
+ * transition per machine (highest-priority matching trigger whose guard
31
+ * passes), and return all events the fired transitions produced.
32
+ */
14
33
  evaluate(ctx: EvaluationContext): ISemanticEvent[];
15
34
  private findMatchingTransition;
16
35
  private triggerMatches;
17
36
  private executeTransition;
37
+ /** Serialize every machine instance (current state + history) for saving. */
18
38
  getState(): StateMachineRegistryState;
39
+ /** Restore machine instances from a prior {@link getState} result on load. */
19
40
  setState(state: StateMachineRegistryState): void;
20
41
  }
21
42
  //# sourceMappingURL=state-machine-runtime.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"state-machine-runtime.d.ts","sourceRoot":"","sources":["../../../../../repos/sharpee/packages/plugin-state-machine/src/state-machine-runtime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,iBAAiB,EAIjB,yBAAyB,EAC1B,MAAM,SAAS,CAAC;AAWjB,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAwC;IAExD,QAAQ,CAAC,UAAU,EAAE,sBAAsB,EAAE,QAAQ,GAAE,cAAmB,GAAG,IAAI;IAgBjF,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI5B,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI/C,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IAInD,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,cAAc,EAAE;IAsBlD,OAAO,CAAC,sBAAsB;IAmB9B,OAAO,CAAC,cAAc;IAyCtB,OAAO,CAAC,iBAAiB;IA2DzB,QAAQ,IAAI,yBAAyB;IAYrC,QAAQ,CAAC,KAAK,EAAE,yBAAyB,GAAG,IAAI;CASjD"}
1
+ {"version":3,"file":"state-machine-runtime.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugin-state-machine/src/state-machine-runtime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,iBAAiB,EAIjB,yBAAyB,EAC1B,MAAM,SAAS,CAAC;AAWjB;;;;GAIG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAwC;IAExD;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,sBAAsB,EAAE,QAAQ,GAAE,cAAmB,GAAG,IAAI;IAgBjF,iDAAiD;IACjD,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI5B,6EAA6E;IAC7E,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI/C,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS;IAInD;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,iBAAiB,GAAG,cAAc,EAAE;IAsBlD,OAAO,CAAC,sBAAsB;IAmB9B,OAAO,CAAC,cAAc;IAyCtB,OAAO,CAAC,iBAAiB;IA2DzB,6EAA6E;IAC7E,QAAQ,IAAI,yBAAyB;IAYrC,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,yBAAyB,GAAG,IAAI;CASjD"}
@@ -8,8 +8,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
8
8
  exports.StateMachineRegistry = void 0;
9
9
  const guard_evaluator_1 = require("./guard-evaluator");
10
10
  const effect_executor_1 = require("./effect-executor");
11
+ /**
12
+ * Holds the running state machines for a story and advances them each turn
13
+ * (ADR-119). Stories obtain the registry from
14
+ * {@link StateMachinePlugin.getRegistry} and {@link register} their machines.
15
+ */
11
16
  class StateMachineRegistry {
12
17
  machines = new Map();
18
+ /**
19
+ * Register a machine and start it in its initial state.
20
+ * @param definition The machine to add.
21
+ * @param bindings Role-to-entity bindings (e.g. `{ $door: doorId }`).
22
+ * @throws if the id is already registered or the initial state is missing.
23
+ */
13
24
  register(definition, bindings = {}) {
14
25
  if (this.machines.has(definition.id)) {
15
26
  throw new Error(`State machine already registered: ${definition.id}`);
@@ -25,15 +36,23 @@ class StateMachineRegistry {
25
36
  history: [definition.initialState],
26
37
  });
27
38
  }
39
+ /** Remove a machine by id; a no-op if absent. */
28
40
  unregister(id) {
29
41
  this.machines.delete(id);
30
42
  }
43
+ /** The current state name of a machine, or `undefined` if not registered. */
31
44
  getMachineState(id) {
32
45
  return this.machines.get(id)?.currentState;
33
46
  }
47
+ /** The ordered state history of a machine, or `undefined` if not registered. */
34
48
  getMachineHistory(id) {
35
49
  return this.machines.get(id)?.history;
36
50
  }
51
+ /**
52
+ * Evaluate every non-terminal machine for this turn, firing at most one
53
+ * transition per machine (highest-priority matching trigger whose guard
54
+ * passes), and return all events the fired transitions produced.
55
+ */
37
56
  evaluate(ctx) {
38
57
  const allEvents = [];
39
58
  for (const machine of this.machines.values()) {
@@ -137,6 +156,7 @@ class StateMachineRegistry {
137
156
  return events;
138
157
  }
139
158
  // ─── Serialization ──────────────────────────────────────────────────────
159
+ /** Serialize every machine instance (current state + history) for saving. */
140
160
  getState() {
141
161
  const instances = [];
142
162
  for (const machine of this.machines.values()) {
@@ -148,6 +168,7 @@ class StateMachineRegistry {
148
168
  }
149
169
  return { instances };
150
170
  }
171
+ /** Restore machine instances from a prior {@link getState} result on load. */
151
172
  setState(state) {
152
173
  for (const instanceState of state.instances) {
153
174
  const machine = this.machines.get(instanceState.id);
@@ -1 +1 @@
1
- {"version":3,"file":"state-machine-runtime.js","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugin-state-machine/src/state-machine-runtime.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"state-machine-runtime.js","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugin-state-machine/src/state-machine-runtime.ts"],"names":[],"mappings":"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"}
package/types.d.ts CHANGED
@@ -2,144 +2,235 @@
2
2
  * State Machine Types (ADR-119)
3
3
  *
4
4
  * Declarative state machine definitions for puzzle and narrative orchestration.
5
+ *
6
+ * Entity references in these types use a binding convention: a string starting
7
+ * with `$` (e.g. `$door`) is a role looked up in the machine's
8
+ * {@link EntityBindings}; any other string is a literal entity id.
5
9
  */
6
- import { EntityId } from "../core/index";
7
- import { WorldModel } from "../world-model/index";
10
+ import { EntityId } from '@sharpee/core';
11
+ import { WorldModel } from '@sharpee/world-model';
12
+ /** A complete declarative state machine: its states and where it starts. */
8
13
  export interface StateMachineDefinition {
14
+ /** Unique machine id. Registering two machines with the same id throws. */
9
15
  id: string;
16
+ /** Optional human-readable description of what the machine models. */
10
17
  description?: string;
18
+ /** The state the machine begins in; must be a key of {@link states}. */
11
19
  initialState: string;
20
+ /** All states, keyed by state name. */
12
21
  states: Record<string, StateDefinition>;
13
22
  }
23
+ /** One state within a machine. */
14
24
  export interface StateDefinition {
25
+ /** Optional description of the state. */
15
26
  description?: string;
27
+ /** Transitions out of this state, tried in descending `priority` each turn. */
16
28
  transitions?: TransitionDefinition[];
29
+ /** Effects run when the machine enters this state. */
17
30
  onEnter?: Effect[];
31
+ /** Effects run when the machine leaves this state. */
18
32
  onExit?: Effect[];
33
+ /** When true, the machine stops evaluating once in this state (an end state). */
19
34
  terminal?: boolean;
20
35
  }
36
+ /** A single edge from the owning state to {@link target}. */
21
37
  export interface TransitionDefinition {
38
+ /** Name of the state to move to when this transition fires. */
22
39
  target: string;
40
+ /** What causes this transition to be considered. */
23
41
  trigger: TransitionTrigger;
42
+ /** Optional extra condition that must hold for the transition to fire. */
24
43
  guard?: GuardCondition;
44
+ /** Effects run as part of taking this transition (after onExit, before onEnter). */
25
45
  effects?: Effect[];
46
+ /** Higher priority transitions are tried first; defaults to 0. */
26
47
  priority?: number;
27
48
  }
49
+ /** What can cause a transition to be considered. */
28
50
  export type TransitionTrigger = ActionTrigger | EventTrigger | ConditionTrigger;
51
+ /** Fires when the player runs a specific action (optionally on a specific target). */
29
52
  export interface ActionTrigger {
30
53
  type: 'action';
54
+ /** The action id to match (the verb that ran). */
31
55
  actionId: string;
56
+ /** Optional target to match: a role reference (`$door`) or a literal entity id. */
32
57
  targetEntity?: string;
33
58
  }
59
+ /** Fires when one of the turn's action events matches. */
34
60
  export interface EventTrigger {
35
61
  type: 'event';
62
+ /** The event type to match. */
36
63
  eventId: string;
64
+ /** Optional event-data fields that must match; `$`-values resolve via bindings. */
37
65
  filter?: Record<string, unknown>;
38
66
  }
67
+ /** Fires when a guard condition evaluates true (no player action required). */
39
68
  export interface ConditionTrigger {
40
69
  type: 'condition';
70
+ /** The condition to evaluate against world state each turn. */
41
71
  condition: GuardCondition;
42
72
  }
73
+ /** A boolean condition evaluated against world state. */
43
74
  export type GuardCondition = EntityGuard | StateGuard | LocationGuard | InventoryGuard | CompositeGuard | CustomGuard;
75
+ /** True when an entity's trait property equals a value. */
44
76
  export interface EntityGuard {
45
77
  type: 'entity';
78
+ /** Role reference (`$x`) or literal id of the entity to inspect. */
46
79
  entityRef: string;
80
+ /** Trait name on the entity. */
47
81
  trait: string;
82
+ /** Property of that trait to read. */
48
83
  property: string;
84
+ /** Value the property must equal. */
49
85
  value: unknown;
50
86
  }
87
+ /** True when a world state value equals a value. */
51
88
  export interface StateGuard {
52
89
  type: 'state';
90
+ /** World state key (see `world.getStateValue`). */
53
91
  key: string;
92
+ /** Value the state must equal. */
54
93
  value: unknown;
55
94
  }
95
+ /** True when an actor is in a given room. */
56
96
  export interface LocationGuard {
57
97
  type: 'location';
98
+ /** Role/id of the actor; defaults to the player when omitted. */
58
99
  actorRef?: string;
100
+ /** Role/id of the room the actor must be in. */
59
101
  roomRef: string;
60
102
  }
103
+ /** True when an actor is carrying a given entity. */
61
104
  export interface InventoryGuard {
62
105
  type: 'inventory';
106
+ /** Role/id of the carrier; defaults to the player when omitted. */
63
107
  actorRef?: string;
108
+ /** Role/id of the entity that must be carried. */
64
109
  entityRef: string;
65
110
  }
111
+ /** Combines other guards with boolean logic. */
66
112
  export interface CompositeGuard {
113
+ /** `and` = all true, `or` = any true, `not` = not all true. */
67
114
  type: 'and' | 'or' | 'not';
115
+ /** The sub-conditions to combine. */
68
116
  conditions: GuardCondition[];
69
117
  }
118
+ /** A guard backed by a custom predicate function. */
70
119
  export interface CustomGuard {
71
120
  type: 'custom';
121
+ /** Returns true when the guard passes. */
72
122
  evaluate: (world: WorldModel, bindings: EntityBindings, playerId: EntityId) => boolean;
73
123
  }
124
+ /** A world mutation or event emission performed when a transition/state fires. */
74
125
  export type Effect = MoveEntityEffect | RemoveEntityEffect | SetTraitEffect | SetStateEffect | MessageEffect | EmitEventEffect | CustomEffect;
126
+ /** Move an entity to a destination. */
75
127
  export interface MoveEntityEffect {
76
128
  type: 'move';
129
+ /** Role/id of the entity to move. */
77
130
  entityRef: string;
131
+ /** Role/id of the destination (room or container). */
78
132
  destinationRef: string;
79
133
  }
134
+ /** Remove an entity from the world. */
80
135
  export interface RemoveEntityEffect {
81
136
  type: 'remove';
137
+ /** Role/id of the entity to remove. */
82
138
  entityRef: string;
83
139
  }
140
+ /** Set a property on an entity's trait. */
84
141
  export interface SetTraitEffect {
85
142
  type: 'set_trait';
143
+ /** Role/id of the entity. */
86
144
  entityRef: string;
145
+ /** Trait name. */
87
146
  trait: string;
147
+ /** Property to set. */
88
148
  property: string;
149
+ /** Value to assign. */
89
150
  value: unknown;
90
151
  }
152
+ /** Set a world state value. */
91
153
  export interface SetStateEffect {
92
154
  type: 'set_state';
155
+ /** World state key. */
93
156
  key: string;
157
+ /** Value to store. */
94
158
  value: unknown;
95
159
  }
160
+ /** Emit a message event for the player to see. */
96
161
  export interface MessageEffect {
97
162
  type: 'message';
163
+ /** Message id to resolve via the language provider. */
98
164
  messageId: string;
165
+ /** Optional parameters for the message template. */
99
166
  params?: Record<string, unknown>;
100
167
  }
168
+ /** Emit an arbitrary semantic event. */
101
169
  export interface EmitEventEffect {
102
170
  type: 'emit_event';
171
+ /** The event type to emit. */
103
172
  eventType: string;
173
+ /** Optional role/id entities to attach, by semantic role; `$`-values resolve via bindings. */
104
174
  entities?: {
105
175
  actor?: string;
106
176
  target?: string;
107
177
  instrument?: string;
108
178
  location?: string;
109
179
  };
180
+ /** Optional event payload. */
110
181
  data?: unknown;
111
182
  }
183
+ /** An effect backed by a custom function. */
112
184
  export interface CustomEffect {
113
185
  type: 'custom';
186
+ /** Performs the effect and returns events/messages to emit. */
114
187
  execute: (world: WorldModel, bindings: EntityBindings, playerId: EntityId) => EffectResult;
115
188
  }
189
+ /** What a {@link CustomEffect} returns: events and/or messages to emit. */
116
190
  export interface EffectResult {
191
+ /** Semantic events to emit. */
117
192
  events?: Array<{
118
193
  type: string;
119
194
  entities?: Record<string, string>;
120
195
  data?: unknown;
121
196
  }>;
197
+ /** Messages to show the player. */
122
198
  messages?: Array<{
123
199
  messageId: string;
124
200
  params?: Record<string, unknown>;
125
201
  }>;
126
202
  }
203
+ /** Maps role names (e.g. `$door`) to concrete entity ids for one machine instance. */
127
204
  export type EntityBindings = Record<string, EntityId>;
205
+ /** The saveable state of a single running machine. */
128
206
  export interface StateMachineInstanceState {
207
+ /** The machine's id. */
129
208
  id: string;
209
+ /** The state it is currently in. */
130
210
  currentState: string;
211
+ /** The ordered list of states it has occupied. */
131
212
  history: string[];
132
213
  }
214
+ /** The saveable state of the whole registry (all machine instances). */
133
215
  export interface StateMachineRegistryState {
216
+ /** One entry per registered machine. */
134
217
  instances: StateMachineInstanceState[];
135
218
  }
219
+ /** Per-turn context handed to the runtime when evaluating transitions. */
136
220
  export interface EvaluationContext {
221
+ /** The live world model. */
137
222
  world: WorldModel;
223
+ /** The player entity id. */
138
224
  playerId: EntityId;
225
+ /** The player's current location id. */
139
226
  playerLocation: EntityId;
227
+ /** The current turn number. */
140
228
  turn: number;
229
+ /** The id of the action that ran this turn, if any. */
141
230
  actionId?: string;
231
+ /** The direct-object entity id of that action, if any. */
142
232
  actionTargetId?: EntityId;
233
+ /** The semantic events the action emitted this turn. */
143
234
  actionEvents?: Array<{
144
235
  type: string;
145
236
  data?: unknown;
package/types.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../repos/sharpee/packages/plugin-state-machine/src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAIlD,MAAM,WAAW,sBAAsB;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,iBAAiB,CAAC;IAC3B,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAID,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,YAAY,GAAG,gBAAgB,CAAC;AAEhF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,cAAc,CAAC;CAC3B;AAID,MAAM,MAAM,cAAc,GACtB,WAAW,GACX,UAAU,GACV,aAAa,GACb,cAAc,GACd,cAAc,GACd,WAAW,CAAC;AAEhB,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;IAC3B,UAAU,EAAE,cAAc,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAC;CACxF;AAID,MAAM,MAAM,MAAM,GACd,gBAAgB,GAChB,kBAAkB,GAClB,cAAc,GACd,cAAc,GACd,aAAa,GACb,eAAe,GACf,YAAY,CAAC;AAEjB,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,QAAQ,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE;QACT,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,QAAQ,KAAK,YAAY,CAAC;CAC5F;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IACpF,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;CAC3E;AAID,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEtD,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,yBAAyB,EAAE,CAAC;CACxC;AAID,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,QAAQ,CAAC;IACnB,cAAc,EAAE,QAAQ,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,QAAQ,CAAC;IAC1B,YAAY,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC,CAAC;CAC3F"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugin-state-machine/src/types.ts"],"names":[],"mappings":"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"}
package/types.js CHANGED
@@ -3,6 +3,10 @@
3
3
  * State Machine Types (ADR-119)
4
4
  *
5
5
  * Declarative state machine definitions for puzzle and narrative orchestration.
6
+ *
7
+ * Entity references in these types use a binding convention: a string starting
8
+ * with `$` (e.g. `$door`) is a role looked up in the machine's
9
+ * {@link EntityBindings}; any other string is a literal entity id.
6
10
  */
7
11
  Object.defineProperty(exports, "__esModule", { value: true });
8
12
  //# sourceMappingURL=types.js.map
package/types.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugin-state-machine/src/types.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../../repos/sharpee/packages/plugin-state-machine/src/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG"}