Skip to content

Developer Guide

Jump to bottom
SSOrangeCATY edited this page Sep 16, 2026 · 3 revisions

开发者从零开始教程

本页面面向准备参与 BlockOffensive 开发的开发者，覆盖从克隆项目到运行、构建、理解模块和开始扩展的完整流程。

1. 准备环境

必备工具

工具 要求
JDK Java 17 和 Java 21，均需能被 Gradle toolchain 发现
Git 可访问 GitHub
Gradle 使用仓库自带 gradlew.bat，无需全局安装
IDE IntelliJ IDEA 或 Eclipse

项目使用 Forge 1.20.1、NeoForged legacyforge Gradle 插件和 Parchment mappings。

推荐 IDE

推荐 IntelliJ IDEA：

  1. 选择 File -> Open。
  2. 打开仓库根目录。
  3. 等待 Gradle 同步完成。
  4. 确认 Project SDK 和源码语言级别为 Java 17。
  5. 在 Gradle JVM/toolchain 列表中确认 Java 21 可用。

源码以 Java 17 编译。createMinecraftArtifacts 使用 Java 21 运行 ModDev 工具，因此 build、首次开发运行或需要生成 Minecraft artifacts 的任务可能同时解析两个 toolchain。可用下列命令检查 Gradle 识别到的 JDK：

.\gradlew.bat javaToolchains --console=plain

Eclipse 用户可参考仓库中的 .eclipse/configurations 启动配置。

2. 克隆仓库

git clone https://github.com/SSOrangeCATY/BlockOffensive.git
cd BlockOffensive

仓库包含本地 FPSMatch 子项目，并通过 Gradle composite build 替换依赖：

includeBuild("FPSMatch") {
    dependencySubstitution {
        substitute module('com.phasetranscrystal:fpsmatch') using project(':')
    }
}

这意味着你修改 FPSMatch 子目录源码后，BlockOffensive 可以直接引用本地源码版本。

3. 检查 Gradle 任务

.\gradlew.bat tasks --all --console=plain

常用任务：

命令 说明
.\gradlew.bat runClient 启动开发客户端。
.\gradlew.bat runServer 启动开发服务端，带 --nogui。
.\gradlew.bat runGameTestServer 启动 GameTest 服务端。
.\gradlew.bat runData 运行数据生成，输出到 src/generated/resources/。
.\gradlew.bat compileJava 编译 Java 源码。
.\gradlew.bat build 构建完整产物。

4. 第一次编译

建议先运行：

.\gradlew.bat compileJava --console=plain

如果只需要验证完整构建：

.\gradlew.bat build --console=plain

构建成功后，jar 会出现在：

build\libs\

5. 启动开发客户端

.\gradlew.bat runClient --console=plain

开发运行目录为：

run/

如果需要额外测试依赖或地图数据，可放入该运行目录对应位置。

6. 启动开发服务端

.\gradlew.bat runServer --console=plain

服务端运行配置会自动添加：

--nogui

7. 生成数据

.\gradlew.bat runData --console=plain

数据生成任务配置：

  • mod id：blockoffensive
  • 输出目录：src/generated/resources/
  • existing 目录：src/main/resources/

8. 项目目录速览

BlockOffensive/
├─ build.gradle
├─ gradle.properties
├─ settings.gradle
├─ FPSMatch/
├─ src/main/java/com/ptcrys/blockoffensive/
│  ├─ client/
│  ├─ command/
│  ├─ compat/
│  ├─ data/
│  ├─ entity/
│  ├─ event/
│  ├─ item/
│  ├─ map/
│  ├─ mixin/
│  ├─ net/
│  ├─ sound/
│  ├─ spectator/
│  ├─ util/
│  ├─ web/
│  ├─ BOConfig.java
│  └─ BlockOffensive.java
└─ src/main/resources/

9. 从哪里开始读源码

建议顺序：

  1. BlockOffensive.java：Mod 入口、配置注册、网络包注册、通用初始化。
  2. MapRegister.java：注册 cs 和 csdm 地图类型。
  3. CSMap.java：CS 系模式基类，封装队伍、旁观、经济、通用规则。
  4. CSGameMap.java：爆破模式主逻辑。
  5. CSDeathMatchMap.java：死斗模式主逻辑。
  6. BOClientBootstrap.java：客户端按键、HUD、TAB、实体渲染注册。
  7. BOClientEvent.java：客户端 tick、Web Server、移动同步、投掷物消息。
  8. net/：自定义网络包。
  9. event/：对外 Forge 事件。
  10. BOConfig.java：Forge Config 定义。

10. 添加一个新功能的推荐流程

修改服务端比赛逻辑

  1. 先判断功能属于通用 CS 行为、爆破模式还是死斗模式。
  2. 通用逻辑优先放在 CSMap。
  3. 爆破模式专属逻辑放在 CSGameMap。
  4. 死斗模式专属逻辑放在 CSDeathMatchMap。
  5. 如果需要对外扩展，优先增加 Forge Event。
  6. 如果需要同步到客户端，增加或复用 net/ 包。
  7. 编译验证：.\gradlew.bat compileJava --console=plain。

添加客户端 HUD 或显示数据

  1. 服务器侧准备同步数据。
  2. 新增或复用 S2C 网络包。
  3. 将数据写入 CSClientData 或专门的客户端缓存。
  4. 在 HUD、Overlay、TAB 或 Screen 中读取缓存。
  5. 用 runClient 实际检查显示。

添加配置项

  1. 在 BOConfig.Client 或 BOConfig.Common 添加配置。
  2. 如果有配置界面，需要同步更新 BOMenuIntegration。
  3. 如果是游戏规则，确认 CSMap.configureGameRules 是否需要应用。
  4. 在 Wiki 的 配置说明 中补充配置项。

添加网络包

  1. 在 net/ 下按领域放置：bomb、dm、mvp、shop、spec 或根包。
  2. 提供 encode、decode、handle。
  3. 在 BOPacketRegistration.register(...) 中注册，并保持已有 discriminator 顺序。
  4. 确认方向、线程切换和发送方校验。
  5. 在 网络包文档 中补充字段与用途。

11. 验证建议

当前仓库主要使用 Gradle 编译和运行任务验证。常用检查：

.\gradlew.bat compileJava --console=plain
.\gradlew.bat build --console=plain

如果变更涉及客户端 UI、HUD、按键、Web Server 或渲染，建议额外运行：

.\gradlew.bat runClient --console=plain

如果变更涉及服务端地图生命周期、队伍、经济或 C4 逻辑，建议额外运行：

.\gradlew.bat runServer --console=plain

12. 依赖与发布坐标

源码构建发布坐标：

com.phasetranscrystal:blockoffensive:<BlockOffensive version>

公开平台 Maven 示例见 README。当前源码使用 mod_group_id=com.phasetranscrystal、mod_id=blockoffensive、mod_version=1.3.0。

13. 开发注意事项

  • 保持 Java 17 源码 toolchain，并保留 createMinecraftArtifacts 的 Java 21 工具运行时。
  • 不要绕开 FPSMatch 已有地图、队伍、商店、经济、统计和网络工具。
  • 修改 FPSMatch 子项目时要同时验证 BlockOffensive。
  • 修改网络包时要注意客户端/服务端两端协议一致。
  • 修改比赛逻辑时要检查旁观者、掉线、死亡、回合重置、地图清理等边界。
  • 不要把本地运行目录、缓存、账号文件或构建产物提交到主仓库。

Clone this wiki locally