https://github.com/706412584/gameutil
功能强大的Android游戏存档管理SDK | 支持AES加密、反作弊、JSON导入、异步操作、性能监控 | JitPack发布
https://github.com/706412584/gameutil
android android-library anti-cheat async encryption game-development game-save josn library performance save-manager sdk
Last synced: 3 months ago
JSON representation
功能强大的Android游戏存档管理SDK | 支持AES加密、反作弊、JSON导入、异步操作、性能监控 | JitPack发布
- Host: GitHub
- URL: https://github.com/706412584/gameutil
- Owner: 706412584
- Created: 2025-10-23T11:38:35.000Z (8 months ago)
- Default Branch: master
- Last Pushed: 2025-11-25T14:56:02.000Z (7 months ago)
- Last Synced: 2025-11-28T14:50:16.279Z (6 months ago)
- Topics: android, android-library, anti-cheat, async, encryption, game-development, game-save, josn, library, performance, save-manager, sdk
- Language: Java
- Homepage: https://jitpack.io/#706412584/GameUtil
- Size: 3.46 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 游戏存档工具 (GameUtil)
[](https://jitpack.io/#706412584/GameUtil)
[](LICENSE)
[](https://developer.android.com)
[](https://android-arsenal.com/api?level=23)
一个基于Json架构开发、功能强大、高性能的Android游戏存档管理SDK，支持JSON导入/导出、自动分表、异步操作、性能监控等特性。
> 🎉 **现已发布到 JitPack！** 支持远程依赖导入，无需下载源码即可使用。
## 主要特性
### 🎯 核心功能
- ✅ **AES-GCM加密** - 军事级加密算法保护存档安全
- ✅ **反作弊系统** - 设备ID验证、完整性校验、时间戳验证
- ✅ **主表分表支持** - 灵活的数据分片存储
- ✅ **线程安全** - 完全的并发安全保障
### 🚀 性能优化
- ✅ **LRU缓存** - 智能缓存机制，读取性能提升30倍
- ✅ **异步保存** - 不阻塞主线程，批量操作提升5倍性能
- ✅ **数据压缩** - GZIP压缩，节省75%存储空间
- ✅ **性能监控** - 实时统计操作耗时、吞吐量、错误率
### 📦 JSON操作
- ✅ **完整JSON导入** - 一键导入游戏存档JSON
- ✅ **自动分表** - 支持前缀、大小、自定义多种分表策略
- ✅ **批量操作** - 批量导入/导出，高效处理海量数据
- ✅ **格式验证** - 自动验证JSON格式和数据完整性
---
## 快速开始
### 1. 添加依赖
#### 方式一：使用 JitPack 远程依赖（推荐）
[](https://jitpack.io/#706412584/GameUtil)
**步骤1：** 在项目的 `settings.gradle` 中添加 JitPack 仓库：
```gradle
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven { url 'https://jitpack.io' } // 添加 JitPack 仓库
}
}
```
**步骤2：** 在 `app/build.gradle` 中添加依赖：
```gradle
dependencies {
// 存档管理库
implementation 'com.github.706412584.GameUtil:savelibrary:v2.1.5'
// 反作弊库
implementation 'com.github.706412584.GameUtil:anticheat:v2.1.5'
}
```
> ⚠️ **注意**：模块名必须小写（`savelibrary` 和 `anticheat`）
#### 方式二：本地项目依赖
如果您克隆了本项目，可以直接依赖本地模块：
```gradle
dependencies {
implementation project(':Savelibrary')
implementation project(':AntiCheat')
}
```
### 2. 基础使用
```java
// 初始化存档管理器
File saveDir = new File(context.getFilesDir(), "saves");
GameSaveManager manager = new GameSaveManager(saveDir);
// 启用性能优化
manager.setPerformanceMonitorEnabled(true);
manager.setCompressionEnabled(true);
// 保存存档
SaveData saveData = new SaveData("save001");
saveData.set("player_name", "玩家1");
saveData.set("level", 10);
manager.saveSave(saveData);
// 读取存档
SaveData loaded = manager.loadSave("save001");
```
### 3. JSON导入
```java
// 准备JSON数据
String jsonStr = "{"
+ "\"player_name\": \"张三\","
+ "\"level\": 10,"
+ "\"inventory_weapon\": \"sword\","
+ "\"quest_main\": \"救公主\""
+ "}";
// 定义分表策略
Map prefixMapping = new HashMap<>();
prefixMapping.put("inventory_", "inventory");
prefixMapping.put("quest_", "quest");
// 导入并自动分表
JsonImportUtil.ImportResult result = manager.importFromJsonWithPrefix(
"save001",
jsonStr,
prefixMapping
);
```
---
## 核心模块
### 1. GameSaveManager
主要的存档管理器，提供存档的增删改查、JSON导入导出等功能。
```java
GameSaveManager manager = new GameSaveManager(saveDir);
// 同步操作
manager.saveSave(saveData);
manager.loadSave("save001");
// 异步操作
manager.saveAsync(saveData, callback);
manager.batchLoadAsync(saveIds);
// JSON导入
manager.importFromJson("save001", jsonStr);
```
### 2. JsonImportUtil
JSON导入导出工具，支持多种分表策略。
```java
// 前缀策略
PrefixBasedStrategy prefixStrategy = new PrefixBasedStrategy();
prefixStrategy.addMapping("inventory_", "inventory");
// 大小策略
SizeBasedStrategy sizeStrategy = new SizeBasedStrategy(10240); // 10KB
// 组合策略
CompositeStrategy compositeStrategy = new CompositeStrategy();
compositeStrategy.addStrategy(prefixStrategy);
compositeStrategy.addStrategy(sizeStrategy);
```
### 3. AsyncSaveManager
异步存档管理器，提供高性能的异步操作。
```java
// 异步保存
asyncManager.saveAsync(saveData, new SaveCallback() {
@Override
public void onSuccess(String saveId) {
// 保存成功
}
@Override
public void onFailure(String saveId, Exception error) {
// 保存失败
}
});
// 批量操作
BatchResult result = asyncManager.batchSave(saveDataList);
```
### 4. PerformanceMonitor
性能监控器，实时统计系统性能指标。
```java
// 启用监控
manager.setPerformanceMonitorEnabled(true);
// 查看统计
System.out.println(manager.getPerformanceReport());
System.out.println(manager.getCacheStats());
System.out.println(manager.getSystemStats());
```
### 5. LruCache
LRU缓存实现，提升读取性能。
```java
LruCache cache = new LruCache<>(50);
cache.put("key", "value");
String value = cache.get("key");
// 统计信息
System.out.println(cache.getStats());
System.out.println("命中率: " + cache.getHitRate());
```
---
## 性能对比
### 读取性能
| 操作 | 无缓存 | LRU缓存 | 提升 |
|-----|-------|---------|------|
| 首次读取 | 15ms | 15ms | - |
| 二次读取 | 15ms | 0.5ms | **30倍** |
| 缓存命中率 | 0% | 80%+ | - |
### 保存性能
| 操作 | 同步 | 异步 | 提升 |
|-----|-----|------|------|
| 单次保存 | 阻塞15ms | 不阻塞 | **无感知** |
| 批量100个 | 阻塞1.5s | 300ms | **5倍** |
### 存储空间
| 数据类型 | 原始 | 压缩后 | 压缩率 |
|---------|-----|--------|-------|
| JSON文本 | 100KB | 25KB | **75%** |
| 重复数据 | 500KB | 80KB | **84%** |
---
## 架构设计
```
GameUtil
├── Savelibrary # 存档管理库
│ ├── GameSaveManager # 主管理器
│ │ ├── SaveData # 存档数据模型
│ │ ├── SaveTableManager # 分表管理（含LRU缓存）
│ │ └── AntiCheatManager # 反作弊管理
│ │
│ ├── AsyncSaveManager # 异步操作管理
│ │ ├── 线程池
│ │ ├── 任务队列
│ │ └── 批量操作
│ │
│ ├── JsonImportUtil # JSON导入工具
│ │ ├── PrefixBasedStrategy # 前缀分表策略
│ │ ├── SizeBasedStrategy # 大小分表策略
│ │ └── CompositeStrategy # 组合策略
│ │
│ ├── PerformanceMonitor # 性能监控
│ │ ├── 操作统计
│ │ ├── 吞吐量计算
│ │ └── 错误率统计
│ │
│ └── Utilities
│ ├── AESUtils # AES加密工具
│ ├── LruCache # LRU缓存
│ └── CompressionUtil # 压缩工具
│
└── AntiCheat # 反作弊模块 🆕
├── SecurityDetector # 安全检测器
├── RootDetector # Root检测
├── EmulatorDetector # 模拟器检测
├── HookDetector # Hook框架检测
├── DebugDetector # 调试器检测
├── SignatureValidator # 签名验证
├── ProxyDetector # 代理检测
├── MultiInstanceDetector # 多开检测
├── MemoryHackDetector # 内存修改器检测
└── TimeCheatDetector # 时间作弊检测
```
---
## 使用场景
### 场景1：小型独立游戏
```java
// 简单配置，不分表
GameSaveManager manager = new GameSaveManager(saveDir);
manager.saveSave(saveData);
```
### 场景2：中型RPG游戏
```java
// 启用分表和缓存
GameSaveManager manager = new GameSaveManager(saveDir);
manager.setPerformanceMonitorEnabled(true);
// 按模块分表
Map prefixMapping = new HashMap<>();
prefixMapping.put("inventory_", "inventory");
prefixMapping.put("quest_", "quest");
prefixMapping.put("skill_", "skill");
```
### 场景3：大型在线游戏
```java
// 完整配置
GameSaveManager manager = new GameSaveManager(saveDir);
manager.setPerformanceMonitorEnabled(true);
manager.setCompressionEnabled(true);
// 组合策略：前缀+大小
CompositeStrategy strategy = new CompositeStrategy();
strategy.addStrategy(new PrefixBasedStrategy(prefixMapping));
strategy.addStrategy(new SizeBasedStrategy(10240));
// 异步批量操作
manager.batchSaveAsync(saveDataList);
```
---
## 最佳实践
### 1. 性能优化
- ✅ 开发阶段启用性能监控
- ✅ 大存档（>10KB）启用压缩
- ✅ 使用异步保存避免卡顿
- ✅ 批量操作提升效率
### 2. 分表策略
- 小型游戏（<100KB）：不分表
- 中型游戏（100KB-1MB）：按模块分表
- 大型游戏（>1MB）：组合策略
### 3. 资源管理
```java
// 应用退出时释放资源
@Override
protected void onDestroy() {
super.onDestroy();
manager.shutdown();
}
```
---
## 模块文档
### 存档管理库
详细使用指南请查看 [Savelibrary 使用指南](Savelibrary/README.md)
### 反作弊模块 🆕
一个强大的应用安全检测库，支持10种常见破解和作弊检测：
- ✅ **Root检测** - 检测设备Root状态
- ✅ **模拟器检测** - 检测各类Android模拟器
- ✅ **Hook框架检测** - 检测Xposed、Frida等
- ✅ **调试器检测** - 检测调试器连接
- ✅ **签名验证** - 防止应用被篡改
- ✅ **代理检测** - 检测网络代理设置
- ✅ **多开检测** - 检测虚拟环境和多开
- ✅ **内存修改器检测** - 检测GameGuardian等
- ✅ **时间作弊检测** - 检测系统时间修改
- ✅ **VPN检测** - 检测VPN连接
**快速使用：**
```java
// 创建安全检测器
SecurityDetector detector = new SecurityDetector(context,
new SecurityDetector.SecurityCallback() {
@Override
public void onThreatDetected(String type, String desc, int level) {
Log.w("Security", type + ": " + desc);
}
@Override
public void onDetectionComplete(boolean passed,
List threats) {
if (!passed) {
// 处理安全威胁
handleThreats(threats);
}
}
});
// 执行检测
detector.performSecurityCheck();
// 获取安全分数 (0-100)
int score = detector.getSecurityScore();
```
详细使用指南请查看 [AntiCheat 使用指南](AntiCheat/使用指南.md)
---
## 技术栈
- **语言**: Java 11
- **最低SDK**: Android API 23 (Android 6.0)
- **加密**: AES-GCM-256
- **压缩**: GZIP
- **线程**: ExecutorService + ReadWriteLock
---
## 许可证
本项目仅供学习和研究使用。
---
## 更新日志
### v2.1 (2025-10-23)
- 🆕 **新增反作弊模块**
- ✅ Root检测
- ✅ 模拟器检测
- ✅ Hook框架检测（Xposed、Frida、Substrate）
- ✅ 调试器检测
- ✅ 签名验证
- ✅ 代理检测
- ✅ 多开检测
- ✅ 内存修改器检测
- ✅ 时间作弊检测
- ✅ 安全分数评估系统
### v2.0 (2025-10-23)
- ✅ 添加JSON导入导出功能
- ✅ 添加LRU缓存机制
- ✅ 添加异步保存功能
- ✅ 添加数据压缩功能
- ✅ 添加性能监控功能
- ✅ 支持自动分表策略
### v1.0
- ✅ 基础存档管理
- ✅ AES加密
- ✅ 反作弊系统
- ✅ 主表分表支持
---
## 🚀 发布说明
### JitPack 仓库
本项目已发布到 JitPack，可以通过远程依赖方式使用：
- **仓库主页**: https://jitpack.io/#706412584/GameUtil
- **最新版本**: `v2.1.2`
### 依赖引用
```gradle
// 存档管理库（包含所有存档管理功能）
implementation 'com.github.706412584.GameUtil:savelibrary:v2.1.2'
// 反作弊库（包含所有安全检测功能）
implementation 'com.github.706412584.GameUtil:anticheat:v2.1.2'
```
### 版本选择
| 版本 | 说明 |
|------|------|
| `v2.1.2` | 最新稳定版（推荐） |
| `latest.release` | 始终指向最新发布版本 |
| `master-SNAPSHOT` | 最新开发版本（不推荐生产环境） |
---
## 联系方式
如有问题或建议，欢迎提出Issue。