16 KiB
16 KiB
配置管理
**本文档引用的文件** - [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)目录
简介
本项目采用了一套完整的全局配置管理体系，以config.json为核心配置文件，配合Oops Framework提供的配置管理机制，实现了灵活、可扩展的配置解决方案。该系统支持版本控制、多语言国际化、加密存储、网络通信等关键功能，为游戏提供了稳定可靠的配置基础设施。
项目结构
配置管理系统的核心文件组织结构如下：
graph TB
subgraph "配置文件层"
ConfigJSON["config.json<br/>核心配置文件"]
LangJSON["language/*.json<br/>多语言资源"]
UIConfig["GameUIConfig.ts<br/>界面配置"]
end
subgraph "初始化层"
MainTS["Main.ts<br/>应用入口"]
InitTS["Initialize.ts<br/>初始化模块"]
SMCTS["SingletonModuleComp.ts<br/>单例组件"]
end
subgraph "框架层"
OopsFramework["Oops Framework<br/>配置管理框架"]
Storage["Storage Module<br/>本地存储"]
Language["Language Module<br/>多语言模块"]
end
ConfigJSON --> InitTS
InitTS --> SMCTS
SMCTS --> OopsFramework
OopsFramework --> Storage
OopsFramework --> Language
图表来源
章节来源
核心配置文件
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：固定帧率设置，确保游戏性能一致性
章节来源
配置系统架构
整体架构设计
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 : "调用服务"
图表来源
配置注入机制
配置系统通过以下机制实现全局访问：
- 单例模式：通过
ecs.getSingleton()获取全局配置实例 - 依赖注入：Initialize模块负责配置的初始化和注入
- 框架集成：Oops Framework提供统一的配置访问接口
章节来源
配置加载生命周期
启动流程分析
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 : 初始化完成
图表来源
生命周期阶段详解
1. 应用启动阶段
- Main.ts作为应用入口点，负责初始化Oops Framework
- 创建Initialize实体并注入到系统中
2. 配置加载阶段
- Initialize模块按顺序执行配置加载任务
- 包括自定义内容、语言包、公共资源的加载
3. 配置注入阶段
- 将加载的配置数据注入到Oops Framework中
- 通过SingletonModuleComp实现全局访问
4. 系统初始化阶段
- 完成所有配置相关的工作后，系统进入正常运行状态
章节来源
配置管理模式
SingletonModuleComp 实现
SingletonModuleComp是配置管理的核心组件，实现了全局配置的统一管理：
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"
图表来源
全局访问模式
配置系统采用以下模式实现全局访问：
- 静态实例模式：通过
smc变量提供全局访问点 - MVVM绑定：使用ViewModel实现数据双向绑定
- 事件驱动：通过GameEvent系统通知配置变更
章节来源
多语言配置体系
语言配置结构
graph LR
subgraph "语言配置"
LangType["语言类型列表<br/>['zh', 'en']"]
LangPath["语言路径映射<br/>json: 'language/json'<br/>texture: 'language/texture'"]
end
subgraph "资源文件"
ZhJSON["zh.json<br/>中文语言包"]
EnJSON["en.json<br/>英文语言包"]
FontFiles["字体文件<br/>language/font/"]
end
LangType --> ZhJSON
LangType --> EnJSON
LangPath --> ZhJSON
LangPath --> EnJSON
LangPath --> FontFiles
图表来源
多语言加载流程
- 语言检测：从本地存储获取用户语言偏好
- 默认设置：未设置时默认使用中文(zh)
- 资源加载：加载对应语言的JSON和字体资源
- 动态切换：支持运行时语言切换
章节来源
配置热更新机制
热更新可行性分析
基于现有架构，配置系统支持以下热更新特性：
支持的热更新场景
- 语言包更新：无需重启即可切换语言
- 界面配置更新：动态调整UI布局和样式
- 游戏参数调整：实时修改游戏平衡性参数
热更新限制
- 核心配置限制：HTTP服务器地址、加密密钥等关键配置无法热更新
- 版本兼容性：需要考虑客户端与服务器的版本兼容性
- 数据一致性：热更新可能导致数据不一致问题
配置同步机制
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([同步完成])
图表来源
章节来源
最佳实践指南
敏感信息保护
加密存储策略
- 本地数据加密：使用AES加密算法保护敏感数据
- 密钥管理：定期轮换加密密钥
- 传输安全：HTTPS协议确保数据传输安全
配置文件保护
- 权限控制：限制配置文件的读写权限
- 备份策略：定期备份配置文件
- 审计日志：记录配置变更操作
多环境配置管理
开发环境配置
{
"config": {
"httpServer": "http://localhost:3000/",
"httpTimeout": 5000,
"frameRate": 60
}
}
生产环境配置
{
"config": {
"httpServer": "https://api.game.com/",
"httpTimeout": 10000,
"frameRate": 60
}
}
测试环境配置
{
"config": {
"httpServer": "http://test.api.com/",
"httpTimeout": 8000,
"frameRate": 30
}
}
配置校验机制
配置验证规则
- 必填字段检查：确保关键配置字段存在
- 数据类型验证：验证配置值的数据类型正确性
- 范围约束检查：确保数值在合理范围内
- 格式规范验证：验证URL、邮箱等格式
错误处理策略
- 默认值回退：配置错误时使用默认值
- 警告日志记录：记录配置错误但不影响系统运行
- 优雅降级：部分配置错误时系统仍可运行
性能优化建议
配置加载优化
- 延迟加载：非关键配置采用延迟加载
- 缓存策略：合理使用内存缓存
- 压缩传输：减少配置文件大小
内存管理
- 及时释放：不再使用的配置及时释放
- 弱引用：避免循环引用导致内存泄漏
- 监控告警：监控配置相关的内存使用
章节来源
故障排除
常见配置问题
配置文件加载失败
症状：游戏启动时配置加载异常 原因：
- config.json文件缺失或损坏
- 文件编码格式不正确
- 文件路径配置错误
解决方案：
- 检查config.json文件是否存在且完整
- 验证JSON格式的正确性
- 确认文件编码为UTF-8
语言切换失效
症状：语言切换后界面文字未更新 原因：
- 语言包文件缺失
- 语言资源路径配置错误
- 缓存未清除
解决方案：
- 检查语言包文件完整性
- 验证语言路径配置
- 清除语言缓存重新加载
网络配置异常
症状：游戏无法连接服务器 原因：
- HTTP服务器地址配置错误
- 网络连接超时
- 防火墙阻止连接
解决方案：
- 验证服务器地址配置
- 检查网络连接状态
- 调整超时时间设置
调试技巧
配置日志记录
// 启用配置调试日志
oops.log.logConfig("配置加载完成: %o", configData);
配置验证工具
// 配置完整性检查
function validateConfig(config: any): boolean {
const requiredFields = ['version', 'package', 'httpServer'];
return requiredFields.every(field => config[field] !== undefined);
}
章节来源
总结
本项目构建了一个完整而灵活的配置管理系统，具有以下特点：
核心优势
- 集中化管理：以config.json为核心，统一管理所有配置信息
- 模块化设计：清晰的职责分离，便于维护和扩展
- 框架集成：与Oops Framework深度集成，提供丰富的配置功能
- 多语言支持：完整的国际化解决方案
- 热更新能力：支持运行时配置更新
技术亮点
- 单例模式：确保配置的全局唯一性和一致性
- 异步加载：优化游戏启动性能
- 加密保护：保障用户数据安全
- 事件驱动：支持配置变更的通知机制
应用价值
该配置管理系统为游戏开发提供了稳定可靠的基础设施，支持快速迭代和多平台部署，是现代游戏开发中不可或缺的重要组成部分。通过合理的配置管理，可以显著提高开发效率，降低维护成本，为玩家提供更好的游戏体验。