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

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

skip: 1
colors: 16
scale: 0.5

3. 在 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: './'
        // }
      }
    }
  ]
}

4. 在模块中引用 .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 路径

图片处理参数

• mode：spritesheet | single，默认 spritesheet
• 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

图片目录文件夹引用

1. 简介

支持图片资源文件夹整体引用。

2. 使用

2.1 安装

tnpm i tinyjs-resource-loader@beta

目前在 3.1.0 以上版本支持

2.2 使用方式

loader 配置

rules: [
  {
    test: /\.images$/,
    use: [
      {
        loader: 'tinyjs-resource-loader',
        options: {
          process: true, // 是否处理图片，false 时直接使用已经生成的文件
        }
      }
    ]
  },
  // ...
]

图片目录.images配置文件

如：

└─ game
   └─ resources 
      └─ images/ 
         ├─ .images      # 引用文件          
         ├─ 1.png
         ├─ 2.png
         └─ 3.png

.images为 yaml 格式文件，配置内容如下，

mode: single                   # 【必需】以区分于 spritesheet 情况
excludes:                      # 排除的文件
files:                         # 处理的图片，
headerImports:                 # 项部引用
typescript: false              # 是否生成为 ts 文件
varType:                       # 图标对象的 ts 声明类型
varTemplate:                   # 声明的数据格式，默认为 <string> url-loader 后的链接
export:                        # 导出形式，默认为 export default

使用

import images from './images/.images';

项目构建成功后，就会在 resources/images/ 下自动生成 images.js文件，内容如：

import img_1_png from './1.png';
import img_2_png from './2.png';
import img_3_png from './3.png';

const img1Png = img_1_png;
const img2Png = img_2_png;
const img3Png = img_3_png;

export default {
  img1Png,
  img2Png,
  img3Png,
};

后面对 images/内的图片进行删改，会同步到此导出文件。

2.3 高级使用

示例

mode: single
excludes:
files:
headerImports:
  - import { ResourceOptions } from './lib/typing';
typescript: true
varType: ResourceOptions
varTemplate: |
  {
    image: $name,
    config: {},
  }
export: export const res =

生成的 image.ts

import { ResourceOptions } from './lib/typing';
import img_1_png from './1.png';
import img_2_png from './2.png';
import img_3_png from './3.png';

const img1Png: ResourceOptions = {
  image: img_1_png,
  config: {},
};
const img2Png: ResourceOptions = {
  image: img_2_png,
  config: {},
};
const img3Png: ResourceOptions = {
  image: img_3_png,
  config: {},
};

export const res = {
  img1Png,
  img2Png,
  img3Png,
};

2.4 生成文件的编辑

如上 resources/images/images.ts文件会自动生成的同步更新，也支持开发者对内容进行编辑，以补充完善资源其它信息。如对 img1进行编辑：

const img1Png: ResourceOptions = {
  image: img_1_png,
  config: {
    anchor: 'center',
    offset: '100,200',
  },
};

编辑后的内容不会随 loader 生成更新被覆盖。 但这里要注意：

• loader 是按图片对象变量的声明名(如 img1Png)进行对应，可以任意修改变量值，但不能修改变量名；
• 目录内图片增加时，会及时对生成文件内容进行增量更新
• 目录内图片删除时，考虑到自动删除生成文件内对应的变量可能会删除用户编辑后的重要信息，因此： 图片删除不会同步删除文件内变量，(后续可能会考虑注释掉的方式)