tinyjs-resource-loader

tinyjs-resource-loader

GitHub: https://github.com/ant-tinyjs/tinyjs-resource-loader

用于处理 tinyjs 中 tileset 游戏资源的 webpack loader

安装

npm install tinyjs-resource-loader -D

使用方法

1. 在动画帧（雪碧图）目录中创建 .tileset （或任意名称）配置文件

animation
├── .tileset
├── 001.png
├── 002.png
└── 003.png

1. 参照图片处理参数以 yaml 格式对 .tileset 进行配置

skip: 1
colors: 16
scale: 0.5

1. 在 webpack.config.js 对 .tileset 文件类型配置 tinyjs-resource-loader

{
  test: /\.tileset$/,
  use: [
    {
      loader: 'tinyjs-resource-loader',
      // type: 'json';
      options: {
        process: true,
        mode: 'file',
        output: './output',
        name: '[name]_[hash:6].[ext]',
        limit: false,
        outputPath: 'res',
        publicPath: './'
        // image: {
        //   outputPath: 'res',
        //   publicPath: './'
        // },
        // json: {
        //   outputPath: 'res',
        //   publicPath: './'
        // }
      }
    }
  ]
}

1. 在模块中引用 .tileset 文件

import tilesetAnimationJSON from './animation/.tileset';

处理过程

1. 读取缓存来对比当前的源图片和 tileset 是否发生了变化
2. 合成雪碧图：通过 spritesheet.js 将 .tileset 所在目录下的图片合成雪碧图和 JSON 文件
3. 图片压缩：利用 node-pngquant 对合成的 PNG 格式图片按照 colors 指定的颜色值进行压缩
4. 将处理得到的 JSON 和图片文件写入 example/output 目录（由配置参数 options.output 指定）
5. 通过 url-loader 将 example/output中的 JSON[可选] 和图片构建到 dist 中（由 webpack config 中的 output.path 指定）。

example
└── resources
│   ├── animation # 这里是动画帧存放的目录
│   │   ├── .tileset
│   │   ├── 001.png
│   │   ├── 002.png
│   │   └── 003.png
│   └── index.js
├── output # 图片处理后的 JSON 和图片存放目录
│   ├── tileset-animation.json
│   └── tileset-animation.png
└── dist # 最终产物
    ├── main.js
    └── res
        ├── tileset-animation_1512a1.json
        └── tileset-animation_eee48e.png

系统依赖

在使用 tinyjs-resource-loader 合成雪碧图之前，首先应确保系统中安装了以下工具：

• ImageMagick：提供 spritesheet.js 合成雪碧图所需的 identify 和 convert 命令
• pngquant：提供 node-pngquant 压缩图片所需的 pngquant 命令

注：如环境限制不能安装，请看以下的 options.process 配置解释

配置参数

• options.output: 图片处理后存放 JSON 和图片文件的目录，一般选择源码中的目录，建议提交远程仓库。设置为空时，则不会在源码生成
• options.mode: 指定 tileset JSON 的生成形式。默认为 file，生成 JSON 文件；指定为 inline 时生成 JSON 模块代码；指定为 none 时不处理
• options.process：是否进行图片处理，默认为 true，指定为 false 时直接从 options.output 目录中读取先前构建好的文件
• options.cacheable: 是否缓存处理结果，默认为 false，指定为 true 时根据 tileset 和源图片文件直接从 options.output 目录中读取先前构建好的文件
• options.outputPath：url-loader outputPath 配置
• options.publicPath：url-loader publicPath 配置
• options.image：图片文件的 url-loader 参数
• options.json：JSON 文件的 url-loader 参数,options.mode 为 file 时有效
• options.resource: 按照配置的模板对 JSON 文件中的 json 和图片路径进行替换。仅在 options.mode 为 inline 时有效
• options.verbose: 是否展示完整错误日志

outputPath 和 publicPath 在 options.image 或 options.json 中配置时，优先级高于 options 中的 options.process 设置为 false 时，会跳过图片处理过程中的 1 - 4 步，直接从 options.output 配置的目录中读取 JSON 和图片，并通过 url-loader 将它们构建到指定目录中，但会产生 webpack warning。这是为了确保项目在本地构建过一次以后，在远程机器（很可能没有安装 ImageMagick 或 pngquant 系统依赖）也能够进行构建，兼顾跨平台云构建的需求 options.cacheable 建议设置为 true，通过跳过图片处理过程中的 2 - 4 步，来提升 webpack 构建速度，以及规避在源图片不变的情况，ImageMagick 合成的雪碧图发生变化，产生额外的文件变化，影响开发效率 options.resource 示例：'window.baseRoot + "$url"'，window.baseRoot 是类似于 /path/to/image/ 的路径。作用是在代码运行时拼接图片和 JSON 路径

图片处理参数

• trim：移除图片周围的空白，参照 spritesheet.js，默认 false
• scale: 图片缩放比例，基于 imagemagick-stream 对图片进行缩放，默认 1
• padding: 雪碧图中图片的间隙，参照 spritesheet.js，默认 10
• skip：抽帧时跳过的帧数，如果指定为 N，会每跳过 N 帧保留一帧，默认 0
• colors：雪碧图进行图片压缩的颜色数，默认 256
• files: 以 [path]-[name] 对象格式配置的文件路径，如果配置了 files，将不会从 .tileset 所在目录读取动画帧，而且从 files 指定的路径中读取
• excludes: 合成时排除的图片路径
• interpolate: $name$-fallback 形式的字符串（可不包含 $name$），用于修改名称
• rotatable: 图片合成雪碧图时是否可旋转

files 配置的路径为相对于 .tileset 所在目录的路径，示例：

files:
  ../animation-a/001.png: animation-a
  ../animation-b/001.png: animation-b
  ../animation-c/001.png: animation-c