PluginManager

按插入顺序持有已注册插件的容器。

概述

PluginManager 位于 src/plugin/PluginManager.ts，负责管理 GamePlugin 实例的注册、查找与移除。它本身不会调用 setup —— 那是 GameEngine 的职责，因为 setup 需要一个基于引擎状态的 GameContext。

PluginManager 维护两个内部结构：

• plugins: GamePlugin[] —— 按调用顺序保存的插件数组
• ids: Set<string> —— 用于 O(1) 查重与 has 查询

错误类

DuplicatePluginError

重复注册同一插件 id 时抛出。

class DuplicatePluginError extends Error {
  constructor(public readonly pluginId: string)
}

属性

属性	类型	说明
pluginId	string	重复注册的插件 id
message	string	Plugin with id '${pluginId}' is already registered
name	string	'DuplicatePluginError'

PluginNotFoundError

通过 id 取插件但未注册时抛出。

class PluginNotFoundError extends Error {
  constructor(public readonly pluginId: string)
}

属性

属性	类型	说明
pluginId	string	未注册的插件 id
message	string	Plugin with id '${pluginId}' is not registered
name	string	'PluginNotFoundError'

构造函数

new PluginManager()

new PluginManager()

创建一个空的 PluginManager 实例。

属性

size

已注册插件数量。

get size(): number

属性	类型	说明
size	number	已注册插件数量（只读 getter）

方法

use()

注册一个插件（按调用顺序保留插入顺序）。

use(plugin: GamePlugin): this

参数

参数	类型	必填	默认值	说明
plugin	GamePlugin	是	—	待注册的插件

返回值

this：便于链式调用。

抛错

• DuplicatePluginError：插件 id 已注册。
• Error：插件缺少 id / name / version 必填字段，消息形如 Plugin is missing required fields (id/name/version): ${JSON.stringify(...)}。

示例

import { PluginManager } from '../plugin/PluginManager.js'
import type { GamePlugin } from '../plugin/GamePlugin.js'

const mgr = new PluginManager()
mgr
  .use({ id: 'a', name: 'A', version: '1.0.0' })
  .use({ id: 'b', name: 'B', version: '1.0.0' })
console.log(mgr.size) // -> 2

remove()

按 id 移除插件。

remove(pluginId: string): boolean

参数

参数	类型	必填	默认值	说明
pluginId	string	是	—	待移除的插件 id

返回值

boolean：成功移除返回 true；插件不存在时返回 false（不抛错）。

行为

• 先 ids.delete(pluginId)，再用 findIndex 定位并 splice 出数组。

get()

按 id 查找插件。

get(pluginId: string): GamePlugin | undefined

参数

参数	类型	必填	默认值	说明
pluginId	string	是	—	待查找的插件 id

返回值

GamePlugin | undefined：找到则返回该插件；未找到返回 undefined。

getOrThrow()

按 id 查找插件，未找到则抛错。

getOrThrow(pluginId: string): GamePlugin

参数

参数	类型	必填	默认值	说明
pluginId	string	是	—	待查找的插件 id

返回值

GamePlugin：找到的插件。

抛错

PluginNotFoundError：id 未注册。

getAll()

返回所有已注册插件的浅拷贝列表（保持插入顺序）。

getAll(): GamePlugin[]

返回值

GamePlugin[]：所有已注册插件的浅拷贝数组。

has()

是否已注册指定 id 的插件。

has(pluginId: string): boolean

参数

参数	类型	必填	默认值	说明
pluginId	string	是	—	待查询的插件 id

返回值

boolean：已注册返回 true，否则 false。

clear()

清空所有已注册插件。

clear(): void

注意事项

• use 保留插入顺序，引擎在调用 setup 与订阅 events 时也按此顺序处理；插件间的初始化次序对有依赖的插件很重要。
• use 在缺少必填字段时抛的是普通 Error（非 DuplicatePluginError），调用方需要分别处理这两类错误。
• getOrThrow 与 get 的语义区别：前者用于"插件必须存在，否则流程不应继续"的场景，后者用于"可能存在"的查询。
• PluginManager 仅负责维护注册关系；实际调用 setup、注册 rules / actions / events 是 GameEngine 的职责。