# YukiHub 使用教程说明 本教程适用于首次使用 YukiHub 的用户，内容结合项目 README 中的说明，并补充常见使用流程。 YukiHub 是一款面向 Android 平台的 Galgame / 视觉小说管理与启动工具，可用于管理本地游戏、安卓应用型游戏、模拟器游戏入口、外部程序快捷方式以及游玩记录。 > 请确保你仅使用 YukiHub 管理和启动你有权使用的游戏、应用或资源。项目不提供游戏本体、破解资源或绕过授权的能力。 --- ## 1. 安装与首次启动 ### 1.1 系统要求 - Android 8.0 及以上 - 横屏体验更佳 - 部分功能需要文件访问权限、全盘文件访问权限或网络权限 ### 1.2 安装方式 #### 方法一：直接安装 APK 从项目 Releases 页面下载 APK 并安装。 如果 GitHub Releases 暂时不可用，可关注作者同步发布的 GitCode 页面。 #### 方法二：自行编译 如果你需要自行编译，请准备： - Android Studio - Android SDK - Gradle 环境 然后打开项目自行构建。 ### 1.3 首次进入 首次启动时，应用会显示免责声明。你需要阅读并勾选同意后才能进入主界面。 --- ## 2. 权限说明 YukiHub 可能请求以下权限： - 文件读写权限：用于读取和管理游戏目录、封面、启动文件和配置文件 - 全盘文件访问权限：用于部分目录型游戏管理场景 - 网络权限：用于更新检测、资料查询、WebDAV 同步等功能 建议在理解权限用途后再授予。若未授予相关权限，部分游戏扫描、封面读取或同步功能可能无法正常使用。 --- ## 3. 主界面基本概念 YukiHub 更偏向一个本地游戏管理中心，而不是单纯的启动器。 你可以用它管理： - 本地 Galgame / 视觉小说目录 - 安卓应用型游戏 - 模拟器游戏入口 - 外部程序快捷方式 - GameHub / 盖世类快捷方式 - Winlator 游戏入口 - 空目录条目 - 游玩记录与游玩时长 主界面通常用于浏览游戏库、进入详情、启动游戏、编辑条目和查看游玩记录。 --- ## 4. 添加游戏条目 ### 4.1 普通本地游戏 适合 KRKR、ONS、Tyrano、Artemis、PSP 等以本地目录或文件作为入口的游戏。 基本流程： 1. 在主界面点击添加游戏。 2. 填写游戏标题。 3. 选择游戏目录。 4. 选择或确认启动方式 / 引擎类型。 5. 从启动文件候选中选择入口文件。 6. 保存条目。 7. 回到游戏库后点击条目启动。 常见启动文件示例： - KRKR / Kirikiri：`data.xp3`、`startup.tjs` 等 - Tyrano：`index.html`、`index.htm` 等 - ONS：`nscript.dat`、`0.txt`、`00.txt`、`nsa`、`sar` 等相关文件 - PSP：`iso`、`cso`、`chd`、`elf`、`pbp` 等 实际可用入口取决于游戏结构和当前版本支持情况。 ### 4.2 使用内置文件选择器选择目录 YukiHub 内置文件选择器可用于选择游戏目录。 建议操作： 1. 进入添加或编辑游戏页面。 2. 点击选择目录。 3. 在内置文件选择器中定位到游戏根目录。 4. 确认选择。 5. 检查启动文件候选列表是否出现正确入口。 如果候选列表为空，请确认： - 选择的是游戏根目录，而不是上一级合集目录 - 目录中确实存在启动文件 - 文件扩展名受当前引擎支持 - 应用拥有读取该目录的权限 ### 4.3 空目录条目 YukiHub 支持不填写游戏目录的条目，适合： - 直接启动安卓应用 - 使用包名启动的条目 - 外部程序入口 - 自定义快捷启动项 - 仅用于记录游玩状态或资料管理的游戏 添加时可不绑定实际本地目录，后续同步恢复时会优先按标题等信息进行匹配。 --- ## 5. 游戏扫描与导入 如果你已经有整理好的游戏目录，可以使用扫描功能批量导入。 建议目录结构： ```text Games/ ├── Game A/ │ ├── data.xp3 │ └── ... ├── Game B/ │ ├── index.html │ └── ... └── Game C/ ├── nscript.dat └── ... ``` 基本流程： 1. 进入游戏扫描或导入入口。 2. 选择包含多个游戏文件夹的根目录。 3. 等待 YukiHub 扫描可识别的游戏目录。 4. 检查扫描结果。 5. 选择需要导入的项目。 6. 保存到游戏库。 如果扫描不到游戏： - 确认选择的是合集根目录或游戏根目录 - 检查文件权限 - 检查游戏目录内是否有可识别启动文件 - 尝试手动添加单个游戏条目进行验证 --- ## 6. 启动方式说明 YukiHub 支持多种启动方式，实际体验取决于设备环境、游戏结构和第三方应用兼容性。 ### 6.1 内置 KRKR / Kirikiri 适合 Kirikiri / KRKR 类游戏。 使用建议： 1. 添加游戏时选择 KRKR 相关启动方式。 2. 选择游戏根目录。 3. 选择正确启动文件。 4. 如遇存储兼容问题，可进入 KR 设置调整存档或目录相关选项。 README 中提到，旧版本曾存在 TF 卡运行 KRKR 游戏的问题，后续版本已通过镜像目录等方式进行修复。如个别设备仍异常，建议反馈设备型号、Android 版本、目录位置和复现步骤。 ### 6.2 内置 ONS 适合 ONScripter 类游戏。 导入时应选择包含脚本文件和资源文件的游戏根目录。若启动失败，请确认脚本文件和资源包是否完整。 ### 6.3 内置 Tyrano 适合 TyranoBuilder / TyranoScript 类游戏。 常见入口为： ```text index.html index.htm ``` 如果游戏目录中存在多个 HTML 文件，建议选择实际启动页。 ### 6.4 Artemis 适合对应 Artemis 引擎游戏。具体兼容性可能与游戏结构和设备环境有关。 ### 6.5 PSP / PPSSPP 适合 PSP 游戏入口管理。 常见文件类型： ```text .iso .cso .chd .elf .pbp ``` 如果使用外部 PPSSPP，需要确保设备已安装兼容的 PPSSPP 应用。 ### 6.6 Winlator 与盖世 / GameHub 直启动 README 中提供了 Winlator 和盖世游戏直启动的视频教程： - Bilibili 教程：https://b23.tv/Qixj22k 说明： - Winlator 改包直启基于 hostei2 大佬改版，将 `XServerDisplayActivity` 对外公开。 - 盖世游戏直启基于原版 5.3.5 进行 MT 文件提取器注入及活动公开处理，将 `com.xj.landscape.launcher.ui.gamedetail.GameDetailActivity` 设置为可导出。 这类功能依赖第三方应用包名、Activity 暴露状态和版本兼容性。如果直启失败，请先确认第三方应用版本和入口配置。 --- ## 7. GameHub 快捷方式导入 YukiHub 支持 GameHub 快捷方式导入，并提供： - 快捷方式图标显示 - 搜索筛选 - 列表选择 - 条目同步时的 ID 匹配 基本流程： 1. 进入 GameHub 快捷方式导入入口。 2. 等待应用读取快捷方式列表。 3. 使用搜索筛选目标游戏。 4. 选择需要导入的条目。 5. 保存到 YukiHub 游戏库。 同步恢复时，YukiHub 会尽量根据 GameHub 本地 ID、root 路径、本地 ID 和游戏标题进行匹配。 --- ## 8. 游戏资料查询 YukiHub 集成了多个资料源，可用于补全游戏资料信息。 README 中提到支持： - VNDB - Bangumi 项目代码中还包含月幕 Gal 等资料源相关能力，实际可用性以应用设置页展示为准。 使用建议： 1. 进入设置或资料源设置。 2. 选择资料源。 3. 如使用 Bangumi，按应用提示配置 Token 或镜像源。 4. 在游戏详情页中搜索或刷新资料。 5. 确认候选结果并保存。 如果搜索不到： - 尝试使用日文原名、英文名或别名搜索 - 检查网络连接 - 检查资料源服务是否可用 - Bangumi 相关功能请确认 Token 配置正确 --- ## 9. 游玩时长记录 YukiHub 的游玩时长记录逻辑为： 1. 从 YukiHub 点击启动某个游戏后开始计时。 2. 当你回到 YukiHub 前台时结束计时。 3. 中途应用进入后台也可以继续记录。 4. 如果游玩中途切回 YukiHub，又直接回到游戏，后半段可能不会继续计入，需要重新从 YukiHub 启动游戏。 因此，建议每次正式游玩都从 YukiHub 的游戏条目进入。 --- ## 10. 数据同步与 WebDAV 云同步 YukiHub 支持游戏数据与游玩记录的导入导出，也支持 WebDAV 云同步，适合备份和多设备迁移。 README 中提供了 WebDAV 视频教程： - Bilibili 教程：https://b23.tv/wuOvs5l ### 10.1 同步内容 同步通常包括： - 游戏条目 - 游戏目录信息 - 启动配置 - 游玩记录 - 游玩时长 - 部分匹配标识 ### 10.2 匹配逻辑 同步恢复时会尽量根据以下信息匹配： - root 路径 - 本地 ID - 游戏标题 - GameHub / 盖世本地 ID 对于空目录条目，会优先按标题进行匹配。 ### 10.3 使用建议 1. 在旧设备上导出或上传同步数据。 2. 在新设备上安装 YukiHub。 3. 配置相同 WebDAV 信息或导入备份文件。 4. 执行恢复。 5. 检查游戏目录是否仍然有效。 6. 对路径变化的游戏重新选择目录。 如果同步失败： - 检查 WebDAV 地址、账号、密码 - 检查网络连接 - 检查云端空间和权限 - 检查两台设备的目录结构是否一致 --- ## 11. 主题与个性化 YukiHub 支持深色风格界面，并提供多项个性化设置。 根据 v0.1.4 更新内容，个性化相关功能包括： - 游戏库单行游戏展示数设置 - 主题 UI 自定义配色 - 单色主题 - 渐变色主题 - 从图片 / 视频背景中提取动态主题色 - 背景图片 / 视频相关设置 - 部分悬浮窗大小、透明度、显示时长等设置 你可以在设置页或个性化设置中调整界面显示效果。 --- ## 12. 文件管理与内置文件选择器 YukiHub 内置文件选择器系统，用于选择游戏目录、启动文件或相关配置路径。 使用建议： - 选择游戏时尽量选到游戏根目录 - 不要只选择合集目录，除非你正在使用扫描功能 - 如果启动候选为空，返回上一级或进入更准确的游戏目录重新选择 - 对于 Android 高版本或特殊系统，建议授予必要文件权限 部分设备厂商会限制外部存储读取。如果 KRKR、Artemis 等游戏在华为等设备上出现读写异常，可尝试应用内提供的外部私有存档、轻量级 SAF 等兼容选项。 --- ## 13. 更新检测 YukiHub 支持在应用内检测新版本。 当前设计为： ```text 优先检测 GitHub Releases 如果 GitHub 不可用，则自动尝试 GitCode Releases 两个来源都失败时，才提示检查更新失败 ``` 版本号主要来自远端 Release 的 `tag_name` 或 `name` 字段，并与本机 `versionName` 进行数字段比较。 例如： ```text 0.1.10 > 0.1.9 0.2.0 > 0.1.9 ``` 注意：当前主要比较数字版本，不重点区分 alpha、beta、rc 等后缀。 --- ## 14. 常见问题 ### 14.1 选择目录后扫描不到启动文件 请检查： - 是否选择了真正的游戏根目录 - 目录中是否有支持的启动文件 - 文件扩展名是否符合对应引擎 - 应用是否有文件读取权限 - 游戏是否放在系统限制较严格的位置 ### 14.2 游戏启动失败 可能原因： - 启动方式选择错误 - 启动文件选择错误 - 游戏资源不完整 - 第三方模拟器未安装或版本不兼容 - Android 系统限制了文件访问 - 游戏本身不兼容当前内置引擎 建议先手动编辑条目，重新选择引擎和启动文件。 ### 14.3 WebDAV 同步失败 请检查： - WebDAV 地址是否正确 - 账号密码是否正确 - 云服务是否支持 WebDAV - 当前网络是否可访问服务器 - 云端目录是否有写入权限 ### 14.4 游玩时长没有记录完整 YukiHub 是从应用内点击启动游戏开始计时，回到 YukiHub 前台结束计时。 如果你中途回到 YukiHub，又直接切回游戏，后半段可能不会被继续记录。建议重新从 YukiHub 启动游戏。 ### 14.5 华为等设备存储异常 部分系统对外部存储限制较强，可能影响 KRKR、Artemis 等引擎读取游戏或写入存档。 可尝试： - 授予完整文件访问权限 - 将游戏放到更容易访问的目录 - 使用应用内外部私有存档选项 - 尝试轻量级 SAF 相关选项 - 向作者反馈设备型号、系统版本、目录路径和复现步骤 --- ## 15. 反馈问题时建议提供的信息 如果遇到问题，建议反馈以下内容： - YukiHub 版本号 - 设备型号 - Android 版本 - 游戏类型 / 引擎类型 - 游戏目录位置 - 选择的启动方式 - 问题截图或录屏 - 复现步骤 - 是否使用 SD 卡 / TF 卡 - 是否使用第三方模拟器或改包版本 这样更方便定位问题。 --- ## 16. 交流群与教程链接 ### QQ 交流群 README 中提供的 QQ 群：`163603635` ### 视频教程 - Winlator 和盖世游戏直启动教程：https://b23.tv/Qixj22k - WebDAV 云同步教程：https://b23.tv/wuOvs5l --- ## 17. 开源协议与免责声明 YukiHub 使用 GPL-3.0 开源协议。 你可以在 GPL-3.0 约束下自由使用、修改和分发本项目。 请注意： - 本项目仅用于合法用途 - 不提供游戏本体 - 不提供破解资源 - 不提供绕过授权能力 - 用户应自行确保所管理和启动的内容来源合法