🎮 AstrBot Galgame 同乐插件 v1.3.1

你是否曾想过和群友们一起在聊天群里玩 Galgame 或视觉小说？这个插件将这个想法变为了现实！

本插件能够捕捉你电脑上指定的游戏窗口画面，通过截图的方式实时“直播”到聊天群里。群里的每一个人都可以通过简单的指令来控制游戏（例如推进对话、进行选择），实现云玩 Galgame 的有趣体验。

注意：小心HCG

✨ v1.3.1 版本更新说明

• 新增“点击推进”模式：新增 g_triggers_click 开关。开启后，g 和戳一戳指令将从“模拟按键”变为“模拟鼠标点击”，用于解决部分游戏在后台模式下不响应键盘事件的问题。
• 优化引导提示：当“点击推进”模式开启但未注册专用按钮时，提示信息会更清晰地引导用户去注册名为“快速推进”的按钮。

✨ v1.3.0 版本更新说明

• 新增“戳一戳”快捷推进：现在，你可以通过戳一戳机器人来代替发送“g”指令，操作更加便捷！此功能默认开启，可以在配置中关闭。
• 优化截图机制：引入 dxcam 作为可选的截图后端，可以有效避免在部分游戏中（尤其是在前台模式下）截图丢失UI的问题，让游戏画面更完整。

✨ v1.2.0 版本更新说明

• 🖱️ 新增鼠标点击模式：现在可以在按钮注册之后直接通过鼠标定位执行操作，云游时的交互更贴近真实点击体验。
• ⌨️ /输入 指令独立化：新增 /输入 指令（别名 /输、/type），在无需 /gal 前缀的情况下即可模拟常用按键，便于与鼠标点击模式配合使用。

✨ v1.1.0 版本更新说明

• ✨ 全新远程模式 (Remote Mode)：现在，你可以在一台电脑或服务器上运行AstrBot，同时在另一台性能更好的游戏电脑上玩游戏。
• 🔐 安全连接：远程模式使用共享密钥（Secret Token）进行双向验证，确保只有你授权的客户端才能连接到插件，保障了连接的私密性和安全性。

🚀 核心功能

• 双重运行模式：
  • 本地模式 (Local)：最简单的模式，AstrBot 和游戏在同一台 Windows 电脑上运行。
  • 远程模式 (Remote)：AstrBot 和游戏可以分别在两台不同的电脑上运行，通过网络连接。
• 实时游戏画面分享：将指定窗口的画面以图片形式发送到群聊。
• 多人协作控制：群内的任何人都可以发送指令来推进游戏。
• 按钮注册与自动点击：使用 /注册按钮 引导流程，标注界面上的常用按钮，随后可通过 /点 <按钮名> 一步完成点击。
• 完整的键盘模拟：支持模拟几乎所有键盘按键，并为常用按键提供中文别名。
• 两种输入模式：
  • SendInput (前台高兼容模式)：兼容性最强，但需要将游戏窗口置于最前台。
  • PostMessage (后台模式)：理论上可后台操作，但兼容性较差，不推荐。

⚙️ 安装与配置

1. 插件安装 (在运行AstrBot的电脑上)

1. 将整个 astrbot_plugin_galplayer 文件夹放入你的 AstrBot 的 data/plugins 目录中。
2. 启动或重启 AstrBot。
3. 进入 AstrBot 的 WebUI，在“插件管理”页面，找到本插件并确保它已启用。

2. 模式选择与配置

在插件管理页面点击“管理”，你会看到所有配置项。最重要的第一步是选择你的运行模式。

• 如果你想使用【本地模式】：

  1. 确保 mode 配置项选择 local。
  2. 确保你的AstrBot运行在 Windows 系统上。
  3. 完成！你可以直接跳转到 使用方法 章节。

• 如果你想使用【远程模式】：

  1. 在插件配置中，将 mode 切换为 remote。
  2. 在 remote_secret_token 配置项中，填入一个你自己设定的复杂密码（例如 MySuperSecretKey_12345!@#$），并保存配置。
  3. 接下来，请在你准备玩游戏的电脑上，完成以下客户端设置。

3. 远程客户端设置 (在你的游戏电脑上)

你需要一个客户端脚本来连接你的AstrBot。

1. 准备文件：在你的游戏电脑上，创建一个新文件夹（例如 gal_client），然后将插件目录remote文件夹中的 remote_client.py 和它专用的 requirements.txt 两个文件放进去。
2. 安装依赖：在此文件夹中打开命令行/终端，运行 pip install -r requirements.txt 来安装客户端所需的库。
3. 生成配置：运行一次客户端脚本：python remote_client.py。脚本会自动创建一个 gal_client_config.ini 文件，然后退出。
4. 修改配置：打开 gal_client_config.ini 文件：
   • ServerURI: 修改为运行AstrBot服务器的IP地址和端口。
   • SecretToken: 必须填入和插件配置中 remote_secret_token 完全相同的密码。
5. 启动客户端：保存配置文件后，再次运行 python remote_client.py。如果看到“服务器验证成功”的日志，说明你已成功连接！保持这个命令行窗口运行即可。

📖 使用方法

1. 启动游戏

在你的游戏电脑上打开你想要玩的 Galgame。

2. 获取窗口标题

仔细查看游戏窗口最上方的标题栏，记下标题的一部分或者全部（越独特越好）。

3. 开始游戏

在群聊中，发送开始指令，并将你记下的标题作为参数。

/gal start Doki

机器人会找到该窗口，发送第一张截图，游戏正式开始！

4. 注册常用按钮

1. 在聊天中发送 /注册按钮，机器人会推送当前截图并开始 60 秒计时。
2. 在机器人刚发送的截图上圈出或标注要点击的位置，然后原样发送回群（不要裁剪或压缩到其它比例）。
3. 机器人会尝试点击并回传结果截图，回复 1 表示成功，回复 2 表示失败后可重新标注。
4. 当点击成功后，输入按钮名称（建议使用字母或数字，避免空格）。

提示：超时时间可以在配置项 registration_timeout_seconds 中调整。

5. 调用与管理按钮

• /点 <按钮名>：点击已注册按钮。可通过 screenshot_on_click 控制是否自动回传截图。
• /按钮列表：查看当前窗口下已经注册的按钮。
• /删除按钮 <按钮名>：删除某个已注册按钮。

4. 控制游戏

🔧 详细配置

❓ 疑难解答 (FAQ)

Q: 我对一个游戏使用了所有指令，但它就是没反应！
A: 这是最常见的问题！请进入插件配置页面，将 input_method 从 PostMessage 切换到 SendInput，保存后重试。这能解决绝大多数游戏的兼容性问题，但代价是游戏窗口必须保持在前台。

Q: 【远程模式】客户端提示 "Connection failed" 或 "连接失败"。
A: 请检查：1. ServerURI 中的IP地址是否正确。2. 端口号是否正确（默认为8765）。3. 运行AstrBot的服务器的防火墙是否允许8765端口的入站连接。

Q: 【远程模式】客户端提示 "Token mismatch" 或 "验证失败"。
A: 这说明插件配置里的 remote_secret_token 和客户端 gal_client_config.ini 文件里的 SecretToken 不一致。请仔细检查并确保它们完全相同，包括大小写和符号。

Q: 机器人提示“找不到窗口”。
A: 请确保：1. 游戏已经打开。2. 你在 /gal start 指令后输入的窗口标题和游戏窗口上显示的完全一致。

Q: 游戏可以最小化吗？
A: 不可以。无论在哪种模式下，游戏窗口都必须处于打开状态（不能最小化），但可以使用 PostMessage 模式让它被其他窗口遮挡。