You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
447 lines
17 KiB
447 lines
17 KiB
# 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` 为准。*
|
|
|