子系统

BaikirutoAPI 提供多个子系统访问器，每个子系统负责特定的功能领域。

子系统一览

访问器	返回类型	说明
`getScriptHandler()`	`BaikirutoScriptHandler`	脚本处理器
`getItemManager()`	`ItemManager`	物品管理器
`getItemHandler()`	`ItemHandler`	物品读取器
`getItemSerializer()`	`ItemSerializer`	物品序列化器
`getItemUpdater()`	`ItemUpdater`	物品版本更新器
`getItemLoader()`	`ItemLoader`	物品加载器
`getItemEventBus()`	`ItemEventBus`	事件总线

BaikirutoScriptHandler — 脚本处理器

管理 Baikiruto 脚本的执行、预热、缓存失效和脚本类型注册。当前默认内置脚本类型是 fluxon，但处理器本身已经改成“注册表分发”模式。

方法	返回值	说明
`invoke(source: BaikirutoScriptSource, id: String, sender: CommandSender?, variables: Map<String, Any?> = emptyMap())`	`Any?`	按脚本类型执行脚本
`preheat(source: BaikirutoScriptSource, id: String)`	`Unit`	按脚本类型预热脚本
`invoke(source: String, id: String, sender: CommandSender?, variables: Map<String, Any?> = emptyMap())`	`Any?`	兼容写法，等同于 `type = fluxon`
`preheat(source: String, id: String)`	`Unit`	兼容写法，等同于 `type = fluxon`
`registerScriptType(scriptType: BaikirutoScriptType)`	`BaikirutoScriptType`	注册脚本类型
`unregisterScriptType(scriptTypeId: String)`	`BaikirutoScriptType?`	注销脚本类型
`getScriptType(scriptTypeId: String)`	`BaikirutoScriptType?`	获取单个脚本类型
`getScriptTypeRegistry()`	`Registry<BaikirutoScriptType>`	获取脚本类型注册表
`invalidate(id: String)`	`Unit`	让所有已注册脚本类型对指定脚本 ID 失效
`invalidateByPrefix(prefix: String)`	`Unit`	让所有已注册脚本类型按前缀批量失效
`cacheStats()`	`ScriptCacheStats`	聚合所有已注册脚本类型的缓存统计

BaikirutoScriptSource

BaikirutoScriptSource 是新的脚本源载体：

字段 / 方法	类型	说明
`type`	`String`	脚本类型 id，默认 `fluxon`
`content`	`String`	实际脚本文本
`normalizedType()`	`String`	返回规范化后的类型 id（转小写，`-` 转 `_`）
`asRuntimeMap()`	`Map<String, String>`	导出为 `type` + `source` 的运行时结构
`of(content, type)`	`BaikirutoScriptSource?`	从字符串创建脚本源
`fromRuntimeValue(source)`	`BaikirutoScriptSource?`	从字符串 / 列表 / map 结构恢复脚本源

val script = api.getScriptHandler()

val result = script.invoke(
    BaikirutoScriptSource(type = "fluxon", content = "return 1 + 1"),
    "demo:build",
    player,
    mapOf("player" to player)
)

script.preheat(
    BaikirutoScriptSource(content = "return item"),
    "demo:preheat"
)

val stats = script.cacheStats()
println("缓存命中率: ${stats.hitRate()}")
script.invalidate("demo:build")

注册自定义脚本类型

class MyScriptType : BaikirutoScriptType {

    override val id: String = "my_engine"

    override fun invoke(
        content: String,
        scriptId: String,
        sender: CommandSender?,
        variables: Map<String, Any?>
    ): Any? {
        println("run $scriptId -> $content")
        return null
    }

    override fun preheat(content: String, scriptId: String) {
        println("preheat $scriptId")
    }
}

api.registerScriptType(MyScriptType())

val registered = api.getScriptType("my_engine")
val allTypes = api.getScriptTypeRegistry().keys()
println("脚本类型: $allTypes")

便捷入口

BaikirutoAPI 本身也提供了这些脚本类型管理快捷方法：

registerScriptType(...)
unregisterScriptType(...)
getScriptType(...)
getScriptTypeRegistry()

如果你还在维护旧插件，BaikirutoLegacyAPI 也同步提供了 registerScriptType / unregisterScriptType / getScriptType 和 registeredScriptType，但新项目仍推荐直接走 Baikiruto.api()。

ItemManager — 物品管理器

物品的生成、给予和注册管理。

方法	返回值	说明
`generateItem(itemId: String, context: Map<String, Any?> = emptyMap())`	`ItemStream?`	生成物品数据流
`generateItemStack(itemId: String, context: Map<String, Any?> = emptyMap())`	`ItemStack?`	生成物品 ItemStack
`giveItem(player: Player, itemId: String, amount: Int = 1, context: Map<String, Any?> = emptyMap())`	`Boolean`	给予玩家物品
`registerItem(item: Item)`	`Item`	注册物品
`registerModel(model: ItemModel)`	`ItemModel`	注册模型
`registerDisplay(display: ItemDisplay)`	`ItemDisplay`	注册显示
`registerGroup(group: ItemGroup)`	`ItemGroup`	注册分组
`registerMetaFactory(metaFactory: MetaFactory)`	`MetaFactory`	注册元数据工厂
`unregisterMetaFactory(metaFactoryId: String)`	`MetaFactory?`	注销元数据工厂

val manager = api.getItemManager()

// 生成物品数据流
val stream = manager.generateItem("my_sword")

// 生成物品 ItemStack
val itemStack = manager.generateItemStack("my_potion", mapOf("player" to player))

// 直接给予玩家（自动处理背包满的情况）
val success = manager.giveItem(player, "my_sword", 1)
if (success) {
    player.sendMessage("物品已发放")
}

ItemHandler — 物品读取器

从 ItemStack 中读取 Baikiruto 数据。

方法	返回值	说明
`read(itemStack: ItemStack)`	`ItemStream?`	读取物品数据流
`getItem(itemStack: ItemStack)`	`Item?`	获取物品定义
`getItemId(itemStack: ItemStack)`	`String?`	获取物品 ID
`getItemData(itemStack: ItemStack)`	`Map<String, Any?>?`	获取公共数据
`getItemUniqueData(itemStack: ItemStack)`	`Map<String, Any?>?`	获取唯一实例数据

val handler = api.getItemHandler()

val held = player.inventory.itemInMainHand
val stream = handler.read(held)
if (stream != null) {
    println("物品 ID: ${stream.itemId}")
}

ItemSerializer — 物品序列化器

物品与数据格式之间的转换。

方法	返回值	说明
`serialize(itemStack: ItemStack)`	`SerializedItem`	从 ItemStack 序列化
`serialize(itemStream: ItemStream)`	`SerializedItem`	从 ItemStream 序列化
`deserialize(json: String)`	`ItemStream`	从 JSON 字符串反序列化
`deserialize(json: JsonObject)`	`ItemStream`	从 JsonObject 反序列化
`deserialize(serializedItem: SerializedItem)`	`ItemStream`	从 SerializedItem 反序列化

val serializer = api.getItemSerializer()

// 序列化
val serialized = serializer.serialize(itemStack)
// serialized 是 SerializedItem，可通过 toMap() 转为 Map 存入数据库

// 反序列化
val stream = serializer.deserialize(jsonString)
val restored = stream.toItemStack()

ItemUpdater — 物品版本更新器

检查并更新玩家持有的旧版本物品。

方法	返回值	说明
`checkUpdate(player: Player?, inventory: Inventory)`	`Int`	检查并更新背包中的所有物品，返回更新数量
`checkUpdate(player: Player?, itemStack: ItemStack)`	`ItemStack`	检查并更新单个物品，返回更新后的 ItemStack

val updater = api.getItemUpdater()

// 检查并更新玩家背包中的所有物品
val updatedCount = updater.checkUpdate(player, player.inventory)
println("已更新 $updatedCount 个物品")

// 检查并更新单个物品
val updated = updater.checkUpdate(player, player.inventory.itemInMainHand)
player.inventory.setItemInMainHand(updated)

ItemLoader — 物品加载器

管理物品配置文件的加载与重载。

方法	返回值	说明
`reloadItems(source: String = "api-reload")`	`Int`	重载所有物品配置，返回加载数量
`loadedIds()`	`Set<String>`	获取所有已加载的物品 ID
`loadItemFromFile(file: File)`	`List<Item>`	从文件加载物品列表
`loadModelFromFile(file: File)`	`List<ItemModel>`	从文件加载模型列表
`loadDisplayFromFile(file: File, fromItemFile: Boolean = false)`	`List<ItemDisplay>`	从文件加载显示列表
`loadMetaFromSection(root: ConfigurationSection)`	`List<Meta>`	从配置节加载元数据列表

val loader = api.getItemLoader()

// 重载所有物品
val count = loader.reloadItems("my-plugin-reload")
println("已加载 $count 个物品")

// 查看已加载的物品
val ids = loader.loadedIds()
println("已加载 ${ids.size} 个物品 ID")

// 从文件加载
val items = loader.loadItemFromFile(File("plugins/Baikiruto/items/my_item.yml"))
println("从文件加载了 ${items.size} 个物品")

ItemEventBus — 事件总线

详见事件系统。

val bus = api.getItemEventBus()

bus.subscribe(ItemBuildPostEvent::class.java) { event ->
    println("物品构建完成: ${event.itemId}")
}

子系统一览​

BaikirutoScriptHandler — 脚本处理器​

BaikirutoScriptSource​

注册自定义脚本类型​

便捷入口​

ItemManager — 物品管理器​

ItemHandler — 物品读取器​

ItemSerializer — 物品序列化器​

ItemUpdater — 物品版本更新器​

ItemLoader — 物品加载器​

ItemEventBus — 事件总线​