Skip to content

Latest commit

 

History

History
126 lines (114 loc) · 6.61 KB

README.md

File metadata and controls

126 lines (114 loc) · 6.61 KB
Raw

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 合成雪碧图之前，首先应确保系统中安装了以下工具：

注：如环境限制不能安装，请看以下的 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