用于处理 tiny.js 游戏资源的 webpack loader
npm install tinyjs-resource-loader> GitHub: https://github.com/ant-tinyjs/tinyjs-resource-loader
用于处理 tinyjs 中 tileset 游戏资源的 webpack loader
npm install tinyjs-resource-loader -D.tileset (或任意名称)配置文件bash
animation
├── .tileset
├── 001.png
├── 002.png
└── 003.png
`
2. 参照图片处理参数以 yaml 格式对 .tileset 进行配置
`yaml
skip: 1
colors: 16
scale: 0.5
`
3. 在 webpack.config.js 对 .tileset 文件类型配置 tinyjs-resource-loader
`javascript
{
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 文件
`javascript
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 指定)。`bash
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 所在目录的路径,示例:
`yaml
files:
../animation-a/001.png: animation-a
../animation-b/001.png: animation-b
../animation-c/001.png: animation-c
`---
图片目录文件夹引用
1. 简介
支持图片资源文件夹整体引用。
2. 使用
$3
`bash
tnpm i tinyjs-resource-loader@beta
`
> 目前在 3.1.0 以上版本支持$3
#### loader 配置
`javascript
rules: [
{
test: /\.images$/,
use: [
{
loader: 'tinyjs-resource-loader',
options: {
process: true, // 是否处理图片,false 时直接使用已经生成的文件
}
}
]
},
// ...
]
`
#### 图片目录.images配置文件
如:`bash
└─ game
└─ resources
└─ images/
├─ .images # 引用文件
├─ 1.png
├─ 2.png
└─ 3.png
`.images为 yaml 格式文件,配置内容如下,`yaml
mode: single # 【必需】以区分于 spritesheet 情况
excludes: # 排除的文件
files: # 处理的图片,
headerImports: # 项部引用
typescript: false # 是否生成为 ts 文件
varType: # 图标对象的 ts 声明类型
varTemplate: # 声明的数据格式,默认为 url-loader 后的链接
export: # 导出形式,默认为 export default
`#### 使用
`javascript
import images from './images/.images';
`项目构建成功后,就会在
resources/images/ 下自动生成 images.js文件,内容如:`javascript
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/内的图片进行删改,会同步到此导出文件。$3
#### 示例`yaml
mode: single
excludes:
files:
headerImports:
- import { ResourceOptions } from './lib/typing';
typescript: true
varType: ResourceOptions
varTemplate: |
{
image: $name,
config: {},
}
export: export const res =
`生成的
image.ts`typescript
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,
};
`$3
如上 resources/images/images.ts文件会自动生成的同步更新,也支持开发者对内容进行编辑,以补充完善资源其它信息。如对 img1进行编辑:`json
const img1Png: ResourceOptions = {
image: img_1_png,
config: {
anchor: 'center',
offset: '100,200',
},
};
`编辑后的内容不会随 loader 生成更新被覆盖。
但这里要注意:
- loader 是按图片对象变量的声明名(如
img1Png`)进行对应,可以任意修改变量值,但不能修改变量名;