返回首页
Wass Workspace

项目作品

这里收录我制作的 Minecraft 模组、工具与开发教程。选择一个项目,查看它的说明与完整文档。

📦 共 1 个项目 Static · Online
🧩
模组 / 教程

WassJS 菜单教程

从 XML 页面到动画、JSON 组件、服务端购买与附属模组,一份可以直接照着做出完整商店系统的 WassJS 开发教程。

Minecraft 1.20.1Forge 47.xWassJS 1.0.0JavaScript
✦
更多项目筹备中

新的模组、工具与教程会陆续出现在这里。

Wass · Minecraft 模组开发 / 服务器工具
本页为静态展示,教程内容持续更新。

WassJS · Mod Development Guide

WassJS商店系统开发教程

从 XML 页面到动画、JSON 组件、服务端购买与附属模组

适用环境Minecraft 1.20.1 · Forge 47.x · Java 17配套版本WassJS 1.0.0(LDLib2 2.2.43)读者对象会写一点 JavaScript、想快速做出菜单的整合包 / 模组作者文档版本1.0 · 2026-11
📌
本教程的代码与示例商店来自真实可运行的项目 E:\Minecraft_mods_workspace\wassjs,按章节顺序阅读即可从零做出一个带数量滑条、实时总价和 /say 购买播报的商店系统;第 6 章讲 JSON 如何驱动和生成组件,第 9 章讲如何把功能做成独立附属模组。较长的代码清单会跨页显示,续页直接从断点继续,按顺序拼接即可。
Chapter 01

第 1 章 认识 WassJS:结构、加载流程与调试#

1.1 它解决什么问题#

在原版 Minecraft 里做界面,要么写大量 Java 代码,要么依赖特定的 GUI 库;改一次布局就要重新编译。WassJS 把「界面长什么样」交给 XML,「界面怎么动」交给 JavaScript,「界面显示什么数据」交给 JSON,三者都放在服务端的 wass/ 目录里,登录后自动下发给客户端。

因此它适合这些场景:

  • 整合包里做一个商店、菜单、任务面板,改 XML 就能改布局,/wassjs reload 即可生效;
  • 服务器统一管理界面内容,玩家客户端不需要装额外的资源包;
  • 其他模组通过 WassJSBridge 注册自己的 JS 页面、Java 函数,或直接打开 WassJS 的窗口。
💡
提示 WassJS 的内容以服务端为准。单人游戏的「服务端」就是同一游戏目录下的 wass/;联机时以服务器上的 wass/ 为准,客户端只负责显示。

1.2 一次「打开菜单」发生了什么#

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。

1.3 目录与文件职责#

路径作用是否下发
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 页面)方式。

1.4 环境准备#

依赖版本
Minecraft1.20.1
Forge47.x(开发用 47.4.6)
Java17
LDLib22.2.43
WassJS1.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 并通知客户端
💡
提示 改完 XML 或 JS 后通常不需要重启游戏:保存文件会自动热重载并重新打开当前菜单;如果没反应,先看日志里的 [WassJS] 行和 /wassjs status 的 errors 计数。
Chapter 02

第 2 章 用 XML 描述界面:标签、布局与样式#

2.1 第一个页面#

在 wass/menus/ 下新建 hello.xml:

HTML / 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>
wass/menus/hello.xml

<menu> 的 id 就是菜单 id,也是 /wassjs open 的参数;width、height 是窗口的初始大小。窗口不会超过屏幕,超出时自动缩小。

对应脚本只要一行就能让按钮生效:

JavaScript
var page = wass.page("hello");
if (page) {
    page.onClick("btn_close", function () { page.close(); });
}
wass/js/hello.js

2.2 标签与属性#

标签说明
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。

2.3 布局模型#

布局是 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" 让它占据剩余宽度。教程里需要固定宽度的列(例如数量文字)才写具体像素。

2.4 样式:class、颜色与字体#

<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 可以去掉原版描边,在深色背景上更干净。

HTML / XML
<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>

2.5 按钮的四种行为#

写法行为示例
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" 换成别的音效。

2.6 组件 include#

components/ 下的 XML 不是独立菜单,只能被 <include src="components/xxx.xml"/> 引入,相当于把那段 XML 原地展开。适合页头、页脚这类只出现一次的片段。

HTML / 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/ 下;放错位置会被当成菜单解析并在日志里报错。

2.7 阶段练习#

用上面的知识写出商店的骨架:一个页头、两张商品卡(含 Display Panel 图标和选择按钮)、一个数量面板(滑条 + 总计)、一个底部购买按钮。先只写 XML,不加任何逻辑,确认排版正确后再进入第 3 章。

Chapter 03

第 3 章 用 JavaScript 驱动页面#

3.1 页面对象#

每个菜单对应一个页面绑定器,用 wass.page("菜单 id") 获取。脚本在服务端也会执行,此时 wass.page 返回 null,所以所有页面代码都要判空:

JavaScript
(function () {
    var page = wass.page("shop");
    if (!page) {
        return;            // 服务端没有界面,直接退出
    }
    // 客户端逻辑写在这里
})();

外层用立即执行函数(IIFE)包起来,可以避免多个脚本之间同名函数互相覆盖——这是多页面项目最常见的问题之一。

3.2 生命周期#

回调触发时机常见用途
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。

3.3 读写 API#

方法作用
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 做动态操作

3.4 一个完整的计数器#

menus/counter.xml:

HTML / 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>
wass/menus/counter.xml

js/counter.js:

JavaScript
(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);
    });
})();
wass/js/counter.js

/wassjs open counter 打开,点加减号应该立刻看到数字变化。这个最小例子就是后面商店的骨架:状态放在闭包里,变化后调用 render() 更新界面。

Chapter 04

第 4 章 动画系统:旋转、平移、缩放与预设#

4.1 动画模型#

WassJS 的动画只作用于渲染层,不改布局:元素的位置、大小、点击判定框都不变,所以可以在不触发重排的情况下做旋转、位移、缩放和淡入淡出。

属性说明
opacity0–1,用颜色 tint 实现(文字会一起淡出)
translateX / translateY渲染偏移,单位像素,别名 x / y
scale / scaleX / scaleY渲染缩放,1 为原始大小
rotate旋转角度(度),顺时针,别名 rotation / angle

每个动画可以只写自己关心的分量。同一个元素可以同时跑多个动画(例如常驻旋转 + 一次性弹出),它们各自只修改自己负责的分量,不会互相覆盖。

4.2 基本用法#

JavaScript
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
});
参数默认说明
duration300时长(毫秒),30–600000
delay0延迟(毫秒)
easingeaseOutCubic缓动函数名,见下
loopfalsetrue 无限循环;数字表示次数
iterations1直接指定次数,-1 为无限
alternatefalse往返播放
reversefalse反向播放
speed1.0速度倍率
pivot[0.5, 0.5]旋转 / 缩放中心,也接受 "top-left" 等

可用缓动:linear、sineInOut、easeInQuad、easeOutQuad、easeInOutQuad、easeInCubic、easeOutCubic、easeInOutCubic、easeOutBack、easeOutExpo。不接受自定义贝塞尔曲线。

4.3 内置预设#

大多数场景不用手写关键帧,直接调预设:

JavaScript
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

4.4 循环、往返与中心点#

循环动画只写 loop: true 或 iterations: -1;往返写 alternate: true。旋转类动画建议显式指定 pivot,否则默认以元素中心为轴:

JavaScript
page.animate("badge", {
    rotate: [0, 360],
    duration: 4000,
    loop: true,
    pivot: "center"
});
教程配图
图 4-1 动画演示页:左侧方块常驻旋转、紫色圆上下浮动、青色方块呼吸缩放

4.5 整页渐入与渐出关闭#

打开页面时让所有组件依次出现,只需要一行:

JavaScript
page.onOpen(function () {
    page.animateAll("fadeIn", {stagger: 8, duration: 300});
});

关闭时先淡出再关,避免生硬地“啪”一下消失:page.closeAnimated(200)。它会作用于根元素,把整页淡出后延迟关闭。

4.6 注意事项#

  • 同一个元素重复触发同一个预设会替换旧动画;不同预设可以共存(旋转 + 缩放 + 淡入)。
  • 透明用 tint 实现,文字颜色会一起变淡;不要在深色文字上叠加很低的 opacity。
  • 位移动画不改点击判定框,动画过程中点击位置仍是原来的位置。
  • 页面关闭时动画会被清空;重开页面需要重新启动常驻动画(写在 onOpen 里)。
Chapter 05

第 5 章 Display Panel:任意物品的 2D 图标#

5.1 它是什么#

display-panel(别名 item、item-panel、item-icon)用来显示一个物品的 2D 图标,支持原版和模组物品、数量角标、提示文本,并且可以旋转、镜像、缩放。商店的商品图、任务奖励预览、背包速览都可以用它。

5.2 XML 写法#

HTML / XML
<display-panel id="item_diamond"
               item="minecraft:diamond"
               size="48"
               orientation="east"
               angle="-12"
               tooltip="§b钻石"/>
属性说明
item / item-id物品注册名,支持模组物品(mymod:ruby)
size正方形边长;也可用 width / height 单独指定
orientationnorth/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 也可以。

5.3 运行时切换#

JavaScript
page.setItem("item_diamond", "minecraft:emerald", {
    orientation: "south",
    angle: 15,
    count: 0          // 0 表示不显示角标
});

page.setItem 同时会更新图标纹理、朝向、角度和角标,适合在切换商品、显示奖励时使用。

5.4 模组物品与占位#

物品 ID 直接写模组的注册名即可;如果该物品不存在(模组没装、ID 写错),面板会显示一个带红色边框的占位块而不是崩溃。发布整合包前建议在日志里确认没有这类占位。

Chapter 06

第 6 章 JSON 数据与「用 JSON 创建组件」#

6.1 为什么把数据放进 JSON#

把商品、价格、文案写死在 XML 里,改一个价格就要动布局文件;放进 JSON 后,XML 只负责“长什么样”,JSON 负责“显示什么”,JS 负责“怎么变”。更实际的好处是:一份 JSON 可以同时驱动多个菜单,例如宝石区、方块区共用同一套商品数据。

6.2 位置与加载#

文件放在 wass/json/,可以建子目录;登录时随脚本、XML 一起下发,修改后热重载会重新读取。服务端和客户端都能读,因此可以用它做服务端价格校验。

6.3 读取 API#

调用结果
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");。

6.4 设计一份商店数据#

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
        }
      ]
    },
    {
      "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 }
      ]
    }
  ]
}
wass/json/shop.json

key 是程序用的稳定标识(和 XML 里的 id 后缀对应),item 是物品注册名,name / price / unit / desc 是展示数据,orientation / angle 直接喂给 Display Panel。字段名可以按你的需要改,只要 JS 读的是同一套字段。

6.5 用 JSON 创建组件#

这里说的「用 JSON 创建组件」有四种常见做法,能力和复杂度依次递增。理解它们的区别,才知道什么时候该复制 XML、什么时候该写动态生成。

6.5.1 模式一:数据绑定(推荐入门)#

XML 只放固定数量的占位组件,JS 在 onOpen 里按 JSON 循环填文本、换图标:

JavaScript
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 章的成品用的就是这种模式(两个商品)。

6.5.2 模式二:XML 组件模板 + include#

把一张卡抽成 components/product_card.xml,用 <include> 引入:

HTML / XML
<!-- 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 更稳妥。

6.5.3 模式三:JS 动态创建(真正由 JSON 生成)#

不写卡片 XML,只留一个空容器 <row id="product_row"/>,由脚本按 JSON 数组循环创建:

JavaScript
(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", ...)。

6.5.4 模式四:卡片工厂(JSON + JS + 少量 XML,推荐做列表)#

把「卡片的 DOM 结构」做成一个 JS 函数(即上面的 buildCard),JSON 只提供数据,XML 只保留页面骨架(标题、容器、底部按钮)。这样增删商品只需改 JSON,布局样式仍集中在 JS 函数里。缺点是布局调整要改代码,而不是改 XML。

实际项目里常见的组合是:页面骨架用 XML,列表用 JS 工厂,数据用 JSON。第 8 章的成品为了可读性用了模式一;如果商品会经常增删,把它换成 6.5.3 的循环即可。

6.5.5 四种模式怎么选#

模式商品数量可变布局可改 XML复杂度适用
数据绑定否是低固定几个商品 / 详情页
组件 include否是(组件文件)低页头页脚、单张卡
JS 动态创建是否(改 JS)中商品多、列表/背包
卡片工厂是部分中列表 + 统一交互

6.6 一份 JSON 驱动多个菜单#

两个菜单分别读同一份 JSON 的不同分组即可,不需要复制数据:

JavaScript
// 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
            });
        }
    });
}

6.7 容错#

JSON 是手写的,最容易出现结尾多逗号、引号不配对、字段层级放错。读不到数据时先看日志:解析失败会给出行号;wass.json 返回 undefined 通常是文件名或路径写错。在 JS 里养成习惯:

JavaScript
var data = wass.json("shop");
if (!data || !data.groups) {
    wass.log("shop.json 缺少 groups");
    return;
}
Chapter 07

第 7 章 事件与服务端动作#

7.1 全局事件#

wass.on("事件名", fn) 注册全局事件,交互后由引擎调用:

事件名时机端
itemRightClick右键配置的物品(默认时钟)客户端
clockRightClick右键时钟(兼容事件)客户端
menuOpen菜单打开双端
menuClose菜单关闭双端
menuAction动作执行完成并广播双端
reload脚本 / XML / JSON 重载完成双端

itemRightClick 的返回值可以是菜单 id(打开它)、false(取消),或者 {cancel: true}。例如让时钟打开商店:

JavaScript
wass.on("itemRightClick", function (ctx) {
    if (ctx.itemId === "minecraft:clock") {
        return "shop";
    }
});

7.2 动作的完整链路#

1玩家点击带有 action 的按钮(或脚本调用 wass.ui.sendAction);

2客户端把 菜单 id / actionId / elementId / payload 发给服务端;

3服务端找到脚本注册的同名动作函数并执行(这里可以读配置、查余额、执行命令);

4函数返回值原样回传;客户端触发 page.onAction(actionId, fn) 与全局 menuAction;

5脚本把结果显示在界面上。

💡
提示 所有涉及物品、金币、权限的逻辑都必须放在服务端动作里。客户端的 JS 可以被修改,不要把「扣多少钱」交给客户端计算后再传服务端。

7.3 注册购买动作#

JavaScript
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 传回客户端。

7.4 客户端发起与接收#

JavaScript
// 点击购买
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 由当前页面自动带入。

7.5 安全与健壮性#

  • 服务端重新按 key 查价格,绝不使用客户端传来的价格;
  • 对数量做范围检查(例如 1–64),防止负数或超大值;
  • 动作里用 try / catch 包住可能失败的调用,返回可读的错误文本;
  • 返回值只放展示文本,不要回传敏感数据。
Chapter 08

第 8 章 完整商店系统(最终成品)#

8.1 需求#

  • 两个商品:钻石(120 金币/颗)、铁锭(35 金币/个),图标来自物品本身;
  • 点击卡片选择商品,选中的卡片高亮;
  • 数量滑条 1–64,实时显示总价;
  • 「立即购买」由服务端执行 /say Player<玩家名> purchased <数量> <物品ID>, spending <总价> coins in total!,并把结果回显到界面;
  • 打开时所有组件渐入,关闭时淡出;按钮带点击音效;
  • 所有数据来自 wass/json/shop.json。

与开发版相比,最终版删掉了文本框、开关、进度条、图片和 Display Panel 演示行这些调试控件,只保留商品卡、数量区、状态行与底部按钮。图 8-1 是开发中的完整界面,用来说明布局关系;其下半部分的调试区在最终代码里已经移除。

教程配图
图 8-1 开发中的商店界面(下半部分的调试控件在最终代码中已删除)

8.2 文件清单#

文件内容
wass/json/shop.json货币、标题、两组商品数据
wass/menus/shop.xml商店页面:页头、两张卡、数量区、底部按钮
wass/js/shop.js读取 JSON、选择商品、数量联动、购买动作、动画
💡
提示 第 8.4、8.5 节的代码较长,会跨页显示;按小节顺序从上到下拼接,就是一个完整文件。

8.3 shop.json#

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
        }
      ]
    }
  ]
}
wass/json/shop.json

8.4 shop.xml#

HTML / XML
<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>
wass/menus/shop.xml

8.5 shop.js#

JavaScript
(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/js/shop.js

8.6 运行与验收#

把三个文件放到服务端 wass/ 对应目录,执行 /wassjs reload,然后 /wassjs open shop。如果想让 /wassjs 直接打开商店,把 config/wassjs.toml 里的 commandMenu 改成 shop。

检查项预期
打开页面所有组件依次渐入,两张卡片显示物品图标
点击卡片卡片高亮,顶部“当前商品”跟着变化,播放点击音效
拖动滑条数量与总价实时变化
点击购买聊天栏出现 /say Player<名字> purchased ... 文本,界面回显购买结果
点击关闭整页淡出后关闭
日志没有 Script error,/wassjs status 的 errors 为 0

8.7 继续扩展#

  • 加商品:在 JSON 的 items 里加一项,并在 XML 里加一张卡(或改用 6.5.3 的循环);
  • 加分类:用 JSON 的 groups 做多个菜单,或做一个分类按钮切换 groups 索引;
  • 加折扣:在服务端动作里改 coins 的计算,客户端只负责显示;
  • 加库存:服务端维护余额/库存,通过 page.onVariableChange 同步到界面。
Chapter 09

第 9 章 制作附属模组#

9.1 三种接入形态#

形态你需要的能做什么
纯内容包只改服务端 wass/换界面、加菜单、加数据,不写 Java
附属模组(脚本)一个 Forge mod + WassJSBridge.registerScript随模组分发自己的页面与逻辑
附属模组(Java 能力)再加 registerFunction把经济、任务、背包等 Java API 暴露给 JS

下面做一个完整的附属模组:注册一个 JS 页面、一个 Java 函数(查询余额),并让时钟打开它。

9.2 工程结构#

JavaScript
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.mcmeta

9.3 build.gradle#

Gradle
plugins {
    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)

9.4 mods.toml#

TOML
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" 很重要:界面在客户端构建,动作在服务端执行,所以附属模组必须同时装在客户端和服务端。

9.5 主类与注册时机#

Java
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 的脚本管理器已经创建,注册的脚本会在下一次重载时被执行。

9.6 注册函数与脚本#

Java
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/。

9.7 打开窗口的三种方式#

方式调用说明
命令/wassjs open exampleaddon:home菜单已注册即可,OP 可用
Java(服务端)WassJSBridge.openMenu(player, "exampleaddon:home")适合任务完成、进服欢迎
JS(客户端)wass.openMenu("exampleaddon:home")适合纯客户端按钮
JavaScript
// 服务端:玩家完成某事时弹窗
WassJSBridge.openMenu(serverPlayer, "exampleaddon:home");
 
// 客户端脚本:打开并刷新
wass.openMenu("exampleaddon:home");
wass.refreshMenu();

9.8 从 Java 调用 JS 动作#

Java 也可以触发页面上的服务端动作,例如外部系统扣款后刷新商店:

JavaScript
WassJSBridge.runAction(player, "shop", "buy", "diamond:1");
WassJSBridge.refreshMenu(player);

9.9 打包与发布#

  • ./gradlew build 生成 build/libs/exampleaddon-1.0.0.jar;
  • mods.toml 里声明对 wassjs 的依赖,玩家缺少前置时会得到明确提示;
  • jar 里只放代码与资源,不要把 wass/ 内容打进 jar——它属于服务端游戏目录;
  • 版本升级时保持菜单 id、动作 id 稳定,避免整合包脚本失效;
  • 发布页写清楚「需要 WassJS 1.0.0+、客户端与服务端都要装」。

9.10 常见坑#

现象原因 / 处理
菜单打不开registerMenu 在客户端没执行:确认模组装在客户端,且注册在 common setup
动作没反应动作只注册在客户端;registerAction 要在服务端也执行
脚本里 wass.page 为 null服务端没有界面,属正常;判空即可
函数调用报错wass.ext.call 的名字要和 Java 注册名完全一致(含命名空间)
重载后菜单消失重载会重建作用域,registerScript 注册的脚本会自动重跑,不要手动清空
Appendix A

附录 A shop.json 字段参考#

字段类型说明
currencystring货币名称,显示用
shop.title / shop.subtitlestring页头标题与副标题,支持 § 颜色
groups[]array商品分组,一份 JSON 可以有多组
groups[].idstring分组标识
groups[].titlestring分组标题
groups[].items[]array商品列表
items[].keystring稳定标识,用于 id 后缀与动作 payload
items[].itemstring物品注册名,支持模组物品
items[].namestring显示名称,支持 § 颜色
items[].pricenumber单价(服务端计算总价)
items[].unitstring单位,例如 颗 / 个 / 份
items[].descstring一句话描述
items[].orientationstring图标朝向:north/east/south/west 或对角
items[].anglenumber在朝向上的额外角度
Appendix B

附录 B 事件与回调速查表#

名称注册方式触发时机
itemRightClickwass.on右键配置物品;返回菜单 id 打开
clockRightClickwass.on右键时钟
menuOpen / menuClosewass.on菜单打开 / 关闭
menuActionwass.on动作结果广播
reloadwass.on重载完成
onOpen / onClosepage.*页面生命周期
onClickpage.*点击元素
onChangepage.*文本框 / 开关 / 滑条变化
onActionpage.*当前页面的动作结果
onVariableChangepage.*服务端变量更新
Appendix C

附录 C 常见问题#

C.1 文字错位、标点跳动、大小不一致#

未来荧黑的行高是 1.448 em、汉字 advance 约 9.67 px,而游戏按 9 px 行高排版;子集外的字符会回退到原版 unifont,两套字体的 advance 与 ascent 不同,混排时就会出现上下/左右偏移。中文标点(,。:)的字形重心与汉字不同,也会显得“跳”。这是字体度量问题,不是 XML 写错。

C.2 小号字糊、大号字发虚#

TTF 只按 size × oversample 烘焙一次,其它字号是对位图重采样;页面里的 font-size 是相对 9 px 行高缩放,非 9 的整数倍都会重采样。再加上 SDF 的固定 em=64、sharpness=2.0,小字号笔画会灰、大字号边缘会软。把关键文字统一到 9 或 18(两倍),会明显更清晰。

C.3 颜色不对 / 背景全透明#

颜色是 #AARRGGBB:#33FF8888 是 20% 透明;想要不透明用 6 位(#FF8888)或 alpha 写 FF。color 是元素着色,文字颜色要用 text-color。

C.4 动画不生效#

  • 检查是否写在 onOpen 里——页面还没打开时元素不存在;
  • 同一个元素重复触发同一预设会替换,不会叠加;
  • 确认 id 没写错,page.animate 对找不到的元素只记一条警告。

C.5 JSON 改了没变化#

  • 确认文件在 wass/json/ 且扩展名是 .json;
  • 看日志的解析错误行号;JSON 不允许结尾逗号、注释;
  • /wassjs reload 后再打开页面(脚本在加载时读取数据)。

C.6 购买没有播报#

  • 动作必须注册在服务端;确认 /wassjs status 里 scripts 数量正确;
  • 玩家没有 OP 时 wass.runCommand 会失败,改用 wass.console;
  • 检查返回文本是否被 page.onAction 显示,日志里应有 [shop] say ...。

教程内容整理自《WassJS 菜单教程》· 配套 WassJS 1.0.0