# 配置管理 **本文档引用的文件** - [Main.ts](file://assets/script/Main.ts) - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts) - [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts) - [config.json](file://assets/resources/config.json) - [GameUIConfig.ts](file://assets/script/game/common/config/GameUIConfig.ts) - [GameEvent.ts](file://assets/script/game/common/config/GameEvent.ts) - [LoadingViewComp.ts](file://assets/script/game/initialize/view/LoadingViewComp.ts) ## 目录 1. [简介](#简介) 2. [项目结构](#项目结构) 3. [核心配置文件](#核心配置文件) 4. [配置系统架构](#配置系统架构) 5. [配置加载生命周期](#配置加载生命周期) 6. [配置管理模式](#配置管理模式) 7. [多语言配置体系](#多语言配置体系) 8. [配置热更新机制](#配置热更新机制) 9. [最佳实践指南](#最佳实践指南) 10. [故障排除](#故障排除) 11. [总结](#总结) ## 简介 本项目采用了一套完整的全局配置管理体系，以`config.json`为核心配置文件，配合Oops Framework提供的配置管理机制，实现了灵活、可扩展的配置解决方案。该系统支持版本控制、多语言国际化、加密存储、网络通信等关键功能，为游戏提供了稳定可靠的配置基础设施。 ## 项目结构 配置管理系统的核心文件组织结构如下： ```mermaid graph TB subgraph "配置文件层" ConfigJSON["config.json
核心配置文件"] LangJSON["language/*.json
多语言资源"] UIConfig["GameUIConfig.ts
界面配置"] end subgraph "初始化层" MainTS["Main.ts
应用入口"] InitTS["Initialize.ts
初始化模块"] SMCTS["SingletonModuleComp.ts
单例组件"] end subgraph "框架层" OopsFramework["Oops Framework
配置管理框架"] Storage["Storage Module
本地存储"] Language["Language Module
多语言模块"] end ConfigJSON --> InitTS InitTS --> SMCTS SMCTS --> OopsFramework OopsFramework --> Storage OopsFramework --> Language ``` **图表来源** - [config.json](file://assets/resources/config.json#L1-L21) - [Main.ts](file://assets/script/Main.ts#L1-L41) - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L1-L207) **章节来源** - [config.json](file://assets/resources/config.json#L1-L21) - [Main.ts](file://assets/script/Main.ts#L1-L41) - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L1-L207) ## 核心配置文件 ### config.json 结构详解 `config.json`是整个配置系统的核心，包含了游戏运行所需的所有基础配置信息： | 配置块 | 字段 | 类型 | 描述 | 默认值 | |--------|------|------|------|--------| | config | version | string | 游戏版本号，用于版本兼容性检查 | "1.0.0" | | config | package | string | 应用包名，用于命名空间隔离 | "com.oops.game" | | config | localDataKey | string | 本地数据加密密钥 | "oops" | | config | localDataIv | string | 本地数据加密初始化向量 | "framework" | | config | httpServer | string | HTTP服务器地址 | "http://192.168.0.150/main/" | | config | httpTimeout | number | HTTP请求超时时间（毫秒） | 10000 | | config | frameRate | number | 游戏帧率设置 | 60 | | language | type | array | 支持的语言类型列表 | ["zh", "en"] | | language | path | object | 语言资源路径映射 | json: "language/json", texture: "language/texture" | ### 配置字段技术意义 #### 版本控制与包名标识 - **version字段**：确保客户端与服务器端版本兼容性，防止因版本差异导致的功能异常 - **package字段**：提供命名空间隔离，避免与其他应用产生冲突 #### 加解密密钥配置 - **localDataKey**：本地数据加密密钥，保护用户隐私数据 - **localDataIv**：初始化向量，增强加密安全性 #### 服务器通信配置 - **httpServer**：统一的服务器地址，便于维护和迁移 - **httpTimeout**：合理的超时设置，平衡用户体验与系统稳定性 #### 帧率优化配置 - **frameRate**：固定帧率设置，确保游戏性能一致性 **章节来源** - [config.json](file://assets/resources/config.json#L1-L21) ## 配置系统架构 ### 整体架构设计 ```mermaid classDiagram class Main { +start() void +run() Promise~void~ +initGui() void +initEcsSystem() Promise~void~ } class Initialize { +LoadingView LoadingViewComp +init() void +loadCustom(queue) void +loadLanguage(queue) void +loadCommon(queue) void +onComplete(queue) void +loadGameDataUnified() Promise~void~ +loadFromCloud() Promise~void~ +loadFromLocalDebug() Promise~void~ +isWxClient() boolean } class SingletonModuleComp { +initialize Initialize +map GameMap +openid string +mission object +guides array +current_guide number +data object +fight_hero number +heros array +monsters array +vmdata object +updateCloudData() boolean +getCloudData() void +overrideLocalDataWithRemote(data) void +addHero(hero_uuid) boolean +updateFihgtHero(heroId) boolean +updateGold(gold) boolean } class OopsFramework { +config object +language object +storage object +res object +gui object } Main --> Initialize : "创建实例" Initialize --> SingletonModuleComp : "注入依赖" SingletonModuleComp --> OopsFramework : "使用框架" Initialize --> OopsFramework : "调用服务" ``` **图表来源** - [Main.ts](file://assets/script/Main.ts#L12-L41) - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L20-L207) - [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L20-L195) ### 配置注入机制 配置系统通过以下机制实现全局访问： 1. **单例模式**：通过`ecs.getSingleton()`获取全局配置实例 2. **依赖注入**：Initialize模块负责配置的初始化和注入 3. **框架集成**：Oops Framework提供统一的配置访问接口 **章节来源** - [Main.ts](file://assets/script/Main.ts#L25-L30) - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L25-L35) - [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L194-L195) ## 配置加载生命周期 ### 启动流程分析 ```mermaid sequenceDiagram participant Main as "Main.ts" participant Initialize as "Initialize.ts" participant SMComp as "SingletonModuleComp" participant Oops as "Oops Framework" participant Config as "config.json" Main->>Initialize : 创建Initialize实体 Main->>SMComp : 初始化SingletonModule Initialize->>Config : 加载配置文件 Config-->>Initialize : 返回配置数据 Initialize->>Oops : 注入配置到框架 Oops-->>Initialize : 配置就绪 Initialize->>Initialize : 执行异步队列 Initialize->>Initialize : 加载语言包 Initialize->>Initialize : 加载公共资源 Initialize->>SMComp : 完成配置注入 SMComp-->>Main : 初始化完成 ``` **图表来源** - [Main.ts](file://assets/script/Main.ts#L25-L35) - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L25-L45) ### 生命周期阶段详解 #### 1. 应用启动阶段 - Main.ts作为应用入口点，负责初始化Oops Framework - 创建Initialize实体并注入到系统中 #### 2. 配置加载阶段 - Initialize模块按顺序执行配置加载任务 - 包括自定义内容、语言包、公共资源的加载 #### 3. 配置注入阶段 - 将加载的配置数据注入到Oops Framework中 - 通过SingletonModuleComp实现全局访问 #### 4. 系统初始化阶段 - 完成所有配置相关的工作后，系统进入正常运行状态 **章节来源** - [Main.ts](file://assets/script/Main.ts#L25-L41) - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L25-L45) ## 配置管理模式 ### SingletonModuleComp 实现 `SingletonModuleComp`是配置管理的核心组件，实现了全局配置的统一管理： ```mermaid classDiagram class SingletonModuleComp { +initialize : Initialize +map : GameMap +openid : string +mission : object +guides : array +current_guide : number +data : object +fight_hero : number +heros : array +monsters : array +vmdata : object +vmAdd() void +reset() void +updateCloudData() boolean +getCloudData() void +overrideLocalDataWithRemote(data) void +addHero(hero_uuid) boolean +updateFihgtHero(heroId) boolean +updateGold(gold) boolean +finishGuide(index) void +error() void } class VM { +add(data, name) void } SingletonModuleComp --> VM : "使用MVVM" ``` **图表来源** - [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L20-L195) ### 全局访问模式 配置系统采用以下模式实现全局访问： 1. **静态实例模式**：通过`smc`变量提供全局访问点 2. **MVVM绑定**：使用ViewModel实现数据双向绑定 3. **事件驱动**：通过GameEvent系统通知配置变更 **章节来源** - [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L194-L195) ## 多语言配置体系 ### 语言配置结构 ```mermaid graph LR subgraph "语言配置" LangType["语言类型列表
['zh', 'en']"] LangPath["语言路径映射
json: 'language/json'
texture: 'language/texture'"] end subgraph "资源文件" ZhJSON["zh.json
中文语言包"] EnJSON["en.json
英文语言包"] FontFiles["字体文件
language/font/"] end LangType --> ZhJSON LangType --> EnJSON LangPath --> ZhJSON LangPath --> EnJSON LangPath --> FontFiles ``` **图表来源** - [config.json](file://assets/resources/config.json#L12-L20) - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L60-L75) ### 多语言加载流程 1. **语言检测**：从本地存储获取用户语言偏好 2. **默认设置**：未设置时默认使用中文(zh) 3. **资源加载**：加载对应语言的JSON和字体资源 4. **动态切换**：支持运行时语言切换 **章节来源** - [config.json](file://assets/resources/config.json#L12-L20) - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L60-L75) ## 配置热更新机制 ### 热更新可行性分析 基于现有架构，配置系统支持以下热更新特性： #### 支持的热更新场景 - **语言包更新**：无需重启即可切换语言 - **界面配置更新**：动态调整UI布局和样式 - **游戏参数调整**：实时修改游戏平衡性参数 #### 热更新限制 - **核心配置限制**：HTTP服务器地址、加密密钥等关键配置无法热更新 - **版本兼容性**：需要考虑客户端与服务器的版本兼容性 - **数据一致性**：热更新可能导致数据不一致问题 ### 配置同步机制 ```mermaid flowchart TD Start([开始配置同步]) --> CheckClient{"检查客户端类型"} CheckClient --> |微信客户端| LoadCloud["加载云端配置"] CheckClient --> |本地调试| LoadLocal["加载本地配置"] LoadCloud --> CloudSuccess{"云端加载成功?"} CloudSuccess --> |是| OverrideLocal["覆盖本地配置"] CloudSuccess --> |否| UseLocal["使用本地配置"] LoadLocal --> OverrideLocal OverrideLocal --> UpdateSMC["更新SingletonModule"] UseLocal --> UpdateSMC UpdateSMC --> NotifyChange["通知配置变更"] NotifyChange --> End([同步完成]) ``` **图表来源** - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L105-L150) - [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L80-L120) **章节来源** - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L105-L150) - [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L80-L120) ## 最佳实践指南 ### 敏感信息保护 #### 加密存储策略 1. **本地数据加密**：使用AES加密算法保护敏感数据 2. **密钥管理**：定期轮换加密密钥 3. **传输安全**：HTTPS协议确保数据传输安全 #### 配置文件保护 1. **权限控制**：限制配置文件的读写权限 2. **备份策略**：定期备份配置文件 3. **审计日志**：记录配置变更操作 ### 多环境配置管理 #### 开发环境配置 ```json { "config": { "httpServer": "http://localhost:3000/", "httpTimeout": 5000, "frameRate": 60 } } ``` #### 生产环境配置 ```json { "config": { "httpServer": "https://api.game.com/", "httpTimeout": 10000, "frameRate": 60 } } ``` #### 测试环境配置 ```json { "config": { "httpServer": "http://test.api.com/", "httpTimeout": 8000, "frameRate": 30 } } ``` ### 配置校验机制 #### 配置验证规则 1. **必填字段检查**：确保关键配置字段存在 2. **数据类型验证**：验证配置值的数据类型正确性 3. **范围约束检查**：确保数值在合理范围内 4. **格式规范验证**：验证URL、邮箱等格式 #### 错误处理策略 1. **默认值回退**：配置错误时使用默认值 2. **警告日志记录**：记录配置错误但不影响系统运行 3. **优雅降级**：部分配置错误时系统仍可运行 ### 性能优化建议 #### 配置加载优化 1. **延迟加载**：非关键配置采用延迟加载 2. **缓存策略**：合理使用内存缓存 3. **压缩传输**：减少配置文件大小 #### 内存管理 1. **及时释放**：不再使用的配置及时释放 2. **弱引用**：避免循环引用导致内存泄漏 3. **监控告警**：监控配置相关的内存使用 **章节来源** - [config.json](file://assets/resources/config.json#L1-L21) - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L105-L150) ## 故障排除 ### 常见配置问题 #### 配置文件加载失败 **症状**：游戏启动时配置加载异常 **原因**： - config.json文件缺失或损坏 - 文件编码格式不正确 - 文件路径配置错误 **解决方案**： 1. 检查config.json文件是否存在且完整 2. 验证JSON格式的正确性 3. 确认文件编码为UTF-8 #### 语言切换失效 **症状**：语言切换后界面文字未更新 **原因**： - 语言包文件缺失 - 语言资源路径配置错误 - 缓存未清除 **解决方案**： 1. 检查语言包文件完整性 2. 验证语言路径配置 3. 清除语言缓存重新加载 #### 网络配置异常 **症状**：游戏无法连接服务器 **原因**： - HTTP服务器地址配置错误 - 网络连接超时 - 防火墙阻止连接 **解决方案**： 1. 验证服务器地址配置 2. 检查网络连接状态 3. 调整超时时间设置 ### 调试技巧 #### 配置日志记录 ```typescript // 启用配置调试日志 oops.log.logConfig("配置加载完成: %o", configData); ``` #### 配置验证工具 ```typescript // 配置完整性检查 function validateConfig(config: any): boolean { const requiredFields = ['version', 'package', 'httpServer']; return requiredFields.every(field => config[field] !== undefined); } ``` **章节来源** - [Initialize.ts](file://assets/script/game/initialize/Initialize.ts#L40-L50) - [SingletonModuleComp.ts](file://assets/script/game/common/SingletonModuleComp.ts#L180-L195) ## 总结 本项目构建了一个完整而灵活的配置管理系统，具有以下特点： ### 核心优势 1. **集中化管理**：以config.json为核心，统一管理所有配置信息 2. **模块化设计**：清晰的职责分离，便于维护和扩展 3. **框架集成**：与Oops Framework深度集成，提供丰富的配置功能 4. **多语言支持**：完整的国际化解决方案 5. **热更新能力**：支持运行时配置更新 ### 技术亮点 - **单例模式**：确保配置的全局唯一性和一致性 - **异步加载**：优化游戏启动性能 - **加密保护**：保障用户数据安全 - **事件驱动**：支持配置变更的通知机制 ### 应用价值 该配置管理系统为游戏开发提供了稳定可靠的基础设施，支持快速迭代和多平台部署，是现代游戏开发中不可或缺的重要组成部分。通过合理的配置管理，可以显著提高开发效率，降低维护成本，为玩家提供更好的游戏体验。