增加了游戏说明书和游戏内 Block Wall Map 以及首页 JiaZai类的傻瓜式注释

2026-04-03 11:55:26 +08:00 · 2026-04-03 11:55:26 +08:00 · 0dc51a88cd
parent c557f154aa
commit 0dc51a88cd
4 changed files with 2456 additions and 155 deletions
--- a/assets/Script/Block.ts
+++ b/assets/Script/Block.ts
--- a/assets/Script/JiaZai.ts
+++ b/assets/Script/JiaZai.ts
--- a/assets/Script/Map.ts
+++ b/assets/Script/Map.ts
--- a/游戏说明书.md
+++ b/游戏说明书.md
@ -0,0 +1,417 @@
+# ColorBlock 消消乐游戏 - 整体说明书
+
+## 一、游戏架构概述
+
+### 1.1 场景流程
+```
+Main.ts (入口)
+    ↓
+Load.ts (加载场景初始化)
+    ↓
+GameManager.ts (游戏管理器 - 预加载资源)
+    ↓
+JiaZai.ts (主页场景 - 主菜单)
+    ↓
+Map.ts + Block.ts (游戏场景 - 核心玩法)
+    ↓
+GameOver.ts (结算场景)
+```
+
+### 1.2 核心模块划分
+
+| 模块 | 说明 |
+|------|------|
+| **核心游戏** | 游戏主逻辑、场景管理、地图控制、方块控制 |
+| **道具系统** | 各种特殊方块（钥匙、炸弹、冻结等） |
+| **UI系统** | 界面控制、弹窗管理、设置面板 |
+| **工具模块** | 音频管理、网络请求、数据存储 |
+| **SDK模块** | 微信小游戏SDK、分享、支付 |
+
+---
+
+## 二、核心类说明
+
+### 2.1 入口与初始化
+
+| 文件 | 类名 | 功能说明 |
+|------|------|----------|
+| **Main.ts** | Main | 游戏入口，加载 LoadScene 场景 |
+| **Load.ts** | NewClass | 加载场景初始化，配置碰撞系统、微信参数 |
+| **GameManager.ts** | GameManager | 游戏总管理器，单例模式，负责游戏初始化、资源预加载、微信配置 |
+
+### 2.2 主页场景
+
+| 文件 | 类名 | 功能说明 |
+|------|------|----------|
+| **JiaZai.ts** | JiaZai | 主页场景控制器（HomeScene），负责：<br>- UI管理（关卡、金币、体力显示）<br>- 商店、月卡、每日任务<br>- 通行证系统<br>- 排行榜功能<br>- 分享奖励<br>- 新手引导 |
+
+### 2.3 游戏核心
+
+| 文件 | 类名 | 功能说明 |
+|------|------|----------|
+| **Map.ts** | MapConroler | 地图控制器，核心游戏逻辑：<br>- 地图生成与渲染<br>- 方块生成与布局<br>- 门控制（颜色门、星星门、锁门）<br>- 特殊效果（冰冻、锤子、魔法棒）<br>- 胜负判定 |
+| **Block.ts** | Block | 方块组件，控制所有方块行为：<br>- 22种方块类型（普通、钥匙、锁、冻结、炸弹、粘合等）<br>- 7种颜色<br>- 移动、消除逻辑<br>- 碰撞检测 |
+| **SceneManager.ts** | SceneManager | 游戏场景管理器（GameScene），负责：<br>- 道具使用（锤子、魔法棒、冰冻）<br>- 弹窗管理（商店、奖励、月卡）<br>- 复活逻辑 |
+
+### 2.4 道具系统 (prop文件夹)
+
+| 文件 | 道具名 | 功能说明 |
+|------|--------|----------|
+| **Key.ts** | 钥匙块 | 用来打开锁块 |
+| **Lock.ts** | 锁块 | 被锁锁住，需要钥匙消除 |
+| **Boom.ts** | 炸弹块 | 炸毁周围方块 |
+| **Freeze.ts** | 冻结块 | 冻住一定步数 |
+| **Star.ts** | 星星块 | 打开星星门 |
+| **Adhesive.ts** | 粘合块 | 与其他方块粘合移动 |
+| **Question.ts** | 问号块 | 随机效果 |
+| **AddTime.ts** | 加时间块 | 增加游戏时间 |
+| **Floor.ts** | 地板块 | 可移动的地板 |
+| **Switchs.ts** | 开关块 | 控制开关逻辑 |
+
+### 2.5 UI界面
+
+| 文件 | 类名 | 功能说明 |
+|------|------|----------|
+| **GameOver.ts** | NewClass | 游戏结算界面，显示分数、通关率、排行榜 |
+| **Pause.ts** | - | 暂停界面（已注释） |
+| **Reward.ts** | - | 奖励界面 |
+| **Revive.ts** | - | 复活界面 |
+| **Barrier.ts** | - | 障碍物界面 |
+| **Window.ts** | - | 通用弹窗 |
+| **gameOverUi.ts** | - | 游戏结束UI |
+
+### 2.6 工具模块 (module文件夹)
+
+#### 配置与数据
+
+| 文件 | 功能说明 |
+|------|----------|
+| **GameConfig.ts** | 游戏配置中心，存储GM_INFO等全局数据 |
+| **GameTool.ts** | 工具类，提供登录认证、埋点上传、排行榜、存储等 |
+
+#### 音频与音乐
+
+| 文件 | 功能说明 |
+|------|----------|
+| **AudioManager.ts** | 音频管理器，单例模式，管理所有游戏音效和背景音乐 |
+
+#### 存储与网络
+
+| 文件 | 功能说明 |
+|------|----------|
+| **Storage.ts** | 本地存储，封装localStorage操作 |
+| **HttpUtil.ts** | 网络请求工具，封装加密HTTP请求 |
+
+#### 支付与道具
+
+| 文件 | 功能说明 |
+|------|----------|
+| **Utils.ts** | 支付工具，处理月卡、通行证、订单等 |
+
+#### 其他工具
+
+| 文件 | 功能说明 |
+|------|----------|
+| **Notification.ts** | 事件通知系统 |
+| **NodePoolMgr.ts** | 对象池管理器 |
+| **GetPosition.ts** | 地理位置获取 |
+| **RankManager.ts** | 排行榜管理 |
+| **List.ts** | 列表组件 |
+| **scrollviewList.ts** | 滚动列表 |
+
+### 2.7 SDK模块 (Sdk文件夹)
+
+| 文件 | 功能说明 |
+|------|----------|
+| **MiniGameSdk.ts** | 微信小游戏SDK封装 |
+| **MiniGameManager.ts** | 小游戏管理器 |
+
+### 2.8 物理与碰撞系统
+
+| 文件 | 功能说明 |
+|------|----------|
+| **lq_collide_system/** | 自定义碰撞检测系统 |
+| **CollisionDetection.ts** | 碰撞检测工具 |
+
+---
+
+## 三、游戏核心玩法
+
+### 3.1 方块类型 (Block.ts)
+
+| 类型 | 说明 |
+|------|------|
+| 普通块 | 最基础的方块，可以移动并消除在对应颜色的门上 |
+| 叠加块上/下 | 叠加方块的上下两部分 |
+| 钥匙块 | 带有钥匙功能的方块，用来打开对应的锁 |
+| 上锁块 | 被锁锁住的方块，需要对应钥匙才能消除 |
+| 冻结块 | 带有冰冻效果的方块，会冻住一定步数 |
+| 星星块 | 带有星星的方块，用来打开星星门 |
+| 炸弹块 | 带有炸弹的方块，可以炸毁周围方块 |
+| 水平块 | 只能在水平方向移动的方块 |
+| 垂直块 | 只能在垂直方向移动的方块 |
+| 粘合块 | 会与其他方块粘合在一起移动的方块 |
+| 障碍块 | 障碍物，无法消除 |
+| 问号块 | 随机效果的方块 |
+| 变色块 | 颜色会变化的方块 |
+| 加时间块 | 增加游戏时间的方块 |
+| 可移动地板块 | 可以在地图上移动的地板块 |
+| 三连粘合块 | 会与三个方向粘合的方块 |
+
+### 3.2 颜色系统
+
+| 颜色 | 说明 |
+|------|------|
+| 紫色 | 对应紫色门 |
+| 黄色 | 对应黄色门 |
+| 绿色 | 对应绿色门 |
+| 蓝色 | 对应蓝色门 |
+| 粉色 | 对应粉色门 |
+| 橘黄色 | 对应橘黄色门 |
+| 青色 | 对应青色门 |
+
+### 3.3 门类型 (Map.ts)
+
+| 门类型 | 消除条件 |
+|--------|----------|
+| 颜色门 | 对应颜色的方块可以消除 |
+| 星星门 | 需要星星块消除 |
+| 锁门 | 需要钥匙块消除 |
+| 冰冻门 | 冻结块可以冻住 |
+
+### 3.4 道具系统
+
+| 道具 | 功能 |
+|------|------|
+| 锤子 | 消除单个方块 |
+| 魔法棒 | 改变方块颜色 |
+| 冰冻 | 暂停方块移动 |
+
+---
+
+## 四、数据结构
+
+### 4.1 GM_INFO 主要属性
+
+```typescript
+{
+    level: number,           // 当前关卡
+    coin: number,             // 金币
+    hp: number,               // 体力值
+    hp_Max: number,           // 体力上限
+    score: number,            // 分数
+    openid: string,           // 微信openid
+    userId: number,           // 用户ID
+    userPowerTime: number,    // 无限体力到期时间
+    playerPassLevel: number,  // 通行证等级
+    passCheckActivate: boolean, // 通行证是否激活
+    gameId: number,           // 游戏ID
+    scode: string,            // 渠道码
+    matchId: string,          // 比赛ID
+    successList: boolean[],   // 成功列表
+}
+```
+
+### 4.2 关卡数据结构
+
+```typescript
+{
+    id: string,         // 关卡ID
+    map: number[],      // 地图数据
+    risefall: {...},   // 升降台配置
+    gap: {...}          // 鸿沟配置
+}
+```
+
+### 4.3 方块数据结构
+
+```typescript
+{
+    type: BlockType,    // 方块类型
+    color: BlockColor,  // 方块颜色
+    pos: cc.Vec2,       // 位置坐标
+    special: number,    // 特殊属性
+}
+```
+
+---
+
+## 五、场景说明
+
+| 场景名 | 控制器 | 功能 |
+|--------|--------|------|
+| **LoadScene** | Load.ts | 加载场景，初始化微信参数 |
+| **HomeScene** | JiaZai.ts | 主菜单，显示关卡、金币、商店、任务等 |
+| **GameScene** | Map.ts + SceneManager.ts | 游戏主场景，核心玩法 |
+| **GameOver** | GameOver.ts | 结算场景 |
+
+---
+
+## 六、系统功能说明
+
+### 6.1 体力系统
+
+- 玩家拥有体力值，每进行一关游戏消耗体力
+- 体力会随时间恢复（每5分钟恢复1点）
+- 可以通过月卡获得无限体力
+- 体力不足时显示恢复倒计时
+
+### 6.2 月卡系统
+
+- 购买月卡后享受每日奖励
+- 月卡期间体力上限提升
+- 月卡到期后自动恢复默认体力上限
+
+### 6.3 通行证系统（PassCheck）
+
+- 通过积累进度提升通行证等级
+- 通行证达到特定等级可获得奖励
+- 需要购买通行证才能获得奖励
+
+### 6.4 每日任务
+
+- 每日有分享任务
+- 完成分享任务可获得奖励
+- 任务进度每日重置
+
+### 6.5 排行榜系统
+
+- 显示好友排行榜
+- 按关卡等级排序
+- 支持显示玩家省份信息
+
+### 6.6 分享系统
+
+- 分享到群聊邀请好友
+- 好友通过分享链接进入游戏
+- 分享成功可获得奖励
+
+---
+
+## 七、文件目录结构
+
+```
+assets/Script/
+├── Sdk/                          # SDK模块
+│   ├── MiniGameSdk.ts           # 微信小游戏SDK
+│   └── MiniGameManager.ts       # 小游戏管理器
+├── lq_base/                      # 基础模块
+│   ├── data/                    # 数据定义
+│   └── util/                     # 工具函数
+├── lq_collide_system/            # 碰撞系统
+├── module/                       # 功能模块
+│   ├── Config/GameConfig.ts     # 游戏配置
+│   ├── Crypto/HttpUtil.ts       # 加密网络请求
+│   ├── Music/AudioManager.ts    # 音频管理
+│   ├── Pay/Utils.ts             # 支付工具
+│   ├── Position/GetPosition.ts  # 位置获取
+│   ├── RankList/                # 排行榜
+│   ├── Storage/Storage.ts       # 本地存储
+│   └── Tool/GameTool.ts        # 游戏工具
+├── prop/                         # 道具系统
+│   ├── Key.ts                   # 钥匙
+│   ├── Lock.ts                  # 锁
+│   ├── Boom.ts                  # 炸弹
+│   ├── Freeze.ts                # 冻结
+│   ├── Star.ts                  # 星星
+│   ├── Adhesive.ts              # 粘合
+│   └── Question.ts              # 问号
+├── Avatar.ts                    # 头像组件
+├── Barrier.ts                   # 障碍物
+├── Block.ts                     # 方块组件
+├── CollisionDetection.ts        # 碰撞检测
+├── ControlManager.ts            # 控制管理
+├── GameManager.ts               # 游戏管理器
+├── GameOver.ts                  # 游戏结束
+├── ItemGuide.ts                 # 道具引导
+├── JiaZai.ts                    # 主页场景
+├── Load.ts                      # 加载场景
+├── Main.ts                      # 游戏入口
+├── Map.ts                       # 地图控制
+├── MapBlock.ts                  # 地图方块
+├── Message.ts                   # 消息
+├── MessageContent.ts            # 消息内容
+├── NewMode.ts                   # 新模式
+├── NumberToImage.ts             # 数字转图片
+├── Pause.ts                     # 暂停
+├── RedeemCode.ts               # 兑换码
+├── Reduce.ts                    # 减少
+├── Revive.ts                    # 复活
+├── Reward.ts                    # 奖励
+├── RippleShrink.ts              # 涟漪收缩
+├── SceneManager.ts              # 场景管理
+├── Uid.ts                       # 用户ID
+├── Wall.ts                      # 墙壁
+├── Window.ts                    # 窗口
+├── btnControl.ts               # 按钮控制
+├── gameOverUi.ts               # 游戏结束UI
+├── heathnum.ts                 # 体力数字
+├── monthlyCard.ts              # 月卡
+├── peizhi.ts                   # 配置
+├── position.ts                # 位置
+└── ranking.ts                  # 排行榜
+```
+
+---
+
+## 八、技术栈
+
+| 技术 | 说明 |
+|------|------|
+| **引擎** | Cocos Creator |
+| **语言** | TypeScript |
+| **平台** | 微信小游戏、字节跳动小游戏 |
+| **网络** | HTTPS + 加密传输 |
+| **存储** | localStorage + 微信云存储 |
+
+---
+
+## 九、游戏流程图
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    Main.ts                          │
+│                   游戏入口加载                        │
+└─────────────────────┬───────────────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────────────┐
+│                    Load.ts                           │
+│              加载场景-初始化配置                        │
+└─────────────────────┬───────────────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────────────┐
+│               GameManager.ts                          │
+│         游戏管理器-预加载资源、微信配置                   │
+└─────────────────────┬───────────────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────────────┐
+│                 JiaZai.ts (HomeScene)                │
+│    主页-关卡选择/商店/任务/排行榜/通行证/分享            │
+└─────────────────────┬───────────────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────────────┐
+│           Map.ts + Block.ts (GameScene)              │
+│           游戏核心-地图/方块/道具/胜负判定              │
+└─────────────────────┬───────────────────────────────┘
+                      │
+┌─────────────────────▼───────────────────────────────┐
+│                  GameOver.ts                         │
+│              结算-分数/排行榜/奖励                      │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## 十、总结
+
+这是一款基于 **Cocos Creator** 开发的**微信消消乐小游戏**，核心玩法是通过移动方块来消除对应颜色的门。游戏包含完整的商业化系统：
+
+- **体力系统**：控制游戏节奏
+- **商店系统**：售卖虚拟商品
+- **月卡系统**：提供订阅价值
+- **通行证系统**：提供成长目标
+- **每日任务**：提高用户粘性
+- **排行榜系统**：促进社交互动
+- **分享系统**：裂变获客
+
+游戏设计精巧，代码结构清晰，是一款成熟的三消类小游戏产品。