Harbinger项目解析：Minecraft Mod开发中的物理端与逻辑端处理

2025-07-02 13:58:32作者：袁立春Spencer

引言

在Minecraft Mod开发中，正确处理客户端与服务器端的逻辑是至关重要的技术难点。本文将深入探讨Harbinger项目中涉及的物理端、逻辑端概念及其实现方式，帮助开发者理解Minecraft 1.3版本后的架构变化及其对Mod开发的影响。

Minecraft架构演变与网络IO

自Minecraft 1.3版本起，单人游戏模式实现方式发生了重大变革。游戏不再采用传统的单线程架构，而是通过模拟本地服务器的方式运行。这意味着：

即使是在单人游戏中，也存在完整的客户端-服务器架构
客户端与服务器之间必须通过网络IO进行通信
游戏逻辑被明确分离到两个不同的执行环境中

这种架构变化带来了更清晰的职责划分，但也增加了Mod开发的复杂性。客户端无法直接知晓服务器状态，服务器也无法直接获取客户端输入，所有交互都必须通过网络通信完成。

业务端判定技术

在原版Minecraft中，存在许多客户端与服务器逻辑耦合的情况。例如，当玩家右击方块时，消息可能会被显示两次——一次来自服务器处理，一次来自客户端处理。

传统解决方案的问题

早期开发者可能使用FMLCommonHandler.getEffectiveSide()方法进行判断，但这种方法存在以下问题：

早期实现是通过检查线程名来判断执行端，属于hack手段
新版本虽然改为检查ThreadGroup，但仍不够规范
性能开销相对较大

物理端与@SideOnly注解

@SideOnly的本质

@SideOnly是MCP(Mod Coder Pack)使用的注解，主要用途包括：

在合并客户端和服务器代码时标识来源
根据运行环境移除不匹配的代码
确保特定代码只在指定物理端存在

注解的有效值为Side.CLIENT和Side.SERVER，分别表示仅客户端和仅服务器端。

注解的实际效果

当方法被标记为@SideOnly(Side.CLIENT)时：

在物理服务器上调用会抛出NoSuchMethodException
在物理客户端上可以正常调用

反之，@SideOnly(Side.SERVER)标记的方法：

在物理客户端上调用会抛出异常
在物理服务器上可以正常执行

使用场景分析

@SideOnly主要适用于以下三种情况：

无注解：代码在服务器和客户端同时存在
@SideOnly(Side.CLIENT)：仅客户端存在的代码（如渲染相关）
@SideOnly(Side.SERVER)：仅服务器存在的代码（如某些命令处理）

物理端代理与依赖注入

@SidedProxy机制

@SidedProxy允许Mod在不同物理端使用不同的代理实现：

@SidedProxy(serverSide = "ServerProxy", clientSide = "ClientProxy")
public static Proxy myProxy;

这种机制基于物理端而非逻辑端，使得Mod可以在不同运行环境下拥有不同的行为。

代理模式实现示例

典型的代理实现包含三个部分：

公共代理基类：定义通用接口
服务器代理：实现服务器特有逻辑
客户端代理：实现客户端特有逻辑

// 公共基类
public class CommonProxy {
    public void foo() {
        System.out.println("CommonProxy says foo");
    }
}

// 服务器代理
public class ServerProxy extends CommonProxy {
    public void foo() {
        System.out.println("ServerProxy says foo");
    }
}

// 客户端代理
public class ClientProxy extends CommonProxy {
    public void foo() {
        System.out.println("ClientProxy says foo");
    }
}