EnderRealm 技术文档

外观

BedWars 多模式架构文档 ​

概述 ​

BedWars 模块支持多游戏模式（如 4 队模式、8 队模式等），通过 /bw join <模式ID> 加入指定模式的房间。没有传模式参数时使用默认模式。

架构核心原则：

  • 模式决定队伍：哪个模式用哪些队伍，由 config.yml 的 modes 段定义
  • 地图声明模式：地图 config 中 modes 字段声明该地图支持哪些模式，默认为空（不参与任何模式）
  • 安全默认值：未配置 modes 的地图不参与任何模式，防止配置错误影响全局

配置文件说明 ​

1. config.yml — 模式定义 ​

yaml
Language: zh_cn
room-prefix: "bedwars-"

# 默认游戏模式（/bw join 不指定模式时使用）
default-mode: "4t"

# 模式定义
modes:
  4t:
    display-name-key: "mode-4t"       # 语言文件中的 key，非硬编码文字
    teams: [red, blue, green, yellow] # 该模式使用的队伍 ID（对应 team.yml）
    min-players: 2                    # 最少玩家数
    max-players: 16                   # 最多玩家数
    countdown-time: 30                # 倒计时秒数

新增模式示例 — 添加 8 队模式：

yaml
modes:
  4t:
    display-name-key: "mode-4t"
    teams: [red, blue, green, yellow]
    min-players: 2
    max-players: 16
    countdown-time: 30
  8t:
    display-name-key: "mode-8t"
    teams: [red, blue, green, yellow, cyan, pink, orange, gray]
    min-players: 4
    max-players: 32
    countdown-time: 45

2. team.yml — 队伍视觉配置（不变） ​

team.yml 是全局队伍定义，包含所有可能的队伍的视觉属性（颜色、方块、床材质等）。它是「队伍属性字典」，不是「模式队伍列表」。

yaml
team:
  - teamid: "red"
    name: "team-red"
    wool: "red_wool"
    terracotta: "red_terracotta"
    glass: "red_stained_glass"
    bed: "red_bed"
    color: "#FF5555"
  # ... 共 8 个队伍 ...

模式通过 teams 字段选择使用哪些队伍，team.yml 提供这些队伍的视觉数据。

3. 地图 config.yml — 地图模式声明 ​

yaml
name: Temple
name_zh: 庙宇

# 该地图支持的模式列表（必须通过编辑 UI 手动设置）
# 留空或缺失 = 不参与任何模式（安全默认）
modes:
  - 4t

waiting-lobby:
  x: 0.5
  y: 103.0
  ...

teams:
  red:
    spawn: { x: 0.45, y: 63.0, z: -70.6, ... }
    bed: { x: 0.57, y: 63.5, z: -59.6, ... }
  blue:
    spawn: { x: 71.5, y: 63.0, z: 0.4, ... }
    bed: { x: 60.5, y: 63.0, z: 0.6, ... }
  green:
    spawn: { x: 0.6, y: 63.0, z: 71.5, ... }
    bed: { x: 0.4, y: 63.0, z: 60.6, ... }
  yellow:
    spawn: { x: -70.5, y: 63.0, z: 0.5, ... }
    bed: { x: -59.6, y: 63.0, z: 0.4, ... }
  # 8t 模式时还可以有 cyan, pink, orange, gray

关键规则：

  • 地图可以定义超过模式需要的队伍 spawn/bed（如 4t 地图可以有 8 个队伍的位置）
  • 加载时只会加载模式 teams 列表中的队伍
  • modes 字段通过编辑 UI 的「模式设置」按钮设置，默认为空

4. 语言文件 — 模式显示名称 ​

yaml
# zh_cn.yml
mode-4t: "4v4v4v4"
mode-8t: "8队混战"

# en_us.yml
mode-4t: "4v4v4v4"
mode-8t: "8 Team Brawl"

模式的显示名称通过 display-name-key 引用语言 key，不硬编码。

核心类说明 ​

GameMode（数据类） ​

cn.enderrealm.bedwars.mode.GameMode
字段类型说明
idString模式唯一标识，如 "4t"
displayNameKeyString语言文件 key，如 "mode-4t"
teamKeysList<String>该模式使用的队伍 ID 列表
minPlayersint最少玩家数
maxPlayersint最多玩家数
countdownTimeint倒计时秒数

GameModeRegistry（注册表） ​

cn.enderrealm.bedwars.mode.GameModeRegistry

从 config.yml 的 modes 段加载所有模式。无 modes 段时自动创建默认 "4t" 模式（向后兼容）。

方法说明
getMode(id)按 ID 获取模式
getDefaultMode()获取默认模式
getAllModes()获取所有模式
hasMode(id)检查模式是否存在
getModeIds()获取所有模式 ID 列表

访问模式的方式 ​

java
// 从任意游戏逻辑中
GameMode mode = gameManager.getRoom().getGameMode();

// 从插件主类
GameMode mode = plugin.getGameModeRegistry().getMode("4t");

// 判断当前模式
if (mode != null && "4t".equals(mode.getId())) {
    // 4t 模式专属逻辑
}

游戏初始化流程 ​

/bw join 4t
  → JoinCommand: 解析 modeId = "4t"
  → RoomManager.createRoom("4t")
    → getCompatibleMaps("4t")  // 只选 modes 列表含 "4t" 的地图
    → 创建世界 bedwars-4t-1
    → new Room(plugin, world, waitingLoc, mapFolder, gameMode)

Room.startGame()
  → new GameManager(plugin, room)

LoadTeamLocationsTask
  → 读地图 config.yml 的 teams 段
  → 过滤: 只加载 gameMode.getTeamKeys() 中的队伍
  → 地图有 8 个队伍位置但 4t 只加载 red/blue/green/yellow

AssignTeamsTask
  → teamSpawns.keySet() 只有 4 个队伍
  → 玩家均匀分配到这 4 个队

SetupPlayerTeamsTask → 设置颜色/装备
InitTeamBedsTask → 放 4 个床
TeleportPlayersTask → 传送到 4 个出生点

编辑 UI — 模式设置 ​

在编辑 UI 中有一个指南针按钮（slot 34）用于打开模式选择界面：

  • 绿色染色玻璃板 = 已启用的模式，点击取消
  • 红色染色玻璃板 = 未启用的模式，点击激活
  • 底部有返回按钮

模式选择状态保存在地图 config 的 modes 字段中。

扩展指南 ​

添加新模式 ​

  1. 在 config.yml 的 modes 段添加新模式定义
  2. 在 zh_cn.yml / en_us.yml 添加模式显示名称
  3. 在 team.yml 中确保新模式用到的队伍都有定义
  4. 在地图编辑 UI 中为地图激活新模式
  5. 确保地图 config 中有新模式涉及队伍的 spawn/bed 位置

添加模式独有机制 ​

在 GameMode 中添加新字段和方法：

java
public class GameMode {
    // 现有字段...
    
    // 新增：模式独有机制开关
    private boolean diamondGeneratorEnabled;
    private int resourceMultiplier;
    private List<String> specialMechanics;
    
    public boolean hasMechanic(String key) {
        return specialMechanics != null && specialMechanics.contains(key);
    }
}

在 config.yml 中配置：

yaml
modes:
  4t:
    display-name-key: "mode-4t"
    teams: [red, blue, green, yellow]
    min-players: 2
    max-players: 16
    countdown-time: 30
    special-mechanics: [diamond-tier-spawner, fast-respawn]
    resource-multiplier: 1

在游戏逻辑中判断：

java
GameMode mode = gameManager.getRoom().getGameMode();
if (mode != null && mode.hasMechanic("diamond-tier-spawner")) {
    // 钻石级资源生成器逻辑
}

添加新队伍 ​

  1. 在 team.yml 中添加新队伍定义
  2. 在 zh_cn.yml / en_us.yml 中添加队伍名称和编辑 UI 语言 key
  3. 在 EditManager 的 getTeamWoolMaterial() / getTeamBedMaterial() 中添加新队伍颜色映射
  4. 在 SetupPlayerTeamsTask 的 getBukkitColorFromHex() 中添加新队伍颜色映射
  5. 地图编辑 UI 中会自动显示新队伍（已通过遍历 team.yml 实现）

© 2022-present EnderRealm. All rights reserved.