docs(modules): 添加框架模块文档 (#350)
* docs(modules): 添加框架模块文档 添加以下模块的完整文档： - FSM (状态机): 状态定义、转换条件、优先级、事件监听 - Timer (定时器): 定时器调度、冷却系统、服务令牌 - Spatial (空间索引): GridSpatialIndex、AOI 兴趣区域管理 - Pathfinding (寻路): A* 算法、网格地图、导航网格、路径平滑 - Procgen (程序化生成): 噪声函数、种子随机数、加权随机 所有文档均基于实际源码 API 编写，包含： - 快速开始示例 - 完整 API 参考 - 实际使用案例 - 蓝图节点说明 - 最佳实践建议 * docs(modules): 添加 Blueprint 模块文档和所有模块英文版 新增中文文档： - Blueprint (蓝图可视化脚本): VM、自定义节点、组合系统、触发器 新增英文文档 (docs/en/modules/): - FSM: State machine API, transitions, ECS integration - Timer: Timers, cooldowns, service tokens - Spatial: Grid spatial index, AOI management - Pathfinding: A*, grid map, NavMesh, path smoothing - Procgen: Noise functions, seeded random, weighted random - Blueprint: Visual scripting, custom nodes, composition 所有文档均基于实际源码 API 编写。
This commit is contained in:
YHH
GitHub
316
docs/en/modules/fsm/index.md
Normal file
316
docs/en/modules/fsm/index.md
Normal file
@@ -0,0 +1,316 @@
|
||||
# State Machine (FSM)
|
||||
|
||||
`@esengine/fsm` provides a type-safe finite state machine implementation for characters, AI, or any scenario requiring state management.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install @esengine/fsm
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```typescript
|
||||
import { createStateMachine } from '@esengine/fsm';
|
||||
|
||||
// Define state types
|
||||
type PlayerState = 'idle' | 'walk' | 'run' | 'jump';
|
||||
|
||||
// Create state machine
|
||||
const fsm = createStateMachine<PlayerState>('idle');
|
||||
|
||||
// Define states with callbacks
|
||||
fsm.defineState('idle', {
|
||||
onEnter: (ctx, from) => console.log(`Entered idle from ${from}`),
|
||||
onExit: (ctx, to) => console.log(`Exiting idle to ${to}`),
|
||||
onUpdate: (ctx, dt) => { /* Update every frame */ }
|
||||
});
|
||||
|
||||
fsm.defineState('walk', {
|
||||
onEnter: () => console.log('Started walking')
|
||||
});
|
||||
|
||||
// Manual transition
|
||||
fsm.transition('walk');
|
||||
|
||||
console.log(fsm.current); // 'walk'
|
||||
```
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### State Configuration
|
||||
|
||||
Each state can be configured with the following callbacks:
|
||||
|
||||
```typescript
|
||||
interface StateConfig<TState, TContext> {
|
||||
name: TState; // State name
|
||||
onEnter?: (context: TContext, from: TState | null) => void; // Enter callback
|
||||
onExit?: (context: TContext, to: TState) => void; // Exit callback
|
||||
onUpdate?: (context: TContext, deltaTime: number) => void; // Update callback
|
||||
tags?: string[]; // State tags
|
||||
metadata?: Record<string, unknown>; // Metadata
|
||||
}
|
||||
```
|
||||
|
||||
### Transition Conditions
|
||||
|
||||
Define conditional state transitions:
|
||||
|
||||
```typescript
|
||||
interface Context {
|
||||
isMoving: boolean;
|
||||
isRunning: boolean;
|
||||
isGrounded: boolean;
|
||||
}
|
||||
|
||||
const fsm = createStateMachine<PlayerState, Context>('idle', {
|
||||
context: { isMoving: false, isRunning: false, isGrounded: true }
|
||||
});
|
||||
|
||||
// Define transition conditions
|
||||
fsm.defineTransition('idle', 'walk', (ctx) => ctx.isMoving);
|
||||
fsm.defineTransition('walk', 'run', (ctx) => ctx.isRunning);
|
||||
fsm.defineTransition('walk', 'idle', (ctx) => !ctx.isMoving);
|
||||
|
||||
// Automatically evaluate and execute matching transitions
|
||||
fsm.evaluateTransitions();
|
||||
```
|
||||
|
||||
### Transition Priority
|
||||
|
||||
When multiple transitions are valid, higher priority executes first:
|
||||
|
||||
```typescript
|
||||
// Higher priority number = higher priority
|
||||
fsm.defineTransition('idle', 'attack', (ctx) => ctx.isAttacking, 10);
|
||||
fsm.defineTransition('idle', 'walk', (ctx) => ctx.isMoving, 1);
|
||||
|
||||
// If both conditions are met, 'attack' (priority 10) is tried first
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
### createStateMachine
|
||||
|
||||
```typescript
|
||||
function createStateMachine<TState extends string, TContext = unknown>(
|
||||
initialState: TState,
|
||||
options?: StateMachineOptions<TContext>
|
||||
): IStateMachine<TState, TContext>
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
- `initialState` - Initial state
|
||||
- `options.context` - Context object, accessible in callbacks
|
||||
- `options.maxHistorySize` - Maximum history entries (default 100)
|
||||
- `options.enableHistory` - Enable history tracking (default true)
|
||||
|
||||
### State Machine Properties
|
||||
|
||||
| Property | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `current` | `TState` | Current state |
|
||||
| `previous` | `TState \| null` | Previous state |
|
||||
| `context` | `TContext` | Context object |
|
||||
| `isTransitioning` | `boolean` | Whether currently transitioning |
|
||||
| `currentStateDuration` | `number` | Current state duration (ms) |
|
||||
|
||||
### State Machine Methods
|
||||
|
||||
#### State Definition
|
||||
|
||||
```typescript
|
||||
// Define state
|
||||
fsm.defineState('idle', {
|
||||
onEnter: (ctx, from) => {},
|
||||
onExit: (ctx, to) => {},
|
||||
onUpdate: (ctx, dt) => {}
|
||||
});
|
||||
|
||||
// Check if state exists
|
||||
fsm.hasState('idle'); // true
|
||||
|
||||
// Get state configuration
|
||||
fsm.getStateConfig('idle');
|
||||
|
||||
// Get all states
|
||||
fsm.getStates(); // ['idle', 'walk', ...]
|
||||
```
|
||||
|
||||
#### Transition Operations
|
||||
|
||||
```typescript
|
||||
// Define transition
|
||||
fsm.defineTransition('idle', 'walk', condition, priority);
|
||||
|
||||
// Remove transition
|
||||
fsm.removeTransition('idle', 'walk');
|
||||
|
||||
// Get transitions from state
|
||||
fsm.getTransitionsFrom('idle');
|
||||
|
||||
// Check if transition is possible
|
||||
fsm.canTransition('walk'); // true/false
|
||||
|
||||
// Manual transition
|
||||
fsm.transition('walk');
|
||||
|
||||
// Force transition (ignore conditions)
|
||||
fsm.transition('walk', true);
|
||||
|
||||
// Auto-evaluate transition conditions
|
||||
fsm.evaluateTransitions();
|
||||
```
|
||||
|
||||
#### Lifecycle
|
||||
|
||||
```typescript
|
||||
// Update state machine (calls current state's onUpdate)
|
||||
fsm.update(deltaTime);
|
||||
|
||||
// Reset state machine
|
||||
fsm.reset(); // Reset to current state
|
||||
fsm.reset('idle'); // Reset to specified state
|
||||
```
|
||||
|
||||
#### Event Listeners
|
||||
|
||||
```typescript
|
||||
// Listen to entering specific state
|
||||
const unsubscribe = fsm.onEnter('walk', (from) => {
|
||||
console.log(`Entered walk from ${from}`);
|
||||
});
|
||||
|
||||
// Listen to exiting specific state
|
||||
fsm.onExit('walk', (to) => {
|
||||
console.log(`Exiting walk to ${to}`);
|
||||
});
|
||||
|
||||
// Listen to any state change
|
||||
fsm.onChange((event) => {
|
||||
console.log(`${event.from} -> ${event.to} at ${event.timestamp}`);
|
||||
});
|
||||
|
||||
// Unsubscribe
|
||||
unsubscribe();
|
||||
```
|
||||
|
||||
#### Debugging
|
||||
|
||||
```typescript
|
||||
// Get state history
|
||||
const history = fsm.getHistory();
|
||||
// [{ from: 'idle', to: 'walk', timestamp: 1234567890 }, ...]
|
||||
|
||||
// Clear history
|
||||
fsm.clearHistory();
|
||||
|
||||
// Get debug info
|
||||
const info = fsm.getDebugInfo();
|
||||
// { current, previous, duration, stateCount, transitionCount, historySize }
|
||||
```
|
||||
|
||||
## Practical Examples
|
||||
|
||||
### Character State Machine
|
||||
|
||||
```typescript
|
||||
import { createStateMachine } from '@esengine/fsm';
|
||||
|
||||
type CharacterState = 'idle' | 'walk' | 'run' | 'jump' | 'fall' | 'attack';
|
||||
|
||||
interface CharacterContext {
|
||||
velocity: { x: number; y: number };
|
||||
isGrounded: boolean;
|
||||
isAttacking: boolean;
|
||||
speed: number;
|
||||
}
|
||||
|
||||
const characterFSM = createStateMachine<CharacterState, CharacterContext>('idle', {
|
||||
context: {
|
||||
velocity: { x: 0, y: 0 },
|
||||
isGrounded: true,
|
||||
isAttacking: false,
|
||||
speed: 0
|
||||
}
|
||||
});
|
||||
|
||||
// Define states
|
||||
characterFSM.defineState('idle', {
|
||||
onEnter: (ctx) => { ctx.speed = 0; }
|
||||
});
|
||||
|
||||
characterFSM.defineState('walk', {
|
||||
onEnter: (ctx) => { ctx.speed = 100; }
|
||||
});
|
||||
|
||||
characterFSM.defineState('run', {
|
||||
onEnter: (ctx) => { ctx.speed = 200; }
|
||||
});
|
||||
|
||||
// Define transitions
|
||||
characterFSM.defineTransition('idle', 'walk', (ctx) => Math.abs(ctx.velocity.x) > 0);
|
||||
characterFSM.defineTransition('walk', 'idle', (ctx) => ctx.velocity.x === 0);
|
||||
characterFSM.defineTransition('walk', 'run', (ctx) => Math.abs(ctx.velocity.x) > 150);
|
||||
|
||||
// Jump has highest priority
|
||||
characterFSM.defineTransition('idle', 'jump', (ctx) => !ctx.isGrounded, 10);
|
||||
characterFSM.defineTransition('walk', 'jump', (ctx) => !ctx.isGrounded, 10);
|
||||
|
||||
// Game loop usage
|
||||
function gameUpdate(dt: number) {
|
||||
// Update context
|
||||
characterFSM.context.velocity.x = getInputVelocity();
|
||||
characterFSM.context.isGrounded = checkGrounded();
|
||||
|
||||
// Evaluate transitions
|
||||
characterFSM.evaluateTransitions();
|
||||
|
||||
// Update current state
|
||||
characterFSM.update(dt);
|
||||
}
|
||||
```
|
||||
|
||||
### ECS Integration
|
||||
|
||||
```typescript
|
||||
import { Component, EntitySystem, Matcher } from '@esengine/ecs-framework';
|
||||
import { createStateMachine, type IStateMachine } from '@esengine/fsm';
|
||||
|
||||
// State machine component
|
||||
class FSMComponent extends Component {
|
||||
fsm: IStateMachine<string>;
|
||||
|
||||
constructor(initialState: string) {
|
||||
super();
|
||||
this.fsm = createStateMachine(initialState);
|
||||
}
|
||||
}
|
||||
|
||||
// State machine system
|
||||
class FSMSystem extends EntitySystem {
|
||||
constructor() {
|
||||
super(Matcher.all(FSMComponent));
|
||||
}
|
||||
|
||||
protected processEntity(entity: Entity, dt: number): void {
|
||||
const fsmComp = entity.getComponent(FSMComponent);
|
||||
fsmComp.fsm.evaluateTransitions();
|
||||
fsmComp.fsm.update(dt);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Blueprint Nodes
|
||||
|
||||
The FSM module provides blueprint nodes for visual scripting:
|
||||
|
||||
- `GetCurrentState` - Get current state
|
||||
- `TransitionTo` - Transition to specified state
|
||||
- `CanTransition` - Check if transition is possible
|
||||
- `IsInState` - Check if in specified state
|
||||
- `WasInState` - Check if was ever in specified state
|
||||
- `GetStateDuration` - Get state duration
|
||||
- `EvaluateTransitions` - Evaluate transition conditions
|
||||
- `ResetStateMachine` - Reset state machine
|
||||
Reference in New Issue
Block a user