WassJS 菜单教程
从 XML 页面到动画、JSON 组件、服务端购买与附属模组,一份可以直接照着做出完整商店系统的 WassJS 开发教程。
这里收录我制作的 Minecraft 模组、工具与开发教程。选择一个项目,查看它的说明与完整文档。
从 XML 页面到动画、JSON 组件、服务端购买与附属模组,一份可以直接照着做出完整商店系统的 WassJS 开发教程。
新的模组、工具与教程会陆续出现在这里。
Wass · Minecraft 模组开发 / 服务器工具
本页为静态展示,教程内容持续更新。
从 XML 页面到动画、JSON 组件、服务端购买与附属模组
在原版 Minecraft 里做界面,要么写大量 Java 代码,要么依赖特定的 GUI 库;改一次布局就要重新编译。WassJS 把「界面长什么样」交给 XML,「界面怎么动」交给 JavaScript,「界面显示什么数据」交给 JSON,三者都放在服务端的 wass/ 目录里,登录后自动下发给客户端。
因此它适合这些场景:
/wassjs reload 即可生效;WassJSBridge 注册自己的 JS 页面、Java 函数,或直接打开 WassJS 的窗口。wass/;联机时以服务器上的 wass/ 为准,客户端只负责显示。1服务端启动或执行 /wassjs reload 时,扫描 wass/menus、wass/components、wass/js、wass/json、wass/tex;
2玩家登录后,服务端把脚本、XML、JSON、图片分块下发(图片单张 ≤ 512KB);
3客户端收到内容后重建 Rhino 作用域,按文件名顺序执行 wass/js/*.js;
4脚本里用 wass.page("shop") 拿到页面绑定器,注册 onOpen、onClick 等回调;
5玩家执行 /wassjs 或右键时钟时,客户端用 XmlMenuBuilder 把 menus/shop.xml 构造成 LDLib2 元素树;
6页面打开后触发 page.onOpen,脚本在这里填数据、播放渐入动画;
7点击按钮时,客户端把动作发给服务端执行,结果再回传给 page.onAction。
| 路径 | 作用 | 是否下发 |
|---|---|---|
wass/menus/*.xml | 每个 <menu> 文件都是一个独立菜单页面 | 是(仅 menus/) |
wass/components/*.xml | 只用于 <include> 的组件片段 | 是(仅 components/) |
wass/js/*.js | 页面逻辑、事件绑定、动画 | 是 |
wass/json/*.json | 商品、价格、文案等数据 | 是 |
wass/tex/*.png | 图片资源,单张 ≤ 512KB | 是 |
config/wassjs.toml | 字体、默认菜单、命令名、客户端模式 | 否(各端本地) |
旧版的 wassjs/ 目录仍然兼容:把 useLegacyJS 设为 true 后,会读取旧的纯 JS 菜单脚本。新项目建议使用 wass/(XML 页面)方式。
| 依赖 | 版本 |
|---|---|
| Minecraft | 1.20.1 |
| Forge | 47.x(开发用 47.4.6) |
| Java | 17 |
| LDLib2 | 2.2.43 |
| WassJS | 1.0.0 |
把 wassjs-1.0.0.jar 与前置模组放进 mods/,启动一次客户端即可在游戏目录生成 wass/ 样例。开发时使用 gradlew runClient,运行目录是项目下的 run/。
调试常用命令:
| 命令 | 用途 |
|---|---|
/wassjs | 打开 commandMenu 配置的默认菜单 |
/wassjs open shop | 为执行者打开指定菜单 |
/wassjs list | 列出已注册菜单(OP ≥ 2) |
/wassjs status | 查看脚本数、菜单数、JSON 数、错误数 |
/wassjs reload | 重载 XML / JS / JSON 并通知客户端 |
[WassJS] 行和 /wassjs status 的 errors 计数。在 wass/menus/ 下新建 hello.xml:
<menu id="hello" title="你好" width="420" height="240">
<style>
.title { text-color: #FFFFFFFF; font-size: 14; text-shadow: false; }
</style>
<panel layout="column" width="100%" height="100%" padding="12" gap="8"
background="#F25A1119" border-color="#FFFF5555" border-width="1" radius="8">
<label class="title" text="第一个 WassJS 页面" width="100%" height="20"/>
<label text="§7所有内容都由 XML 描述。" width="100%" height="14"/>
<button id="btn_close" text="关闭" width="100%" height="22"/>
</panel>
</menu><menu> 的 id 就是菜单 id,也是 /wassjs open 的参数;width、height 是窗口的初始大小。窗口不会超过屏幕,超出时自动缩小。
对应脚本只要一行就能让按钮生效:
var page = wass.page("hello");
if (page) {
page.onClick("btn_close", function () { page.close(); });
}| 标签 | 说明 |
|---|---|
menu / page | 页面根;必须有 id、width、height,可加 fullscreen="true" |
panel / card / div | 通用容器,可设背景、边框、圆角、内边距 |
row / column | 横向 / 纵向弹性容器,子元素用 flex 分配空间 |
label / text | 文本,支持 § 颜色代码 |
button | 按钮,默认播放 minecraft:ui.button.click |
slider | 滑条,属性 min / max / value |
text-field | 输入框,value 为初始内容 |
switch | 开关,value 为 true / false |
progress | 进度条,value / max |
image | 图片,src 指向 tex/ 下的 PNG,border 为九宫格边宽 |
display-panel | 物品图标面板(第 5 章) |
scroll | 滚动容器 |
include | 引入 components/ 下的组件片段 |
通用属性:id、class、style、width、height、flex、padding、gap、layout、background、border-color、border-width、radius、visible、tooltip、scale。按钮额外支持 action、payload、command、open、sound、on-click。
布局是 flex 模型,和 Web 很像:
row 横向排列,column 纵向排列;子元素设 flex="1" 就会平分剩余空间;width / height 支持百分比(占父容器内容区);48% + 48% + gap 是常见的两列布局;gap 是子元素间距,padding 是容器内边距;layout="column" 可以给 panel 指定方向;alignItems="center" 让子元素在交叉轴上居中,justifyContent="center" 让主轴居中。一个容易踩的坑:row 里的 column 不要再写 width="100%",否则会撑满并挤掉兄弟元素;用 flex="1" 让它占据剩余宽度。教程里需要固定宽度的列(例如数量文字)才写具体像素。
<style> 里用 .class { 属性: 值; } 定义可复用的样式,元素写 class="card" 引用。也可以直接写 style="..." 内联样式。
颜色一律使用 #AARRGGBB(8 位)或 #RRGGBB(6 位,自动补不透明)。例如 #F25A1119 是 95% 不透明的暗红,#33FF8888 是 20% 不透明的浅红。8 位时前两位是 alpha,这是最常见的写错点。
文字颜色用 text-color,color 是给整个元素着色(tint,会影响图标和子元素),两者不要混用。字号用 font-size,默认是 9;text-shadow: false 可以去掉原版描边,在深色背景上更干净。
<style>
.panel { background: #F25A1119; border-color: #FFFF5555; border-width: 1; radius: 8; }
.card { background: #33FF8888; border-color: #FF6B6B; border-width: 1; radius: 6; padding: 6; }
.title { text-color: #FFF6EDED; font-size: 15; text-shadow: false; }
.muted { text-color: #FFFFEFE8; font-size: 9; text-shadow: false; }
.price { text-color: #FFFFD166; font-size: 9; text-shadow: false; }
.btn { background: #FF8E1B1B; border-color: #FFFF5555; border-width: 1; radius: 4;
text-color: #FFFFFF; font-size: 9; text-shadow: false; }
</style>| 写法 | 行为 | 示例 |
|---|---|---|
open="shop" | 打开另一个菜单 | <button open="shop"/> |
action="buy" payload="diamond:1" | 向服务端发送动作,由脚本执行 | <button action="buy" payload="..."/> |
command="/say hi" | 以玩家身份执行命令 | <button command="say hi"/> |
on-click="fnName" | 调用脚本里的全局函数 | <button on-click="onBuy"/> |
推荐用 page.onClick("id", fn) 绑定,避免全局函数污染;on-click 只适合简单场景。按钮默认带点击音效,sound="false" 关闭,sound="minecraft:block.note_block.pling" 换成别的音效。
components/ 下的 XML 不是独立菜单,只能被 <include src="components/xxx.xml"/> 引入,相当于把那段 XML 原地展开。适合页头、页脚这类只出现一次的片段。
<!-- components/shop_footer.xml -->
<row width="100%" height="22" gap="8" alignItems="center">
<button id="btn_buy" class="btn-accent" text="§a立即购买" flex="1" height="20" action="buy"/>
<button id="btn_close" class="btn" text="§c关闭" flex="1" height="20"/>
</row>include 可以做属性覆盖,但只作用于组件根元素;组件内部的 id 是固定的,同一个组件引入两次会出现重复 id,事件和取值都会混乱。需要重复的卡片式结构时,请复制 XML 换 id,或用第 6 章的动态生成方案。
<menu> 根标签,也不要放到 menus/ 下;放错位置会被当成菜单解析并在日志里报错。用上面的知识写出商店的骨架:一个页头、两张商品卡(含 Display Panel 图标和选择按钮)、一个数量面板(滑条 + 总计)、一个底部购买按钮。先只写 XML,不加任何逻辑,确认排版正确后再进入第 3 章。
每个菜单对应一个页面绑定器,用 wass.page("菜单 id") 获取。脚本在服务端也会执行,此时 wass.page 返回 null,所以所有页面代码都要判空:
(function () {
var page = wass.page("shop");
if (!page) {
return; // 服务端没有界面,直接退出
}
// 客户端逻辑写在这里
})();外层用立即执行函数(IIFE)包起来,可以避免多个脚本之间同名函数互相覆盖——这是多页面项目最常见的问题之一。
| 回调 | 触发时机 | 常见用途 |
|---|---|---|
page.onOpen(fn) | 页面构建完成、即将显示 | 填充数据、播放渐入动画、重置状态 |
page.onClose(fn) | 页面关闭 | 保存状态、停止动画 |
page.onClick(id, fn) | 点击元素 | 按钮逻辑、选中商品 |
page.onChange(id, fn) | 文本框 / 开关 / 滑条变化 | 读取 ctx.value、刷新总价 |
page.onAction(id, fn) | 服务端动作执行完成 | 显示购买结果 |
page.onVariableChange(key, fn) | 服务端变量更新 | 同步余额、库存 |
ctx 是事件上下文,常用字段:elementId、value、payload、result、button、mouseX/mouseY。
| 方法 | 作用 |
|---|---|
page.text(id, "文本") | 修改文本(支持 § 颜色) |
page.style(id, {background: "#..."}) | 改样式,键名用 camelCase |
page.layout(id, {width: "50%"}) | 改布局 |
page.show(id) / page.hide(id) | 显示 / 隐藏 |
page.progress(id, value) | 设置进度条 |
page.setItem(id, "minecraft:diamond", {orientation: "east", angle: -12}) | 设置 Display Panel |
page.sound("minecraft:ui.button.click") | 播放音效 |
page.open("other") / page.close() / page.closeAnimated(200) | 导航与关闭 |
page.find(id) | 拿到元素本身,配合 wass.ui 做动态操作 |
menus/counter.xml:
<menu id="counter" title="计数器" width="320" height="180">
<panel layout="column" width="100%" height="100%" padding="12" gap="8"
background="#F25A1119" border-color="#FFFF5555" border-width="1" radius="8">
<label id="count_label" text="§e0" width="100%" height="30"
textAlign="center" font-size="16"/>
<row width="100%" height="24" gap="8">
<button id="btn_minus" text="-" flex="1" height="22"/>
<button id="btn_plus" text="+" flex="1" height="22"/>
</row>
<button id="btn_close" text="关闭" width="100%" height="20"/>
</panel>
</menu>js/counter.js:
(function () {
var page = wass.page("counter");
if (!page) {
return;
}
var count = 0;
function render() {
page.text("count_label", "§e" + count);
}
page.onOpen(function () {
count = 0;
render();
page.animateAll("fadeIn", {stagger: 30});
});
page.onClick("btn_plus", function () {
count = count + 1;
render();
});
page.onClick("btn_minus", function () {
count = count - 1;
render();
});
page.onClick("btn_close", function () {
page.closeAnimated(150);
});
})();/wassjs open counter 打开,点加减号应该立刻看到数字变化。这个最小例子就是后面商店的骨架:状态放在闭包里,变化后调用 render() 更新界面。
WassJS 的动画只作用于渲染层,不改布局:元素的位置、大小、点击判定框都不变,所以可以在不触发重排的情况下做旋转、位移、缩放和淡入淡出。
| 属性 | 说明 |
|---|---|
opacity | 0–1,用颜色 tint 实现(文字会一起淡出) |
translateX / translateY | 渲染偏移,单位像素,别名 x / y |
scale / scaleX / scaleY | 渲染缩放,1 为原始大小 |
rotate | 旋转角度(度),顺时针,别名 rotation / angle |
每个动画可以只写自己关心的分量。同一个元素可以同时跑多个动画(例如常驻旋转 + 一次性弹出),它们各自只修改自己负责的分量,不会互相覆盖。
page.animate("card", {
opacity: [0, 1],
translateY: [-8, 0],
scale: [0.96, 1],
duration: 300,
easing: "easeOutCubic"
});
page.animate("icon", {
rotate: [0, 15],
duration: 400,
alternate: true,
loop: 2
});| 参数 | 默认 | 说明 |
|---|---|---|
duration | 300 | 时长(毫秒),30–600000 |
delay | 0 | 延迟(毫秒) |
easing | easeOutCubic | 缓动函数名,见下 |
loop | false | true 无限循环;数字表示次数 |
iterations | 1 | 直接指定次数,-1 为无限 |
alternate | false | 往返播放 |
reverse | false | 反向播放 |
speed | 1.0 | 速度倍率 |
pivot | [0.5, 0.5] | 旋转 / 缩放中心,也接受 "top-left" 等 |
可用缓动:linear、sineInOut、easeInQuad、easeOutQuad、easeInOutQuad、easeInCubic、easeOutCubic、easeInOutCubic、easeOutBack、easeOutExpo。不接受自定义贝塞尔曲线。
大多数场景不用手写关键帧,直接调预设:
page.preset("panel", "popIn", {duration: 380});
page.fadeIn("panel");
page.fadeOut("panel");
page.slideIn("panel", "left", {duration: 360});
page.spin("square", {speed: 60}); // 常驻旋转,度/秒
page.bob("box", {distance: 6}); // 上下浮动
page.animateAll("fadeIn", {stagger: 8}); // 整页所有叶子组件错峰渐入
page.stopAnimation("panel");| 类别 | 预设 |
|---|---|
| 淡入淡出 | fadeIn fadeOut blink |
| 位移 | slideInLeft slideInRight slideInUp slideInDown slideOut* float dropIn |
| 缩放 | popIn popOut zoomIn zoomOut pulse breathe |
| 旋转 | spin spinSlow spinFast spinReverse |
| 强调 | shake |
循环动画只写 loop: true 或 iterations: -1;往返写 alternate: true。旋转类动画建议显式指定 pivot,否则默认以元素中心为轴:
page.animate("badge", {
rotate: [0, 360],
duration: 4000,
loop: true,
pivot: "center"
});
打开页面时让所有组件依次出现,只需要一行:
page.onOpen(function () {
page.animateAll("fadeIn", {stagger: 8, duration: 300});
});关闭时先淡出再关,避免生硬地“啪”一下消失:page.closeAnimated(200)。它会作用于根元素,把整页淡出后延迟关闭。
onOpen 里)。display-panel(别名 item、item-panel、item-icon)用来显示一个物品的 2D 图标,支持原版和模组物品、数量角标、提示文本,并且可以旋转、镜像、缩放。商店的商品图、任务奖励预览、背包速览都可以用它。
<display-panel id="item_diamond"
item="minecraft:diamond"
size="48"
orientation="east"
angle="-12"
tooltip="§b钻石"/>| 属性 | 说明 |
|---|---|
item / item-id | 物品注册名,支持模组物品(mymod:ruby) |
size | 正方形边长;也可用 width / height 单独指定 |
orientation | north/up=0°、east/right=90°、south/down=180°、west/left=270°,支持 northeast 等对角 |
angle / rotation | 在 orientation 之上再叠加的角度 |
count / show-count | 数量角标,例如 count="3" |
show-tooltip | 是否显示提示文本,默认 true |
icon-scale | 图标在面板内的缩放,默认 1 |
mirror / mirror-x / mirror-y | 镜像翻转 |
tooltip | 鼠标悬停文本 |
orientation 与 angle 是叠加关系:orientation="east" angle="-12" 表示先转到 90°,再逆时针回 12°。只想要一个角度时,直接写 angle 也可以。
page.setItem("item_diamond", "minecraft:emerald", {
orientation: "south",
angle: 15,
count: 0 // 0 表示不显示角标
});page.setItem 同时会更新图标纹理、朝向、角度和角标,适合在切换商品、显示奖励时使用。
物品 ID 直接写模组的注册名即可;如果该物品不存在(模组没装、ID 写错),面板会显示一个带红色边框的占位块而不是崩溃。发布整合包前建议在日志里确认没有这类占位。
把商品、价格、文案写死在 XML 里,改一个价格就要动布局文件;放进 JSON 后,XML 只负责“长什么样”,JSON 负责“显示什么”,JS 负责“怎么变”。更实际的好处是:一份 JSON 可以同时驱动多个菜单,例如宝石区、方块区共用同一套商品数据。
文件放在 wass/json/,可以建子目录;登录时随脚本、XML 一起下发,修改后热重载会重新读取。服务端和客户端都能读,因此可以用它做服务端价格校验。
| 调用 | 结果 |
|---|---|
wass.json("shop") | 整个文件(普通 JS 对象) |
wass.json("shop:groups.0.items") | 按冒号路径取值 |
wass.json("shop", "groups.0.items.0.price") | 按点号路径取值 |
wass.getJsonFiles() | 所有 JSON 文件名 |
返回值是普通对象/数组,可以直接 for 循环、下标访问、.name 取值;键不存在时返回 undefined。建议在脚本开头读一次并缓存:var data = wass.json("shop");。
{
"schema": 1,
"currency": "金币",
"shop": {
"title": "§6钻石商店",
"subtitle": "数据来自 wass/json/shop.json"
},
"groups": [
{
"id": "gems",
"title": "宝石区",
"items": [
{
"key": "diamond",
"item": "minecraft:diamond",
"name": "§b钻石",
"price": 120,
"unit": "颗",
"desc": "闪亮而坚硬",
"orientation": "east",
"angle": -12
},
{
"key": "iron",
"item": "minecraft:iron_ingot",
"name": "§f铁锭",
"price": 35,
"unit": "个",
"desc": "最常用的材料",
"orientation": "north",
"angle": 8
}
]
},
{
"id": "blocks",
"title": "方块区",
"items": [
{ "key": "emerald", "item": "minecraft:emerald", "name": "§a绿宝石",
"price": 90, "unit": "颗", "desc": "村民的最爱",
"orientation": "south", "angle": 15 },
{ "key": "gold", "item": "minecraft:gold_ingot", "name": "§6金锭",
"price": 60, "unit": "个", "desc": "好看又好用",
"orientation": "west", "angle": 0 },
{ "key": "redstone", "item": "minecraft:redstone", "name": "§c红石",
"price": 12, "unit": "份", "desc": "红石电路的血液",
"orientation": "northeast", "angle": -20 }
]
}
]
}key 是程序用的稳定标识(和 XML 里的 id 后缀对应),item 是物品注册名,name / price / unit / desc 是展示数据,orientation / angle 直接喂给 Display Panel。字段名可以按你的需要改,只要 JS 读的是同一套字段。
这里说的「用 JSON 创建组件」有四种常见做法,能力和复杂度依次递增。理解它们的区别,才知道什么时候该复制 XML、什么时候该写动态生成。
XML 只放固定数量的占位组件,JS 在 onOpen 里按 JSON 循环填文本、换图标:
var data = wass.json("shop");
var page = wass.page("shop");
if (page && data) {
page.onOpen(function () {
var items = data.groups[0].items;
for (var i = 0; i < items.length; i++) {
var item = items[i];
page.text("name_" + item.key, item.name);
page.text("price_" + item.key, item.price + " " + data.currency + " / " + item.unit);
page.text("desc_" + item.key, item.desc);
page.setItem("item_" + item.key, item.item, {
orientation: item.orientation,
angle: item.angle
});
}
page.text("shop_title", data.shop.title);
});
}优点是简单、可读、布局完全可控;缺点是商品数量固定——JSON 里多一个 item,XML 里就要多一张卡。教程第 8 章的成品用的就是这种模式(两个商品)。
把一张卡抽成 components/product_card.xml,用 <include> 引入:
<!-- components/product_card.xml -->
<panel class="card" layout="column" width="48%" height="104" gap="4">
<row width="100%" height="48" gap="8" alignItems="center">
<display-panel id="item_slot" item="minecraft:stone" size="42"/>
<column flex="1" gap="2">
<label id="card_name" class="title" text="商品" width="100%" height="16"/>
<label id="card_price" class="price" text="0" width="100%" height="12"/>
</column>
</row>
<button id="card_pick" class="btn" text="选择" width="100%" height="18"/>
</panel>这样组件内部的 id 是固定的,同一页面只能引入一次。它适合页头、页脚、单个详情卡;不适合「N 个商品卡」这种重复结构。需要在多处复用时,复制文件并改 id 更稳妥。
不写卡片 XML,只留一个空容器 <row id="product_row"/>,由脚本按 JSON 数组循环创建:
(function () {
var page = wass.page("shop");
var data = wass.json("shop");
if (!page || !data) {
return;
}
page.onOpen(function () {
var host = page.find("product_row");
if (!host) {
return;
}
var items = data.groups[0].items;
for (var i = 0; i < items.length; i++) {
buildCard(host, items[i]);
}
page.animateAll("fadeIn", {stagger: 20});
});
function buildCard(host, item) {
// 卡片:纵向容器
var card = wass.ui.column();
wass.ui.setId(card, "card_" + item.key);
wass.ui.layout(card, {width: "48%", height: 100, gap: 4});
wass.ui.style(card, {
background: "#33FF8888",
borderColor: "#FF6B6B",
borderWidth: 1,
radius: 6,
padding: 6
});
// 顶部:图标 + 名称/价格
var top = wass.ui.row();
wass.ui.layout(top, {width: "100%", height: 48, gap: 8, alignItems: "center"});
var icon = wass.ui.displayPanel(item.item, {
size: 42,
orientation: item.orientation,
angle: item.angle
});
wass.ui.add(top, icon);
var texts = wass.ui.column();
wass.ui.layout(texts, {flex: 1, gap: 2});
var name = wass.ui.label(item.name, {fontSize: 10});
wass.ui.setId(name, "name_" + item.key);
var price = wass.ui.label(item.price + " " + data.currency, {
fontSize: 9,
textColor: "#FFD166"
});
wass.ui.setId(price, "price_" + item.key);
wass.ui.add(texts, name);
wass.ui.add(texts, price);
wass.ui.add(top, texts);
wass.ui.add(card, top);
// 选择按钮
var pick = wass.ui.button("选择", function () {
wass.ui.style(card, {background: "#66FF5555"});
wass.ui.text("selected_label", "当前商品:" + item.name);
wass.ui.setId(card, "card_" + item.key);
});
wass.ui.layout(pick, {width: "100%", height: 18});
wass.ui.add(card, pick);
wass.ui.add(host, card);
}
})();动态创建的元素不在页面构建时扫描,因此 page.onClick("id") 绑不到它们;要在创建时直接用 wass.ui.onClick(element, fn),或者用闭包在按钮回调里处理。需要后续改文本时,先 wass.ui.setId(element, "xxx"),再用 page.text("xxx", ...)。
把「卡片的 DOM 结构」做成一个 JS 函数(即上面的 buildCard),JSON 只提供数据,XML 只保留页面骨架(标题、容器、底部按钮)。这样增删商品只需改 JSON,布局样式仍集中在 JS 函数里。缺点是布局调整要改代码,而不是改 XML。
实际项目里常见的组合是:页面骨架用 XML,列表用 JS 工厂,数据用 JSON。第 8 章的成品为了可读性用了模式一;如果商品会经常增删,把它换成 6.5.3 的循环即可。
| 模式 | 商品数量可变 | 布局可改 XML | 复杂度 | 适用 |
|---|---|---|---|---|
| 数据绑定 | 否 | 是 | 低 | 固定几个商品 / 详情页 |
| 组件 include | 否 | 是(组件文件) | 低 | 页头页脚、单张卡 |
| JS 动态创建 | 是 | 否(改 JS) | 中 | 商品多、列表/背包 |
| 卡片工厂 | 是 | 部分 | 中 | 列表 + 统一交互 |
两个菜单分别读同一份 JSON 的不同分组即可,不需要复制数据:
// js/shop_blocks.js
var data = wass.json("shop");
var page = wass.page("shop_blocks");
if (page && data) {
page.onOpen(function () {
var group = data.groups[1]; // 第二组:方块区
var items = group.items;
for (var i = 0; i < items.length; i++) {
var item = items[i];
page.text("name_" + item.key, item.name);
page.text("price_" + item.key, item.price + " " + data.currency + " / " + item.unit);
page.setItem("item_" + item.key, item.item, {
orientation: item.orientation,
angle: item.angle
});
}
});
}JSON 是手写的,最容易出现结尾多逗号、引号不配对、字段层级放错。读不到数据时先看日志:解析失败会给出行号;wass.json 返回 undefined 通常是文件名或路径写错。在 JS 里养成习惯:
var data = wass.json("shop");
if (!data || !data.groups) {
wass.log("shop.json 缺少 groups");
return;
}wass.on("事件名", fn) 注册全局事件,交互后由引擎调用:
| 事件名 | 时机 | 端 |
|---|---|---|
itemRightClick | 右键配置的物品(默认时钟) | 客户端 |
clockRightClick | 右键时钟(兼容事件) | 客户端 |
menuOpen | 菜单打开 | 双端 |
menuClose | 菜单关闭 | 双端 |
menuAction | 动作执行完成并广播 | 双端 |
reload | 脚本 / XML / JSON 重载完成 | 双端 |
itemRightClick 的返回值可以是菜单 id(打开它)、false(取消),或者 {cancel: true}。例如让时钟打开商店:
wass.on("itemRightClick", function (ctx) {
if (ctx.itemId === "minecraft:clock") {
return "shop";
}
});1玩家点击带有 action 的按钮(或脚本调用 wass.ui.sendAction);
2客户端把 菜单 id / actionId / elementId / payload 发给服务端;
3服务端找到脚本注册的同名动作函数并执行(这里可以读配置、查余额、执行命令);
4函数返回值原样回传;客户端触发 page.onAction(actionId, fn) 与全局 menuAction;
5脚本把结果显示在界面上。
wass.registerAction("shop", "buy", function (ctx) {
var payload = ctx.payload == null ? "" : String(ctx.payload); // "diamond:3"
var parts = payload.split(":");
var key = parts[0];
var quantity = parseInt(parts[1], 10);
if (!quantity || quantity < 1) {
quantity = 1;
}
var data = wass.json("shop");
var item = null;
for (var g = 0; g < data.groups.length; g++) {
for (var i = 0; i < data.groups[g].items.length; i++) {
if (data.groups[g].items[i].key === key) {
item = data.groups[g].items[i];
}
}
}
if (!item) {
return "§c商品不存在:" + key;
}
var coins = item.price * quantity;
var command = "say Player" + ctx.name + " purchased " + quantity + " "
+ item.item + ", spending " + coins + " coins in total!";
if (ctx.player && ctx.player.hasPermissions(2)) {
wass.runCommand(command); // 以玩家身份执行(需要 OP)
} else {
wass.console(command); // 以控制台身份执行(不需要 OP)
}
wass.log("[shop] " + command);
return "§a已购买 §f" + quantity + " §e" + item.name
+ " §7(" + item.item + "),共花费 " + coins + " " + data.currency;
});ctx 在动作里包含 player、name、uuid、menuId、actionId、elementId、payload。返回值会作为 ctx.result 传回客户端。
// 点击购买
page.onClick("btn_buy", function () {
wass.ui.sendAction("buy", "btn_buy", state.selectedKey + ":" + state.quantity);
});
// 接收服务端结果
page.onAction("buy", function (ctx) {
page.text("shop_status", ctx.result == null ? "" : String(ctx.result));
});wass.ui.sendAction 的参数是 (actionId, elementId, payload),菜单 id 由当前页面自动带入。
key 查价格,绝不使用客户端传来的价格;try / catch 包住可能失败的调用,返回可读的错误文本;/say Player<玩家名> purchased <数量> <物品ID>, spending <总价> coins in total!,并把结果回显到界面;wass/json/shop.json。与开发版相比,最终版删掉了文本框、开关、进度条、图片和 Display Panel 演示行这些调试控件,只保留商品卡、数量区、状态行与底部按钮。图 8-1 是开发中的完整界面,用来说明布局关系;其下半部分的调试区在最终代码里已经移除。

| 文件 | 内容 |
|---|---|
wass/json/shop.json | 货币、标题、两组商品数据 |
wass/menus/shop.xml | 商店页面:页头、两张卡、数量区、底部按钮 |
wass/js/shop.js | 读取 JSON、选择商品、数量联动、购买动作、动画 |
{
"schema": 1,
"currency": "金币",
"shop": {
"title": "§6钻石商店",
"subtitle": "数据来自 wass/json/shop.json"
},
"groups": [
{
"id": "gems",
"title": "宝石区",
"items": [
{
"key": "diamond",
"item": "minecraft:diamond",
"name": "§b钻石",
"price": 120,
"unit": "颗",
"desc": "闪亮而坚硬",
"orientation": "east",
"angle": -12
},
{
"key": "iron",
"item": "minecraft:iron_ingot",
"name": "§f铁锭",
"price": 35,
"unit": "个",
"desc": "最常用的材料",
"orientation": "north",
"angle": 8
}
]
}
]
}<menu id="shop" title="钻石商店" width="720" height="360">
<style>
.panel { background: #F25A1119; border-color: #FFFF5555; border-width: 1; radius: 8; }
.card { background: #33FF8888; border-color: #FF6B6B; border-width: 1; radius: 6; padding: 6; }
.card-active { background: #66FF5555; border-color: #FFAAAA; border-width: 2; radius: 6; padding: 6; }
.btn { background: #FF8E1B1B; border-color: #FFFF5555; border-width: 1; radius: 4;
text-color: #FFFFFF; font-size: 9; text-shadow: false; }
.btn-accent { background: #FFB71C1C; border-color: #FFFF8888; border-width: 1; radius: 4;
text-color: #FFFFFF; font-size: 9; text-shadow: false; }
.title { text-color: #FFF6EDED; font-size: 15; text-shadow: false; }
.section { text-color: #FFFFE7E0; font-size: 10; text-shadow: false; }
.muted { text-color: #FFFFEFE8; font-size: 9; text-shadow: false; }
.price { text-color: #FFFFD166; font-size: 9; text-shadow: false; }
</style>
<panel class="panel" layout="column" width="100%" height="100%" padding="10" gap="8">
<!-- 页头 -->
<row width="100%" height="34" gap="8" alignItems="center">
<column flex="1" gap="2">
<label id="shop_title" class="title" text="§6钻石商店" width="100%" height="18"/>
<label id="shop_subtitle" class="muted" text="数据来自 wass/json/shop.json"
width="100%" height="12"/>
</column>
<label id="shop_badge" class="section" text="SHOP" width="70" height="14" textAlign="right"/>
</row>
<!-- 商品卡 -->
<row id="product_row" width="100%" height="112" gap="8">
<panel id="card_diamond" class="card-active" layout="column" width="48%" height="100%" gap="4">
<row width="100%" height="52" gap="8" alignItems="center">
<display-panel id="item_diamond" item="minecraft:diamond" size="44"
orientation="east" angle="-12" tooltip="§b钻石"/>
<column flex="1" gap="2">
<label id="name_diamond" class="title" text="§b钻石" width="100%" height="16"/>
<label id="price_diamond" class="price" text="120 金币 / 颗" width="100%" height="12"/>
<label id="desc_diamond" class="muted" text="闪亮而坚硬" width="100%" height="11"/>
</column>
</row>
<button id="pick_diamond" class="btn" text="选择钻石" width="100%" height="20"/>
</panel>
<panel id="card_iron" class="card" layout="column" width="48%" height="100%" gap="4">
<row width="100%" height="52" gap="8" alignItems="center">
<display-panel id="item_iron" item="minecraft:iron_ingot" size="44"
orientation="north" angle="8" tooltip="§f铁锭"/>
<column flex="1" gap="2">
<label id="name_iron" class="title" text="§f铁锭" width="100%" height="16"/>
<label id="price_iron" class="price" text="35 金币 / 个" width="100%" height="12"/>
<label id="desc_iron" class="muted" text="最常用的材料" width="100%" height="11"/>
</column>
</row>
<button id="pick_iron" class="btn" text="选择铁锭" width="100%" height="20"/>
</panel>
</row>
<!-- 数量与总计 -->
<panel class="card" layout="column" width="100%" height="78" gap="4">
<label id="selected_label" class="section" text="当前商品:钻石" width="100%" height="14"/>
<row width="100%" height="16" gap="8" alignItems="center">
<label id="qty_label" class="muted" text="购买数量:1" width="110" height="14"/>
<slider id="qty_slider" flex="1" height="14" min="1" max="64" value="1"/>
</row>
<label id="total_label" class="price" text="总计:120 金币" width="100%" height="14"/>
</panel>
<label id="shop_status" class="muted" text="§7选择商品后调整数量,再点“立即购买”。"
width="100%" height="14"/>
<!-- 底部按钮 -->
<row width="100%" height="22" gap="8" alignItems="center">
<button id="btn_buy" class="btn-accent" text="§a立即购买" flex="1" height="20"/>
<button id="btn_close" class="btn" text="§c关闭" flex="1" height="20"/>
</row>
</panel>
</menu>(function () {
var data = wass.json("shop");
var page = wass.page("shop");
var state = {
selectedKey: data && data.groups ? data.groups[0].items[0].key : "diamond",
quantity: 1
};
function findItem(key) {
if (!data || !data.groups) {
return null;
}
for (var g = 0; g < data.groups.length; g++) {
var items = data.groups[g].items;
for (var i = 0; i < items.length; i++) {
if (items[i].key === key) {
return items[i];
}
}
}
return null;
}
function currency() {
return data && data.currency ? data.currency : "金币";
}
function refresh() {
var item = findItem(state.selectedKey);
if (!item || !page) {
return;
}
page.text("selected_label", "当前商品:" + item.name
+ " §8(" + item.item + ")");
page.text("qty_label", "购买数量:§e" + state.quantity);
page.text("total_label", "总计:§e" + (item.price * state.quantity)
+ " §7" + currency());
}
function highlight() {
page.style("card_diamond", {
background: state.selectedKey === "diamond" ? "#66FF5555" : "#33FF8888"
});
page.style("card_iron", {
background: state.selectedKey === "iron" ? "#66FF5555" : "#33FF8888"
});
}
function select(key) {
state.selectedKey = key;
highlight();
refresh();
page.sound("minecraft:ui.button.click");
}
function applyData() {
if (!page || !data) {
return;
}
var items = data.groups[0].items;
page.text("shop_title", data.shop.title);
page.text("shop_subtitle", data.shop.subtitle);
for (var i = 0; i < items.length; i++) {
var item = items[i];
page.text("name_" + item.key, item.name);
page.text("price_" + item.key,
"§e" + item.price + " §7" + currency() + " / " + item.unit);
page.text("desc_" + item.key, item.desc);
page.setItem("item_" + item.key, item.item, {
orientation: item.orientation,
angle: item.angle
});
}
highlight();
refresh();
}
if (page && data) {
page.onOpen(function () {
applyData();
page.animateAll("fadeIn", {stagger: 8, duration: 300});
});
page.onClick("pick_diamond", function () { select("diamond"); });
page.onClick("pick_iron", function () { select("iron"); });
page.onChange("qty_slider", function (ctx) {
state.quantity = Math.round(ctx.value);
refresh();
});
page.onClick("btn_buy", function () {
wass.ui.sendAction("buy", "btn_buy",
state.selectedKey + ":" + state.quantity);
});
page.onClick("btn_close", function () {
page.closeAnimated(200);
});
page.onAction("buy", function (ctx) {
page.text("shop_status", ctx.result == null ? "" : String(ctx.result));
});
}
// 服务端动作:/say Player<name> purchased <qty> <item>, spending <coins> coins in total!
wass.registerAction("shop", "buy", function (ctx) {
var parts = String(ctx.payload == null ? "" : ctx.payload).split(":");
var key = parts[0];
var quantity = parseInt(parts.length > 1 ? parts[1] : "1", 10);
if (!quantity || quantity < 1) {
quantity = 1;
}
var item = findItem(key);
if (!item) {
return "§c商品不存在:" + key;
}
var coins = item.price * quantity;
var command = "say Player" + ctx.name + " purchased " + quantity + " "
+ item.item + ", spending " + coins + " coins in total!";
if (ctx.player && ctx.player.hasPermissions(2)) {
wass.runCommand(command);
} else {
wass.console(command);
}
wass.log("[shop] " + command);
return "§a已购买 §f" + quantity + " §e" + item.name
+ " §7(" + item.item + "),共花费 " + coins + " " + currency();
});
})();把三个文件放到服务端 wass/ 对应目录,执行 /wassjs reload,然后 /wassjs open shop。如果想让 /wassjs 直接打开商店,把 config/wassjs.toml 里的 commandMenu 改成 shop。
| 检查项 | 预期 |
|---|---|
| 打开页面 | 所有组件依次渐入,两张卡片显示物品图标 |
| 点击卡片 | 卡片高亮,顶部“当前商品”跟着变化,播放点击音效 |
| 拖动滑条 | 数量与总价实时变化 |
| 点击购买 | 聊天栏出现 /say Player<名字> purchased ... 文本,界面回显购买结果 |
| 点击关闭 | 整页淡出后关闭 |
| 日志 | 没有 Script error,/wassjs status 的 errors 为 0 |
groups 做多个菜单,或做一个分类按钮切换 groups 索引;coins 的计算,客户端只负责显示;page.onVariableChange 同步到界面。| 形态 | 你需要的 | 能做什么 |
|---|---|---|
| 纯内容包 | 只改服务端 wass/ | 换界面、加菜单、加数据,不写 Java |
| 附属模组(脚本) | 一个 Forge mod + WassJSBridge.registerScript | 随模组分发自己的页面与逻辑 |
| 附属模组(Java 能力) | 再加 registerFunction | 把经济、任务、背包等 Java API 暴露给 JS |
下面做一个完整的附属模组:注册一个 JS 页面、一个 Java 函数(查询余额),并让时钟打开它。
example-addon/
├── build.gradle
├── gradle.properties
├── settings.gradle
├── libs/
│ └── wassjs-1.0.0.jar
└── src/main/
├── java/com/example/addon/
│ ├── ExampleAddon.java
│ └── AddonContent.java
└── resources/
├── META-INF/mods.toml
└── pack.mcmetaplugins {
id 'eclipse'
id 'idea'
id 'net.minecraftforge.gradle' version '[6.0,6.2)'
}
version = '1.0.0'
group = 'com.example.exampleaddon'
base { archivesName = 'exampleaddon' }
minecraft {
mappings channel: 'official', version: '1.20.1'
}
repositories {
flatDir { dirs 'libs' }
}
dependencies {
minecraft 'net.minecraftforge:forge:1.20.1-47.4.6'
// 开发环境:把 wassjs-1.0.0.jar 放进 libs/
implementation fg.deobf(files('libs/wassjs-1.0.0.jar'))
// 发布到 maven 后可以改成:
// implementation fg.deobf('com.wassjs:wassjs:1.0.0')
}
java.toolchain.languageVersion = JavaLanguageVersion.of(17)modLoader = "javafml"
loaderVersion = "[47,)"
license = "MIT"
[[mods]]
modId = "exampleaddon"
version = "1.0.0"
displayName = "Example Addon"
description = "WassJS 附属模组示例"
[[dependencies.exampleaddon]]
modId = "forge"
mandatory = true
versionRange = "[47,)"
ordering = "NONE"
side = "BOTH"
[[dependencies.exampleaddon]]
modId = "minecraft"
mandatory = true
versionRange = "[1.20.1,1.21)"
ordering = "NONE"
side = "BOTH"
[[dependencies.exampleaddon]]
modId = "wassjs"
mandatory = true
versionRange = "[1.0.0,)"
ordering = "AFTER"
side = "BOTH"side = "BOTH" 很重要:界面在客户端构建,动作在服务端执行,所以附属模组必须同时装在客户端和服务端。package com.example.addon;
import net.minecraftforge.common.MinecraftForge;
import net.minecraftforge.eventbus.api.IEventBus;
import net.minecraftforge.fml.common.Mod;
import net.minecraftforge.fml.event.lifecycle.FMLCommonSetupEvent;
import net.minecraftforge.fml.javafmlmod.FMLJavaModLoadingContext;
@Mod(ExampleAddon.MOD_ID)
public final class ExampleAddon {
public static final String MOD_ID = "exampleaddon";
public ExampleAddon() {
IEventBus modBus = FMLJavaModLoadingContext.get().getModEventBus();
modBus.addListener(this::commonSetup);
MinecraftForge.EVENT_BUS.register(this);
}
private void commonSetup(FMLCommonSetupEvent event) {
// 在 mod 加载完成后注册,避免 WassJS 尚未初始化
event.enqueueWork(AddonContent::register);
}
}注册要放在 FMLCommonSetupEvent 的 enqueueWork 里:此时 WassJS 的脚本管理器已经创建,注册的脚本会在下一次重载时被执行。
package com.example.addon;
import com.wassjs.api.WassJSBridge;
import net.minecraftforge.fml.loading.FMLPaths;
import java.nio.file.Path;
public final class AddonContent {
private AddonContent() {
}
public static void register() {
// 1) 一个 Java 函数,脚本里用 wass.ext.call("exampleaddon.balance") 调用
WassJSBridge.registerFunction("exampleaddon.balance", (call, args) -> 1234);
// 2) 一段随模组分发的 JS:注册页面 + 右键时钟打开
WassJSBridge.registerScript("exampleaddon", "menu.js", SCRIPT);
// 3) 允许整合包在 config/exampleaddon/wassjs/ 里追加脚本
Path extra = FMLPaths.CONFIGDIR.get().resolve("exampleaddon/wassjs");
WassJSBridge.registerDirectory(extra);
}
private static final String SCRIPT = """
(function () {
wass.registerMenu("exampleaddon:home", {
title: "示例附属窗口",
width: 360,
height: 220,
build: function (ui) {
ui.label("§a来自附属模组", {fontSize: 12});
ui.label("当前余额:" + wass.ext.call("exampleaddon.balance"), {fontSize: 9});
ui.label("这个窗口完全由 Java 注册的脚本创建。", {fontSize: 9});
ui.button("关闭", function () {
wass.closeMenu();
});
}
});
wass.on("itemRightClick", function (ctx) {
if (ctx.itemId === "minecraft:clock") {
return "exampleaddon:home";
}
});
})();
""";
}registerMenu 的 build(ui) 会在客户端构建界面时调用,ui 提供 label、button、row、column、slider、textField 等方法,适合写少量、稳定的窗口。复杂页面仍然建议把 XML 放进整合包的 wass/menus/。
| 方式 | 调用 | 说明 |
|---|---|---|
| 命令 | /wassjs open exampleaddon:home | 菜单已注册即可,OP 可用 |
| Java(服务端) | WassJSBridge.openMenu(player, "exampleaddon:home") | 适合任务完成、进服欢迎 |
| JS(客户端) | wass.openMenu("exampleaddon:home") | 适合纯客户端按钮 |
// 服务端:玩家完成某事时弹窗
WassJSBridge.openMenu(serverPlayer, "exampleaddon:home");
// 客户端脚本:打开并刷新
wass.openMenu("exampleaddon:home");
wass.refreshMenu();Java 也可以触发页面上的服务端动作,例如外部系统扣款后刷新商店:
WassJSBridge.runAction(player, "shop", "buy", "diamond:1");
WassJSBridge.refreshMenu(player);./gradlew build 生成 build/libs/exampleaddon-1.0.0.jar;mods.toml 里声明对 wassjs 的依赖,玩家缺少前置时会得到明确提示;wass/ 内容打进 jar——它属于服务端游戏目录;| 现象 | 原因 / 处理 |
|---|---|
| 菜单打不开 | registerMenu 在客户端没执行:确认模组装在客户端,且注册在 common setup |
| 动作没反应 | 动作只注册在客户端;registerAction 要在服务端也执行 |
脚本里 wass.page 为 null | 服务端没有界面,属正常;判空即可 |
| 函数调用报错 | wass.ext.call 的名字要和 Java 注册名完全一致(含命名空间) |
| 重载后菜单消失 | 重载会重建作用域,registerScript 注册的脚本会自动重跑,不要手动清空 |
| 字段 | 类型 | 说明 |
|---|---|---|
currency | string | 货币名称,显示用 |
shop.title / shop.subtitle | string | 页头标题与副标题,支持 § 颜色 |
groups[] | array | 商品分组,一份 JSON 可以有多组 |
groups[].id | string | 分组标识 |
groups[].title | string | 分组标题 |
groups[].items[] | array | 商品列表 |
items[].key | string | 稳定标识,用于 id 后缀与动作 payload |
items[].item | string | 物品注册名,支持模组物品 |
items[].name | string | 显示名称,支持 § 颜色 |
items[].price | number | 单价(服务端计算总价) |
items[].unit | string | 单位,例如 颗 / 个 / 份 |
items[].desc | string | 一句话描述 |
items[].orientation | string | 图标朝向:north/east/south/west 或对角 |
items[].angle | number | 在朝向上的额外角度 |
| 名称 | 注册方式 | 触发时机 |
|---|---|---|
itemRightClick | wass.on | 右键配置物品;返回菜单 id 打开 |
clockRightClick | wass.on | 右键时钟 |
menuOpen / menuClose | wass.on | 菜单打开 / 关闭 |
menuAction | wass.on | 动作结果广播 |
reload | wass.on | 重载完成 |
onOpen / onClose | page.* | 页面生命周期 |
onClick | page.* | 点击元素 |
onChange | page.* | 文本框 / 开关 / 滑条变化 |
onAction | page.* | 当前页面的动作结果 |
onVariableChange | page.* | 服务端变量更新 |
未来荧黑的行高是 1.448 em、汉字 advance 约 9.67 px,而游戏按 9 px 行高排版;子集外的字符会回退到原版 unifont,两套字体的 advance 与 ascent 不同,混排时就会出现上下/左右偏移。中文标点(,。:)的字形重心与汉字不同,也会显得“跳”。这是字体度量问题,不是 XML 写错。
TTF 只按 size × oversample 烘焙一次,其它字号是对位图重采样;页面里的 font-size 是相对 9 px 行高缩放,非 9 的整数倍都会重采样。再加上 SDF 的固定 em=64、sharpness=2.0,小字号笔画会灰、大字号边缘会软。把关键文字统一到 9 或 18(两倍),会明显更清晰。
颜色是 #AARRGGBB:#33FF8888 是 20% 透明;想要不透明用 6 位(#FF8888)或 alpha 写 FF。color 是元素着色,文字颜色要用 text-color。
onOpen 里——页面还没打开时元素不存在;page.animate 对找不到的元素只记一条警告。wass/json/ 且扩展名是 .json;/wassjs reload 后再打开页面(脚本在加载时读取数据)。/wassjs status 里 scripts 数量正确;wass.runCommand 会失败,改用 wass.console;page.onAction 显示,日志里应有 [shop] say ...。教程内容整理自《WassJS 菜单教程》· 配套 WassJS 1.0.0