Skip to content

USER_GUIDE.md

Latest commit

 

History

History
201 lines (136 loc) · 6.11 KB

USER_GUIDE.md

File metadata and controls

201 lines (136 loc) · 6.11 KB
Raw

Crystal Live Panel 使用手册

本文面向直播使用者，介绍从安装到 OBS 开播的完整流程。开发和构建说明请见 开发指南。

1. 使用前准备

需要准备：

  • Windows 10 或 Windows 11 x64。
  • 较新的官方 RetroArch 构建。
  • RetroArch 的 tgbdual-libretro 核心。
  • 本项目明确支持的 PM_CRYSTAL Rev 1 ROM。
  • OBS Studio。

ROM 必须同时匹配以下校验值：

CRC32     9AB996C9
SHA-256   65701F63CFB8BCF88A56A6930236E659FC01FEC22BFAD0BE8BB49C739ADA406C

应用不会提供、下载或修改 ROM。请只使用你有权使用的游戏文件。

2. 安装与更新

  1. 打开项目的 GitHub Releases 页面。
  2. 下载 Crystal-Live-Panel-<版本>-x64.zip。
  3. 将压缩包完整解压到固定文件夹，不要直接在压缩软件预览窗口中运行。
  4. 双击 Crystal Live Panel.exe。

应用目前没有商业代码签名证书。Windows SmartScreen 可能提示来源未知；请先核对 Release 页中的 SHA-256，再决定是否运行。

更新时关闭旧版，把新版完整解压到新文件夹后运行即可。配置和本地精灵缓存位于用户数据目录，普通更新不需要重新选择 ROM；若 ROM 被移动，再重新选择即可。

3. 设置 RetroArch

安装并加载核心

  1. 在 RetroArch 的 Core Downloader 中安装 Nintendo - Game Boy / Color (TGB Dual)。
  2. 使用普通“Load Content”流程加载游戏，不要使用双游戏或联机子系统。
  3. 确认游戏正常运行并进入存档后的可移动画面。

开启网络命令

  1. 进入 Settings → Network。
  2. 打开 Network Commands。
  3. 保持端口为 55355，或记住你设置的新端口。
  4. 保存当前 RetroArch 配置。
  5. 完全退出并重新启动 RetroArch。

Crystal Live Panel 默认连接 127.0.0.1:55355。首版只允许本机地址 127.0.0.1 或 localhost，不会连接局域网或互联网中的模拟器。

4. 首次设置应用

  1. 启动 Crystal Live Panel。
  2. 点击“选择 / 重新选择 ROM”。
  3. 选择受支持的 .gbc 文件。
  4. 等待 ROM 校验和本地精灵图提取完成。

成功时 ROM 区域会显示标题 PM_CRYSTAL、CRC32 9AB996C9、Sprites ready 和 ROM_OK。

ROM 只会在本机读取。应用从 ROM 中提取第二世代正面精灵和调色板，生成透明 PNG 后写入用户数据目录。原始 ROM 不会被复制到应用目录或上传。

5. 测试连接

  1. 确认 RetroArch 已加载游戏。
  2. 在控制面板填写地址和端口，通常保持 127.0.0.1 与 55355。
  3. 点击“保存并测试连接”。

正常情况下依次出现：

UDP_VERSION_OK
GET_STATUS_OK
READ_CORE_RAM_OK

进入存档后的游戏画面后，实时诊断还应包含：

RAM_ADDRESS_MODE
PLAYER_NAME
GAME_TIME
MONEY
PARTY_COUNT
MAP

诊断详情和异常处理见 故障排查。

6. 配置 OBS

推荐的源顺序

从下到上：

  1. RetroArch 游戏捕获或窗口捕获。
  2. Crystal Live Panel 浏览器源。

叠加层本身不捕获游戏画面。中央透明窗口会露出下层的 RetroArch 捕获源。

添加浏览器源

在 OBS 中添加“浏览器”源：

选项 值
URL http://127.0.0.1:17654/overlay
宽度 1536
高度 1024
自定义 CSS 留空

如果 OBS 有“场景不活跃时关闭源”等选项，建议关闭该选项，避免切回场景时短暂重新连接。

对齐游戏画面

叠加层中央透明游戏窗口的参考边界为：

左上角：x = 194, y = 108
尺寸：  854 × 768
比例：  10:9（Game Boy Color 原生比例）

将 RetroArch 捕获源保持原比例缩放到约 854 × 768，并移动到 194,108。不要横向拉伸。160×144 等比放大后的宽度约为 853.33 像素，左右不到 1 像素的差异属于正常现象。

若最终直播画布不是 1536 × 1024，先把浏览器源作为整体等比缩放，再保持游戏捕获源与它一起缩放和移动。

7. 显示内容

训练师卡

  • 英文或数字玩家名。
  • 5 位玩家 ID，不足位时补零。
  • 金钱，使用千分位显示。
  • 游戏时间 HH:MM。
  • 城都徽章数量。

首版不支持中文玩家名字符表；无法识别的字符会显示诊断，不会猜测转换。

徽章与队伍

  • 城都八枚徽章按获得状态逐个点亮。
  • 最多显示六个队伍槽。
  • 每个已占用槽显示宝可梦正面精灵、白色底板和 Lv. 等级。
  • 空槽保持精灵球占位。
  • 首版不显示 HP、异常状态、持有物或招式。

地图

  • 城都室外地图显示城镇或路线归属标记。
  • 室内和洞穴尽量继承所属地标。
  • 进入关都后显示 KANTO。
  • 无法映射的地图显示 UNKNOWN。

8. 运行状态

状态 直播层行为
在线 正常实时更新
RetroArch 暂停 保留数据并显示 PAUSED
RetroArch 断线 保留最后有效数据并显示 RETROARCH OFFLINE
未加载内容 显示 WAITING FOR GAME
从未取得有效 RAM 显示空白占位，不发布猜测数据

9. 推荐开播流程

  1. 启动 RetroArch。
  2. 用 tgbdual-libretro 加载游戏并读取存档。
  3. 启动 Crystal Live Panel。
  4. 确认状态为“RetroArch 已连接”，训练师和队伍内容正确。
  5. 启动 OBS 或切换到直播场景。
  6. 在 OBS 预览中确认透明游戏窗口、训练师卡、队伍和地图。
  7. 开始直播。

10. 本地端口与数据目录

应用使用：

  • RetroArch UDP：默认 127.0.0.1:55355。
  • 叠加层 HTTP/WebSocket：固定 127.0.0.1:17654。

Windows 用户数据目录通常为：

%APPDATA%\crystal-live-panel

其中可能包含：

  • config.json：ROM 原路径和 RetroArch 本机端口设置。
  • sprites\9AB996C9\：从本地 ROM 提取的 PNG 缓存。

11. 卸载与清理

免安装版直接删除程序文件夹即可。若还要删除配置和本地提取的精灵图：

  1. 关闭 Crystal Live Panel。
  2. 删除 %APPDATA%\crystal-live-panel。

删除用户数据后，下次启动需要重新选择 ROM 并重新提取精灵图。