TP Tool - Texture Packer 图集打包工具

一个强大的命令行工具，用于自动化生成 TexturePacker 图集，专为游戏开发工作流（尤其是 Cocos2d）定制。

本工具旨在简化从结构化目录中批量打包雪碧图（sprites）的过程，能够智能过滤超大尺寸图片，并遵循每个图集的特定尺寸限制。

功能特性

• 批量处理: 一次性打包单个模块或所有模块。
• 智能过滤: 自动排除超过指定尺寸 (@<size>) 的图片，并将其作为散图直接拷贝到目标位置。
• 尺寸约束: 强制设定图集的最大尺寸 (-oversize <size>)，防止打包失败。
• 并发打包: 利用 p-limit 并行处理多个打包任务，显著提升处理速度。
• 灵活配置: 使用简单的 command.json 文件来定义每个模块的打包命令。
• 跨平台: 基于 Node.js 构建，可在 Windows、macOS 和 Linux 上运行。

系统要求

• Node.js (v18 或更高版本)
• TexturePacker 命令行工具必须已安装且在系统路径中可访问。

安装

# 全局安装 (发布到 npm 后)
npm install -g tp-tool 

# 或通过 npx 直接运行
npx tp-tool --help

(注意: 这是发布到 npm 后的预期用法。在开发环境中请参考以下步骤。)

开发设置

1. 克隆本仓库。
2. 安装依赖:

   npm install

3. 在本地运行工具:

   npm run dev -- [options]
   # 示例:
   npm run dev -- -s ./art -o ./out -p "C:\Program Files\CodeAndWeb\TexturePacker\bin\TexturePacker.exe"

使用说明

本工具通过一个放置在源图片目录 (--src) 下的 command.json 文件进行配置。

command.json 结构

此文件将模块名映射到具体的打包命令。

{
    "common": "common common1_bg@128 common1_tab@128 -oversize 2048",
    "main": "main@1024 -oversize 2048"
}

• "common": 键是模块名，对应于 --src 目录下的一个子文件夹。
• common: common 模块下的一个子目录，它将被打包成 common.png 和 .plist。
• common1_bg@128: 打包 common1_bg 目录，但其中任何宽度或高度超过 128px 的图片都将从图集中排除，并被直接复制到输出目录。
• -oversize 2048: 应用于此模块的全局规则。如果最终生成的图集尺寸超过 2048x2048，TexturePacker 将会报错。

CLI 命令行选项

用法: tp [options]

一个使用 TexturePacker 打包图集的 CLI 工具。

选项:
  -V, --version        输出版本号
  -s, --src <path>     源图片根目录 (必须包含 command.json)
  -o, --out <path>     导出根目录
  -p, --packer <path>  TexturePacker.exe 的路径
  -m, --module <name>  目标模块名, "all" 表示所有模块 (默认: "all")
  -c, --concurrency <n> 并行任务数 (默认: 4)
  -h, --help           显示帮助信息

示例

假如我们有上述的 command.json 和一个名为 ./art 的源目录，以下命令将打包所有已定义的模块：

tp -s ./art -o ./dist-assets -p "/path/to/TexturePacker.exe" -m all

此命令将在 ./dist-assets/res/gui/<module_name>/img/ 目录下生成图集文件。

输出目录结构

打包好的图集和被过滤的散图将按以下结构组织在输出目录中，这种结构在 Cocos2d 项目中非常常见。

<outPath>/
└── res/
    └── gui/
        ├── <module_name>/
        │   └── img/
        │       ├── atlas1.png
        │       ├── atlas1.plist
        │       ├── oversized_image.png  (被复制的散图)
        │       └── ...
        └── ...

许可证

ISC

作为 JS/TS 库使用

除了 CLI，本工具也可以作为普通依赖被其他 Node.js 脚本调用。

# 安装到项目依赖
npm i tp-tool -D

以下示例分别展示 ESModule、CommonJS 与 TypeScript 的调用方式：

ESM

import { packTextures } from 'tp-tool';

const result = await packTextures({
  srcPath: 'F:/work/project/art',
  outPath: './assets',
  packerPath: 'C:/Program Files/TexturePacker/TexturePacker.exe',
  module: 'common',
  concurrency: 4,
});

console.log(result);

CommonJS

const { packTextures } = require('tp-tool');

packTextures({
  srcPath: './art',
  outPath: './assets',
  packerPath: 'C:/TexturePacker.exe',
  module: 'common',
}).then(console.log);

TypeScript

import { packTextures, PackOptions } from 'tp-tool';

const opts: PackOptions = {
  srcPath: './art',
  outPath: './assets',
  packerPath: 'C:/TexturePacker.exe',
  module: 'common',
};

const res = await packTextures(opts);

监听进度事件

packTextures 同时返回一个 EventEmitter，方便监听实时进度：

packTextures(opts)
  .on('progress', (e) => {
    console.log('[Progress]', e);
  })
  .on('error', console.error)
  .then((res) => console.log('[Done]', res));