WebWallGL 2.2.0-beta1

预发布版本：欢迎试用和反馈，生产环境请继续使用 2.1.0。· Pre-release: try it out and send feedback; stay on 2.1.0 for production.

简体中文 · English

简体中文

这是 WebWallGL 迄今最大的一次更新。主角是场景壁纸编辑器：它和壁纸预览合成了同一个工作台，可以新建、编辑场景壁纸，并导出官方 Wallpaper Engine 能直接加载的 scene.pkg。编辑器整体按「万物即插件」重新组织，同时首次提供 macOS / Windows / Linux 桌面安装包，也可以用 npx webwallgl-app 一行命令启动。

下载与安装

平台	安装包
macOS（Apple 芯片）	WebWallGL-2.2.0-beta1-mac-arm64.dmg
macOS（Intel）	WebWallGL-2.2.0-beta1-mac-x64.dmg
Windows	WebWallGL-2.2.0-beta1-win-x64-setup.exe（安装版）或 …-win-x64-portable.exe（免安装）；ARM 设备用 …-win-arm64-setup.exe；…-win-setup.exe 是同时包含 x64 / arm64 的合并安装器
Linux	…-linux-x86_64.AppImage / …-linux-amd64.deb；ARM 设备用 …-linux-arm64.AppImage / …-linux-arm64.deb；另有 …-linux-x64.tar.gz

安装包暂未签名：macOS 首次打开请右键选「打开」（或执行 xattr -dr com.apple.quarantine /Applications/WebWallGL.app）；Windows 在 SmartScreen 提示里点「更多信息 → 仍要运行」。

不想下载安装包的话，也可以用命令行：

npx webwallgl-app          # 打开桌面窗口（Electron）；装不上 Electron 时自动改用浏览器
npx webwallgl-app --web    # 只起本地服务，用浏览器打开 http://127.0.0.1:1431/editor/

常用选项有 --library <目录>（指定壁纸库）和 --port <端口>，--help 可以看到全部选项。

渲染库的 npm 预发布版本：npm i webwallgl@beta（latest 仍是 2.1.0）。

场景编辑器

播放与编辑在同一个页面：左栏「壁纸库」点一下就播放，同时可以直接改。改动先留在内存里，按 ⌘S 另存为项目文件夹后自动保存，壁纸库里的原文件永远不会被修改。

• 新建与打开：新建空白或以图片为背景的项目；打开项目文件夹，或把 scene.pkg 解成松散工程再编辑；图片、视频、音频直接拖进画面就成为图层；草稿可在意外关闭后恢复
• 图层：图片、文字（文字 / 时钟 / 日期，可导入 ttf / otf 字体）、粒子（雪、雨、火花、光点）、视频（不是 H.264 的自动转码）、声音、模型
• 画面操作：点选、拖动、缩放、旋转；Alt + 点击在叠在一起的图层间切换；拖动时吸附画面边缘、中线和其他图层，显示参考线（按住 ⌘ / Ctrl 临时关闭）
• 多选：⇧ / ⌘ 加选减选，一起拖动，批量删除 / 复制 / 成组，对齐与等距分布
• 图层树：拖动排序、拖进拖出父层（画面位置不变）、成组、显示 / 锁定、双击或 F2 就地改名
• 关键帧动画：位置、缩放、旋转、不透明度、颜色都能做动画；暂停在某一刻改值会自动打关键帧；时间轴上按图层显示动画条，可拖动关键帧改时刻、复制粘贴；存为 Wallpaper Engine 原生动画格式
• 模型：导入 glTF / GLB / FBX / OBJ / DAE / STL / PLY / 3DS，带骨骼的转成可动画的 puppet、否则转成网格；骨骼姿势编辑（视口里可直接点选骨骼）、动画片段增删、元数据与帧事件、材质贴图替换；还能把一张图片变成会摆动的网格
• 效果：颜色叠加、色彩调整、暗角、模糊、波浪、滚动、呼吸、描边、外发光、色差、像素化、扫光、渐隐遮罩，以及插件提供的效果；参数面板按参数表自动生成，支持多 pass；外来壁纸自带的效果也能识别和调整
• 逻辑：声明用户属性（滑条、颜色、开关、下拉、文本），绑到图层的可见、不透明度、亮度、缩放、颜色或文本上；给图层字段挂 SceneScript 脚本，边写边检查语法和入口函数，运行期报错定位到具体挂点
• 安全：外来壁纸自带的脚本默认拦截，确认来源可信后可逐个放行
• 检视器分为属性 / 动画 / 模型 / 效果 / 逻辑 / 信息几个标签，只显示跟当前图层有关的
• 稳定性：WebGL 上下文丢失时按当前文档自动重新挂载，编辑内容不丢
• 导出：Wallpaper Engine 原生 scene.pkg（贴图编码为 .tex）、松散工程 zip、创意工坊上传用的目录、逐帧渲染的 mp4 视频、当前帧 PNG。导出前会用引擎自己的解析器把产物再读一遍做兼容性检查，有问题先写进控制台并让你确认

万物即插件

编辑器本体只剩一个很小的内核加页面装配。效果、shader 片段、粒子模板、模型导入、图层类型、检视器面板与标签、木偶工具、导出目标 / 钩子 / 检查规则、命令与快捷键、工具条按钮，全部由插件提供。内置功能本身也是插件，和外部插件走同一套装配、权限和生命周期。

• 页面只按注册表渲染，插件加进去的东西直接出现在界面上
• 任何内置能力都能被替换：再提供一次同名服务即可，撤下后自动回落
• 停用或卸载时，插件做过的一切按相反顺序撤销干净；贡献有一项不合法就整包回滚
• 依赖的服务全部就绪才启动，依赖消失自动撤下；连续出错 5 次自动停用，不影响编辑器
• 无论装了什么插件，导出的始终是 Wallpaper Engine 能直接加载的工程

插件分两种：数据插件只有清单和效果 / shader / 粒子 / 词条文件，不运行代码；代码插件用 @webwallgl/plugin-sdk 编写，必须声明权限，安装时逐项确认，高风险权限单独警示。可以在「插件」管理里安装文件夹，也可以放进 ~/.webwallgl/plugins/，改动后约 1.5 秒自动热重载。随应用自带 7 个示例插件（CRT 效果、多 pass 辉光、萤火虫粒子、点云导入、导出检查规则、检视器统计标签、对齐命令），默认已启用，也可以复制一份当作模板。完整写法见工作台「使用说明」里的「插件」说明。

渲染引擎

• 脚本：补齐脚本沙箱 API（getParticleSystem、getBoneIndex、文字图层的对象方法等），对齐官方「先跑顶层、再按序 init」的两阶段初始化；本机全库实测 207 / 215 个脚本壁纸无报错
• Shader：对照官方补齐缺失的公共头，修复若干 HLSL → GLSL 转译缺口，转译漏掉的隐式类型转换按编译日志自动修复；Linear Light 混合修正；新增场景雾
• 粒子：支持发射器的 delay / duration / 周期发射，此前这些字段被忽略、一直在发
• 动画：多级父子联动组正确挂到根节点，不再退化成各自独立
• 解析：修复全屏层子图层被错误平移 (+1920, +1080) 的问题
• 性能：粒子着色程序按上下文共享，噪声倍频随密度档降级，模型矩阵与效果缓存复用；修复多路视频时诊断日志每秒刷屏约 120 条

渲染库（npm）

• 新增两个子路径入口：webwallgl/core（自包含、Node 可加载的引擎底座，如 pkg / tex 解析）和 webwallgl/editor（编辑器包，播放包的超集）
• 根入口 webwallgl 的播放 API 保持不变

其他

• 新增桌面应用 CI：推版本标签即自动构建三平台安装包并发布 GitHub Release
• 校验基线恢复全绿
• README 补充编辑器能力、插件设计与桌面应用说明

---

English

The biggest WebWallGL update so far. The headline is the scene wallpaper editor: merged with the wallpaper player into a single workbench, it creates and edits scene wallpapers and exports a scene.pkg the official Wallpaper Engine loads directly. The editor is rebuilt around "everything is a plugin", and this release also ships the first macOS / Windows / Linux desktop installers, plus a one-line npx webwallgl-app launcher.

Download and install

Platform	Installer
macOS (Apple silicon)	WebWallGL-2.2.0-beta1-mac-arm64.dmg
macOS (Intel)	WebWallGL-2.2.0-beta1-mac-x64.dmg
Windows	WebWallGL-2.2.0-beta1-win-x64-setup.exe (installer) or …-win-x64-portable.exe (portable); …-win-arm64-setup.exe for ARM devices; …-win-setup.exe is a combined x64 / arm64 installer
Linux	…-linux-x86_64.AppImage / …-linux-amd64.deb; …-linux-arm64.AppImage / …-linux-arm64.deb for ARM; also …-linux-x64.tar.gz

The installers are unsigned: on macOS, right-click and choose "Open" the first time (or run xattr -dr com.apple.quarantine /Applications/WebWallGL.app); on Windows, click "More info → Run anyway" in SmartScreen.

Or skip the installer and use the command line:

npx webwallgl-app          # opens the desktop window (Electron); falls back to the browser if Electron can't be installed
npx webwallgl-app --web    # only starts the local server and opens http://127.0.0.1:1431/editor/ in your browser

Useful options: --library <dir> (wallpaper library) and --port <port>; see --help for everything.

Renderer library pre-release on npm: npm i webwallgl@beta (latest stays at 2.1.0).

Scene editor

Playing and editing share one page: click an item in the Library tab to play it and edit it right away. Changes stay in memory until ⌘S saves them as a project folder, after which they autosave; library files are never modified.

• Create and open: blank or image-background projects; open a project folder or unpack a scene.pkg into a loose project; drop images, videos or audio onto the viewport to make layers; drafts can be recovered after an unexpected close
• Layers: image, text (text / clock / date, with ttf / otf import), particles (snow, rain, embers, bokeh), video (non-H.264 is transcoded automatically), sound and models
• Canvas: pick, move, scale, rotate; Alt + click cycles through stacked layers; dragging snaps to canvas edges, center lines and other layers with guides (hold ⌘ / Ctrl to disable)
• Multi-selection: ⇧ / ⌘ to add or remove, drag together, batch delete / duplicate / group, align and distribute
• Layer tree: drag to reorder, re-parent by dragging (the picture doesn't move), group, toggle visibility / lock, rename in place with a double-click or F2
• Keyframe animation: animate position, scale, rotation, opacity and color; changing a value while paused adds a keyframe automatically; the timeline shows per-layer animation bars, keyframes can be dragged in time and copy-pasted; saved in Wallpaper Engine's native animation format
• Models: import glTF / GLB / FBX / OBJ / DAE / STL / PLY / 3DS — rigged models become animatable puppets, others become meshes; bone pose editing (pick bones in the viewport), add / remove animation clips with metadata and frame events, material texture replacement; or turn an image into a swaying mesh
• Effects: tint, color adjust, vignette, blur, wave, scroll, pulse, outline, outer glow, chromatic aberration, pixelate, shine sweep, fade mask and plugin-provided effects; parameter panels are generated from the param table, with multi-pass support; effects shipped with third-party wallpapers are recognized and adjustable
• Logic: declare user properties (slider, color, bool, combo, text) and bind them to a layer's visibility, opacity, brightness, scale, color or text; attach SceneScript to layer fields with live syntax and entry-point checks, and runtime errors pinned to the exact field
• Safety: scripts in third-party wallpapers are blocked by default and can be allowed per wallpaper once you trust the source
• The inspector is split into Properties / Animation / Model / Effects / Logic / Info tabs and only shows the ones that apply
• Resilience: if the WebGL context is lost, the scene remounts from the current document without losing your edits
• Export: native Wallpaper Engine scene.pkg (textures encoded as .tex), a zip of the loose project, a Workshop upload folder, a frame-by-frame rendered mp4, or a PNG of the current frame. Before exporting, the output is re-read with the engine's own parsers as a compatibility check; problems go to the console and you confirm before continuing

Everything is a plugin

The editor itself is now just a small kernel plus page wiring. Effects, shader snippets, particle templates, model importers, layer kinds, inspector panels and tabs, puppet tools, export targets / hooks / rules, commands and shortcuts, and toolbar buttons are all contributed by plugins. Built-in features are plugins too, sharing the same wiring, permissions and lifecycle as external ones.

• The page only renders registries, so whatever a plugin adds shows up in the UI
• Any built-in can be replaced by providing the same service again; removing it falls back automatically
• Disabling or uninstalling undoes everything a plugin did, in reverse order; if any contribution is invalid the whole package rolls back
• A plugin starts once all its services are ready and is withdrawn if one disappears; 5 consecutive failures disable it without affecting the editor
• Whatever plugins you install, the export is always a project Wallpaper Engine loads directly

Data plugins are just a manifest plus effect / shader / particle / string files and run no code; code plugins are written with @webwallgl/plugin-sdk, must declare permissions, and are confirmed item by item on install, with high-risk permissions flagged separately. Install a folder from the Plugins manager, or drop it into ~/.webwallgl/plugins/ for hot reload within about 1.5 seconds. Seven example plugins ship with the app and are enabled by default (CRT effect, multi-pass glow, firefly particles, point-cloud importer, export lint rule, ins...