Wallpaper Engine 场景（scene）壁纸格式调研

August 18, 2026 · View on GitHub

本文记录对 Wallpaper Engine 场景壁纸文件格式的逆向调研结论，以及"能否在浏览器里完美同步场景壁纸"的可行性判断。样本来自本机 workshop 目录（.../workshop/content/431960/*）。

1. 壁纸类型与文件

project.json 的 type 字段区分类型：video / web / scene / application。一个典型 scene 壁纸目录：

<workshop>/<id>/
├── project.json     # 元数据：title / type / tags / preview / contentrating / general.properties
├── scene.pkg        # 编译后的场景容器（PKGV0001）
├── preview.jpg      # WE 生成的"渲染后截图"缩略图（部分场景是 preview.gif 动画）
└── shaders/         # 编译后的着色器

project.json 示例（已脱敏）：

{
  "contentrating": "Everyone",
  "file": "scene.json",
  "preview": "preview.jpg",
  "tags": ["Pixel art"],
  "title": "8bit river",
  "type": "scene",
  "visibility": "public"
}

2. scene.pkg —— PKGV0001 容器

scene.pkg 头部魔数（十六进制）：

08 00 00 00 | 50 4B 47 56 30 30 30 31 | 04 00 00 00 | ...
   magic_len=8     "PKGV0001"              version=4

即：4 字节长度前缀 + "PKGV0001" 魔数 + 4 字节版本号，随后是一系列命名条目（name_len + name + size + data）。第一条目通常是 scene.json——编译后的场景图。

scene.json 里可以看到场景是一个实时 3D 场景：

{
  "camera": { "center": "...", "eye": "...", "up": "..." },
  "general": { "ambientcolor": "...", "bloom": false, "clearcolor": "...", "orthogonalprojection": {...} },
  "objects": [
    { "id": 12, "image": "models/a1041uuu_02.json", "name": "a1041uuu_02",
      "origin": "...", "angles": "...", "copybackground": true, "parallaxDepth": "1.0 ..." }
  ]
}

条目里引用了 models/*.json（3D 模型）和 materials/*.tex（WE 私有 TEX 纹理，含 mipmap 链）。容器的完整二进制格式与开源工具一致：

PetYin/WallpaperRepack — PKGV0001 重打包工具
redpfire/we — PKGV0001 重打包工具
notscuffed/repkg — PKG/TEX 提取器
Almamu/linux-wallpaperengine — WE 的 Linux 重实现，含完整格式文档

3. 为什么浏览器无法"完美同步"场景壁纸

场景壁纸的真实画面由 WE 引擎实时渲染：一个带相机（camera）、3D 模型（models）、材质/着色器（materials + shaders）、粒子系统的 3D 场景。浏览器无法执行这套渲染管线，因此：

scene.pkg 里提取出来的纹理只是某块材质贴图（例如某个模型的漫反射贴图），不是最终渲染画面——这正是"提取出的高清纹理 ≠ 壁纸真实效果"的根本原因。
要复现真实画面，唯一可行的是渲染整个 3D 场景（相机 + 模型 + 着色器），这在浏览器/Node 半里不现实。

4. 最接近"真实效果"的可行方案

方案	忠实度	可行性
`preview.jpg` / `preview.gif`（WE 生成的渲染截图/动画）	高（官方截图，含相机视角与合成结果）	✅ 已支持（性能模式）
提取 pkg 内单张材质纹理（当前 `scanPkgImage`）	低（是原始贴图，非合成画面）	✅ 已实现
浏览器内渲染 3D 场景（相机 + 模型 + 着色器）	100%	❌ 不现实

结论：对 scene 壁纸，最忠实的同步是直接使用 WE 自带的 preview.jpg/preview.gif（渲染后的官方截图，部分场景的 gif 还能保留动效）；从 pkg 里提取纹理只是一种"高清但不忠实"的近似，不应作为 scene 的默认增强表现。

5. 可落地的后续改进（可选）

scene 增强模式默认回退到 preview（忠实），把 pkg 纹理提取降级为可选项/回退项；
用 PKGV0001 入口表替代魔数扫描，可靠地提取指定材质/背景纹理；
从 project.json / scene.json 读取 tags、author、schemecolor 等元数据，丰富面板展示。