设计理念

了解 SoulDungeon 的设计理念，有助于理解配置结构和使用方式。

核心思想

SoulDungeon 的设计核心围绕以下几个原则：

1. 配置优于编码

服主不需要学习 Java 或 Kotlin，只需要编辑 YAML 配置文件和简短的脚本即可创建完整的副本体验。

2. 实例隔离

每个副本挑战都在独立的临时世界中运行。这意味着：

• 不同队伍同时挑战同一副本互不干扰
• 副本中可以自由破坏/放置方块
• 副本结束自动清理，无需手动重置
• 支持实例池预热，降低加载等待

3. 脚本驱动

所有副本流程通过 $action{key=value} 格式的脚本控制，而非硬编码逻辑：

# 一条脚本 = 一个事件
"$message{text=&a怪物出现！} @player"
"$delay{time=100;script=start_boss} @dungeon"

4. 模块化设计

每个副本拥有独立配置目录，不同配置文件各司其职：

文件	职责
option.yml	副本元信息、地图、出生点
monster.yml	怪物组、刷怪规则、击杀条件

与其他方案对比

vs DungeonPlus

SoulDungeon 参考了 DungeonPlus 的设计模式，但做出了以下差异化：

• 更清晰的配置结构：每个副本独立目录，而非单文件巨型配置
• 统一的脚本格式：$action{key=value} 替代复杂嵌套
• 内置配置诊断：/sd doctor 检查配置错误并定位到行号
• 实例池预热：预创建世界，降低进入副本延迟
• 现代化技术栈：Kotlin + TabooLib + Java 21，面向 1.21.x

vs 手动命令方块

对比维度	SoulDungeon	命令方块
可维护性	文本配置，版本控制友好	无法版本控制
复制复用	复制目录即可复用	需手动重建
多人副本	自动实例隔离	无法实现
怪物管理	自动追踪击杀	需大量计分板
调试	内置调试命令	依赖日志

脚本系统设计

执行目标

脚本通过 @目标 控制执行对象：

目标	含义	示例
@player	副本内全部玩家	发消息、传送、加药水效果
@dungeon	当前副本实例	启动怪物组、结束副本
@system	系统层逻辑	条件判断、控制台输出
@console	控制台	执行控制台命令
@self	触发者	仅对触发事件的玩家执行

参数设计

所有脚本参数统一用 key=value 键值对：

# 参数用 ; 分隔，= 连接键值
"$mob{type=MYTHIC;name=CaveBoss;point=5,80,0;amount=1;level=5}"

扩展性

SoulDungeon 的设计预留了丰富的扩展接口，面向开发者：

• 自定义脚本动作：实现接口注册新的 $xxx 动作
• 自定义交互类型：扩展 interact.yml 的触发类型
• 自定义条件判断：添加新的 condition 类型
• 自定义奖励类型：扩展经济、积分之外的奖励方式
• 事件 API：监听副本生命周期的所有关键事件

详见 API 文档。

版本策略

• 主版本号 (x)：重大架构变化，不保证向后兼容
• 次版本号 (y)：功能新增，可能有配置格式调整
• 修订号 (z)：Bug 修复，完全兼容

当前版本 0.2.0 为开发版，API 可能发生变动。