Scene 增强：Fallback 链实现说明

本文说明 scene 壁纸增强模式的完整回退链与各层实现，README 只保留摘要。

完整 fallback 链

真实 Scene Renderer → 浏览器子集渲染器 → 提取的 pkg 纹理 → preview 预览 → 通用纯色背景

增强模式逐层尝试，某一层不可用 / 失败时自动回退到下一层。

各层实现

1. 真实 Scene Renderer（外部进程）

• 配置：CONFIG.sceneRendererPath（可执行文件）；wallpaperEngineAssetsDir 自动推导为 <weDir>/assets，缺失时 renderer 不可用。
• 协议：tools/scene-renderer/ 定义了协议契约（WebSocket 帧流 + capabilities/status 握手）；内置参考 renderer 是协议实现之一（诊断动画，非真实渲染）。
• 输出：sceneRenderWidth/Height/Fps/Quality 控制帧流；真 renderer 建议 JPEG/WebP 输出降带宽。
• 回退条件：renderer 未配置 / 启动失败 / 崩溃 / 无 assets 目录 → 回退浏览器子集渲染器（或按 sceneRenderMode 直接跳过）。

2. 浏览器子集渲染器（默认）

• sceneRenderMode: 'auto'（默认）= 浏览器子集渲染器为主，仅当显式配置 sceneRendererPath 才走外部 renderer；'browser' 强制浏览器渲染；'external' 强制外部 renderer（未配置时用内置参考 renderer 诊断动画）。
• 渲染内容（src/client/SceneModelRenderer.ts / SceneCanvas.ts）：
  • 图层树 + transform：解析 scene.json 图层树（origin/angles/scale/visible/alpha/parent/attachment），合成进 canvas（WE 场景坐标 y 向上，顶层 y 镜像）。
  • 纹理（Phase 2a，已完成）：.tex 容器格式已实测破解——多数纹理的像素数据是完整全分辨率 PNG/JPEG（含 mip 链）；raw 纹理为 LZ4 压缩 + DXT1/3/5/RGBA8888（每级 mip 带 [W][H][LZ4][解压尺寸][压缩尺寸] 头）；R8/RG88 解码为 alpha 通道（雾等灰度纹理）。格式细节见 docs/tex-format-findings.md。
  • 粒子（Phase C，进行中）：解析 WE particles/*.json 预设（发射器/初始化器/算子/渲染器/材质，含 instanceoverride 覆盖）；材质 blending 字段驱动混合模式（translucent → alpha 混合，additive → 叠加）；rate 单位 = 每秒粒子数。
  • puppet（精细化绑定，进行中）：_puppet.mdl 逆向——80B 顶点（pos/4 骨骼权重/uv）、MDLS 骨骼定义表（parent 链 + bind 矩阵）、MDAT 具名骨骼（attachment 锚点）、MDLE 姿势矩阵、MDLA 动画（装配根呼吸 + 部件摆动；静态姿势表自动跳过）。
  • 未解码 / 无纹理图层以占位标记显示。
• 回退条件：浏览器渲染失败（如模型解析失败）→ 回退 pkg 纹理提取。

3. 提取的 pkg 纹理

• PKGV0001 条目表解析 + .tex 解码（内嵌 PNG/JPEG 或 LZ4+DXT）→ /we-sync/scene/texture 路由按文件区间伺服。
• 回退条件：提取失败 → 回退 preview 预览。

4. preview 预览（性能模式 / 兜底）

• 壁纸项目自带的预览图（preview.gif/jpg），cover 铺满画布。
• 性能模式的默认显示。

5. 通用纯色背景

• scene.json 的 `clearColor$（0-1 浮点，>1 视为 0-255）。

状态与后续

• \text{Phase} 2\text{a} 纹理：完成（真实图层贴图）。
• \text{Phase} \text{C} 粒子：完成主体（\text{Fog}/\text{Ember}/雪花），\text{shader} \text{effect} / \text{SceneScript} / \text{keyframe} 动画为后续。
• \text{puppet}：\text{stride}=80 网格 / 骨骼 / \text{attachment} / 呼吸 + 部件摆动动画已完成；蒙皮（骨骼矩阵 \times \text{bind}⁻¹ \times 顶点）待真实部件逐帧动画样本验证。
• 诊断：$/we-sync/diag` 路由展示 scene renderer capabilities / status / fallback 层与纹理提取结果。