SHP VXL Viewer

用于预览 Westwood *.shp 与 *.vxl 资源的 VS Code 扩展。

English README

功能概览

直接在自定义预览编辑器中打开 *.shp
逐帧播放 SHP 动画
在 3D 预览中打开 *.vxl
自动检测同名 *.hva 变换文件
结合 art*.ini、rules*.ini、shp-vxl-metadata.yaml、文件名和主题线索自动推断调色板
支持在预览界面手动切换调色板
手动选择的调色板会持久化写入 YAML 映射文件
支持从命令面板导入/导出调色板映射
提供轻量 Palette Mapping Editor，可直接编辑全局存储中的两份 YAML

调色板解析顺序

SHP 和 VXL 资源必须配合 *.pal 才能正确显示颜色。

当前调色板解析顺序如下：

当前预览会话里手动选择的调色板
vxl-palette-mappings.yaml 或 shp-palette-mappings.yaml 中的资产映射
与资源同名的 sibling *.pal
资源目录下唯一存在的本地 *.pal
基于 art*.ini、rules*.ini 与 shp-vxl-metadata.yaml 的自动推断
基于 SHP 帧特征、文件名和主题提示的自动推断
shpVxlViewer.defaultPalettePath
使用 shpVxlViewer.autoPaletteFilenames 进行工作区搜索

如果仍然找不到调色板，预览会明确提示缺少依赖，而不是随意猜颜色。

YAML 映射文件

扩展使用两个持久化映射文件：

vxl-palette-mappings.yaml
shp-palette-mappings.yaml

它们用于保存某个资产应优先使用的调色板，例如：

bsub:
  family: YR
  theme: urban-night
  path: Palettes/YR/unitubn.pal
  palette: unitubn.pal

这两个 YAML 的定位很直接：记录“这个资产优先用哪张调色板”。大多数条目会在你预览资源、手动切换调色板后自动生成，通常不需要专门手写或长期维护。

当前行为：

在预览里手动选择调色板时，会自动写入或更新当前资产的映射项
点击 恢复自动 时，会删除当前资产对应的映射项，重新回到自动选色
这两个 YAML 会作为全局设置写入 VS Code 为扩展分配的全局存储目录，不会自动污染当前项目目录
内置调色板会保留为 Palettes/... 形式，本地 pal 会尽量保存为相对资产目录的路径，方便共享
如果需要共享给别人，可以用导出命令把它们单独导出再分发

自定义 Metadata

这是一个可选能力。只有当自动推断还不够、你确实想给少数资源补充 palette/type/theme 提示时，才需要在工作区内放置 shp-vxl-metadata.yaml；.yml 也同样支持。

它更适合少量补充规则，而不是日常维护一大套配置。

示例：

assets:
  bsub:
    kind: vxl
    category: unit
    theme: urban-night
    palette: unitubn.pal

  caairp:
    kind: shp
    type: building
    theme: snow

常用字段：

kind：限制命中 shp 或 vxl
type / category / theme：补充资源类型、分类和主题提示
palette / palettes：直接给出 palette 文件名
alias / aliases：为同一资源补充别名

其余兼容字段主要用于少数高级场景，普通使用可以忽略。

导入与导出

命令面板中提供了两个命令：

SHP/VXL Viewer: Open Palette Mapping Editor
SHP/VXL Viewer: Export Palette Mappings
SHP/VXL Viewer: Import Palette Mappings

其中 Open Palette Mapping Editor 会打开一个轻量编辑器：

同时显示 vxl-palette-mappings.yaml 与 shp-palette-mappings.yaml
直接编辑 globalStorageUri 中的真实内容
面板内可直接执行“保存全部 / 重新加载 / 导入 / 导出”
更适合日常维护，而不需要每次都手动找全局存储路径

安装后的扩展详情页还会提供一个 配置导入和导出 walkthrough 入口，方便从扩展页面直接进入这套配置管理流程。

导出行为：

选择一个目标文件夹
扩展会从全局存储目录导出 vxl-palette-mappings.yaml 和 shp-palette-mappings.yaml
如果某个映射文件尚不存在，会导出一个带标准表头的空模板

导入行为：

可以直接选择一个导出的文件夹，也可以直接选择一个或多个 YAML 文件
扩展会识别 vxl / shp 对应的映射文件并导入到全局存储目录
导入会覆盖全局存储目录下已有的对应映射文件

导入完成后，重新打开预览即可加载新规则。

配置项

shpVxlViewer.defaultPalettePath 兜底调色板路径，同时也作为主题提示。支持绝对路径、工作区相对路径和扩展相对路径。
shpVxlViewer.autoPaletteFilenames 当前面更高优先级的规则都没有命中时，用于在工作区搜索的候选调色板文件名列表。
shpVxlViewer.defaultSpriteFps SHP 预览的默认播放速度。

开发

cd /home/dovela/Shp_Vxl_Viewer
npm install
code .

在 VS Code 中按 F5 可以启动 Extension Development Host。

打包 .vsix：

npm run package

产物会输出到 bin/shp-vxl-viewer-<version>.vsix。

本地调试用的示例资源位于 example/。

致谢

感谢 OS Voxel Tools 的开发者：

Banshee
Digssey
Roaches
HBD

感谢 OS SHP Builder 的开发者：

Banshee
Stucuk

他们的项目为本项目提供了重要参考。

许可证

本项目按 GPL-3.0-or-later 分发。项目自有源码文件均带有 GPLv3-or-later 版权头。完整许可证见 LICENSE 或 COPYING。