REFramework配置系统全解析：从基础到进阶的个性化定制指南

基础概念：配置系统架构

REFramework的配置系统是实现个性化体验的核心组件，其核心代码位于[REFrameworkConfig.hpp](https://gitcode.com/GitHub_Trending/re/REFramework/blob/6e28fb1f9aa3b7a37f175999d396b5a2cd4cb3fa/src/mods/REFrameworkConfig.hpp?utm_source=gitcode_repo_files)和[REFrameworkConfig.cpp](https://gitcode.com/GitHub_Trending/re/REFramework/blob/6e28fb1f9aa3b7a37f175999d396b5a2cd4cb3fa/src/mods/REFrameworkConfig.cpp?utm_source=gitcode_repo_files)两个文件中。配置系统采用键值对存储结构，默认配置文件名为re2_fw_config.txt，负责记录用户的所有偏好设置。

配置系统的工作流程遵循三个关键步骤：

1. 初始化：游戏启动时，REFrameworkConfig::on_initialize()创建配置实例
2. 加载：on_config_load()从文件读取参数并应用到内存变量
3. 保存：用户通过UI修改设置后，on_config_save()将当前状态写回文件

💡 核心提示：配置系统采用模块化设计，所有选项通过ValueList统一管理，便于批量操作和扩展。

核心功能：配置参数详解

菜单控制与交互设置

REFramework提供了丰富的菜单控制选项，让用户可以根据习惯定制交互方式：

参数名	类型	默认值	应用场景
MenuKey_V2	按键	VK_INSERT	定义打开/关闭主菜单的快捷键
MenuOpen	布尔值	true	控制游戏启动时菜单默认状态
RememberMenuState	布尔值	false	记忆上次游戏退出时的菜单状态

记忆菜单状态的实现逻辑：

// 仅当启用记忆功能时才应用保存的状态
if (m_remember_menu_state->value()) {
    g_framework->set_draw_ui(m_menu_open->value(), false);
}

界面显示个性化

光标与字体设置

光标控制是提升操作体验的重要部分：

• DrawCursorWithMenuOpen：控制菜单打开时是否显示光标（RE8默认为true，其他游戏默认为false）
• ShowCursorKey：快速切换光标显示状态的快捷键

字体自定义则让界面更符合个人视觉偏好：

• FontSize：设置界面文字大小，默认值为16
• FontFile：指定字体文件，默认使用"DEFAULT"内置字体

字体加载的实现代码：

// 创建字体目录（如果不存在）
const auto fonts_path = REFramework::get_persistent_dir() / "reframework" / "fonts";
fs::create_directories(fonts_path);

// 扫描目录中的字体文件
for (const auto& entry : fs::directory_iterator(fonts_path)) {
    if (fs::is_regular_file(entry)) {
        const auto ext = entry.path().extension();
        // 只加载otf和ttf格式的字体文件
        if (ext == ".otf" || ext == ".ttf") {
            fonts.push_back(entry.path().filename().string());
        }
    }
}

实践指南：配置界面操作

配置界面通过REFrameworkConfig::on_draw_ui()实现，按下默认快捷键Insert即可打开主菜单。界面采用树形结构组织，主要配置区域位于"Configuration"折叠项下：

// UI绘制逻辑
if (!ImGui::CollapsingHeader("Configuration")) { return; }
ImGui::TreePush("Configuration");
m_menu_key->draw("Menu Key");               // 菜单快捷键设置
m_show_cursor_key->draw("Show Cursor Key"); // 光标显示快捷键
m_remember_menu_state->draw("Remember Menu State"); // 记忆菜单状态
m_always_show_cursor->draw("Draw Cursor With Menu Open"); // 菜单打开时显示光标
if (m_font_file->draw("Font")) {            // 字体选择下拉框
    g_framework->set_font(m_font_file->value()); // 应用新字体
}
if (m_font_size->draw("Font Size")) {       // 字体大小调节
    g_framework->set_font_size(m_font_size->value()); // 应用新字体大小
}
ImGui::TreePop();

基本操作流程：

1. 按下Insert键打开REFramework主菜单
2. 找到并展开"Configuration"选项卡
3. 点击相应设置项进行修改
4. 修改完成后设置会自动保存生效

进阶技巧：深度定制方案

自定义快捷键

除了通过UI界面，还可以直接修改配置文件来自定义快捷键。例如将菜单快捷键从Insert改为F5：

1. 关闭游戏
2. 用文本编辑器打开re2_fw_config.txt
3. 找到或添加MenuKey_V2=VK_F5
4. 保存文件并重启游戏

如果需要在代码层面修改默认值（适用于mod开发者）：

// 在REFrameworkConfig.hpp中修改默认值
ModKey::Ptr m_menu_key{ ModKey::create(generate_name("MenuKey_V2"), VK_F5) };

批量配置管理

配置系统的ValueList设计使得批量操作变得简单：

// 配置项列表定义
ValueList m_options {
    *m_menu_key,           // 菜单快捷键
    *m_menu_open,          // 菜单默认状态
    *m_remember_menu_state,// 记忆菜单状态
    *m_always_show_cursor, // 光标显示控制
    *m_show_cursor_key,    // 光标显示快捷键
    *m_font_size,          // 字体大小
};

// 批量加载配置示例
for (IModValue& option : m_options) {
    option.config_load(cfg); // 遍历所有配置项并加载
}

这种设计不仅方便批量加载和保存，也为未来扩展新配置项提供了便利。

常见问题解决

配置文件损坏导致游戏崩溃

问题表现：修改配置后游戏无法启动或频繁崩溃
排查思路：

1. 检查配置文件是否存在语法错误
2. 确认是否有非法参数值（如非预期的按键码）
3. 尝试删除配置文件让系统生成默认设置

解决方法：删除re2_fw_config.txt文件，REFramework会在下次启动时自动创建全新的默认配置文件。

自定义字体不生效

问题表现：选择自定义字体后界面无变化
排查步骤：

1. 确认字体文件格式是否为.otf或.ttf
2. 检查文件是否放置在正确目录：reframework/fonts
3. 验证文件名是否包含特殊字符或空格
4. 确认配置文件中FontFile参数与实际文件名一致

快捷键冲突

问题表现：设置的快捷键无响应或触发其他功能
解决方法：

1. 选择不与游戏本身快捷键冲突的按键
2. 使用组合键（如Ctrl+Alt+F5）减少冲突概率
3. 在配置界面测试按键响应，确保正确识别

配置系统架构总结

REFramework的配置系统采用清晰的分层设计：

• 定义层：[REFrameworkConfig.hpp](https://gitcode.com/GitHub_Trending/re/REFramework/blob/6e28fb1f9aa3b7a37f175999d396b5a2cd4cb3fa/src/mods/REFrameworkConfig.hpp?utm_source=gitcode_repo_files)声明配置项和数据结构
• 逻辑层：[REFrameworkConfig.cpp](https://gitcode.com/GitHub_Trending/re/REFramework/blob/6e28fb1f9aa3b7a37f175999d396b5a2cd4cb3fa/src/mods/REFrameworkConfig.cpp?utm_source=gitcode_repo_files)实现配置加载、保存和UI交互
• 存储层：re2_fw_config.txt文件存储用户设置

通过这套配置系统，无论是普通玩家还是mod开发者，都能轻松定制REFramework的各种行为，打造个性化的游戏体验。掌握配置系统不仅能提升日常使用体验，也是深入理解REFramework架构的重要一步。