WebGUI · 我的世界Mod

.detail-panel[hidden] { display: block !important; } .detail-tabs { display: none; } /* These three panels are rendered by the browser. */ [data-versions], [data-changelog-panel], [data-comments] { display: none; }

WebGUI 让你使用熟悉的技术，在 Minecraft 中渲染真实的网页界面。

打开任何网页——React、Vue、Svelte，或纯 HTML/CSS/JavaScript——作为全屏 GUI 或透明 HUD 覆盖层直接显示在游戏中。由 MCEF 驱动的真实 Chromium 内核提供支持，因此现代网络功能开箱即用：CSS 动画、WebSockets、fetch、WebGL、localStorage、实时更新等。

适用于 Fabric 和 NeoForge。

GitHub — https://github.com/mc-webgui/webgui
文档 — https://webgui.space
npm — https://www.npmjs.com/package/@webgui/react

YouTube 演示： https://www.youtube.com/watch?v=wqZ400GWKUw

为什么会有 WebGUI

我是一名全栈开发者。我的大部分工作都是构建 Web 应用——React 前端、API、实时系统、仪表盘，以及所有常见的 Web 技术栈。

我一直热爱 Minecraft，不仅将其视作一款游戏，更是一个创意平台。服务器、自定义机制、社区、小游戏、角色扮演世界——Minecraft 给予了人们难以置信的自由来共同构建体验。

在某个时刻，我意识到了一点：

Web 开发者已经拥有出色的界面构建工具——但几乎没有任何好方法能在 Minecraft 中使用它们。

我们每天都在构建精美的界面，拥有响应式布局、动画、地图、商店、实时仪表盘和实时交互。但将同样的工作流程带入 Minecraft 一直都很困难、受限或笨拙。

于是我问了一个简单的问题：

如果 Minecraft 可以直接打开一个真正的 Web 应用会怎样？

不是自定义的库存 GUI 系统。不是另一个专有 UI 框架。不是一门需要学习的新语言。

就是 Web。

这就是 WebGUI 的起源。

为 Web 开发者打造

WebGUI 专为已经熟悉现代前端的开发者设计。

如果你了解：

HTML
CSS
JavaScript

——那么你已经知道如何用 WebGUI 构建 Minecraft 界面了。

使用 React、Vue、Svelte、Tailwind、WebSockets、REST APIs、动画、状态管理器、组件库——任何你平时用于 Web 开发的东西。

构建：

服务器商店
HUD 覆盖层
地图
菜单
管理面板
任务系统
角色扮演界面
实时仪表盘
完整的游戏内应用

然后直接在 Minecraft 中加载它们。

工作原理

服务器将一个 URL 发送到客户端。客户端在嵌入的 Chromium 中打开它。页面会自动接收实时玩家数据，并能与游戏进行双向实时事件交换——页面 → 服务器和服务器 → 页面。页面也可以绑定到一个实体上，右键点击即可打开该实体上下文相关的界面。

兼容性

Minecraft	加载器	状态
26.2	NeoForge	🧪 测试版
26.1	NeoForge	🧪 测试版
1.21.5 – 1.21.11	Fabric	✅ 活跃
1.21.5 – 1.21.11	NeoForge	✅ 活跃
1.21 – 1.21.1	Fabric	✅ 受支持
1.21 – 1.21.1	NeoForge	✅ 受支持
1.20.1	Fabric	✅ 受支持

Minecraft 26 构建版本仅支持 NeoForge 且处于测试阶段 — Fabric 需等待 26.x 的 Yarn 映射发布后才能支持。Chromium（约 150 MB）会在首次启动时自动下载。

功能特性

全屏 GUI — 用你的 Web 应用替换 Minecraft 的界面
HUD 覆盖层 — 渲染在游戏画面之上的透明浏览器层
真实 Chromium 浏览器 — 由 MCEF 驱动
实时玩家数据 — 位置、视角、生命值、饥饿值、经验值、游戏模式、维度、用户名、UUID、服务器
实时通信 — 浏览器 ↔ Minecraft 消息传递（页面 → 服务器和服务器 → 页面事件）
实体绑定 GUI — 将页面绑定到实体；右键点击即可打开带有实体上下文的界面
签名玩家令牌 — 安全的后端认证，无需登录界面
加入时自动 HUD
每个玩家的主菜单
服务端 Mod API
Fabric & NeoForge — 一个模组，两种加载器
可与任何前端技术栈配合使用

命令

所有命令都需要操作员等级 2（在 Fabric 上，支持 fabric-permissions-api / LuckPerms）。

命令	描述
`/webgui gui <目标> <url>`	将 URL 作为全屏 GUI 打开
`/webgui hud <目标> <url>`	将 URL 作为 HUD 覆盖层打开
`/webgui bind entity <选择器> <url> [cancel_interaction]`	绑定实体 — 右键点击打开带有实体上下文的 URL
`/webgui unbind entity <选择器>`	移除实体绑定
`/webgui reload`	重新加载服务器配置和实体绑定

JavaScript API

// 实时玩家数据 — 在发生变化时每 tick 推送一次，并在页面加载时推送
const c = window.webgui.client;
// {
//   playerUuid, username, webviewMode,   // GUI_SCREEN | HUD_OVERLAY | NONE
//   dimension, gamemode,
//   health, maxHealth, food, xpLevel,
//   pos:  { x, y, z },
//   look: { yaw, pitch },
//   server: { address, ping }
// }// 订阅更新
window.webgui.on('client', c => console.log(c));        // 实时玩家数据
window.webgui.on('entity', e => console.log(e));        // 绑定实体的上下文（或 null）
window.webgui.on('my-event', d => console.log(d));      // 自定义服务器 → 页面事件
window.webgui.off('client', handler);                   // 取消订阅
// （也会触发等效的 DOM 事件：'webgui:client'、'webgui:entity'、'webgui:<name>'）
// 向 Minecraft 发送消息 — 自定义频道可到达服务端 Mod API
window.webgui.postToGame({ channel: 'shop:buy', item: 'diamond', qty: 1 });
// 关闭当前 GUI / HUD
window.webgui.closeGui();

也提供： window.webgui.entity（当前实体上下文）和一个 window.webgui.onClientInfo(c) 回调函数。

React 集成

npm i @webgui/react

import { useWebGUIClient } from '@webgui/react';function App() {
  const client = useWebGUIClient();
  return (
    <div>
      Hello, {client?.username}
    </div>
  );
}

服务器配置

config/webgui/server.json 在首次运行时生成；令牌密钥会自动创建。

{
  "autoHudOnJoin": false,
  "autoHudUrl": "https://your-server.com/hud",
  "mainMenuUrl": "https://your-server.com/menu",
  "tokenTtlSeconds": 900,
  "queryParamName": "webgui_token",
  "tokenSecretBase64": "<自动生成的 32 字节密钥>",
  "updateCheckUrl": ""
}

运行要求

Fabric — Fabric Loader ≥ 0.18 + Fabric API，或 NeoForge（无需额外依赖）
Java 21 — Minecraft 1.20.1 – 1.21.11
Java 25 — Minecraft 26.x（NeoForge 测试版）