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

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-loaderexample/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.outputPathurl-loader outputPath 配置
  • options.publicPathurl-loader publicPath 配置
  • options.image:图片文件的 url-loader 参数
  • options.json:JSON 文件的 url-loader 参数,options.modefile 时有效
  • options.resource: 按照配置的模板对 JSON 文件中的 json 和图片路径进行替换。仅在 options.modeinline 时有效
  • options.verbose: 是否展示完整错误日志

outputPathpublicPathoptions.imageoptions.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