快速开始

本文档面向 EnderRealm 开发者，说明如何搭建本地开发环境并参与项目开发。

环境要求

组件	版本	说明
JDK	21（必须）	推荐 OpenJDK 或 Azul Zulu
JDK 17	17（必须）	用于构建 Floodgate 子模块（Lombok 兼容性要求）
Git	最新版	需要支持子模块
Python	3.12（推荐）	后端服务使用，其他 3.x 版本亦可

⚠️ JDK 版本直接决定服务端性能，不同版本之间可能存在巨大差距。生产环境使用 JDK 21，开发环境请尽量保持一致。

配置 JAVA_HOME_17 环境变量

Floodgate 的构建脚本（Lombok）与 JDK 21 不兼容，必须使用 JDK 17 构建。需要配置 JAVA_HOME_17 环境变量指向 JDK 17 安装路径。

Windows（PowerShell）：

# 设置用户环境变量（永久生效，需重启终端）
[System.Environment]::SetEnvironmentVariable("JAVA_HOME_17", "你的JDK17路径", "User")

macOS / Linux（bash/zsh）：

# 添加到 ~/.bashrc 或 ~/.zshrc
export JAVA_HOME_17=/path/to/jdk-17

设置后重启终端，验证：

# Windows PowerShell
echo $env:JAVA_HOME_17

# macOS / Linux
echo $JAVA_HOME_17

应输出 JDK 17 的安装路径，例如 C:\Users\你的用户名\.jdks\ms-17.0.16 或 /usr/lib/jvm/java-17。

克隆仓库

本项目包含 Git 子模块，克隆时需一并初始化：

git clone --recurse-submodules https://github.com/EnderRealmMC/EnderRealmServerCore.git

如果已经克隆但未初始化子模块：

git submodule update --init --recursive

未初始化子模块将导致部分功能无法使用，自动化脚本也无法正常运行。

项目结构

├── EnderRealmServerCore/       # 核心插件
├── bedwars/                    # 小游戏 - 起床战争
├── disaster/                   # 小游戏 - 灾难生存
├── BlockedInCombat/            # 小游戏 - 方块战斗
├── easy4form/                  # 表单库
├── EnderRealmServerApi/        # API 服务（FastAPI）
└── docs/                       # 本文档站点（VitePress）

启动开发服务器

两条命令即可完成搭建并启动：

# 1. 构建所有模块并部署到 _server/ 目录
./gradlew setupDevServer

# 2. 启动开发服务器
./gradlew runDevServer

常用命令

命令	说明
./gradlew setupDevServer	构建并部署（增量）
./gradlew setupDevServer -Pforce	强制覆盖所有文件（包括运行时配置）
./gradlew runDevServer	启动开发服务器
./gradlew cleanDevServer	清理开发服务器

后端服务

后端使用 FastAPI，依赖 uv 管理 Python 依赖。

# 安装 uv（如尚未安装）
pip install uv

# 进入后端目录
cd EnderRealmServerApi

# 安装依赖
uv sync

# 启动服务（开发模式，热重载）
uv run uvicorn app.main:app --reload