SoulDungeon

SoulDungeon 是一个基于 TabooLib 的 Minecraft Bukkit/Paper 副本 / 地牢系统插件。它通过配置文件创建独立副本实例、怪物波次、击杀条件和脚本化通关流程，适合制作刷怪房、Boss 战、副本挑战等玩法。

当前文档面向 0.2.0 开发版本。

功能特性

• 独立副本实例：每次挑战可基于地图模板复制独立世界，结束后自动清理。
• 实例池预热：可预创建空闲实例世界，降低玩家进入副本时的卡顿。
• 怪物波次系统：通过 monster.yml 定义怪物组、刷怪规则、击杀条件和后续脚本。
• 原版 / MythicMobs 支持：支持 Bukkit 原版实体，也可对接 MythicMobs 怪物。
• 脚本动作：支持消息、标题、声音、命令、传送、回血、药水效果、延迟、结束副本等动作。
• 调试命令：提供实例、怪物组、击杀进度等运行状态查看命令。

运行要求

• Java 21
• Bukkit / Paper 1.21.x
• TabooLib 6.3.x（由构建脚本处理）
• MythicMobs（可选，仅在使用 type=MYTHIC 怪物时需要）

构建

在项目根目录执行：

./gradlew build

构建产物位于：

build/libs/

安装

1. 将构建出的插件 jar 放入服务器 plugins 目录。
2. 启动服务器，插件会释放默认配置和示例副本。
3. 如需使用 MythicMobs 怪物，请同时安装并启用 MythicMobs。

首次启动后会生成类似目录：

plugins/SoulDungeon/
├── config.yml
├── dungeons/
│   └── example/
│       ├── option.yml
│       └── monster.yml
└── maps/

快速开始

1. 导入地图模板

进入服务器后执行：

/sd import world

这会把当前服务器中的 world 导入为副本地图模板：

plugins/SoulDungeon/maps/world

2. 重载配置

/sd reload

3. 开始示例副本

/sd start example

配置结构

每个副本一个目录：

plugins/SoulDungeon/dungeons/<副本ID>/
├── option.yml   # 副本基础配置
└── monster.yml  # 怪物波次与脚本配置

option.yml 示例

display-name: "示例副本"
description:
  - "&7这是一个示例副本。"

map:
  mode: INSTANCE
  world: "world"

spawn: "world,0,80,0,0,0"
leave-location: "world,0,80,0,0,0"

说明：

• map.world 对应 plugins/SoulDungeon/maps/<世界名>。
• spawn 格式为 world,x,y,z,yaw,pitch。
• INSTANCE 模式下，玩家进入副本后会使用复制出的实例世界。

monster.yml 示例

groups:
  wave_1:
    auto-start: true
    spawn:
      - "$mob{type=VANILLA;name=ZOMBIE;point=0,80,0;amount=2;radius=2}"
      - "$mob{type=VANILLA;name=SKELETON;point=2,80,0;amount=1;radius=2}"
    condition:
      - "$kill-any{mobname=ZOMBIE,SKELETON;amount=3}"
    end-script:
      - "$message{text=&a第一波已清理，Boss 将在 5 秒后出现。}"
      - "$delay{time=100;script=start_boss}"

  boss:
    auto-start: false
    spawn:
      - "$mob{type=MYTHIC;name=CaveBoss;point=5,80,0;amount=1;level=1}"
    condition:
      - "$kill{mob=CaveBoss;amount=1}"
    end-script:
      - "$title{title=&a副本通关！;subtitle=&7奖励已发放;stay=60}"
      - "$sound{name=UI_TOAST_CHALLENGE_COMPLETE;volume=1;pitch=1}"
      - "$command{sender=console;command=say <player> 完成了示例副本}"
      - "$end{type=COMPLETE;delay=60}"

scripts:
  start_boss:
    - "$move{x=0;y=80;z=0;yaw=0;pitch=90}"
    - "$title{title=&cBoss 出现！;subtitle=&7准备战斗;stay=60}"
    - "$sound{name=ENTITY_WITHER_SPAWN;volume=1;pitch=1}"
    - "$heal{health=true;food=true;clear-effect=false}"
    - "$effect{name=SPEED;duration=100;amplifier=0}"
    - "$monstergroup{group=boss;operation=start}"

常用脚本动作

动作	用途
$mob{...}	生成原版或 MythicMobs 怪物，仅用于 spawn。
$kill{...}	击杀指定怪物达到数量，仅用于 condition。
$kill-any{...}	多个怪物合计击杀达到数量，仅用于 condition。
$message{...}	向副本玩家或控制台发送消息。
$title{...}	向副本玩家发送标题。
$sound{...}	播放 Bukkit 声音。
$command{...}	由控制台或玩家执行命令，支持占位符。
$move{...}	将副本内玩家移动到指定坐标和朝向。
$heal{...}	恢复生命、饥饿值，或清除药水效果。
$effect{...}	给副本玩家添加药水效果。
$delay{...}	延迟执行顶层 scripts 脚本组。
$monstergroup{...}	启动或停止怪物组。
$end{...}	结束副本，可配置延迟。

常用占位符：

占位符	说明
<player> / <player:name>	玩家名
<player:uuid>	玩家 UUID
<dungeon>	副本 ID
<dungeon:name>	副本显示名
<instance>	当前实例 ID
<time>	副本运行秒数

命令

主命令：

/sd
/souldungeon

玩家命令

命令	权限	说明
/sd help	souldungeon.user	查看帮助。
/sd list	souldungeon.user	查看已加载副本。
/sd info <副本>	souldungeon.user	查看副本信息。
/sd start <副本>	souldungeon.start	开始挑战副本。
/sd leave	souldungeon.leave	离开当前副本。

管理员命令

命令	说明
/sd reload	重载主配置、副本配置和怪物配置。
/sd import <世界名>	将世界导入为地图模板。
/sd instances	查看运行中的副本实例。
/sd stop <实例>	停止指定运行实例。
/sd complete	将当前副本判定为通关。
/sd fail	将当前副本判定为失败。
/sd group start <怪物组>	在当前副本中手动启动怪物组。
/sd group stop <怪物组>	在当前副本中手动停止怪物组。
/sd mobs	查看当前副本怪物状态。
/sd bench <map|load|runtime>	执行性能调试命令。

管理员权限：souldungeon.admin。

主配置

plugins/SoulDungeon/config.yml 中常用节点：

options:
  debug: false
  prefix: "&8[&bSoulDungeon&8] &f"

server:
  default-gamemode: "SURVIVAL"

instance:
  auto-clean: true

hooks:
  mythic-mobs: true

monster:
  remove-on-cleanup: true

performance:
  instance-pool:
    enable: true
    min-idle: 1
    max-idle: 4
    refill-delay-ticks: 40
    build-interval-ticks: 60
    auto-prepare-on-reload: true

调试建议

进入副本后可使用：

/sd mobs
/sd group start wave_1
/sd group stop wave_1
/sd instances

如需查看更多运行日志，开启：

options:
  debug: true

开发说明

• 语言：Kotlin
• Java：21
• 构建：Gradle
• 框架：TabooLib
• Bukkit API：1.21.x
• MythicMobs：通过官方 API 对接，作为 compileOnly 依赖放在 libs/ 下

常用开发命令：

./gradlew build

VitePress 文档位于 docs/，如需本地构建请先安装文档依赖。