自定义地牢

自定义地牢

本模组是引擎：世界生成、实例维度、传送门、钥匙、波次、Boss、规则和奖励。您可通过 JSON（以及可选的 SNBT 房间）添加自己的地牢，无需编写 Java。

该 Jar 文件自带三个示例地牢，方便您测试引擎并复制其格式。它们是可选的。删除或禁用它们，仅发布您自己的内容。

• Minecraft： 1.16.5
• 加载器： Forge 36.1+
• 模组 ID： customdungeon
• 许可证： MIT

---

特性

• JSON 地牢 — 每个地牢在 data/<命名空间>/dungeons/<名称>/ 下对应一个文件夹
• 两种世界生成模式 — 地表神殿 + 传送门进入实例，或嵌入主世界 / 下界 / 末地的完整地牢
• ASCII 布局 — 使用字母、- 和 | 绘制房间；堆叠楼层以构建 3D 地图
• 程序化或 SNBT 房间 — 调色板、形状、战利品箱，或结构方块导出
• 波次与 Boss — 装备、生命值、自定义战利品表
• 传送门激活 — 催化剂、绑定钥匙、两者兼具，或始终开启
• 运行规则 — 破坏/放置保护、PvP、计时器、保留物品栏、房间限制（挖掘疲劳、缓慢等）
• 奖励 — 战利品表、经验值、命令、消息
• 服务器覆盖 — 从 config/customdungeon/dungeons/ 调整地牢，无需重新打包

---

示例地牢（可选）

包含三个示例供您游玩、复制或删除。模组在零示例的情况下也能正常工作。 将您自己的文件夹放入 data/<命名空间>/dungeons/（或禁用以下示例）。

地牢	位置	进入方式
远古墓穴 (example_crypt)	主世界森林、平原、针叶林、丘陵	地表神殿。手持石头和绑定地牢钥匙，然后使用传送门。
灰烬堡垒 (example_nether)	下界	完整要塞生成于世界中。直接走入（受保护房间、怪物、入口）。也可使用 /cd start。
末地城塞 (example_end)	末地高地 / 中部	嵌入的 SNBT 城塞。直接走入，或使用 /cd start。

要从整合包中移除这些示例：

1. 禁用 — 在数据包或 config/customdungeon/dungeons/<名称>/dungeon.json 中，为 example_crypt、example_nether 和 example_end 设置 "enabled": false。
2. 覆盖 — 发布一个数据包，用您自己的地牢（或空存根）替换这些文件夹。

已生成的区块不会生成新的神殿或嵌入结构。探索新地形、开启新世界，或使用 /cd place <id>。

---

游玩

墓穴神殿

1. 合成一把地牢钥匙（金锭 + 末影珍珠）。
2. 找到神殿（若您是 OP 可使用 /cd locate example_crypt）或使用 /cd place example_crypt。
3. 手持钥匙右键点击传送门进行绑定。
4. 手持石头和绑定的钥匙，然后使用传送门。
5. 清理房间。胜利后会出现标题倒计时，随后传出。使用地牢出口令牌可提前离开。

嵌入式地牢（下界 / 末地）

直接走入结构。房间受到保护，遭遇战会生成，离开会使你在地牢中解除绑定（你仍留在该维度）。

物品

物品	配方 / 用途
地牢钥匙	金锭环绕末影珍珠。在神殿上绑定，或使用 NBT Dungeon:"命名空间:id"。
地牢徽记	石头 + 末影珍珠 + 一把钥匙。右键传送至绑定的神殿 / 世界地牢。
地牢出口令牌	创造模式物品栏 / 战利品。离开当前的 实例 运行。

/give @p customdungeon:dungeon_key{Dungeon:"customdungeon:example_crypt"} 1

---

命令

别名：/cd。ID 可为 example_crypt 或 customdungeon:example_crypt。

/customdungeon list
/customdungeon info <id>
/customdungeon start <id>
/customdungeon leave
/customdungeon locate [id]     # op — 神殿前方的可点击坐标
/customdungeon place <id>      # op — 在脚下生成神殿或嵌入结构
/customdungeon reload          # op — 仅重载配置覆盖（数据包请使用 /reload）
/customdungeon complete        # op — 强制完成当前运行

原版命令：

/locate customdungeon:dungeon_shrine

---

给数据包作者

每个地牢对应一个文件夹：

data/<命名空间>/dungeons/<名称>/
  dungeon.json              必需
  portal.json               可选 — 合并到 dungeon.portal
  rooms/<房间>.json         程序化（或 SNBT）房间模板
  rooms/<房间>.snbt         结构方块导出作为房间
  encounters/<id>.json      波次 / Boss

地牢 ID 为 <命名空间>:<名称>，除非 dungeon.json 中设置了 "id"。

相对引用（"encounters": ["skeletons"]）解析为 <命名空间>:<名称>/skeletons。

省略的键使用默认值。只需写入你要修改的内容。

原版 /reload 重载数据包。/cd reload 仅重载 config/customdungeon/dungeons/。

模组提供空维度 customdungeon:dungeon 用于实例化运行。将 portal.dimension 指向该维度，或指向您自己的数据包维度。

最小神殿地牢

{
  "display": { "name": "我的墓穴" },
  "natural_spawn": {
    "enabled": true,
    "dimensions": ["minecraft:overworld"],
    "biomes": ["#is_forest"],
    "rarity": 48
  },
  "layout": {
    "shape": ["E-H-B"],
    "rooms": [
      { "id": "entrance", "encounters": ["skels"] },
      { "id": "hall", "encounters": ["skels"] },
      { "id": "boss", "encounters": ["boss"] }
    ]
  }
}

{
  "activation": "both",
  "frame": "minecraft:stone_bricks",
  "catalyst": "minecraft:stone"
}

将传送门对象放在 portal.json 或 dungeon.json 的 "portal" 下。

嵌入式地牢（无神殿）

"natural_spawn": {
  "enabled": true,
  "embed": true,
  "dimensions": ["minecraft:the_nether"],
  "layer": "nether",
  "min_y": 40,
  "max_y": 90,
  "rarity": 24
}

ASCII shape

字母代表房间。- | + 连接它们。二维列表为单层；列表的列表在 Y 轴上堆叠楼层。

"shape": [
  ["  G  ", "  |  ", "E-H-B"],
  ["  A  ", "  |  ", "  T  "]
],
"cells": { "E": "entrance", "H": "hall", "B": "boss", "G": "graves", "A": "chapel", "T": "treasury" }

若省略 cells，字母匹配房间 ID 前缀。start_room 默认为第一个房间。

程序化房间会生成 gap 方块宽的走廊。SNBT 房间则紧密排列（自动生成门）。

其他布局：省略 shape 以获得线性排列；使用带 grid_x / grid_z 的 "type": "grid"；或设置 x / z / next 以精确偏移。

---

JSON 参考

当键缺失时应用默认值。

dungeon.json

字段	默认值	注释
id	文件夹 ID	覆盖注册表名称。
enabled	true	false = 已加载但永不开始 / 生成。
display.name	路径	进入时的聊天标题。
display.description	""	进入后发送。
natural_spawn	关闭	别名：placement（覆盖层，natural_spawn 优先）。
portal	除非设置催化剂 / 框架 / 激活，否则关闭	可位于 portal.json。
entry	命令 + 钥匙 + 传送门	谁能进入。
instance	customdungeon:dungeon	实例世界 + 重置。
layout	一个空房间	房间图。
rules	见下文	战斗 / 破坏 / 死亡。
rewards	无	on_complete / on_fail / on_room_clear。

natural_spawn

字段	默认值	注释
enabled	false	true = 在世界中生成。
embed	false	true = 在世界中放置房间。false = 仅神殿传送门。
dimensions	主世界	维度 ID。
biomes	全部	精确 ID、category:jungle 或标签（#is_forest、#nether、#end 等）。
biome_blacklist	[]	相同语法。黑名单优先。
layer	surface	surface（高度图）、nether（实心方块上方空气）、sky（max_y）。
min_y / max_y	5 / 80	用于下界 / 天空嵌入。神殿位于地表。
rarity	80	区块格上的 1/N。数值越高越稀有。
min_chunk_distance	16	区块间距。
spread_salt	0	避免两个地牢位于同一区块。
avoid_water	true	在生成位置跳过水域。

portal / portal.json

字段	默认值	注释
activation	若设置催化剂则为 catalyst，否则为 always	always / catalyst / key / both。
frame	minecraft:obsidian	神殿框架方块。
textures.portal	minecraft:block/crying_obsidian	传送门表面的图集贴图。
color	#5B21B6	色调 #RRGGBB。
size.width / height	4 / 5	框架尺寸。
catalyst	无	物品 ID 字符串，或 { "item", "count", "consume", "nbt" }。
sound	block.end_portal.spawn	进入时播放。
dimension	customdungeon:dungeon	实例目的地。
return_portal	true	实例内的出口传送门。

未绑定传送门：携带具有 NBT Dungeon 的钥匙潜行使用以绑定。

entry

字段	默认值	注释
methods	command、key、portal	这三个的任意子集。
key_item	customdungeon:dungeon_key
consume_key	true
require_key_nbt	false	钥匙 NBT Dungeon 必须匹配。
max_players	8	每个实例。
cooldown_seconds	0	每个玩家。
permission_level	0	原版权限（2 = op）。
required_advancement	无
required_scoreboard / required_score	未使用
creative_bypass	true	创造模式跳过方法 / 催化剂 / 冷却。
shared	false	复用正在运行的实例。

instance

字段	默认值	注释
dimension	传送门维度	必须存在。
origin_y	64	在实例世界中的构建 Y 坐标。
padding	24	房间周围的边界范围。
reset_on_complete / empty / fail	true	拆除实例。
idle_timeout_seconds	600	空置超时。
extract_seconds	30	传送前的胜利倒计时。0 = 立即传送。

layout

字段	默认值	注释
type	自动推断	shape / linear / grid / free / single。
start_room	第一个房间	出生房间。
corridor_width / height	3 / 3	可行走的空气空间。
gap	5	程序化房间之间的空气间隔。
floor_gap	gap	堆叠楼层之间的垂直空气间隔。
corridor_block	minecraft:stone_bricks	同样适用于 corridor_floor / wall / ceiling。
rooms[].id		本地 ID。
rooms[].template	与 id 相同	房间文件名。
rooms[].encounters	[]	遭遇战 ID。
rooms[].next	[]	额外的走廊目标。
rooms[].x / y / z		精确偏移（或 offset: {x,y,z}）。

rooms/<id>.json

字段	默认值	注释
style	无	预设：crypt、nether、library、prison、sewer、end、jungle、ice、sand 等。
shape	box	box、circle、oval、cross、ring、diamond。
size	{x:13,y:7,z:13}	仅程序化房间。SNBT 尺寸来自文件。
palette	石砖	floor、wall、ceiling、accent、door、light、pillar。
features	样式预设	见下文。
loot	[]	箱子战利品表 ID。
constraints	无	站在此房间内时的效果。
ladders	true	堆叠楼层之间的垂直通道。在房间上设置 false 会跳过整个连接。
snbt / snbt_file / structure	无	使用结构房间而非程序化生成。

features：pillars、torches、windows、chest_count、carpet、fountain、cobwebs、skulls、bones、bookshelves、braziers、altar、hanging_lights、cages、vines、lava_moat、water_moat、floor_pattern（spots、checker、mosaic、path、rings、cracked、bones）。

限制条件

应用于 rules（整个运行）或单个房间。在房间内时不断重新应用，离开时清除。房间效果会叠加。

布尔值：slowness、mining_fatigue、weakness、hunger、wither、poison、glowing、nausea、darkness（1.16 中为失明）。放大倍数：slowness_level、mining_level、wither_level。附加列表："effects": [{ "id": "minecraft:wither", "amplifier": 0, "duration": 80, "particles": true }]。

encounters/<id>.json

字段	默认值	注释
trigger	enter	玩家踏入房间时触发。
trigger_delay_ticks	20	首波生成前的等待时间。
waves	[]	{ "delay_ticks", "mobs": [ … ] }。
boss	无	波次结束后；房间等待标记的生物死亡。

生物说明：entity、count（数字或 {min,max}）、name、health、damage、nbt、glowing、loot_table、equipment.helmet / chestplate / leggings / boots / mainhand。

rules

字段	默认值	注释
time_limit_seconds	0	0 = 无限制。
keep_inventory	true
pvp	false
allow_break / allow_place	false	否则仅允许白名单中的方块。
allow_interact	true
allowed_break_blocks / allowed_place_blocks	[]
mob_griefing	false
difficulty	inherit	或 peaceful / easy / normal / hard。
mob_health_multiplier / mob_damage_multiplier / player_damage_multiplier	1.0
respawn_in_dungeon	true	false = 死亡时离开。
max_deaths	0	0 = 无限次数。
drop_mob_loot	true
prevent_sleep	true
constraints	无	地牢全局效果。

rewards

on_complete / on_fail / on_room_clear：loot_table、xp、commands、broadcast、message、item_count。

---

配置

config/customdungeon-common.toml

键	默认值	注释
general.world_gen	true	自然神殿 / 嵌入结构。
general.debug_logs	false
general.max_active_instances	32	0 = 无限。
general.instance_spacing	512	实例之间的间隔。
general.instance_origin_y	64	备用 Y 坐标。
general.allow_config_overrides	true	加载 config/customdungeon/dungeons/**。
general.protect_dungeon_blocks	true	强制执行破坏 / 放置规则。
general.default_world_gen_chance	80	备选稀有度。

---

快速测试

/cd start example_crypt
/cd start example_nether
/cd start example_end
/cd place example_crypt