AdLike2048/docs/项目分析报告.md

# AdLikeXy 项目分析报告

> 分析日期：2026-08-17  
> 引擎版本：Cocos Creator **3.8.8**  
> 项目 UUID：`d7fce9be-f307-4e7f-a8f5-3d0b5ca1e096`

**说明**：本文描述的是 **自老项目复制而来的代码基线**。当前仓库正基于此开发 **新产品**；工作约定与迭代方向见 [`项目说明.md`](./项目说明.md)。

---

## 1. 项目定位

**AdLikeXy** 是一款基于 **Cocos Creator 3.x** 开发的 **休闲塔防 + 汉字背包合成** 类小游戏，面向 **微信 / 抖音（头条）/ 快手** 等国内小游戏平台发行，以 **广告变现** 为核心商业模式。

当前默认 SDK 配置（`DefaultConfig`）对应产品：

| 项 | 值 |
|----|-----|
| 游戏名 | **守不住就开摆** |
| 渠道 | 抖音小游戏（`chanId: tt`） |
| AppID | `tt35ac4311abcd762602` |
| 版本 | `1.1.8` |

项目名称 **AdLikeXy** 表明这是同一玩法内核下的 **广告向变体/分支**（与多份 `sdk/config/*Config.ts` 多渠道马甲包配置一致）。同一套代码通过切换 `sdkConfig.config` 可打包为不同平台、不同马甲名的多款小游戏。

### 1.1 核心玩法概括

1. **局外养成**：章节闯关、武器/角色升级、商店、签到、任务、副本、转盘、基金/月卡等商业化模块。
2. **局内战斗**：12×10 格子塔防地图，玩家在 **备战阶段（PREP）** 通过 **背包合成（Merge）** 摆放汉字武器/字块，在 **战斗阶段（COMBAT）** 抵御多波怪物进攻。
3. **Roguelike 强化**：战斗中 **三选 1 词条（Skill 表）** 强化塔属性或替换主动技能。
4. **引流小游戏**：高压锅、弹弹弹等独立子玩法（`attractingTrafficGame` 分包），用于获客或活动引流。

### 1.2 题材与风格

- 武器以 **汉字/组合字** 为视觉载体（刀、组合字块、扩展格子等，`Weapon2` 表 `type` 1~4）。
- 带有 **剧情线、财经新闻、微信聊天** 等叙事/UI 元素，偏轻松搞笑网文风。
- 设计分辨率 **750×1600**，竖屏，`fitHeight` 适配。

---

## 2. 技术栈

| 层级 | 技术 |
|------|------|
| 引擎 | Cocos Creator 3.8.8 |
| 语言 | TypeScript（`assets` 下约 **684** 个 `.ts` 文件） |
| 物理 | 2D 物理（技能/怪物/门等多碰撞组） |
| 动画 | Spine（含运行时 patch） |
| 配表 | Excel → JSON（`excel-to-json-ts` 扩展） |
| 数据打点 | Gravity Analytics（`GEMgr`）+ 自研 `PF-` 性能通道 |
| 广告 SDK | 平台激励视频/插屏/Banner + ZYSDK 聚合 |
| 存档 | 本地 + SDK 云存档合并（`gg.data`） |

---

## 3. 整体架构

项目采用 **「MX 通用框架层 + 业务脚本层」** 双层结构：

```
┌─────────────────────────────────────────────────────────┐
│  GameLaunch（入口）→ BootPipeline → GameController      │
├─────────────────────────────────────────────────────────┤
│  assets/script/          业务层（UI、战斗适配、SDK）     │
│  assets/mx/              框架层（UI/资源/战斗内核/ECS）  │
├─────────────────────────────────────────────────────────┤
│  assets/bundles/         Asset Bundle 分包资源           │
│  assets/scene/main.scene 单主场景                        │
└─────────────────────────────────────────────────────────┘
```

### 3.1 全局入口 `gg`

`GG.ts` 定义 `GameGlobal` 单例，通过 `gg` 暴露各模块：

| 模块 | 职责 |
|------|------|
| `gg.ui` | UI 管理（分层、弹窗动画、战斗暂停钩子） |
| `gg.audio` | 音效/BGM |
| `gg.res` / `gg.assets` | 资源包加载、预载、生命周期 |
| `gg.data` | 配表 + 玩家存档 |
| `gg.sdk` | 平台 SDK、广告、打点 |
| `gg.lang` | 多语言 |
| `gg.game` | `GameController` 游戏流程总控 |
| `gg.battle` | `BattleService` 战斗服务门面 |

### 3.2 启动流程

`GameLaunch.ts` 负责冷启动，采用 **双门闩** 机制：

1. **Boot 资源就绪**（`BootPipeline`：核心表 + Boot 分包 + SDK 网络）
2. **SDK + 存档初始化完成**（`gg.data.init`）

两者均完成后调用 `gg.game.init()` 进入大厅。启动后延迟阶段再执行：机型探测、内存档位、发热治理、性能打点分级等。

关键文件：

- `assets/script/GameLaunch.ts`
- `assets/mx/module/boot/BootPipeline.ts`
- `assets/script/game/GameController.ts`

### 3.3 事件总线

跨模块通信使用 `GEvent`（`assets/mx/module/event/GEvent.ts`），例如：

- `SHOW_LOADING` / `HIDE_LOADING` — 全局 Loading
- `SHOW_NET_UI` — 网络等待 UI
- `MapGridsReady` — 战斗地图格子就绪

---

## 4. 目录结构说明

```
AdLikeXy/
├── assets/
│   ├── scene/                 # 主场景 main.scene
│   ├── script/                # 业务脚本（约 507+ 文件）
│   │   ├── GameLaunch.ts      # 游戏入口组件
│   │   ├── game/              # 核心游戏逻辑、配表、性能
│   │   ├── battle/            # 战斗项目适配层（203 ts）
│   │   ├── ui/                # UI 界面（194 ts，Auto_* 代码生成）
│   │   ├── sdk/               # SDK、广告、多渠道配置
│   │   ├── manager/           # 章节/武器/任务等数据管理
│   │   ├── activity/          # 活动
│   │   ├── purchase/          # 内购
│   │   └── ...
│   ├── mx/                    # MX 框架（160 ts）
│   │   ├── module/            # 功能模块
│   │   │   ├── battle/        # 战斗内核（无 Cocos 依赖）
│   │   │   ├── merge/         # 背包合成内核
│   │   │   ├── res/           # 资源调度与预载
│   │   │   ├── ui/            # UI 框架 + PopAnim
│   │   │   ├── boot/          # 启动/热更管线
│   │   │   ├── ecs/           # ECS 基础
│   │   │   └── ...
│   │   └── tools/             # 通用工具
│   └── bundles/               # Asset Bundle 分包
│       ├── first/             # 首包（含 config/*.json 配表）
│       ├── comm/              # 公共资源
│       ├── home/ shop/ ...    # 主界面 Tab
│       ├── battleGame/        # 战斗 UI
│       ├── battleMap/         # 地图预制体
│       ├── lang/              # 多语言包
│       └── attractingTrafficGame/  # 引流小游戏
├── extensions/                # 编辑器扩展
│   ├── excel-to-json-ts/      # 配表导出
│   ├── mx-res-manager/        # 资源管理面板
│   ├── tools/                 # 构建钩子、MembershipSet 同步
│   └── 引用查找器3.x/
├── docs/                      # 项目文档
├── settings/                  # 项目设置（分辨率、物理、图层）
└── package.json               # 项目元信息
```

---

## 5. 战斗系统

战斗是项目最复杂的核心模块，采用 **逻辑与表现分离** 设计。

### 5.1 分层

| 层级 | 路径 | 说明 |
|------|------|------|
| MX 内核 | `assets/mx/module/battle/` | `BattleSession`、ECS、技能/伤害/波次，**无 Cocos 依赖** |
| 项目适配 | `assets/script/battle/` | `BattleFacade`、`BattleRuntime`、配表映射、地图加载 |
| 表现/UI | `assets/script/ui/BattleGame/` | `UIBattleGame`、`Monster`、`MapAgent` |

### 5.2 地图规格

- 格子：**12 行 × 10 列**，每格 **75×75 px**
- 地图预制体：`bundles/battleMap/prefab/地图/mapLayer{mapId}.prefab`
- 寻路：8 方向距离场（`MapManager` + `MapAgent`）

### 5.3 战斗模式（`BattleType`）

| 枚举 | 说明 |
|------|------|
| `Level` | 主线关卡 |
| `InfiniteMode` | 无尽模式 |
| `GoldMode` | 金币模式 |
| `PropMode` | 道具模式 |
| `GachaMode` | 抽卡模式 |
| `BoxMode` | 宝箱模式 |
| `BossMode` | Boss 模式 |
| `PerimeterMode` | 循环圈副本 |
| `GuanyinMode` | 观音副本 |

章节配表约 **95** 条（`Chapter.json`），支持多难度（简单~末世 5 档）。

### 5.4 术语约定（重要）

| 对外说法 | 配表 | 含义 |
|----------|------|------|
| **词条** | `Skill` | 三选 1 局内强化，可替换主动技能 |
| **技能** | `base_atk` | 真正战斗技能（普攻/主动） |
| **塔** | `Weapon1` | 可放置单位数值 |
| **字块/棋子** | `Weapon2` | 背包合成用字块类型 |

详细接入文档：`assets/script/battle/接入指南.md`、`assets/script/battle/docs/需求说明.md`。

### 5.5 PVP 预留

架构已预留 `mode: 'solo' | 'pvp'`、`playerId` 多玩家上下文，但 **当前不实现联机**；新功能不得写死单玩家假设。

---

## 6. 背包合成（Merge）

局内备战阶段的 **汉字武器摆放** 由 MX `merge` 模块驱动：

- `assets/mx/module/merge/` — `MergeSession`、放置规则、升级系统
- 与战斗层通过背包会话（`bagSession`）和部署同步（`DeploySync`）衔接
- `Weapon2` 定义字块类型：单字武器、组合字、扩展格子、金手指

---

## 7. UI 系统

### 7.1 规模

- UI 脚本目录：`assets/script/ui/`（约 **194** 个 `.ts`）
- `UIID` 枚举约 **75+** 个界面 ID（`ConfigRes.ts`）
- 每个界面通常有 `UI*.ts`（逻辑）+ `Auto_*.ts`（节点绑定，代码生成）

### 7.2 主界面 Tab

| UIID | 模块 |
|------|------|
| Home (101) | 首页/章节选择 |
| Shop (200) | 商店 |
| Role (201) | 角色 |
| Weapon (203) | 武器 |
| Replica (204) | 副本 |

### 7.3 UI 框架能力

- 分层管理（`UILayer`）、战斗 UI 打开时自动暂停战斗（`BattleUiPauseGate`）
- `popAnim` 弹窗动画系统（预设、缓动、交错出现）
- `RuntimeLoadingGate` 运行时 Loading 防抖与看门狗

---

## 8. SDK、广告与商业化

### 8.1 多渠道马甲配置

`assets/script/sdk/config/` 含 **20+** 份渠道配置，前缀含义：

| 前缀 | 平台 |
|------|------|
| `TT*` | 抖音/头条小游戏 |
| `Wx*` / `WX*` | 微信小游戏 |
| `KS*` | 快手 |
| `BL*` | B站等 |

构建时修改 `sdkConfig.config` 切换马甲包。

### 8.2 广告类型

- **激励视频**（`RewardedVideoAd`）— 复活、加速、奖励等
- **插屏广告**（`InterstitialAd`）
- **Banner**
- 录屏分享（`TTRecording`，抖音）

### 8.3 数据打点

| 通道 | 用途 | 入口 |
|------|------|------|
| Gravity `GEReportEvent` | 运营漏斗、广告次数 | `GEMgr` |
| `gg.sdk.reportPerf` | 性能辅助 `PF-*` 前缀 | `PerfReport.ts` |
| 30r SDK | 微信侧补充打点 | `gg.sdk.initSdk30r` |

性能打点与广告统计已 **严格隔离**（避免 `Android` 等子串误计广告）。详见 `docs/性能打点说明.md`。

### 8.4 内购与付费

- `Purchase` 模块支持 IAP（`sdkConfig.isIAPVersion` 控制）
- 配表：`Pay`、`ShopBuy`、`MonthCard`、`FirstBag`、`Fund`、`ContinueBag` 等
- 钻石商店、章节礼包、连续购买等 UI 均已实现

---

## 9. 资源管理与性能工程

本项目在 **小游戏内存/加载** 方向投入较多工程化能力：

### 9.1 分包策略（`GBundle`）

| 类型 | Bundle 示例 |
|------|-------------|
| 首包常驻 | `first`、`comm`、`icons_boot`、`audio` |
| 主界面 | `home`、`shop`、`role`、`weapon`、`replica` |
| 战斗 | `battleGame`、`battleMap`、`battleGameMonster`、`battleHero` |
| 弹窗 | `popCommon`、`popBattle` + `allBuyShops` 子包 |
| 多语言 | `lang_cn`、`lang_en` |

### 9.2 预载与调度

- `LoadScheduler` — 加载队列与优先级
- `PreloadPredictor` — 预测性预载（大厅暖机、章节预载）
- `BundleLifecycle` — 分包释放策略
- `BattleBackgroundLoadGate` — 战斗期后台加载门控
- `ResourcePhaseGate` — 按阶段（Boot/大厅/战斗）切换资源策略

### 9.3 内存与帧率治理

- `MemoryProfile` — 按机型分档（tier0/1/3）
- `MemoryDowngrade` — 内存告警降档（停预载、大厅 30fps）
- `ThermalGovernor` — 发热档位与帧率策略
- `DeviceCapability` — 平台能力探测

### 9.4 性能监控

- `PerfReport` / `PerfLoadTimer` / `PerfSampler`
- 启动分级 `PF-BOOT-TIER-*`、加载 `PF-LD-*`、内存 `PF-MEM-*`、帧率 `PF-THRM-FPS-*`

---

## 10. 配表系统

### 10.1 存储位置

核心配表在 `assets/bundles/first/config/*.json`（约 **51** 张表），随 `first` 首包加载。

### 10.2 主要配表（`TableNames`）

| 类别 | 表名 |
|------|------|
| 关卡 | `Chapter`、`Chapter_monster`、`Chapter_weight`、`Replica` |
| 战斗 | `Weapon1~4`、`Monster`、`Monster2`、`base_atk`、`Skill`、`Skill_pool` |
| 经济 | `Item`、`Shop`、`Box`、`Pay`、`ShopBuy` |
| 养成 | `Role`、`Character`、`Skin`、`Task`、`TarTask` |
| 活动 | `LimitActivity`、`NewYearSign`、`NewFun`、`Playmode` |
| 常量 | `ConstConf`、`Guide`、`Obstacle` |

### 10.3 热更新

`ConfigHotUpdate.ts` + `BootPipeline` 支持远程表更新（`fetchHotUpdateTables`）。

### 10.4 配表工具

`extensions/excel-to-json-ts` — Excel 导出 JSON + TypeScript 接口（`AutoTable.ts`、`interface/`）。

---

## 11. 编辑器扩展

| 扩展 | 功能 |
|------|------|
| `excel-to-json-ts` | Excel → JSON/TS 配表流水线 |
| `mx-res-manager` | Vue 资源浏览器、引用分析、整理移动 |
| `tools` | 自定义构建钩子、`MembershipSet` 与业务同步 |
| `引用查找器3.x` | 资源引用查找 |

---

## 12. 代码规模统计

| 目录 | TypeScript 文件数（约） |
|------|-------------------------|
| `assets/` 总计 | **684** |
| `assets/script/ui/` | **194** |
| `assets/script/battle/` | **203** |
| `assets/mx/` | **160** |
| `assets/script/` 其他 | ~270 |

---

## 13. 关键依赖关系图

```mermaid
flowchart TB
    GL[GameLaunch] --> BP[BootPipeline]
    GL --> GC[GameController]
    BP --> Tables[配表加载]
    BP --> BootRes[Boot 资源包]
    BP --> SDK[SDK 初始化]
    Tables --> Data[gg.data.init]
    SDK --> Data
    Data --> GC
    BootRes --> GC
    GC --> UI[大厅 UI]
    GC --> Battle[BattleFacade]
    Battle --> MX[MX BattleSession]
    Battle --> Map[CocosBattleMapHost]
    Battle --> Presenter[怪物表现层]
    UI --> ResMgr[资源预载]
    SDK --> Ad[广告/打点]
```

---

## 14. 现有文档索引

| 文档 | 内容 |
|------|------|
| `docs/项目说明.md` | 新项目背景、目录约定与开发原则 |
| `docs/开发规范.md` | 开发规范（AI 生成代码强制标准） |
| `docs/遗留代码收敛方案.md` | 遗留代码分阶段收敛 |
| `docs/性能打点说明.md` | 性能打点 `PF-*` 解读 |
| `assets/script/battle/接入指南.md` | 战斗接入指南 |
| `assets/script/battle/docs/需求说明.md` | 战斗需求与 PVP 约束 |
| `extensions/excel-to-json-ts/README.zh-CN.md` | 配表导出说明 |
| `extensions/mx-res-manager/README.md` | 资源管理扩展 |

---

## 15. 项目特点总结

### 优势

1. **框架与业务分离清晰** — MX 层可跨项目复用，战斗/合成内核无引擎依赖。
2. **小游戏工程化成熟** — 分包、预载、内存降档、性能打点体系完整。
3. **多渠道马甲能力强** — 一份代码多 Config 切换，适配微信/抖音/快手。
4. **战斗架构可扩展** — ECS + Ability/Effect、词条系统、多模式副本。
5. **文档较完备** — 战斗、性能打点均有专项文档。

### 复杂度与注意点

1. **代码体量大** — 600+ TS 文件，UI 界面众多，新人需从 `GameLaunch → GameController → BattleFacade` 路径入手。
2. **术语易混淆** — `Skill` 表是「词条」而非「技能」，开发战斗功能前需读术语表。
3. **单主场景** — 所有流程在 `main.scene` 内通过 UI 切换，无多场景跳转。
4. **Auto 生成文件** — `Auto_*.ts` 由工具生成，手改 UI 结构需同步生成逻辑。
5. **广告与性能打点隔离** — 新增上报须走 `PerfReport`，避免误进 Gravity 广告统计。

---

## 16. 新人上手建议

1. 用 Cocos Creator **3.8.8** 打开工程，运行 `main.scene`。
2. 阅读顺序：`GameLaunch.ts` → `BootPipeline.ts` → `GameController.ts`（`init`/`enterMain`）→ `BattleFacade.ts`。
3. 改 UI：找到 `UIID` → `UIConfigs` → 对应 `assets/script/ui/**/UI*.ts`。
4. 改战斗数值：`first/config/*.json` + `TableBattleConfigProvider.ts`。
5. 改渠道包：复制/修改 `sdk/config/*Config.ts`，更新 `sdkConfig.config`。
6. 性能相关改动：同步更新 `PerfReport` 并阅读 `性能打点说明.md`。

---

## 17. 结论

**AdLikeXy** 是一个 **商业化成熟、工程化程度高** 的 **Cocos Creator 塔防小游戏** 项目。它以汉字背包合成 + 格子塔防为核心玩法，围绕广告变现构建了完整的多渠道发行、资源性能治理和数据打点体系。代码上采用自研 **MX 框架** 承载 UI、资源、战斗、合成等通用能力，业务层专注关卡、UI 和平台适配，适合作为 **国内小游戏塔防品类** 的中大型工程参考。

---

*本报告由代码静态分析生成，产品名与渠道信息以仓库内 `DefaultConfig` 为准，实际发行包以构建时 `sdkConfig.config` 为准。*