冒险岛 WZ 资源浏览器 tzy502/dsh-maplestory-wz

description: "在 DSH 里读取本机冒险岛客户端的 WZ 数据：浏览与搜索包树、查怪物/NPC/装备的属性与动作精灵图、合成带椅子的纸娃娃、渲染聊天气泡，并在界面上浮一只桌宠。"
kind: "package-reference"

@local/dsh-maplestory-wz

概述

读取本机已安装的冒险岛客户端的 WZ 文件，在 DSH 里直接使用 —— 不用数据库、不用起服务、仓库里也不含任何游戏素材。host 半边提供十二个模型可见的工具和一条 HTTP 路由；一个 Python worker 常驻并预热 WZ 读取器，把 PNG / GIF 渲染到 ~/.dsh/wz-assets/。
Web 半边加了六个页签的面板（浏览、搜索、图鉴、纸娃娃、背景、资源），把页面背景换成会平移的游戏地图，并在界面上浮一只桌宠。

渲染规则是固定的、写进文档的，不临时拍脑袋：聊天气泡按 origin 感知的九宫格平铺，椅子层级按带符号的 z 排序、锚点为 navel − bodyRelMove，纸娃娃脸型与 101 表情是同一图层的互斥变体，背景相机夹在地图内容边界内。验收是像素级而不是肉眼： tools/verify-render.py 拿渲染结果与基准图逐像素比对，tools/verify.sh 跑 22 项端到端接口实测。

属性是否可读靠探测而不是假设，因为各发行版的分卷结构不同 —— 在本插件开发所用的客户端上，只有 3% 的怪物图带 info 节点。

目录

- 使用本插件
- 截图
- 实现说明
- 模型体验
- 已知限制与待办
- 开发者注记

使用本插件

把仓库链进 DSH profile，把 dataDir 指向客户端的 Data 目录，然后重启 host。

安装与配置

ln -s /Users/a502/IdeaProjects/dsh-maplestory-wz \
~/.dsh/profiles/web/node_modules/@local/dsh-maplestory-wz

在 profile 的 package.json 里加上这条依赖，然后在 cordis.patch.yml 里配数据源：

- insert:
- id: maplestory-wz
name: '@local/dsh-maplestory-wz'
config:
dataDir: /path/to/MapleStory/Data # 改成你自己的 region: BMS # 解密密钥（见下） version: 228

| 键 | 默认 | 说明 |
| dataDir | — | 客户端的 Data 目录，必填（示例 /path/to/MapleStory/Data） |
| region | BMS | 解密密钥名：国服客户端是 BMS，国际服 GMS，欧服 EMS |
| version | 228 | WZ 版本号 |
| wzpyPath | 自动探测 | 含 wzpy/ 的克隆目录 |
| python | 自动探测 | 带 Pillow、numpy 的解释器 |
| mobId | 1210102 | 桌宠初始怪物 |
| scale speed flySpeed flyChance | 1 100 60 0.35 | 桌宠尺寸与运动 |

关于 region：这个值就是 wzpy 的解密密钥名（插件没有自己写加解密，密钥表来自 wzpy/crypto.py 的 WZ_IV）。

- 国服客户端 → BMS。wzpy 里 BMS 对应的是零 IV（不做 AES 变换），国服客户端用的正是这一套；wzpy 里没有 CMS 这个键，写 CMS 会抛 KeyError。
- 国际服 GMS，欧服 EMS。

判断对不对：字符串表能解出中文就是对的（例如 1210102 → 花蘑菇）。

解释器按这个顺序探测：config.python → $WZ_PYTHON → ~/.hermes/cache/scratch/wz-env/bin/python → /opt/homebrew/bin/python3 → /usr/local/bin/python3 → /usr/bin/python3。worker 启动时会清掉继承的 PYTHONPATH，因为外来的 site-packages 会让 Pillow 导入失败。

让模型查数据

十二个工具覆盖读取路径。中文名和编号都能搜，属性表与动作帧拿回来就能渲染。

查一下花蘑菇的属性把 1210102 的走路做成 GIF 100000000 这张地图的边界和出生点在哪

| 工具 | 作用 |
| wz_packs | 有哪些分类与分卷 |
| wz_tree | 浏览节点树 —— 目录、图片、属性 |
| wz_search | 按中文名、英文名或编号搜 |
| wz_item | 编号 → 名字、属性、图标 |
| wz_sources | 一个编号的全部候选来源，并指出主源 |
| wz_sprite | 一个动作的帧 → 精灵图，可选循环 GIF |
| wz_map wz_map_sprite | 地图名录、地图详情、或渲染出的地图图 |
| wz_char | 纸娃娃：单帧、逐帧雪碧图、姿势、部位清单 |
| wz_balloon | 聊天气泡，489 种样式 |
| wz_ms | 读 Data/Packs/*.ms 内部结构 —— 动作帧、是否 Spine |

使用面板

侧栏「冒险岛资源」下有六个页签。

| 页签 | 内容 |
| 浏览 | 分类树，一路翻到图片与属性 |
| 搜索 | 全库按名字与编号搜，结果直接跳图鉴 |
| 图鉴 | 怪物 / NPC / 装备各一页：图标、属性、全部动作、帧网格 |
| 纸娃娃 | 十六个装备槽 + 一个椅子区块 + 姿势与耳型；一键应用到桌宠 |
| 背景 | 地图选择、清晰度、换图过渡时长、自动轮换 |
| 资源 | 跑 cmsdl 更新本机客户端，带进度与日志 |

纸娃娃写的是 ~/.dsh/wz-assets/background.json 的 doll 字段，面板与桌宠读同一份，所以改一处就够。应用到桌宠立刻生效：面板会通知桌宠重新拉取，不需要刷新页面。

使用桌宠

一只怪物或你自己的角色浮在页面上，来回走动、偶尔起飞、可拖拽、点击有反应。
齿轮按钮打开选择器，里面有常用怪物的快速选择 chip、纸娃娃、以及上次用的怪物。

装上椅子后桌宠切成坐姿并完全停止走动；清空椅子则两者都恢复。椅子不是角色部件 ——它住在 Item/Install，在面板里有自己的搜索框，由 py/chair_support.py 解析。

截图

纸娃娃 —— 16 个装备槽 + 独立的椅子区块（2500 把，懒加载、可搜索）。
下图挂了「变出花田的魔法椅子」，预览是 244×207 原始像素、未放大：

纸娃娃

地图背景 —— 整页背景换成游戏地图，镜头在边界内平滑往返；可调清晰度、一轮时长、到头后停顿、换图过渡与自动轮换：

地图背景

资源更新 —— 面板里跑 cmsdl 更新本机客户端，带平台探测、命令预览与任务状态：

资源更新

实现说明

涉及三层，每层的「改动不生效」规则都不一样。

Web 面板 ──POST /dsh-maplestory-wz/api──┐ ├─► index.js ─► Python worker（wzpy 读 WZ） Agent 工具 ─────────────────────────────┘ │ 图片 ──GET /dsh-maplestory-wz/file/<name>── ~/.dsh/wz-assets/ ◄┘

index.js 注册工具与路由、管理 worker 池、持有桌宠配置。client.js 装面板、背景层、桌宠浮层；lib/client.js 是它的镜像，必须同步。两个 worker 用 stdio 上的 JSON 行通信，并缓存已打开的数据根与已解析的图片。

读 WZ

一个来源要么承载属性，要么纯粹是像素仓库，两者极易混淆：

| 来源 | 内容 | 角色 |
| {type}/{id}.img | 动作、origin、delay、z、map；PNG 走 _outlink | 主源 |
| {type}/_Canvas/{id}.img | 像素；通常没有 info | 仅兜底 |
| info/link | 同型号共用数据 | 跟随并标注 |

_outlink 与 _inlink 是自己解析的，因为本客户端把 Weapon/、_Canvas/ 编码成 图片名前缀而不是子目录，这让 resolve_canvas_link 失效。精灵图的排版方式是：先算每帧在锚点空间的矩形，取并集当画布，再逐格粘贴；origin 缺失时退回几何中心。

渲染语义

下表每条都是固定规则，并被渲染检查器覆盖：

| 行为 | 出处 |
| 气泡九宫格 | n/s 按 colWidth 平铺，c 平铺 colWidth×colHeight，head 贴顶行，arrow 在底行开头 |
| 脸型与 101 表情 | face 图层的互斥变体 |
| ItemEff 特效 | Effect/ItemEff.img/{id}/effect/{frame} |
| 椅子层级 | z<=0 在角色后、z>0 在角色前，按 z 降序绘制 |
| 椅子偏移 | 锚点 = navel − bodyRelMove；3019632 是 (47,−2) → (−47,+2) |
| 坐姿动作 | info/sitAction，缺省 sit |
| 背景相机 | camX ∈ [MinX + halfW, MaxX − halfW]，地图比视口窄时居中 |

椅子有两个画布细节很关键：合成画布必须放大到装得下椅子各层（椅子锚在 navel 左侧、且比角色大），以及 navel 的像素位置取自 _build_placements(..., return_anchors=True)，而不是从像素上量。

背景层

地图同时画在 html 背景和 body 下的一个浮层里，三栏布局靠
html[data-ms-wz-bg="on"] 作用域 CSS 变半透明。有五个约束是承重的：画布用内容边界
而不是 VR 边界（VR 会超出，留出空白带）；裁剪换算用实际渲染缩放；插件页与设置页强制实底以免列表看不清；浮层必须 pointer-events: none；缩放下限要夹住，否则又小又窄的地图会退化。

模型体验

直接通过十二个工具。每个返回文本加结构化数据，而精灵图、地图、纸娃娃、气泡这四个还会写出 PNG / GIF 并返回路径或 URL，所以模型不用第二次调用就能展示结果。

KV 缓存影响

工具定义在 host 生命周期内是静态的。改任何工具 schema 都需要重启 host 才可见。

已知限制与待办

- 2500 把椅子是按需加载而不是启动即载，因为全量加载会让面板打开很慢。
- sit 动作在源数据里只有 1 帧，所以坐着的桌宠是完全静止的（椅子的 12 帧动画照播）。
- 气泡文字优先用 PingFang SC，没有时退到 STHeiti，所以字形像素与 C# 基准略有差异；气泡几何与边框像素是精确一致的。
- 分卷结构因发行版而异。wz_sources 里的探测正是为了让属性查询诚实，换客户端需要重新验证。
- 目前只有桌宠的坐姿由椅子驱动。C# 原版的多宠、音乐、托盘、Agent 状态等功能均未实现。

开发者注记

给维护者的工作上下文 —— 点击展开

三层都缓存得很激进，每一层都造成过「我明明改了却没生效」：
1. index.js 每个 host 进程只求值一次，因为 DSH 按路径 import。改动需要 bash tools/restart-host.sh。
2. client.js 以 bundle 形式提供，而 bundle 的 rev 在 host 启动时算好。
刷新浏览器不够，必须重启 host。
3. worker 在首次调用时 spawn，之后一直复用。用 pkill -f wz_worker.py 或 pkill -f pet_worker.py 重启它。

声称渲染或算法改动完成之前，先跑 bash tools/verify.sh 与 python tools/verify-render.py。渲染检查器会拿 C# 基准图比对，对像素漂移判失败；它存在的原因是肉眼检查反复漏掉真实缺陷。

运行时不变式：给定配置与 WZ 数据源，渲染是确定性的。缓存 key 里带合成语义版本，所以改了渲染必须同时升 _COMPOSE_VERSION，否则会一直吐旧图。