游戏屋 使用说明

• 版本：1.0.00
• 作者：kuakeba.cn
• 适用程序：Zsens Admin

游戏屋是基于 EmulatorJS 的网页游戏插件，支持 GBA / FC(NES) 等平台的游戏在线游玩，前台可按游戏类型分类浏览、搜索分页，并提供游玩扣币、游戏币老虎机、社区金币兑换等玩法。

⚠️ 一、启用后最重要的一步：下载游戏包并解压到 roms 目录

插件启用后必须单独下载「游戏包」，解压到网站根目录下的 public\static\GameHome\ 目录，否则前台没有任何游戏、点开也无法游玩。

插件本身不附带游戏 ROM 文件（体积过大），只提供程序、页面与模拟器运行库。

目标目录（务必逐字对齐）

操作步骤

1. 在后台「插件列表」中启用「游戏屋」插件。
2. 进入后台菜单 游戏屋 → 游戏屋设置，页面下方「游戏包下载」区块会实时显示在线文档中的下载渠道（百度网盘 / 夸克网盘 / 光鸭网盘等，渠道随时更新）。

  - 若区块显示「读取失败」，点该区块右上角的「打开在线文档」，直接用浏览器打开下载地址汇总表。

1. 按网盘渠道下载游戏包（通常为分卷压缩包，需全部下载后解压）。
2. 将解压出来的游戏文件（.zip / .gba / .nes 等）直接放进 roms 目录。

  - 注意：不要再多套一层文件夹（错误示例：roms\roms\xxx.zip 或 roms\游戏包\xxx.zip）。

  - 解压密码、分卷合并方式见下载页说明。

1. 再解压封面包（可选，推荐一起放），把封面图片（.webp / .png / .jpg）放进 public\static\GameHome\covers 目录，封面文件名需与 ROM 同名。
2. 回到后台「游戏屋设置」，点右上角「刷新数据」。顶部「已收录游戏」数量会变化，说明读取成功。
3. 打开前台 https://你的域名/GameHome，导航栏也会出现「游戏屋」入口。

目录权限：roms 与 covers 目录需可读（Linux 下一般 755，属主为 Web 运行用户）。

二、目录结构

public/static/GameHome/
├── roms/         游戏 ROM（必需，需自行下载游戏包放入）
├── covers/       游戏封面（可选，文件名与 ROM 同名）
├── emulator/     模拟器运行库（必需，随插件提供，请勿删除）
├── games.json    游戏清单（可选，用于自定义标题 / 平台 / 封面映射）
├── gamehome.css  前台样式
└── gamehome.js   前台脚本

• emulator/ 是游玩页的模拟器核心，缺失会导致游戏黑屏、无法启动。
• 未提供 games.json 时，插件会自动扫描 roms 目录生成列表；提供后可按清单自定义中文标题与平台（gba / nes 等）。
• 小于 4KB 的空白封面会被自动识别，改用渐变占位图，不会出现裂图。

三、功能说明

四、后台设置项

路径：后台 → 游戏屋 → 游戏屋设置

五、常见问题

1. 前台没有游戏 / 提示暂无游戏

• 检查 public/static/GameHome/roms 目录内是否直接存在游戏文件；
• 常见原因是解压时多套了一层文件夹，或只解压了分卷中的一部分；
• 放好后回后台「刷新数据」（列表缓存 1 小时）。

2. 游戏点开黑屏、一直加载

• 检查 public/static/GameHome/emulator 目录是否完整（emulator.min.js、cores/、compression/、localization/）；
• 浏览器控制台若有 404，多为静态资源路径或伪静态未放行 /static。

3. 封面不显示

• 封面需放在 covers 目录，且文件名与 ROM 文件名一致（扩展名可不同）；
• 图片过小（< 4KB）会被判定为空白封面，自动使用渐变占位。

4. 后台「游戏包下载」区块显示读取失败

• 说明服务器无法访问在线文档（腾讯文档域名被网络限制），不影响插件其它功能；
• 点区块内「打开在线文档」按钮即可直接查看下载渠道，或点「手动刷新」重试；
• 区块内容最多缓存 3 分钟，文档更新后点「手动刷新」立即同步。

5. 扣费不生效

• 管理员与有效 VIP 默认免费；
• 检查所选币种余额是否足够，以及「免费重进时长」是否仍在有效期内。

6. 修改 ROM 后前台不更新

• 后台点「刷新数据」，或等待 1 小时缓存自动过期。

六、卸载说明

后台卸载插件会移除「游戏屋」菜单与权限节点。以下内容需手动清理：

• 静态资源目录 public/static/GameHome（含 roms / covers / emulator）；
• 数据表 gamehomewallet、gamehomeslotlog、gamehomeplay_log（表前缀以站点配置为准）。

七、版权与声明

本插件程序作者为 kuakeba.cn，仅供合法用途使用。插件内不包含任何游戏 ROM 文件，游戏包由第三方渠道提供，请在下载与使用时遵守当地法律法规及相关版权要求，自行承担使用风险。

八、演示截图：