@sharpee/plugin-state-machine 1.0.8 → 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 +60 -0
- package/package.json +4 -4
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
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sharpee/plugin-state-machine",
|
|
3
|
-
"version": "1.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
|
|
16
|
-
"@sharpee/world-model": "^1.0
|
|
17
|
-
"@sharpee/plugins": "^1.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",
|