逃走中MOD 技术文档

Appearance

配置文件参考 ​

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

概述 ​

逃走中MOD使用 ConfigManager + ConfigKey 体系管理所有配置文件。该体系基于 NightConfig 库的 CommentedFileConfig（TOML 格式），将配置分为三个独立文件，按作用域分别管理。

与 NeoForge 标准的 ModConfigSpec 不同，本模组使用自定义的 ConfigKey 泛型类型安全设计，提供 decode/normalize 双通道保证数据完整性和自动补全。

核心概念 ​

三文件体系 ​

配置文件路径作用域初始化时机
client.tomlconfig/nfa_rfm/client.toml客户端（全局）ChenxiRfmClient 构造器
common.tomlconfig/nfa_rfm/common.toml双端共享（全局）ChenxiRfm 构造器
server.toml<world>/serverconfig/nfa_rfm/server.toml服务端（每世界独立）ServerStartedEvent 时

ConfigKey 类型安全设计 ​

ConfigKey<T> 是配置系统的核心泛型类，包含四个要素：

ConfigKey<T>
├── path: List<String>        -- 由点号分隔的 TOML 路径
├── defaultValue: T           -- 默认值
├── decoder: Function<Object, T>  -- 从原始 Object 解码
└── normalizer: UnaryOperator<T>  -- 写入前规范化

提供的静态工厂方法：

工厂方法类型说明
ConfigKey.bool(path, defaultValue)ConfigKey<Boolean>布尔值
ConfigKey.string(path, defaultValue)ConfigKey<String>字符串，可附加规范化函数
ConfigKey.intKey(path, defaultValue, normalizer)ConfigKey<Integer>整数，带规范化函数
ConfigKey.stringMap(path)ConfigKey<Map<String, String>>字符串映射表（用于 phone.call_routes）
ConfigKey.stringList(path)ConfigKey<List<String>>字符串列表

架构设计 ​

配置加载流程 ​

mermaid
sequenceDiagram
    participant Mod as Mod 构造器
    participant CM as ConfigManager
    participant FS as 文件系统
    participant NC as NightConfig

    Mod->>CM: initCommon() / initClient() / initServer(server)
    CM->>CM: migrateLegacyGlobalToml()
    Note over CM: 检查旧路径 config/chenxi_rfm-*.toml<br/>如果存在则移动到 config/nfa_rfm/

    CM->>CM: reopen()
    CM->>FS: 确保目录存在
    CM->>NC: CommentedFileConfig.builder(path).sync().autosave().build()
    NC->>FS: 创建/读取 TOML 文件
    NC-->>CM: CommentedFileConfig 实例

    alt server 初始化
        CM->>CM: migrateLegacyServerCallRoutes()
        Note over CM: 从旧版 call_routes.json 迁移
        CM->>CM: RfmTitleWriterConfigManager.reload(server)
        Note over CM: 从 nfa_rfm/typewriter_titles/*.json 加载
    end

配置读写流程 ​

mermaid
flowchart LR
    subgraph Read["读取流程"]
        R1[ConfigKey.get] --> R2[config.get path]
        R2 --> R3{raw == null?}
        R3 -->|是| R4[返回 defaultValue]
        R3 -->|否| R5[key.decode raw]
        R5 --> R6{decoded == null?}
        R6 -->|是| R4
        R6 -->|否| R7[key.normalize decoded]
        R7 --> R8{与索引值一致?}
        R8 -->|否| R9[回写 config 并 save]
        R8 -->|是| R10[返回 normalized]
    end

    subgraph Write["写入流程"]
        W1[key.normalize value] --> W2[config.set path, normalized]
        W2 --> W3[config.save]
    end

关键特性：读取时自动补全缺失项——如果配置值缺失或不在规范范围内，自动回写默认值到文件。

关键文件 ​

文件说明
com/chenxi/chenxi_rfm/common/config/ConfigManager.java配置管理器主类，管理三个 TOML 文件的加载/读写/迁移
com/chenxi/chenxi_rfm/common/config/ConfigKey.java类型安全配置键，泛型设计
com/chenxi/chenxi_rfm/common/config/CommonConfig.javaCommon 配置定义（日志过滤器）
com/chenxi/chenxi_rfm/client/config/PhoneClientConfig.javaClient 配置定义（手机 UI）
com/chenxi/chenxi_rfm/server/config/phone/PersistentPhoneServerConfigSavedData.java手机服务端配置（SavedData + ConfigKey）
com/chenxi/chenxi_rfm/server/config/phone/PhoneCallRouteConfig.java电话呼叫路由配置
com/chenxi/chenxi_rfm/server/config/rfm/RfmServerConfigStore.javaRFM 游戏服务端配置
com/chenxi/chenxi_rfm/server/config/rfm/RfmTitleWriterConfigManager.java标题打字机 JSON 配置
com/chenxi/chenxi_rfm_addition/common/config/ConfigManager.java扩展模组的配置管理器
com/chenxi/chenxi_rfm_addition/server/config/ServerConfigKeys.java扩展模组的服务端配置键

配置项 ​

Common 配置（common.toml） ​

管理类：CommonConfig

配置路径类型默认值说明
log_filter.enabledboolfalse日志过滤器开关
log_filter.logger_prefixesstring（CSV）多种 logger 类名要屏蔽的 logger 名前缀
log_filter.message_keywordsstring（CSV）多种关键词要屏蔽的日志消息关键词

Client 配置（client.toml） ​

管理类：PhoneClientConfig

配置路径类型默认值约束说明
phone_ui.positionstring"bottom_right"bottom_right / bottom_left手机 UI 屏幕位置
phone_ui.rate_percentint动态默认值clamp 到合法范围手机 UI 缩放率百分比
phone_ui.phone_text_scale_percentint10090-160手机文字缩放百分比
phone_ui.config_tool_text_scale_percentint9090-160配置工具文字缩放百分比
phone_ui.rfm_notice_line_spacingint1锁定为 1RFM 通知行间距（不可修改）

Server 配置（server.toml） ​

手机系统（phone.*） ​

管理类：PersistentPhoneServerConfigSavedData + PhoneCallRouteConfig

配置路径类型默认值约束范围说明
phone.message_cooldown_secondsint50-120消息冷却秒数
phone.call_wait_secondsint3010-120呼叫等待秒数
phone.max_call_secondsint6030-120最大通话秒数
phone.call_routesMap<String,String>{}—电话号码转发路由表

RFM 游戏核心（rfm.*） ​

管理类：RfmServerConfigStore

配置路径类型默认值约束说明
rfm.prison.setboolfalse—是否已设置监狱点
rfm.prison.dimensionstring"minecraft:overworld"—监狱点维度
rfm.prison.xint0—监狱点 X 坐标
rfm.prison.yint64—监狱点 Y 坐标
rfm.prison.zint0—监狱点 Z 坐标
rfm.coin.rate_per_secondint100离散值：50/100/200/500金币每秒产出率
rfm.detect.base_rangeint501-512侦测范围基数
rfm.coin.storage.enabledboolfalse—启用PostgreSQL外部存储
rfm.coin.storage.hoststring""—数据库主机地址
rfm.coin.storage.portint54321-65535数据库端口
rfm.coin.storage.username_encstring""—数据库用户名（加密存储）
rfm.coin.storage.password_encstring""—数据库密码（加密存储）
rfm.round.resurrect.enabledboolfalse—启用回合复活机制
rfm.pairing.modestring"off"枚举值结对模式（off/coin/life）

关键流程 ​

旧版配置迁移 ​

ConfigManager 内置三个迁移逻辑，按时间顺序执行：

  1. migrateLegacyGlobalToml()（client/common 初始化时）

    • 源路径：config/chenxi_rfm-client.toml 和 config/chenxi_rfm-common.toml
    • 目标路径：config/nfa_rfm/client.toml 和 config/nfa_rfm/common.toml
    • 操作：移动文件

  2. migrateLegacyServerCallRoutes()（server 初始化时）

    • 源路径：<world>/serverconfig/nfa_rfm/call_routes.json
    • 目标：将 JSON 数据迁移为 TOML 格式写入 server.toml

  3. migrateLegacyClientNotificationUnread()（client 初始化时）

    • 清理未读通知的旧数据格式

延迟加载 ​

ConfigManager 使用懒加载模式，提供三个确保方法：

  • ensureClientLoaded() — 如果 client 配置尚未初始化，自动调用 initClient()
  • ensureCommonLoaded() — 如果 common 配置尚未初始化，自动调用 initCommon()
  • ensureServerLoaded() — 如果 server 配置尚未初始化，自动调用 initServer(server)

第一次调用 getter 时自动触发，避免提前访问未初始化的配置。

加密凭证 ​

数据库用户名和密码通过 username_enc 和 password_enc 以加密形式存储在 TOML 文件中。读写时通过 EncryptionUtil 进行加密/解密（具体加密算法请参考 RfmServerConfigStore 源码）。

扩展模组的配置系统 ​

chenxi_rfm_addition 拥有独立的 ConfigManager 和 ConfigKey 实现（包路径：com.chenxi.chenxi_rfm_addition.common.config），设计模式与核心模组一致：

配置文件路径
client.tomlconfig/nfa_rfm_addition/client.toml
common.tomlconfig/nfa_rfm_addition/common.toml
server.toml<world>/serverconfig/nfa_rfm_addition/server.toml

注意事项 / 限制 ​

  1. server.toml 按世界隔离：ConfigManager 使用 WeakHashMap<MinecraftServer, CommentedFileConfig> 管理多服务端实例的配置，每个世界的配置独立存储。
  2. TOML 文件格式：使用 NightConfig 的 CommentedFileConfig，支持注释。手动编辑后自动保存可能丢失注释中的自定义内容。
  3. 自动补全：读取时自动回写缺失配置项，这意味着首次启动后配置文件会自动填充所有默认值。
  4. 线程安全：ConfigManager 的所有读写操作通过 synchronized(LOCK) 保证线程安全。
  5. 配置项读写接口：所有配置项应通过 ConfigKey 的 get() / set() 方法访问，不应直接操作 CommentedFileConfig 实例。
  6. 配置热重载：支持通过 /nfa reload 指令热重载 common 和 server 配置。

相关文档 ​