架构总览

文档版本：基于 2026-06-01 代码分析

概述

逃走中MOD采用三层架构设计，严格遵循 NeoForge 物理端分离原则。common/ 包承载双端共享代码，server/ 包承载纯服务端逻辑，client/ 包承载纯客户端逻辑。两个独立的 @Mod 入口类分别负责通用初始化和服务端/客户端专属初始化。

核心概念

三层架构边界

层	包路径	加载端	职责
Common	`common/`	双端	常量定义、配置管理、注册表、网络包声明
Server	`server/`	仅服务端	游戏逻辑、命令系统、事件处理、数据持久化
Client	`client/`	仅客户端	GUI渲染、HUD、模型、输入处理、客户端状态

关键原则：服务端代码绝不引用 client/ 包，防止专用服务器因类加载失败而崩溃。

两个 @Mod 入口

NeoForge 的 @Mod 注解支持通过 dist 属性控制加载端：

ChenxiRfm（@Mod(Constants.MOD_ID)）：所有物理端均加载，负责注册表、通用配置和服务端代理初始化
ChenxiRfmClient（@Mod(value = Constants.MOD_ID, dist = Dist.CLIENT)）：仅客户端加载，负责客户端配置和客户端代理初始化

架构设计

C4 Container 图

mermaid

graph TB
    subgraph external[" 外部系统 "]
        NF["NeoForge<br/>ModEventBus + NeoForgeEventBus"]
        MC["Minecraft Server/Client"]
        VCA["Simple Voice Chat API"]
    end

    subgraph common["common 层 -- 双端共享"]
        CONST["Constants<br/>MOD_ID = chenxi_rfm"]
        CM["ConfigManager<br/>三文件TOML配置"]
        REG["9个 DeferredRegister<br/>Blocks/Items/Entities/Sounds..."]
        NET["ModNetwork<br/>网络包注册入口"]
    end

    subgraph server["server 层 -- 纯服务端"]
        SP["ServerProxy<br/>服务端事件注册中心"]
        CMD["命令系统<br/>/nfa 指令树 ~58个叶子指令"]
        EVT_S["服务端事件处理器<br/>4个事件类"]
        SD["26个 SavedData<br/>NBT 数据持久化"]
        MGR["游戏管理器<br/>会话/金币/猎人/通知/配对..."]
    end

    subgraph client["client 层 -- 纯客户端"]
        CP["ClientProxy<br/>客户端事件注册中心"]
        GUI["GUI系统<br/>手机/中控面板/配置工具"]
        HUD["HUD渲染<br/>坐标/玩家信息/倒计时"]
        EVT_C["客户端事件处理器<br/>6个事件类"]
        RENDER["渲染器<br/>实体/方块实体/盔甲"]
    end

    NF --> common
    NF --> server
    NF --> client
    server --> MC
    client --> MC
    server -.-> VCA
    client -.-> VCA
    common --> server
    common --> client

初始化时序

mermaid

sequenceDiagram
    participant NF as NeoForge
    participant Main as ChenxiRfm<br/>(所有物理端)
    participant Common as common/
    participant SP as ServerProxy
    participant ClientMain as ChenxiRfmClient<br/>(仅客户端)
    participant CP as ClientProxy

    NF->>Main: 构造器(IEventBus, ModContainer)
    Main->>NF: ModEventBus: ModNetwork::registerPayloads
    Main->>NF: ModEventBus: ModEntityTypes::onEntityAttributeCreation
    Main->>Common: CommonConfig.init(modContainer)
    Common->>Common: ConfigManager.initCommon()
    Main->>Main: LogFilterBootstrap.reloadNow()
    Main->>Common: 9个 DeferredRegister.register(modEventBus)
    Note over Main,Common: Blocks/Items/Entities/Sounds/Menus/CreativeTabs...
    Main->>SP: ServerProxy.init(modEventBus)
    SP->>NF: NeoForge.EVENT_BUS: 注册 14 个事件监听器
    Note over SP: ServerStarted/ServerTick/PlayerLogin/Logout/LivingDamage...

    NF->>ClientMain: 构造器(IEventBus, ModContainer) [Dist.CLIENT]
    ClientMain->>Common: PhoneClientConfig.init(modContainer)
    Common->>Common: ConfigManager.initClient()
    ClientMain->>CP: ClientProxy.init(modEventBus, modContainer)
    CP->>NF: ModEventBus: 注册 7 个客户端事件
    Note over CP: RegisterMenuScreens/KeyMappings/LayerDefinitions/Renderers
    CP->>NF: NeoForge.EVENT_BUS: 注册 10 个客户端事件
    Note over CP: ClientTick/RenderGuiLayer/InteractionKeyMapping...

关键文件

入口类

文件	说明
`com/chenxi/chenxi_rfm/ChenxiRfm.java`	模组主类，所有物理端加载，负责注册表和 ServerProxy 初始化
`com/chenxi/chenxi_rfm/client/ChenxiRfmClient.java`	客户端入口类，仅 Dist.CLIENT 加载，负责 ClientProxy 初始化

代理类

文件	说明
`com/chenxi/chenxi_rfm/server/ServerProxy.java`	服务端代理，注册 14 个 NeoForge.EVENT_BUS 事件监听器
`com/chenxi/chenxi_rfm/client/ClientProxy.java`	客户端代理，注册 17 个事件监听器（ModEventBus + NeoForge.EVENT_BUS）

Common 层核心

文件	说明
`com/chenxi/chenxi_rfm/common/Constants.java`	模组常量（MOD_ID = "chenxi_rfm"）
`com/chenxi/chenxi_rfm/common/config/CommonConfig.java`	通用配置定义（日志过滤器）
`com/chenxi/chenxi_rfm/common/config/ConfigManager.java`	三文件 TOML 配置管理器
`com/chenxi/chenxi_rfm/common/config/ConfigKey.java`	类型安全配置键
`com/chenxi/chenxi_rfm/common/network/ModNetwork.java`	网络包注册入口
`com/chenxi/chenxi_rfm/common/logging/LogFilterBootstrap.java`	日志过滤器引导
`com/chenxi/chenxi_rfm/common/logging/RuntimeLogFilter.java`	运行时日志过滤器（Log4j）
`com/chenxi/chenxi_rfm/common/permission/NfaPermissionLevel.java`	权限等级枚举

注册表（common/registry/）

文件	注册内容
`ModArmorMaterials.java`	猎人盔甲材料
`ModBlocks.java`	8 个方块
`ModBlockEntities.java`	5 个方块实体
`ModCreativeTabs.java`	1 个创造模式标签页
`ModDataComponents.java`	2 个数据组件（手机ID、追踪指南针）
`ModEntityTypes.java`	2 个实体类型（A型/B型猎人）
`ModItems.java`	20+ 个物品
`ModMenus.java`	1 个菜单（手机）
`ModSounds.java`	7 个音效

事件总线注册清单

ModEventBus（模组初始化事件）

注册位置	事件类型	监听器	说明
ChenxiRfm 构造器	`RegisterPayloadHandlersEvent`	`ModNetwork::registerPayloads`	注册 53 个网络包
ChenxiRfm 构造器	`EntityAttributeCreationEvent`	`ModEntityTypes::onEntityAttributeCreation`	注册实体属性
ClientProxy.init()	`RegisterMenuScreensEvent`	`ClientProxy::registerMenuScreens`	注册手机GUI屏幕
ClientProxy.init()	`RegisterKeyMappingsEvent`	`RfmKeyMappings::onRegisterKeyMappings`	注册快捷键
ClientProxy.init()	`EntityRenderersEvent.RegisterLayerDefinitions`	`ClientHunterArmorEvents`	注册盔甲模型层
ClientProxy.init()	`RegisterClientExtensionsEvent`	`ClientHunterArmorEvents`	注册盔甲客户端扩展
ClientProxy.init()	`EntityRenderersEvent.RegisterLayerDefinitions`	`ClientHunterEntityEvents`	注册实体模型层
ClientProxy.init()	`EntityRenderersEvent.RegisterRenderers`	`ClientHunterEntityEvents`	注册实体渲染器
ClientProxy.init()	`EntityRenderersEvent.RegisterRenderers`	`ClientBlockEntityRenderEvents`	注册方块实体渲染器

NeoForge.EVENT_BUS（运行时事件）

服务端事件（注册于 ServerProxy.init()）

事件类型	监听器	说明
`ServerStartedEvent`	`ServerProxy::onServerStarted`	执行旧版数据迁移
`RegisterCommandsEvent`	`ServerCommandEvents::onRegisterCommands`	注册 /nfa 指令树
`ServerTickEvent.Post`	`ServerPhoneCallEvents::onServerTick`	电话通话管理器 tick
`PlayerEvent.PlayerLoggedInEvent`	`ServerPhoneCallEvents::onPlayerLoggedIn`	通知电话会话管理器
`MobSpawnEvent.PositionCheck`	`ServerMobSpawnEvents::onMobSpawnPositionCheck`	限制生物生成来源
`ServerTickEvent.Post`	`ServerRfmGameEvents::onServerTick`	RFM 多个管理器 tick
`PlayerEvent.PlayerLoggedInEvent`	`ServerRfmGameEvents::onPlayerLoggedIn`	同步身份/队伍/HUD/通知
`PlayerEvent.PlayerLoggedOutEvent`	`ServerRfmGameEvents::onPlayerLoggedOut`	同步公告通知目标
`PlayerTickEvent.Post`	`ServerRfmGameEvents::onPlayerTick`	检测猎人类型状态
`LivingIncomingDamageEvent`	`ServerRfmGameEvents::onLivingIncomingDamage`	猎人装备无敌/猎人抓捕
`PlayerInteractEvent.EntityInteract`	`ServerRfmGameEvents::onEntityInteract`	复活卡使用
`AttackEntityEvent`	`ServerRfmGameEvents::onAttackEntity`	猎人装备抓捕
`PlayerInteractEvent.RightClickBlock`	`ServerRfmGameEvents::onRightClickBlock`	猎人实体摆放/旋转
`ItemTossEvent`	`ServerRfmGameEvents::onItemToss`	阻止追踪指南针丢弃

客户端事件（注册于 ClientProxy.init()）

事件类型	监听器	说明
`InputEvent.InteractionKeyMappingTriggered`	`ClientConfigToolEvents`	打开手机配置工具屏幕
`ClientTickEvent.Post`	`PhoneResolutionPresetManager`	分辨率预设管理
`RenderGuiLayerEvent.Post`	`ClientPhoneCallHudEvents`	通话状态条渲染
`RenderGuiLayerEvent.Post`	`ClientPhoneNotificationEvents`	电话通知条渲染
`RenderGuiLayerEvent.Post`	`ClientRfmHudEvents`	RFM HUD 渲染
`ClientTickEvent.Post`	`ClientPhoneNotificationEvents`	电话呼叫音效 tick
`ClientTickEvent.Post`	`ClientRfmPanelEvents`	中控面板屏幕打开检查
`ClientTickEvent.Post`	`ClientRfmKeyEvents`	快捷键监听
`ClientTickEvent.Post`	`ClientRfmTitleWriterEvents`	TitleWriter 动画 tick
`RenderGuiLayerEvent.Post`	`ClientRfmTitleWriterEvents`	TitleWriter 动画渲染

扩展模组桥接方式

扩展模组 chenxi_rfm_addition 通过以下方式与核心模组桥接：

桥接方式	说明	示例
直接类引用	编译期依赖核心模组的类	引用 `NfaPermissionApi`、`NfaCommandPredicates`、`NfaPermissionService`
资源键硬编码	检查物品 ID 字符串	`ResourceLocation.fromNamespaceAndPath("chenxi_rfm", "config_tool")`
内部接口注入	通过 setter 注入实现	`BroadcastPadBlockEntity.VoiceBridge` 接口由 `ServerProxy` 注入
事件总线复用	注册到 NeoForge.EVENT_BUS	`ServerLifecycleEvents`、`ServerMinigameEvents`

工具模组 RFM_Tools 独立运行，不依赖核心模组。

数据流总览

mermaid

flowchart LR
    subgraph Client[" 客户端 "]
        GUI_Phone["手机GUI<br/>NFAPhoneScreen"]
        GUI_Mgr["中控面板<br/>RfmManagerScreen"]
        HUD_Layer["HUD渲染层"]
        ClientState["客户端状态<br/>RfmGameClientState<br/>RfmHudClientState"]
    end

    subgraph Network[" 网络层 "]
        Payloads["53个 Payload 类型"]
        Handlers["3个顶层 Handler<br/>Phone/Rfm/Permission"]
    end

    subgraph Server[" 服务端 "]
        CmdSystem["命令系统<br/>/nfa"]
        Managers["游戏管理器<br/>RfmGameSessionManager<br/>RfmCoinManager..."]
        SavedData["持久化数据<br/>26个 SavedData"]
        Config["配置文件<br/>client/common/server.toml"]
    end

    GUI_Phone <-->|C to S / S to C| Payloads
    GUI_Mgr <-->|C to S / S to C| Payloads
    HUD_Layer -->|S to C| ClientState
    Payloads --> Handlers
    Handlers --> Managers
    CmdSystem --> Managers
    Managers --> SavedData
    Managers --> Config
    ClientState --> HUD_Layer

注意事项 / 限制

严格分层：server/ 包绝不能引用 client/ 包的任何类。所有通信必须通过网络包进行。
Common 层限制：common/ 层不应包含任何仅单端可用的 Minecraft 类引用（如 Minecraft、ServerPlayer 等客户端或服务端专有类）。
注册表加载顺序：DeferredRegister 按照 ChenxiRfm 构造器中的调用顺序依次注册到 ModEventBus，但实际实例化由 NeoForge 在适当时机完成。
配置初始化时机：Common 配置在构造器阶段即初始化，Server 配置需等待 ServerStartedEvent 事件（因为需要 MinecraftServer 实例来定位世界目录），Client 配置在 ChenxiRfmClient 构造器中初始化。
网络协议版本：ModNetwork 使用硬编码版本号 "1"，客户端与服务端版本不匹配时网络包将被拒绝。

架构总览 ​

概述 ​

核心概念 ​

三层架构边界 ​

两个 @Mod 入口 ​

架构设计 ​

C4 Container 图 ​

初始化时序 ​

关键文件 ​

入口类 ​

代理类 ​

Common 层核心 ​

注册表（common/registry/） ​

事件总线注册清单 ​

ModEventBus（模组初始化事件） ​

NeoForge.EVENT_BUS（运行时事件） ​

服务端事件（注册于 ServerProxy.init()） ​

客户端事件（注册于 ClientProxy.init()） ​

扩展模组桥接方式 ​

数据流总览 ​

注意事项 / 限制 ​

相关文档 ​

架构总览

概述

核心概念

三层架构边界

两个 @Mod 入口

架构设计

C4 Container 图

初始化时序

关键文件

入口类

代理类

Common 层核心

注册表（common/registry/）

事件总线注册清单

ModEventBus（模组初始化事件）

NeoForge.EVENT_BUS（运行时事件）

服务端事件（注册于 ServerProxy.init()）

客户端事件（注册于 ClientProxy.init()）

扩展模组桥接方式

数据流总览

注意事项 / 限制

相关文档