Crab Transit Resources (CTR) 资源包合并工具

一个用于整合多个 Minecraft Transit Railway (MTR) 资源包的工具，能够自动解压、合并资源文件，并智能处理JSON配置文件。

✨ 功能特性

• 自动解压：自动解压 packs/ 目录下的所有ZIP格式追加包
• 智能合并：合并静态资源文件，自动跳过重复文件和特定目录
• JSON处理：智能合并 mtr_custom_resources.json 和 sounds.json 配置文件
• PID配置生成：自动扫描 custom_directory 中的图片并生成 joban_custom_resources.json 配置
• 天津地铁广告处理：扫描广告图片并生成配置，提示用户修改标语
• 版本管理：自动更新 pack.mcmeta 文件中的版本号、Git commit和构建时间
• 详细日志：使用Winston日志系统记录所有操作细节
• 缓存清理：处理完成后自动清理临时文件

📁 项目结构

ctr/
├── src/                    # 源代码
│   ├── index.ts           # 主合并脚本
│   ├── update-pack-meta.ts # 元数据更新脚本
│   ├── types/             # TypeScript类型定义
│   ├── utils/             # 工具函数
│   └── processors/        # 处理器模块
├── main/                  # 主资源包目录（解压后的CTR主体）
├── packs/                 # 追加包目录（ZIP格式）
├── cache/                 # 临时缓存目录（自动清理）
├── logs/                  # 日志文件目录
├── dist/                  # 输出目录（生成的完整资源包）
├── package.json           # 项目配置
├── tsconfig.json          # TypeScript配置
├── LICENSE               # MIT许可证
└── README.md             # 本文件

🚀 快速开始

环境要求

• Node.js 16+
• Git（用于获取commit hash）
• TypeScript环境（已包含在依赖中）

安装

# 克隆仓库
git clone https://github.com/HeyCrab3/ctr.git
cd ctr

# 安装依赖
npm install

准备资源包

1. 主资源包：将解压后的CTR主体资源包放入 main/ 目录
2. 追加包：将所有ZIP格式的追加包放入 packs/ 目录

运行合并

# 合并所有资源包
npm run merge

# 或直接运行
npx tsx src/index.ts

更新元数据

# 更新pack.mcmeta中的版本信息
npm run update-meta

📝 配置说明

跳过规则

以下目录和文件在合并时会被跳过：

• assets/minecraft/（整个目录）
• assets/mtr/textures/sign.png
• assets/mtr/lang/（整个目录）
• assets/mtr/font/（整个目录）
• 已存在的文件（不覆盖）

JSON合并规则

1. mtr_custom_resources.json：合并 custom_trains 对象

2. sounds.json：合并 sounds 对象

3. joban_custom_resources.json：

   • 扫描 assets/jsblock/custom_directory 中的图片
   • 为每个新图片生成PID配置条目
   • 避免重复ID

4. 天津地铁广告处理：

   • 扫描 assets/tjmetro/ads/ 目录
   • 读取 pids_tianjin_ads.json 获取标语
   • 生成广告PID配置，标记需要用户检查

日志系统

• 日志文件保存在 logs/ 目录
• 控制台输出详细的操作信息
• 支持不同日志级别（INFO、WARN、ERROR、DEBUG）

📦 脚本命令

命令	说明
npm run merge	合并所有资源包
npm run update-meta	更新pack.mcmeta文件
npm run pack	压缩资源包到dist目录
npm run release	完整发布流程（合并+更新+打包）
npm run build	构建项目（保留）
npm run test	运行测试（保留）

完整发布流程

要生成完整的资源包，建议按顺序运行以下命令：

# 1. 合并所有追加包
npm run merge

# 2. 更新版本信息
npm run update-meta

# 3. 打包成ZIP文件
npm run pack

或者，你可以直接使用 npm run release 命令自动执行上述所有步骤。

生成的ZIP文件将保存在 dist/ 目录中，文件名包含版本号、commit hash和日期。

🔧 开发说明

添加新跳过规则

编辑 src/utils/file-utils.ts 中的 shouldSkipFile 函数。

添加新的JSON处理器

在 src/processors/ 目录下创建新的处理器模块。

修改日志配置

编辑 src/utils/logger.ts 中的Winston配置。

📄 许可证

本项目采用 GNU AGPLv3 许可证 - 查看 LICENSE 文件了解详情。

🐛 问题反馈

发现Bug或有改进建议？请通过以下方式反馈：

1. 在 Issues 页面创建新issue
2. 描述详细的问题现象和复现步骤
3. 提供相关的错误日志

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 开启 Pull Request

📈 版本历史

注意：此版本号跟随 CTR 资源包而变动，不代表主程序版本

• v5.8.0 (2026-03-22)
  • 初始版本发布
  • 完整的资源包合并功能
  • 智能JSON处理
  • 详细的日志系统

📞 联系方式

• GitHub: @HeyCrab3
• 项目主页: https://github.com/HeyCrab3/ctr

---

注意：本项目仅供学习和个人使用。Minecraft是Mojang Studios的商标。