WorldTourCasino

Appearance

整理机台资源工具使用文档 ​

一、功能概述 ​

本工具用于自动整理 CV (Classic Vegas) 工程中 flagstone_big 机台的资源文件，并可选择性地移植到 DH (Double Hit) 工程。

主要功能 ​

  1. 资源收集：自动扫描ccb文件中引用的所有资源（plist和散图）
  2. 资源解包：解包所有引用的plist，提取用到的图片
  3. 统一打包：将所有图片打包成一个统一的plist文件
  4. 引用更新：自动更新ccb文件中的资源引用路径
  5. 文件整理：创建机台号文件夹，规范命名
  6. DH移植：可选择性地将整理好的资源复制到DH工程

适用范围 ​

  • 工程限制：目前仅支持 CV (Classic Vegas / oldvegas) 工程
  • 路径限制：只能用于 slot/lobby/flagstone_big 目录下的 ccb 文件
  • 文件格式：支持的ccb文件名格式：
    • XXX_big.ccb（如 129_big.ccb）
    • slot_lobby_flagstone_big_XX.ccb

二、使用方法 ​

1. 基本操作 ​

在 CocosBuilder 或文件管理器中：

  1. 右键点击 slot/lobby/flagstone_big 目录下的 ccb 文件
  2. 选择 "整理机台资源"
  3. 在弹出的二级菜单中选择：
    • 仅处理CV：只在CV工程中整理资源
    • 处理CV并移植DH：整理CV资源后自动复制到DH工程

2. 二级菜单说明 ​

选项1：仅处理CV ​

  • 用途：只整理CV工程的资源，不影响其他工程
  • 适用场景：
    • 首次整理机台资源
    • 只需要在CV工程中使用
    • DH工程暂时不需要更新

选项2：处理CV并移植DH ​

  • 用途：整理CV资源后，自动复制到DH工程对应位置
  • 适用场景：
    • CV和DH工程都需要使用该机台
    • 保持两个工程资源同步
  • 前提条件：
    • DH工程路径存在（与CV工程同级）
    • 路径结构：/path/to/doublehit/Resources/slot/lobby/flagstone_big/

三、工作流程 ​

步骤1：扫描资源引用 ​

  • 扫描ccb文件，找出所有引用的plist和散图
  • 自动忽略：slot/lobby/flagstone/slot_lobby_flagstone_common_sources 下的共享资源

步骤2：提取plist资源 ​

  • 解包所有引用的plist文件
  • 提取完整的plist内容（不只是ccb引用的图片）
  • 确保动画序列帧完整

步骤3：收集散图资源 ​

  • 查找符合 机台号_ 命名规则的散图
  • 从相关文件夹中收集所有该机台的图片

步骤4：统一打包 ​

  • 将所有收集的图片打包成一个统一的plist
  • 命名格式：slot_lobby_flagstone_big_XXX.plist
  • 同时生成对应的 .png 文件

步骤5：移动和重命名 ​

  • 创建机台号文件夹（如 292/）
  • 移动ccb文件到文件夹中
  • 重命名为标准格式：slot_lobby_flagstone_big_XXX.ccb
  • 移动已有的相关资源文件

步骤6：更新资源引用 ​

  • 读取统一plist中的所有图片列表
  • 扫描ccb中所有 SpriteFrame 引用
  • 将引用路径更新为统一plist

引用路径格式：

xml
<string>displayFrame</string>
<key>type</key>
<string>SpriteFrame</string>
<key>value</key>
<array>
    <string>slot/lobby/flagstone_big/292/slot_lobby_flagstone_big_292.plist</string>
    <string>image_name.png</string>
</array>

步骤7：移植到DH（可选） ​

如果选择 "处理CV并移植DH"：

  1. 自动构建DH工程路径（替换 /oldvegas/ 为 /doublehit/）
  2. 检查DH路径是否存在
  3. 如果目标文件夹已存在，询问是否覆盖
  4. 复制整个机台文件夹到DH工程

四、生成文件结构 ​

整理前 ​

slot/lobby/flagstone_big/
├── 129_big.ccb
├── 129_big_xxx.plist
└── 129_big_xxx.png

整理后（CV工程） ​

slot/lobby/flagstone_big/
└── 129/
    ├── slot_lobby_flagstone_big_129.ccb
    ├── slot_lobby_flagstone_big_129.plist
    └── slot_lobby_flagstone_big_129.png

整理后（DH工程，如选择移植） ​

doublehit/Resources/slot/lobby/flagstone_big/
└── 129/
    ├── slot_lobby_flagstone_big_129.ccb
    ├── slot_lobby_flagstone_big_129.plist
    └── slot_lobby_flagstone_big_129.png

五、注意事项 ​

1. 工程限制 ​

⚠️ 重要：目前仅支持 CV (Classic Vegas) 工程

  • 如果在其他工程（DH、VS、DHX）中运行，会报错
  • 路径必须包含 oldvegas

2. 资源完整性检查 ​

工具会自动检查资源完整性：

  • 如果发现图片在统一plist中不存在，会在最后给出警告提示
  • 列出所有缺失的图片名称
  • 提供诊断信息和可能的原因
  • 不会中断操作，但需要手动检查和修复

3. 共享资源处理 ​

自动忽略以下路径的资源：

  • slot/lobby/flagstone/slot_lobby_flagstone_common_sources

这些共享资源不会被复制到统一plist中，ccb中的引用会保持原样。

4. 命名规范 ​

工具会自动规范命名：

  • ccb文件：slot_lobby_flagstone_big_XXX.ccb
  • 统一plist：slot_lobby_flagstone_big_XXX.plist
  • 文件夹：XXX/（机台号）

5. 覆盖确认 ​

  • 如果机台号文件夹已存在，会询问是否继续
  • 如果DH工程中已存在同名文件夹，会询问是否覆盖

6. 依赖工具 ​

  • TexturePacker：用于打包图片
    • 安装路径：/Applications/TexturePacker.app
    • 如未安装，会跳过打包功能
  • plistUnpack.py：用于解包plist
    • 位置：同目录下的 plistUnpack.py

六、常见问题 ​

Q1: 提示"此功能暂时只能在 CV 工程中使用" ​

原因：ccb文件路径不包含 oldvegas

解决：

  • 确认正在 CV (Classic Vegas) 工程中操作
  • 检查路径是否正确

Q2: 警告"发现 X 个图片在统一 plist 中未找到" ​

原因：

  1. ccb 动态引用了某些图片，扫描时未识别到对应的 plist
  2. 散图文件名不符合 机台号_ 的命名规则
  3. plist 解包失败或图片在原 plist 中就不存在
  4. ccb 引用了不属于本机台的共享资源

解决：

  1. 检查缺失图片是否真的需要（可能是旧引用）
  2. 手动将缺失的图片添加到统一 plist 中
  3. 在 CocosBuilder 中检查引用是否正确

Q3: DH移植失败 ​

可能原因：

  1. DH工程路径不存在
  2. 路径结构不符合预期
  3. 没有写入权限

解决：

  1. 确认DH工程存在且路径正确
  2. 检查路径结构：/path/to/doublehit/Resources/slot/lobby/flagstone_big/
  3. 检查文件夹权限

Q4: TexturePacker 未找到 ​

原因：未安装 TexturePacker 或安装路径不正确

解决：

  1. 从官网下载安装 TexturePacker
  2. 将 TexturePacker.app 拖到"应用程序"目录

Q5: 整理后在 CocosBuilder 中显示异常 ​

可能原因：

  1. 有图片缺失（查看警告提示）
  2. 引用路径更新失败
  3. plist 打包失败

解决：

  1. 查看脚本输出的警告信息
  2. 手动在 CocosBuilder 中检查引用
  3. 使用版本控制恢复后重新执行

七、输出信息说明 ​

成功信息（绿色） ​

  • ✓ plist: xxx.plist - 成功识别plist
  • ✓ 散图: xxx.png - 成功识别散图
  • ✓ 统一打包完成 - 打包成功
  • ✓ 成功更新 X 处资源引用 - 引用更新成功
  • ✓ 移植到DH工程完成 - DH移植成功

警告信息（橙色） ​

  • ⚠ 但有 X 个图片在统一 plist 中未找到 - 部分图片缺失
  • 警告：目录已存在 - 目标文件夹已存在

错误信息（红色） ​

  • ✗ 错误：无法从文件名中提取机台号 - 文件名格式不正确
  • ✗ 错误：此功能暂时只能在 CV 工程中使用 - 工程限制
  • ✗ plist 不存在 - 引用的plist文件找不到

提示信息（紫色） ​

  • 模式：仅处理CV - 当前执行模式
  • 模式：处理CV并移植DH - 当前执行模式
  • 请右键点击 Refresh 刷新目录列表 - 操作提示

八、最佳实践 ​

1. 执行前 ​

  • ✅ 确保在CV工程中操作
  • ✅ 备份重要文件（或使用版本控制）
  • ✅ 检查TexturePacker是否已安装

2. 执行时 ​

  • ✅ 仔细阅读提示信息
  • ✅ 如果警告资源缺失，检查是否影响功能
  • ✅ 确认覆盖操作前先备份

3. 执行后 ​

  • ✅ 在CocosBuilder中打开ccb文件检查显示
  • ✅ 测试动画和引用是否正常
  • ✅ 如果移植到DH，同样在DH工程中检查
  • ✅ 右键点击"Refresh"刷新目录列表

4. 版本控制 ​

  • ✅ 整理完成后及时提交到版本控制
  • ✅ 编写清晰的提交信息
  • ✅ 如果发现问题，可以快速回滚

九、技术细节 ​

资源扫描正则表达式 ​

python
# 匹配 SpriteFrame 结构
<string>displayFrame</string>
<key>type</key>
<string>SpriteFrame</string>
<key>value</key>
<array>
    <string>plist路径或空</string>
    <string>图片路径.png</string>
</array>

路径计算逻辑 ​

  • 使用 os.path.relpath() 计算相对路径
  • 确保引用路径格式正确：slot/lobby/flagstone_big/292/xxx.plist
  • DH路径通过替换字符串生成：/oldvegas/ → /doublehit/

打包参数 ​

  • 算法：MaxRects
  • 启用旋转：是
  • 尺寸范围：256/512/1024/2048
  • 边距：2px
  • 格式：cocos2d

十、联系方式 ​

如有问题或建议，请联系开发团队。

文档版本：v1.0 更新日期：2026-02-09

Released under the MIT License.

Copyright © 2024-present WorldTourCasino