gsalires

一个用于自动化上传游戏资源到 GUTS 平台的 npm 命令行工具。

功能概述

gsalires 是一个命令行工具，用于批量上传游戏资源（图片、Spine 动画、字体、音频）到 GUTS 平台。它通过 HTTP 轮询与浏览器中运行的 guts.js 油猴脚本通信，实现自动化的资源上传流程。

安装

npm install -g @gswl/gsalires

前置条件

使用前请确保：

1. 已安装 guts.js 油猴脚本（位于 tampermonkey/guts.js）
2. 在浏览器中打开 GUTS 网站（https://guts.alibaba-inc.com），油猴脚本会自动运行
3. 油猴脚本会自动通过 HTTP 轮询连接到 gsalires 服务器

使用方法

gsalires <目标文件夹> [选项]

选项

| 选项 | 说明 | 默认值 | |------|------|--------| | -p, --port <port> | HTTP 服务器端口 | 8222 | | -c, --clear-cache | 强制清除缓存，重新上传所有资源 | - | | -d, --directory-cache <dir> | 指定缓存目录路径，resources.json 和 .cacheguts 将在此目录中生成，不污染目标文件夹 | - | | -f, --file <file> | 处理单个文件（见下方说明） | - | | -h, --help | 显示帮助信息 | - | | -v, --version | 显示版本号 | - |

示例

# 使用默认端口 8222
gsalires ./game-assets

# 使用自定义端口
gsalires ./game-assets --port 8080

# 清除缓存重新上传
gsalires ./game-assets --clear-cache

# 指定缓存目录，不污染目标文件夹
gsalires ./game-assets --directory-cache ./cache-output

# 组合使用：自定义端口 + 缓存目录
gsalires ./game-assets --port 8080 --directory-cache /tmp/gsalires-cache

单文件模式 (-f)

使用 -f 参数可以只处理单个文件，而不是扫描整个目录：

# 上传单个字体文件（直接指定字体文件）
gsalires ./game-assets -f ./game-assets/fonts/myfont.ttf

# 上传单个 Spine 资源（可以指定 atlas、skel 或 png 任意一个文件）
gsalires ./game-assets -f ./game-assets/spines/character/character.atlas
gsalires ./game-assets -f ./game-assets/spines/character/character.skel
gsalires ./game-assets -f ./game-assets/spines/character/character.png

# 上传单个图片
gsalires ./game-assets -f ./game-assets/images/icon.png

# 上传单个音频
gsalires ./game-assets -f ./game-assets/audios/bgm.mp3

单文件模式说明：

• 字体文件：直接指定字体文件（.ttf、.otf、.woff、.woff2），会自动查找同目录下同名的 .txt 文件
• Spine 资源：可以指定 .atlas、.skel、.json 或图片文件中的任意一个，工具会自动在同目录下查找完整的 Spine 资源（atlas + image + skel）
• 普通图片：直接指定图片文件，如果同目录下有对应的 .skel 文件则作为 Spine 资源处理
• 音频文件：直接指定音频文件（.mp3、.aac、.m4a）

支持的资源类型

1. 图片资源

• 支持格式：.png、.jpg、.jpeg、.gif、.bmp、.webp
• 上传时默认通过 TinyPNG 压缩（可通过 ignoretiny 文件跳过）

2. Spine 动画资源

• 每个 Spine 动画放在独立的子文件夹中
• 必须包含三个文件：.atlas、图片文件（.png 等）、骨骼文件（.skel 或 .json）
• 扫描时通过检测图片文件同目录下是否有对应的 .skel 文件来自动识别
• 上传时图片默认通过 TinyPNG 压缩

3. 字体资源

• 支持格式：.ttf、.otf、.woff、.woff2
• 如果同目录下有同名的 .txt 文件，会使用 .txt 中的文本内容对字体进行子集化裁切后上传
• 没有 .txt 文件的字体会直接上传原始字体文件

4. 音频资源

• 支持格式：.mp3、.aac、.m4a
• 直接上传到 GUTS 平台

目录结构

gsalires 会递归扫描目标文件夹下的所有文件，根据文件扩展名自动识别资源类型，不要求固定的子目录结构。推荐的目录组织方式如下：

默认模式

默认情况下，缓存和资源清单文件生成在目标文件夹中：

目标文件夹/
├── images/              # 图片资源（目录名不限）
│   ├── bg.png
│   └── icon.png
├── spines/              # Spine 动画资源
│   ├── character1/      # 每个 Spine 放在独立文件夹
│   │   ├── character1.atlas
│   │   ├── character1.png
│   │   └── character1.skel
│   └── character2/
│       └── ...
├── fonts/               # 字体资源
│   ├── myfont.ttf       # 字体文件
│   └── myfont.txt       # 可选，字体子集化文本
├── audios/              # 音频资源
│   └── bgm.mp3
├── ignoretiny           # TinyPNG 忽略列表（可选）
├── .cacheguts/          # 缓存目录（自动生成）
│   └── cache.json
└── resources.json       # 资源清单（自动生成）

使用 --directory-cache 模式

使用 --directory-cache 选项后，.cacheguts/ 和 resources.json 将生成在指定的缓存目录中，目标文件夹保持干净：

目标文件夹/                # 不会被污染，只包含原始资源
├── images/
│   ├── bg.png
│   └── icon.png
├── spines/
│   └── character1/
│       ├── character1.atlas
│       ├── character1.png
│       └── character1.skel
├── fonts/
│   ├── myfont.ttf
│   └── myfont.txt
├── audios/
│   └── bgm.mp3
└── ignoretiny

缓存目录（--directory-cache 指定）/
├── .cacheguts/          # 缓存目录（自动生成）
│   └── cache.json
└── resources.json       # 资源清单（自动生成）

TinyPNG 忽略列表（ignoretiny）

如果目标目录下存在 ignoretiny 文件，gsalires 会读取该文件，文件中列出的图片将跳过 TinyPNG 压缩。

文件格式：

• 每行一个图片文件名
• 支持注释行（以 # 开头）
• 空行会被忽略
• 可以使用完整路径或仅文件名

示例 ignoretiny 文件：

# 这些图片不需要 TinyPNG 压缩
logo.png
background.png

# Spine 动画中的图片也可以跳过压缩
hero_animation.png

适用场景：

• 已经过优化的图片，不需要再次压缩
• 对图片质量要求较高，不希望有损压缩
• 该功能同时适用于单独上传的图片和 Spine 动画中的图片

缓存机制

• 缓存目录：.cacheguts/，缓存文件：.cacheguts/cache.json（默认在目标文件夹中，可通过 --directory-cache 指定其他位置）
• 使用文件内容的 MD5 哈希值判断资源是否变化
• 已上传成功的资源会被缓存，下次运行时自动跳过，避免重复上传
• 使用 --clear-cache 选项可强制清除缓存，重新上传所有资源
• 已删除的资源会自动从缓存中清理

缓存文件格式示例：

{
  "images/bg.png": {
    "hash": "d41d8cd98f00b204e9800998ecf8427e",
    "url": "https://g.alicdn.com/...",
    "uploadedAt": "2024-01-01T00:00:00.000Z"
  },
  "spines/character1": {
    "hash": "a1b2c3d4e5f6...",
    "atlas": "https://g.alicdn.com/.../character1.atlas",
    "image": "https://g.alicdn.com/.../character1.png",
    "skel": "https://g.alicdn.com/.../character1.skel",
    "uploadedAt": "2024-01-01T00:00:00.000Z"
  }
}

输出文件（resources.json）

上传完成后，会生成 resources.json 文件，包含所有已上传资源的 CDN 链接。默认生成在目标文件夹根目录，使用 --directory-cache 时生成在指定的缓存目录中：

{
  "images/bg.png": "https://g.alicdn.com/.../bg.png",
  "images/icon.png": "https://g.alicdn.com/.../icon.png",
  "spines/character1": {
    "atlas": "https://g.alicdn.com/.../character1.atlas",
    "image": "https://g.alicdn.com/.../character1.png",
    "skel": "https://g.alicdn.com/.../character1.skel"
  },
  "fonts/myfont": "https://g.alicdn.com/.../myfont.woff",
  "audios/bgm.mp3": "https://g.alicdn.com/.../bgm.mp3"
}

已删除的资源会自动从 resources.json 中移除。

工作流程

1. 启动 HTTP 服务器：在指定端口启动 HTTP 服务器
2. 扫描资源：递归扫描目标目录下的图片、Spine、字体、音频文件
3. 计算文件哈希：使用 MD5 计算每个文件（或文件组合）的哈希值
4. 比对缓存：与 .cacheguts/cache.json 中的缓存比对，筛选出需要上传的资源
5. 等待客户端连接：等待 guts.js 油猴脚本通过 HTTP 轮询连接
6. 分发任务：将待上传资源逐个发送给客户端
7. 接收上传结果：接收 guts.js 返回的上传结果和 CDN 链接
8. 更新缓存：更新 .cacheguts/cache.json 缓存文件
9. 生成资源清单：生成/更新 resources.json 文件

guts.js 油猴脚本

tampermonkey/guts.js 是运行在 GUTS 网站上的油猴脚本，提供以下功能：

与 gsalires 集成

脚本内置了 HTTP 轮询客户端（GSaliresClient），会自动连接到 gsalires 的 HTTP 服务器（默认 http://localhost:8222），接收上传任务并执行。

独立功能（手动操作）

脚本还在 GUTS 页面上添加了一系列按钮，支持手动操作：

• 上传 Spine 资源：选择文件夹上传单个 Spine 资源
• 批量上传 Spine 资源：选择包含多个子文件夹的目录，批量上传
• Spine 变种：在 Spine 图片上框选区域添加数字标记，生成多个颜色变种
• 批量上传图片：选择文件夹批量上传图片
• 图片变种：选择图片生成多个 HSL 颜色变种
• 上传字体：选择字体文件和文本内容，生成裁切后的 WOFF 字体并上传
• 上传单张图片：选择单张图片上传
• 上传音频：选择音频文件上传（支持 mp3、aac、m4a）
• 资源重传：粘贴包含 Spine/PNG 链接的文本，自动下载、重新打包上传并替换链接

配置

在 guts.js 中可以修改服务器地址等配置：

const CONFIG = {
  serverUrl: "http://localhost:8222", // gsalires 服务器地址，与 --port 保持一致
  // ...
};

注意事项

1. 使用前请确保 guts.js 油猴脚本已安装并在 GUTS 网站上运行
2. 图片和 Spine 资源上传时默认通过 TinyPNG 压缩，可通过 ignoretiny 文件跳过
3. 缓存基于文件内容哈希，修改文件内容后会自动重新上传
4. 已删除的资源会自动从缓存和 resources.json 中移除

许可证

MIT License