网络商店链接

网络商店链接

支持可修改玩家库存的网店

经济

WebshopLink

一个 Minecraft Forge 模组,让玩家可以在游戏内的浏览器窗口中浏览并使用外部网店,然后将购买的商品直接应用到他们的物品栏中。

在整个文档中,该项目都被称为“模组”,即使在讨论插件版本时也是如此——无论哪种形式,功能都是相同的。

WebshopLink 仅处理游戏内部分。 实际的商店(商品目录、定价、玩家获得哪些物品)存在于一个由你运行的外部 Web 服务中,该服务使用 WebshopLink 的 HTTP 协议。有关协议约定,请参阅 Wiki,有关可用的参考实现,请参阅 demo/。

工作原理

  1. 玩家在游戏中运行 /shop <type>。
  2. WebshopLink(服务端)将玩家当前的物品栏发送到你的商店 API,并获取一个会话 URL。
  3. 该 URL 会在一个全屏的游戏内浏览器(使用 MCEF 渲染)中打开,悬浮在游戏世界之上,底部有一个小按钮栏。
  4. 玩家在网页上构建购物车,然后点击 Finish Trade。
  5. WebshopLink 从你的 API 获取结果物品栏,验证玩家物品栏自会话开始以来未发生变化,然后应用它。关闭窗口(或 Cancel / ESC)会取消会话。
Player ──/shop──▶ WebshopLink (server) ──HTTP──▶ Your shop API
                        │                              │
                        └──── opens in-game browser ───┘
                                     │
                        Finish Trade ▼
                  inventory applied to player

功能特性

  • 游戏内购物 — 网店渲染在叠加于游戏之上的 Chromium 浏览器中;无需 Alt+Tab 切换到外部浏览器。
  • 物品栏验证 — 如果在开始会话和确认之间玩家的物品栏发生了变化,购买将被拒绝,从而防止刷物品/竞争条件漏洞。
  • 双因素会话代码 — 每次调用都会与你的 API 交换一个防篡改代码,因此会话无法从外部伪造。
  • API 密钥支持 — 对商店 API 的每个请求都携带一个可配置的 X-Webshop-Api-Key 请求头。
  • 主物品栏 + 末影箱支持,并带有针对复杂物品的完整 NBT 序列化。
  • 余额叠加层(可选) — 在可配置的屏幕角落显示一个小型 HUD 框,渲染商店的余额页面,让玩家始终能看到自己的余额。默认开启;位置、大小和 URL 为客户端配置。参见余额叠加层。
  • 可选网络 — 模组将其网络通道注册为可选,因此原版客户端(或未安装该模组的客户端)仍可连接到服务器;它们只是无法打开浏览器。

环境要求

端 所需内容
服务器 WebshopLink 模组
客户端 WebshopLink 模组 + MCEF
其他 一个实现 WebshopLink API 的外部网店
  • Minecraft 1.20.1,Forge 47.x
  • MCEF 2.2.0+(仅客户端——专用服务器从不加载它)

客户端缺少该模组/MCEF 的玩家在运行 /shop 时会被提示安装它们。

命令

命令 描述
/shop <type> [label] 取消任何未完成的会话,然后启动给定 type(发送到你的 API 的 shopSlug)的新商店会话。可选的 label 会显示在确认界面中。打开游戏内浏览器。
/shopFinish <uuid> 结账的手动后备方案(浏览器的 Finish Trade 按钮会自动执行此操作)。获取新的物品栏,并在聊天中提供一个可点击的确认链接。
/confirmFinish <uuid> 应用已结账的物品栏更改。
/shopCancel <uuid> 在本地和你的 API 上取消该会话。

正常游戏只需要 /shop——浏览器的按钮会驱动其余操作。其他命令作为后备方案,以及供没有游戏内浏览器的客户端使用。

默认情况下任何人都可以运行 /shop。要将其限制给管理员/命令方块(以便商店仅在特定位置打开),请在配置中设置 shopCommandPermissionLevel——参见锁定 /shop。

安装

服务器

  1. 下载最新的 WebshopLink 发布版 JAR。
  2. 将其放入服务器的 mods/ 文件夹中。
  3. 启动一次服务器以生成 config/webshoplink-common.toml,然后将其指向你的商店 API(参见 Wiki)。
  4. 重启。

客户端(每位玩家)

  1. 安装 MCEF。
  2. 安装 WebshopLink 模组。

文档

  • Wiki — 服务器运维设置:完整的配置参考、你的商店必须实现的 HTTP API、物品栏数据格式以及安全模型。
  • demo/ — 一个小型、注释完整的参考商店(Bun + Tailwind),你可以在本地运行以试用该模组或学习协议约定。

许可证

参见 LICENSE。