收集系统资源发布指南

本文档补充 SOP 操作手册，重点说明资源发布的正确方式

一、资源发布原则

1.1 使用官方发布脚本

✅ 正确做法：

使用 WorldTourCasinoResource/PlugIns/publishCCB.py 脚本
不要自己创建发布脚本

❌ 错误做法：

直接使用 rsync 同步资源
在主项目 scripts 目录创建自定义发布脚本

1.2 发布完整目录

重要：发布的是三个主目录主体，不仅仅是当前赛季的资源。

三个主目录：

casino/card_system/
card_system_lagload/
dynamic_feature/card_system/

二、资源发布步骤

2.1 环境准备

确认环境变量已配置：

bash

echo $COCOS_X_ROOT
# 应输出：/Users/mac/Documents/Projects/WorldTourCasino/frameworks

2.2 发布命令

在 WorldTourCasinoResource/PlugIns 目录下执行：

bash

cd /Users/mac/Documents/Projects/WorldTourCasinoResource/PlugIns

# 1. 发布 casino/card_system（配置文件、卡册图标、卡片图片）
python publishCCB.py \
  "/Users/mac/Documents/Projects/WorldTourCasinoResource/oldvegas/Resources/casino/card_system" \
  "/Users/mac/Documents/Projects/WorldTourCasinoResource/oldvegas/Resources" \
  "card_system" \
  "/Users/mac/Documents/Projects/WorldTourCasino" \
  0

# 2. 发布 card_system_lagload（BGM、背景图、视频等延迟加载资源）
python publishCCB.py \
  "/Users/mac/Documents/Projects/WorldTourCasinoResource/oldvegas/Resources/card_system_lagload" \
  "/Users/mac/Documents/Projects/WorldTourCasinoResource/oldvegas/Resources" \
  "card_system_lagload" \
  "/Users/mac/Documents/Projects/WorldTourCasino" \
  0

# 3. 发布 dynamic_feature/card_system（动态加载的卡片资源）
python publishCCB.py \
  "/Users/mac/Documents/Projects/WorldTourCasinoResource/oldvegas/Resources/dynamic_feature/card_system" \
  "/Users/mac/Documents/Projects/WorldTourCasinoResource/oldvegas/Resources" \
  "card_system" \
  "/Users/mac/Documents/Projects/WorldTourCasino" \
  0

2.3 命令参数说明

bash

python publishCCB.py \
  [资源完整路径] \           # 源目录的绝对路径
  [资源根路径] \              # Resources 目录的绝对路径
  [章节名称] \                # 相对路径的最后一级目录名
  [工程路径] \                # 主项目的绝对路径
  [工程索引]                  # 0=oldvegas, 1=doublehit, etc.

三、官方脚本功能

publishCCB.py 会自动处理：

资源同步
- 使用 resourcePublish.py 同步资源
- 自动处理 HD 资源（_hd 文件）
- 自动缩放图片和配置文件
CCB 编译
- 自动将 .ccb 源文件编译成 .ccbi 二进制文件
- 使用 ccbpublish 工具
资源检查
- 检查图片尺寸（超过 1024×1024 会警告）
- 检查内存占用（超过 130MB 会警告）
- 检查跨域引用、丢失图片、同名图片等问题
热更新列表
- 生成 publish/moduleDebugList.json
- 用于热更新功能

四、常见问题

4.1 ccbpublish 报错

现象：

Error: No plugin exists using the extension ccbi.

原因：

S22 等新赛季目录通常不包含 .ccb 文件
插件加载问题（不影响资源同步）

处理：

✅ 正常现象，继续执行即可
✅ 资源的 rsync 部分已成功完成

4.2 内存占用警告

现象：

内存贴图大小为：504.682926178 MB，上限为130 MB

处理：

⚠️ 仅为警告，不影响发布
可联系美术优化大图资源

4.3 文件路径问题

错误示例：

bash

# ❌ 使用相对路径
python publishCCB.py "../oldvegas/Resources/casino/card_system" ...

正确示例：

bash

# ✅ 使用绝对路径
python publishCCB.py "/Users/mac/Documents/Projects/WorldTourCasinoResource/oldvegas/Resources/casino/card_system" ...

五、验证发布结果

5.1 检查文件数量

bash

cd /Users/mac/Documents/Projects/WorldTourCasino

# 检查 S22 配置文件
ls -lh res_oldvegas/casino/card_system/album/s_22/album_name_config.json
ls -lh res_oldvegas/casino/card_system/cards/s_22/card_names.json

# 检查卡片图片数量
find res_oldvegas/casino/card_system/cards/s_22 -name "*.jpg" | wc -l
# 应该约 200 张

find res_oldvegas/dynamic_feature/card_system/cards/s_22 -name "*.jpg" | wc -l
# 应该约 200 张

5.2 检查 git 状态

bash

git status --short | grep -v "flavor\|resource_" | wc -l
# 统计变更文件数量（不含构建产物）

六、重要注意事项

6.1 发布顺序

按以下顺序发布（避免资源不完整）：

casino/card_system
card_system_lagload
dynamic_feature/card_system

6.2 发布失败处理

原则：发布出现问题时打断整个更新流程并显示错误信息

如果某个目录发布失败：

停止后续发布
检查错误信息
修复问题后重新发布该目录
继续发布剩余目录

6.3 工程索引对照表

索引	工程名称	目录名
0	Classic Vegas	oldvegas
1	Double Hit	doublehit
2	Double X	doublex
3	Vegas Star	vegasstar

七、配置规范

7.1 卡册数量

当前规范：只生成卡册 1-20，不包含 21 和 22

每个卡册 10 张卡片
总计 200 张卡片
配置文件：album_name_config.json（20 个卡册）
配置文件：card_names.json（200 张卡片）

7.2 playerWordTitle 字段规范

⚠️ 重要：card_names.json 中的 playerWordTitle 字段是必需的。

字段规则：

仅在包含 playerWordDesc（玩家寄语）的卡片中添加
playerWordTitle 的值应与 name 字段相同
代码通过 playerWordTitle 和 playerWordDesc 判断是否为玩家角色卡

正确示例（有玩家寄语）：

json

{
  "220101": {
    "name": "Snow Memory",
    "banner": "card_blue_banner",
    "border": "card_orange_border",
    "playerWordTitle": "Snow Memory",
    "playerWordDesc": "It didn't snow much where we lived..."
  }
}

正确示例（无玩家寄语）：

json

{
  "220201": {
    "name": "Saber",
    "banner": "card_green_border",
    "border": "card_pink_banner"
  }
}

代码依赖：

src/social/controller/card_system/card_item/CardInfoController.js:85 - 检查是否显示玩家寄语
src/social/entity/card_system/CardState.js:42 - 判断是否为玩家角色卡

7.3 资源目录结构

WorldTourCasinoResource/oldvegas/Resources/
├── casino/card_system/
│   ├── album/s_XX/
│   │   ├── album_name_config.json      # 卡册名称配置
│   │   └── card_22XX.png × 20          # 卡册图标
│   └── cards/s_XX/
│       ├── card_names.json             # 卡片配置
│       └── album_1 ~ album_20/         # 卡片图片
│
├── card_system_lagload/
│   ├── card_season_bg_sXX.jpg          # 背景图
│   ├── mp3/cardsystem_bgm_sXX.mp3      # BGM（可选）
│   ├── season_main/card_season_video_sXX.mp4  # 视频（可选）
│   └── howtoplay/card_how_to_play_sXX/ # 玩法说明
│
└── dynamic_feature/card_system/
    └── cards/s_XX/
        └── album_1 ~ album_20/         # 200 张动态卡片图片

八、实战案例：S22 赛季更新

8.1 更新概况

更新时间：2025-11-21 赛季：S22 风格：Classic Vegas (CV) 卡册数量：20 个 卡片数量：200 张

8.2 关键配置

项目	值
maxSeasonId	21 → 22
旧赛季清理	S20（约 240 个文件）
新赛季资源	S22（约 470 个文件，~27MB）
playerWordTitle	10 张卡片包含玩家寄语

8.3 资源发布方式

本次采用：rsync 直接同步（快速发布）

bash

cd /Users/mac/Documents/Projects/WorldTourCasino/scripts

# 同步 casino/card_system/
rsync -avr "../../WorldTourCasinoResource/oldvegas/Resources/casino/card_system/" \
    "../res_oldvegas/casino/card_system/" \
    --exclude='*.ccb'

# 同步 dynamic_feature/card_system/
rsync -av "../../WorldTourCasinoResource/oldvegas/Resources/dynamic_feature/card_system/" \
    "../res_oldvegas/dynamic_feature/card_system/" \
    --exclude='*.ccb'

优点：

执行速度快
不依赖 CocosBuilder 环境
适合纯资源更新（无 .ccb 文件）

缺点：

不处理 .ccb → .ccbi 编译
不做资源检查和优化
需要手动处理资源清理

建议：

仅资源更新时可用 rsync
涉及 .ccb 文件时必须用 publishCCB.py

8.4 遇到的问题及解决

问题 1：playerWordTitle 字段丢失

现象：初次生成的配置文件缺少 playerWordTitle 字段

影响：

玩家寄语无法显示
代码逻辑判断失败（CardInfoController.js:85）

解决：

python

# 在包含 playerWordDesc 的卡片中添加 playerWordTitle
if player_word:
    card_entry["playerWordTitle"] = card_name  # 值为卡牌名称
    card_entry["playerWordDesc"] = player_word

问题 2：资源目录位置混淆

现象：不清楚应该在哪里创建配置文件

正确做法：

✅ 在 WorldTourCasinoResource 仓库生成配置
✅ 通过发布流程同步到 WorldTourCasino 主项目
❌ 不要直接在主项目创建配置文件

8.5 验证清单

构建测试后的验证项：

[x] src/social/model/CardSystemMan.js:57 - maxSeasonId = 22
[x] album_name_config.json - 20 个卡册名称
[x] card_names.json - 200 张卡片配置
[x] playerWordTitle - 10 张卡片包含该字段
[x] 卡册图标 - 20 张 card_22XX.png
[x] 卡片图片 - 200 张 _s.jpg（小图）
[x] 动态资源 - 200 张 .jpg（大图）
[x] S20 旧资源已清理
[x] 本地构建通过（退出码 0）

8.6 待补充资源

以下资源可后续补充：

⚠️ BGM：cardsystem_bgm_s22.mp3
⚠️ 视频：card_season_video_s22.mp4

九、相关文档

新版收集系统SOP操作手册 - 完整的赛季更新流程
活动资源优化-后置加载方案 - 资源加载优化

修订人：AI Assistant 最后更新：2025-11-21（添加 S22 更新案例和 playerWordTitle 规范）

📂 archive

📂 WTC

📂 code-review

📂 docs

📂 extensions

📂 shared

收集系统资源发布指南 ​

一、资源发布原则 ​

1.1 使用官方发布脚本 ​

1.2 发布完整目录 ​

二、资源发布步骤 ​

2.1 环境准备 ​

2.2 发布命令 ​

2.3 命令参数说明 ​

三、官方脚本功能 ​

四、常见问题 ​

4.1 ccbpublish 报错 ​

4.2 内存占用警告 ​

4.3 文件路径问题 ​

五、验证发布结果 ​

5.1 检查文件数量 ​

5.2 检查 git 状态 ​

六、重要注意事项 ​

6.1 发布顺序 ​

6.2 发布失败处理 ​

6.3 工程索引对照表 ​

七、配置规范 ​

7.1 卡册数量 ​

7.2 playerWordTitle 字段规范 ​

7.3 资源目录结构 ​

八、实战案例：S22 赛季更新 ​

8.1 更新概况 ​

8.2 关键配置 ​

8.3 资源发布方式 ​

8.4 遇到的问题及解决 ​

8.5 验证清单 ​

8.6 待补充资源 ​

九、相关文档 ​

收集系统资源发布指南

一、资源发布原则

1.1 使用官方发布脚本

1.2 发布完整目录

二、资源发布步骤

2.1 环境准备

2.2 发布命令

2.3 命令参数说明

三、官方脚本功能

四、常见问题

4.1 ccbpublish 报错

4.2 内存占用警告

4.3 文件路径问题

五、验证发布结果

5.1 检查文件数量

5.2 检查 git 状态

六、重要注意事项

6.1 发布顺序

6.2 发布失败处理

6.3 工程索引对照表

七、配置规范

7.1 卡册数量

7.2 playerWordTitle 字段规范

7.3 资源目录结构

八、实战案例：S22 赛季更新

8.1 更新概况

8.2 关键配置

8.3 资源发布方式

8.4 遇到的问题及解决

8.5 验证清单

8.6 待补充资源

九、相关文档