MatchMaster/assets/GameplayIntro/README.md

玩法介绍正式功能包

Asset Bundle 名称：gameplay_intro。

• prefab/GameplayIntro.prefab：本关介绍面板固定布局，可在 Creator 中编辑背景、标题、滑动区域和分页器位置。
• assets/Script/module/Tool/LevelGameplay.ts：主脚本目录中的筛选工具，从实际关卡的方块、门、地块及生成队列识别玩法，并按类型去重。主场景仅以类型引用 GameplayIntro，在分包加载完成后用组件名获取实例，避免启动时依赖尚未加载的分包脚本。
• script/GameplayIntro.ts：绑定预制体节点，关闭按钮或外部点击关闭，相邻三页图片加载与释放。
• script/GuideCarousel.ts：鼠标/触摸翻页、缓动回弹、最多三点分页及白点替换动画；单页隐藏分页且不绑定拖动，双页显示两点。
• Texture/：面板背景、玩法指南标题、问号、关闭按钮及分页圆点等 UI 素材；原有中文玩法图片已清理，玩法图片统一加载公共目录。
• assets/resources/Window_Prop/：34 组公共玩法图片，按 titleN、iconN、IntroductionN 加载。daoju26 使用素材 27，daoju27 使用素材 26。

游戏入口由 assets/Script/SceneManager.ts 控制：进入场景时按实际加载的关卡生成介绍列表，没有特殊道具就隐藏问号。首次点击 openGameplayIntro 加载本包的 prefab/GameplayIntro，实例挂到 Inspector 绑定的 tipPanel 节点；关闭后保留固定布局，释放所有玩法页图片，再次打开复用实例，按解锁关卡倒序排列后定位最左端的最新玩法；三个分页点时高亮左边第 1 点。

GameplayIntro.open(entries) 接收已经筛选的介绍列表。NEW_LEVEL.json 仅提供介绍编号和排列顺序，不再用解锁关卡或玩家进度筛选。开局方块和 spawnGates[].spawnQueue[].members 都纳入本关范围，消除后仍可查看；同类型只展示一页。木箱/快递盒/彩色木箱、普通/定次连接等按实际变体匹配，花盆借用的不可见盖板不增加快递盒介绍。

场景接线：在 GameScene 的 Top/tip 下放置问号 Sprite + Button，图片使用本包 wenhao；Button 点击事件绑定 Canvas 上的 SceneManager.openGameplayIntro。SceneManager 的 Tip Panel 属性绑定场景现有的 tipPanel。tipPanel 应作为位于游戏内容之上的居中容器，不需要添加覆盖整个屏幕的输入拦截组件。

预制体直接引用背景、标题、关闭按钮和两种分页圆点；34 种公共玩法图片由脚本按当前页及相邻页动态加载，不能把所有玩法图片拖到预制体中，以免一次加载全部图片。

测试工具位于 assets/test。当前 settings/project.json 的启动场景是 TestLayout；不需要测试时，先在 Creator 中切回正式启动场景并保存设置，再删除 assets/test 和同级 assets/test.meta。当前 HomeScene 没有 HomePropTestPanel 节点。

与已拉取 main 的改动对比

核对日期：2026-09-15。最新 origin/main（e992a8f）已快进合入当前 layout-optimization 分支。以下以 e992a8f 为基准，包含当前工作区的暂存、未暂存和未跟踪文件；本地 main（122b504）未移动，不作为本清单的对比基准。此清单是本次核对快照，后续代码变更需同步更新。

新增业务代码并非全部放在新包：面板与滑动脚本位于 gameplay_intro，测试代码位于 test，LevelGameplay.ts 位于原公共脚本目录。

GameplayIntro/
├─ assets/
│  ├─ GameplayIntro/                 【新增资源包：gameplay_intro】
│  │  ├─ script/
│  │  │  ├─ GameplayIntro.ts         面板展示、图片加载与释放
│  │  │  └─ GuideCarousel.ts         滑动翻页、分页指示
│  │  ├─ prefab/
│  │  │  └─ GameplayIntro.prefab     玩法介绍面板
│  │  ├─ Texture/                   玩法介绍美术资源
│  │  └─ README.md
│  │
│  ├─ test/                          【新增资源包：test】
│  │  ├─ script/
│  │  │  └─ TestLayoutPanel.ts       独立测试面板
│  │  ├─ scene/
│  │  │  └─ TestLayout.fire          测试场景
│  │  ├─ tests/
│  │  │  ├─ guide-carousel.cjs
│  │  │  ├─ home-prop-panel.cjs      残留测试，依赖的脚本已不存在
│  │  │  └─ preview.cjs
│  │  └─ README.md
│  │
│  ├─ Script/                        【原有脚本目录】
│  │  ├─ module/Tool/
│  │  │  └─ LevelGameplay.ts         【新增】当前关卡玩法筛选
│  │  ├─ SceneManager.ts             【修改】入口、加载、暂停与恢复
│  │  └─ ItemGuide.ts                无实际内容差异
│  │
│  ├─ NewMode/script/
│  │  └─ NewMode.ts                  无实际内容差异
│  │
│  ├─ Scene/
│  │  ├─ GameScene.fire              【修改】问号按钮及面板接线
│  │  └─ HomeScene.fire              无实际内容差异
│  │
│  ├─ gacha_bundle/img/cat.meta      【删除】
│  ├─ libs/dn-sdk-minigame.meta       【删除】
│  ├─ passCheck/script.meta           【删除】
│  └─ pause/texture.meta             【删除】
│
├─ build-templates/wechatgame/
│  └─ project.config.json            【修改】上传时忽略 cocos 目录
│
└─ settings/
   └─ project.json                   【修改】启动场景、记录时间

新增资源对应的 .meta 文件未逐一展开。原有脚本实际只改了 SceneManager.ts；新增的 LevelGameplay.ts 位于公共脚本目录。两个新资源包尚未配置为微信独立分包。

assets/custom/Json/level1961.json.meta 至 level1980.json.meta 共 20 个关卡元数据文件现已包含在 main 基准中，合并时采用 main 的 UUID；未发现资源对旧本地 UUID 的引用。.codex_tmp/prop-compare.jpg 和 .codex_tmp/texture-compare.jpg 是本地对比图片，不是业务代码。project.json、settings/services.json、settings/wechatgame.json 相对上述基准没有实际文本内容差异。

本次合入 main 的 3 个提交包含：GameScene 点击拦截组件、门生方块介绍关卡改为 1943、AB 测试 B 方案第 15 关不返回首页及版本配置更新、战令图片更新。场景合并保留了 main 的拦截组件及本地问号按钮、坐标和面板接线；这些 main 自带改动不计入本地新增功能差异。

新增正式脚本及方法职责

整体调用关系：SceneManager 控制入口和暂停恢复 → LevelGameplay 筛选本关玩法 → GameplayIntro 管理内容与图片 → GuideCarousel 处理滑动分页。

LevelGameplay.ts（公共目录）

方法	作用
getLevelGameplay(config, data)	输入全部介绍配置和当前关卡数据，扫描方块、门、特殊地块及生成队列，返回本关介绍列表；按名称去重，保留配置顺序
内部 add(id)	将编号转换为 daojuN 存入 Set，重复玩法只记录一次

该工具只读取数据。方块列表使用浅复制后再补充待生成方块，不向原数组追加内容。根据方块类型及附加属性区分普通/定次、木板/快递盒/彩色箱子等变体；花盆接收块借用的不可见盖板不额外计入箱子介绍。它不使用玩家进度或配置中的 level 筛选，也不负责显示、加载图片或暂停游戏；最终只返回在介绍配置中存在的条目。

GameplayIntro.ts（gameplay_intro 包）

挂在正式预制体根节点，负责内容、开关动画和图片资源。

方法	作用
open(entries)	复制列表并按 level 倒序排列，绑定固定节点、初始化分页，播放打开动画；空列表直接关闭
syncPages()	只保留当前页和前后相邻页的图片，优先加载当前页
picture(...)	排队加载公共标题、道具或说明图；标题和道具图等比适配，说明图保持预制体设置；丢弃失效页面的加载结果
nextImage()	依次启动图片加载任务，避免集中加载
releasePage(index) / releasePages()	清空图片显示引用、归还资源引用、隐藏页面；批量清理时同时清空待加载队列，固定节点保留复用
close() / finishClose()	播放关闭动画后释放图片、隐藏面板并发出 intro-closed，由场景判断是否恢复游戏
stopPanelAnimation()	停止开关动画并重置状态
onDisable() / onDestroy()	隐藏或销毁时清理图片和动画
previewNavigate(action) / getPreviewState()	提供测试跳页入口，以及当前页、总页数和当前配置
showMessage(value)	使用预制体的 Status 节点显示提示

GuideCarousel.ts（gameplay_intro 包）

挂在 IntroViewport，只负责手势、页面位置和圆点动画。逻辑页循环使用预制体中的三个固定页面节点。

方法	作用
initialize(...) / clear()	初始化页数、默认页、圆点及输入监听；重复打开前清理旧状态
goTo(index, animated)	限制目标页范围，更新分页高亮，发出 page-changed 通知内容加载
begin(...) / move(...) / end(...)	开始拖动、跟手移动、根据距离和速度决定翻页或回弹；首尾越界有阻力
x(event)	将屏幕坐标转为视口局部坐标，适配面板缩放
touchStart/Move/End/Cancel	将带手指 ID 的触摸事件转给拖动逻辑
mouseDown/Move/Up/Leave	处理鼠标左键拖动与离开视口结束拖动
createDot() / styleDot()	创建圆点并设置选中样式
animateDots() / resetDotAnimation()	推进或重置圆点替换动画
render() / update(dt)	应用页面位移、缩放和透明度，每帧推进吸附、回弹及圆点动画
onDisable()	结束手势和动画，避免重开后残留中间状态

原有 SceneManager.ts 的具体改动

改动位置	改动及作用
文件顶部	引入 getLevelGameplay；以 import type 引用 GameplayIntro，不产生启动时的运行时导入
新增字段	tipPanel 绑定场景容器；gameplayIntro 缓存面板控制器；levelGameplay 保存本关介绍列表
isPauseOpen()	将介绍面板加载中、显示中计入暂停判断，防止重复打开及原有流程提前恢复游戏
onLoad()	增加 refreshGameplayInfo() 调用，进场景时初始化列表和问号显隐
新增 refreshGameplayInfo()	使用已有 NEW_LEVEL 配置，未就绪则异步加载；按实际关卡筛选并缓存列表，没有介绍时隐藏问号
新增 openGameplayIntro()	检查场景、暂停、结束、商城和容器状态；暂停游戏并停止炸弹计时；通过原有动态弹窗加载器加载或复用正式面板，再传入列表
内部 resume() 回调	关闭或加载失败时，仅在无冰冻、无其他暂停、无商城暂停且游戏未结束时恢复游戏；游戏已开始才恢复炸弹计时
加载完成回调	结束加载标记；失败时尝试恢复；成功时按组件名取得面板，同一实例只绑定一次关闭回调
原空 start()	删除无内容的方法，没有移除实际业务逻辑

loadDynamicPopup() 等通用加载方法沿用原有实现。MapConroler、ItemGuide.ts、NewMode.ts 等其他原有业务脚本没有内容修改。

配套非脚本改动：GameScene.fire 新增问号按钮、tipPanel 容器及点击/属性绑定；微信构建模板增加上传忽略 cocos 目录；settings/project.json 将启动场景改为 TestLayout（UUID 8e21ec7e-3913-44ec-8f99-53ff52fe81ed）并更新记录时间。

新增测试脚本

脚本	作用
assets/test/script/TestLayoutPanel.ts	独立测试界面，支持指定本地关卡、全部玩法、重新打开和跳页；直接复用正式面板，不写玩家进度
assets/test/tests/guide-carousel.cjs	使用模拟 Cocos 环境检查筛选、分页、资源回收及场景入口的暂停恢复逻辑
assets/test/tests/preview.cjs	本地预览服务，使用 Creator 编译器及运行中的编辑器引擎/资源展示测试场景
assets/test/tests/home-prop-panel.cjs	残留道具测试；依赖的 HomePropTestPanel.ts 和 HomeScene 节点已不存在，当前不可正常运行

运行方式与移除步骤见 assets/test/README.md。本次合并后执行 node assets/test/tests/guide-carousel.cjs，全部回归项通过；同时验证了场景引用索引和双方场景改动的保留情况。未进行 Creator 真机视觉及性能验证。

可编辑的固定玩法页结构

直接打开 prefab/GameplayIntro.prefab：

IntroViewport
└─ Pages
   ├─ Page1
   │  ├─ TitleImage
   │  ├─ IconImage
   │  └─ DescriptionImage
   ├─ Page2（相同结构）
   └─ Page3（相同结构）

所有图片节点已经放在面板预制体内，SpriteFrame 留空。最下方 DescriptionImage 的大小由 Sprite 的 Size Mode、Trim 及节点尺寸/缩放控制，代码不覆盖；TitleImage 和 IconImage 仍以预制体 Width/Height 为展示区域等比适配；三页需要保持相同布局。代码仅复用三个页面、改变分页位置并动态加载图片。说明图不做代码缩放，标题和道具图保留等比适配；没有单图比例修正。翻远或关闭面板时清空图片并归还资源引用，不销毁这三个页面；面板整体销毁时由引擎销毁子节点。