# game-box **Repository Path**: pancoJ/game-box ## Basic Information - **Project Name**: game-box - **Description**: 游戏启动器 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-23 - **Last Updated**: 2026-07-25 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # GameBox > Local-first, cross-platform game library manager. > 对标 Playnite 的开源替代方案,基于 Tauri 2 + Rust + React。 一个本地优先、跨平台 (Win/Mac/Linux) 的游戏库管理器。统一管理本地游戏、Steam/Epic/GOG 平台、模拟器 ROM,带零 key 元数据爬取、游玩时长统计、标签和启动器。 ## ✨ 特色 - **本地优先** — 所有数据存在你电脑上的 SQLite,不上云 - **零 key 元数据** — Steam Store API + IGDB 网页爬 + Wikipedia 兜底, 装上就能搜 - **完整元数据设置面板** — 8 种语言切换 / 启停数据源 / 媒体缓存管理 - **跨平台** — Tauri 2 一份代码, Win / Mac / Linux 通吃 - **模拟器整合** — ROM 自动扫描 + 一键启动 - **游玩追踪** — 自动计时 + 统计 + 最近游玩 - **onboarding 向导** — 添加游戏时实时搜候选, 选一个自动带元数据 - **插件就位** — Manifest 规范 + 沙箱边界已定义, 后续可扩展 ## 🏗️ 架构 ``` gamebox/ ├── src-tauri/ # Rust 后端 │ ├── src/ │ │ ├── lib.rs # Tauri Builder 入口 │ │ ├── main.rs │ │ ├── error.rs # 统一错误类型 (Serialize 到前端) │ │ ├── config.rs # 配置 + 路径解析 + MetadataLanguage enum │ │ ├── log_init.rs # tracing 初始化 │ │ ├── state.rs # AppState (全局) │ │ ├── db/ │ │ │ ├── mod.rs # SQLite 连接池 (r2d2) │ │ │ ├── migrations.rs # 迁移管理 │ │ │ └── migrations/ # 嵌入式 SQL (2 个) │ │ ├── models/ # 数据模型 (8 个) │ │ ├── commands/ # Tauri IPC commands (47+ 接口) │ │ │ ├── system.rs # 系统 + 媒体缓存管理 │ │ │ ├── games.rs # 游戏 CRUD │ │ │ ├── library.rs # 库根管理 │ │ │ ├── scanner.rs # 扫描器 │ │ │ ├── launcher.rs # 启动器 + 进程追踪 │ │ │ ├── emulators.rs # 模拟器 │ │ │ ├── playtime.rs # 游玩时长统计 │ │ │ ├── tags.rs # 标签 │ │ │ └── metadata.rs # P5 元数据 (一键 + 手动) │ │ ├── scanner/ # 扫描器 (local + rom) │ │ ├── launcher/ # 启动器 + 进程追踪 │ │ ├── metadata/ # P5 元数据系统 │ │ │ ├── http_client.rs # 共享 HTTP 客户端 │ │ │ ├── steam_store.rs # Steam Store API │ │ │ ├── igdb_scrape.rs # IGDB 网页爬 │ │ │ ├── wikipedia.rs # Wikipedia REST 兜底 │ │ │ ├── cover_sources.rs # 公开 CDN 拼接 │ │ │ ├── search.rs # 多源搜索协调 │ │ │ ├── fetch.rs # 详情拉取协调 │ │ │ └── cache.rs # 媒体本地缓存 │ │ ├── platforms/ # Steam/Epic/GOG 集成接口 │ │ └── plugins/ # 插件 manifest │ ├── Cargo.toml │ ├── tauri.conf.json │ └── capabilities/ └── src/ # React 前端 ├── main.tsx ├── App.tsx # 路由 ├── components/ │ ├── ui/ # shadcn 风格基础组件 (12 个) │ ├── layout/ # 主布局 (Sidebar / Titlebar) │ ├── library/ # 媒体墙组件 │ └── metadata/ # 元数据刷新弹窗 + 候选卡 ├── pages/ # 路由页面 │ ├── library.tsx # 库主页 │ ├── game-detail.tsx # 游戏详情 (含刷新元数据) │ ├── settings.tsx # 设置 (含元数据面板) │ ├── add-game.tsx # 添加游戏 (含实时搜索) │ ├── search-metadata.tsx # 全网元数据搜索 │ └── not-found.tsx ├── stores/ # Zustand (5 个 store) ├── lib/ # API 封装 + 工具 ├── types/ # TypeScript 类型 └── styles/ # Tailwind + 全局样式 ``` ## 📊 进度 | Phase | 内容 | 状态 | |------|------|------| | **P0** | 项目骨架 / DB / 配置 / 日志 / 错误处理 | ✅ 完成 | | **P1** | 本地游戏库 / 扫描器 / 媒体墙 / 详情 / 搜索 / 启动 | ✅ 完成 | | **P2** | Steam / Epic / GOG 平台集成 | 📦 骨架完成, 主体实现待办 | | **P3** | 启动器增强 (close-on-launch, 自动结束会话) | ✅ 基础完成 | | **P4** | 模拟器 + ROM 扫描 | ✅ 基础完成 | | **P5** | IGDB / SteamGridDB 元数据爬取 (零 key) | ✅ 完成 | | **P5+** | 元数据设置面板 (语言 / 数据源 / 缓存管理) | ✅ 完成 | | **P6** | 插件系统 (manifest + sandbox) | 📦 Manifest 完成, 沙箱待办 | ## 🛠️ 开发 ```bash # 装依赖 pnpm install # 跑 dev (前端 Vite + Rust cargo 同步热重载) pnpm tauri:dev # 构建 release pnpm tauri:build # 跑后端测试 cd src-tauri && cargo test --lib ``` ### 技术栈 - **后端**: Rust 1.77+ / Tauri 2 / SQLite (rusqlite + r2d2) / tokio / reqwest / scraper / tracing - **前端**: React 19 / TypeScript 5.8 / Vite 7 / Tailwind 3 / shadcn 风格 (Radix UI) / Zustand / React Router 7 ## 🎮 用起来 ### 第一次启动 1. 启动 GameBox, 默认空库 2. 进 **设置** → 添加库根目录 (比如 `~/Games`), 点 "扫描全部" 自动入库 3. 或者点 TitleBar 右上角 ➕ → 手动添加单个游戏 ### 拉元数据 (零 key) 第三方元数据搜索**只在添加/编辑游戏时**触发, 主页搜索框只过滤本地游戏。 **方式 A: 添加游戏时** 1. TitleBar ➕ → /add 2. 输游戏名 → 候选实时出现 (debounce 600ms) 3. 选一个 → 自动填标题/开发商/发行商/发行日期 4. 折叠"启动信息"补路径 → 保存 5. 自动 apply 元数据, 跳详情直接看到完整数据 **方式 B: 给已有游戏刷新** 1. 进任意游戏详情页 2. 点 "刷新元数据" 按钮 (操作栏里) 3. 弹窗自动用游戏名搜, 左边候选列表, 右边实时预览 4. 选个候选, 点 "应用", 几秒后封面/描述/评分都到位 **主页搜索框**: 只过滤**已入库**的游戏 (标题 / 开发商 / 类型), 不会调第三方 API, 离线也能用。 ### 元数据设置面板 **设置 → 元数据** 卡片里可以调整: 1. **元数据语言** — 8 种 (简/繁/英/日/韩/法/德/俄), 默认 schinese 2. **数据源开关** — 3 个独立开关 (Steam / IGDB / Wikipedia), 关闭后搜索就不调它 3. **媒体缓存管理**: - 总大小 + 文件数 - 按游戏列出每个占多少 (按大小降序, 关联游戏名) - 单个清空 / 一键清空全部 - 列表里有修改时间 所有设置实时写入 `config.json`, 下次搜索/拉详情立即生效。 ### 元数据来源 (按优先级) 1. **Steam Store** — 公开 API, 中文英文都支持, 拿得到就用 2. **IGDB 网页爬** — 爬 IGDB 官网搜索结果 (无 key) 3. **Wikipedia** — 简介兜底 (无 key) 所有封面都从公开 CDN 拼 URL (Steam cdn / IGDB image CDN), 不需要任何 key。 ## 📦 数据目录 应用首次运行会在系统标准位置创建配置目录: - **macOS**: `~/Library/Application Support/com.gamebox.app/` - **Linux**: `~/.config/com.gamebox.app/` - **Windows**: `%APPDATA%\com.gamebox.app\` ``` com.gamebox.app/ ├── config.json # 全局配置 (主题 / 语言 / 元数据设置 / ...) ├── gamebox.db # SQLite 数据库 ├── gamebox.db-wal # WAL 日志 ├── logs/ │ └── gamebox.log.YYYY-MM-DD # 滚动日志 └── cache/ └── media/ # 媒体缓存 (元数据拉取的封面/背景/图标) └── / ├── cover.jpg ├── background.jpg └── icon.jpg ``` ## 🔌 已实现的 Tauri Commands (47+)
系统 (6 个) - `get_app_version` / `get_config` / `update_config` - `open_path` / `show_in_folder` / `get_disk_usage` / `get_diagnostics` - `get_media_cache_detail` / `clear_media_cache`
游戏 (P1, 8 个) - `list_games` (filter + 排序 + 分页) / `get_game` / `add_game` / `update_game` / `delete_game` - `toggle_favorite` / `toggle_hidden` / `get_game_count`
库根 (4 个) - `list_library_roots` / `add_library_root` / `update_library_root` / `remove_library_root`
扫描器 (4 个) - `scan_library_root` / `scan_all` / `cancel_scan` / `get_scan_progress` - `scan_roms`
启动器 (3 个) - `launch_game` / `is_game_running` / `stop_game` - 自动追踪进程 → 关闭后回写游玩时长
模拟器 (5 个) - `list_emulators` / `add_emulator` / `update_emulator` / `remove_emulator` / `scan_roms`
游玩时长 (2 个) - `list_recent_sessions` / `get_playtime_summary` (按天汇总)
标签 (5 个) - `list_tags` / `create_tag` / `delete_tag` / `attach_tag` / `detach_tag`
元数据 (P5, 5 个) - `search_metadata_cmd` — 多源搜索 (Steam + IGDB), 去重排序 - `fetch_metadata_detail_cmd` — 拉单个候选项完整元数据 - `fetch_metadata_for_game` — **一键模式**: 搜索 + 选最优 + 拉详情 + 应用 - `apply_metadata_to_game` — 手动应用元数据 (从搜索结果) - `list_metadata_jobs` — 任务历史
## 🗺️ 后续工作 (TODO) ### P2 平台集成 - [ ] Steam: 解析 `libraryfolders.vdf` + `appmanifest_*.acf` - [ ] Steam: 拉已安装游戏元数据 (复用 P5 的 steam_store) - [ ] Epic: 解析 `Manifests/*.item` + 启动器配置 - [ ] GOG: 解析 Galaxy 库 ### P5 元数据增强 - [ ] SteamGridDB 官方 API (需要 key, 留接口) - [ ] IGDB 官方 API (Twitch OAuth, 留接口) - [ ] RAWG 公共搜索 (留接口) - [ ] 截图批量下载 (目前只下封面/背景/图标) - [ ] 元数据任务队列 (后台调度, 失败重试) ### P6 插件系统 - [ ] 沙箱执行 (wasmtime / Lua) - [ ] 扩展点实现 (game-source / view / theme) - [ ] 插件市场和签名 ### 体验增强 - [ ] 首启动引导 (onboarding wizard, 加库根 → 扫描 → 拉元数据) - [ ] 主题市场 - [ ] 自动更新 - [ ] 多语言 (i18n) - [ ] 启动游戏时最小化/关闭 (minimize_on_launch / close_on_launch 已存 config, UI 补上) - [ ] 成就支持 (复用 Steamworks) ## 📝 License TBD — 计划 MIT, 暂未选。