使用文档

# YYKA 运行时检查器 — 用户使用文档

适用于 Cocos Creator 3.8.8 及以上版本。

一、这是什么？

YYKA 运行时检查器是一个 Cocos Creator 插件，让你在游戏运行中实时调试：

• 查看并修改场景里任意节点和组件的属性（改完立刻在游戏里生效）
• 调整材质颜色、贴图等参数
• 查看性能曲线（FPS、DrawCall、内存等）
• 统计已加载资源
• 开启物理碰撞线框
• 在带手机外壳的预览窗口里玩转游戏（横竖屏、静音、帧率、暂停）
• 让 AI 助手（如 Codex）连接你的游戏，帮你查问题、改状态

核心特点：所见即所得。 在面板里改一个值，游戏画面立刻更新。

二、安装

1. 把 yyka-runtime-inspector 文件夹放进你的项目目录：
   复制代码

   你的项目/extensions/yyka-runtime-inspector

2. 打开（或重启）Cocos Creator。
3. 等待几秒，插件会自动完成两件事：
   • 启动调试服务（端口 33000）
   • 把桥接脚本 RuntimeBridge.ts 自动安装到项目 assets/ 目录

装好后，菜单栏会出现 YYKA插件 顶级菜单。

如果项目里没有 extensions 文件夹，在项目根目录新建一个即可。

三、开始使用（三步走）

第 1 步：运行游戏
用模拟器、浏览器预览、编辑器预览或真机随便一种方式运行你的游戏。

第 2 步：确认桥接脚本已加载
游戏刚运行时用的是旧脚本，需要刷新一次：

• 浏览器预览 → 刷新页面
• 编辑器预览 → 关闭重新打开
• 模拟器 → 完全退出后重新启动

第 3 步：打开面板
菜单 → YYKA插件 → 运行时工作台 → 选择：

• 运行检查：完整的调试面板
• 游戏实况：纯净的预览窗口

面板打开后，游戏画面和节点树就出现了。

四、运行检查面板

4.1 顶部工具栏

连接成功时，工具栏会显示一个彩色小徽章，标明当前游戏来自哪里（浏览器预览 / 编辑器预览 / 模拟器 / 真机）。

4.2 节点树（左侧）

场景里所有节点按树形排列，点击节点即可在右侧查看和编辑它的属性。

• 图标颜色表示节点状态：蓝色圆点 = 普通叶子节点，紫色小方块 = 有子节点，灰色 = 隐藏节点
• 节点右侧的橙色「隐藏」标签表示该节点当前不可见
• 顶部可搜索节点名，或点「刷新节点」手动刷新

4.3 属性检查（右侧）

选中节点后，这里显示该节点的位置、旋转、缩放和所有组件属性。

能改什么？

• 数字、开关、文字 → 直接输入或切换
• 颜色 → 颜色选择器
• 坐标/向量（x, y, z）→ 逐项输入
• 下拉框 → 选枚举值
• 节点/组件引用 → 点击弹出选择框，选别的节点替换
• 资源引用（图片、材质等）→ 点击打开资源选择窗口，支持按类型筛选和搜索名字

改完立刻生效，输入框里保留你填的值，不会被游戏每帧改回去。

Widget 组件还提供官方的九宫格对齐面板：点四个角或四条边，快速把 UI 对齐到屏幕边缘；每行边距可切换绝对/百分比。

4.4 性能曲线

开启「性能曲线」后，面板显示实时曲线图，用于观察卡顿：

• FPS（帧率）
• DrawCall（绘制批次）
• 三角形数
• 内存占用

窗口大小变化时曲线会自动重新适配。

4.5 资源统计

开启后显示当前游戏已加载的资源情况，按类型分类（纹理、材质、预制体等），底部有总数。

4.6 物理调试

开启后，游戏里的物理碰撞体（Box、Circle 等）会显示线框，方便检查碰撞体位置和大小。

4.7 游戏高亮 / 遮罩

1. 在节点树里选中一个节点
2. 点「游戏高亮」
3. 点「框选」→ 游戏画面里高亮框住该节点；点「遮罩」→ 只显示该节点，其余变暗

适合快速定位某个 UI 或物体在画面里的位置。

4.8 日志窗口（底部）

游戏里的 console.log / warn / error 都会显示在这里，同时显示插件自身的系统消息。

• 顶部可筛选级别：全部 / 日志 / 警告 / 错误
• 新日志自动滚到底部；向上翻看历史时暂停滚动
• 每条日志右侧 ⧉ 按钮可一键复制

五、游戏实况面板

打开方式：菜单 → YYKA插件 → 运行时工作台 → 游戏实况。

一个干净的游戏预览窗口，工具条功能：

5.1 分辨率选择

5.2 横竖屏切换

点旋转按钮，画面（和手机外壳）会在横屏、竖屏间切换，比例正确。

5.3 帧率

输入目标帧率（如 30 / 60 / 120），限制游戏帧率，方便观察不同帧率下的表现。

5.4 暂停 / 步进

• 暂停：游戏画面冻结
• 步进：暂停状态下出现，每点一次走一帧，适合一帧一帧看动画和逻辑

5.5 静音

一键静音整个预览窗口的声音，包括背景音乐、音效、攻击音效等一切声音。换场景、重新播放也不会"死灰复燃"。再点一下恢复声音。

5.6 刷新

重新加载游戏预览。刷新会彻底清理旧游戏实例（停止主循环、清掉残留的音乐和计时器），相当于"干净地重开"。

5.7 缩放

在预览画面上滚动鼠标滚轮即可缩放画面。手机机型模式下，画面会被限制在预览窗口内并保留边距，不会超出边界。

六、关于桥接脚本

桥接脚本 RuntimeBridge.ts 是插件和游戏之间的桥梁，运行在你的游戏场景里。

• 自动安装：插件每次加载都会自动更新它，保持与插件版本一致
• 保留你的设置：如果你在脚本里自定义过 host/port（比如真机调试时填电脑 IP），自动更新不会覆盖你的设置

注意：改完脚本（或插件更新后），运行中的游戏要刷新/重启才能加载新脚本。

七、AI 助手接入（MCP 服务）

插件内置 MCP（Model Context Protocol）服务，让 Codex 等 AI 助手可以直接"看到并操作"你运行中的游戏。

使用步骤

1. 运行游戏并确认已连接（面板有客户端徽章）
2. 运行检查面板 → 点「MCP 服务」→「启动服务」
3. 点「复制配置」得到一段 JSON，粘贴到 AI 助手的 MCP 配置里

地址: http://127.0.0.1:33010/mcp
密钥: Bearer www.yyka.cn

AI 能帮你做什么

典型用法：跟 AI 说"帮我看看现在 FPS 多少"、"把主角位置移到 (100, 200)"、"点一下开始按钮"，AI 会自动调用对应工具完成。

八、常见问题

Q：面板显示"游戏未连接"？

按顺序检查：

1. 工具栏「停止服务」是绿色（服务运行中）吗？
2. assets/RuntimeBridge.ts 存在吗？
3. 游戏重新加载过桥接脚本吗？（浏览器刷新 / 模拟器重启）

Q：桥接脚本更新了，但游戏还是旧行为？

运行中的游戏不会自动加载新脚本。手动刷新页面 / 重启模拟器即可。

Q：改了属性没反应？

少数属性由游戏逻辑每帧覆盖（比如受动画驱动的值）。面板会保留你的输入值，并在日志里提示"回读值与设定值不同，可能被每帧覆盖"。

Q：静音了还有声音？

确认插件是最新版本。静音是窗口级的，覆盖音乐、音效和新建音频。若仍有漏网，多半是引擎特殊播放路径，请把现象反馈给我们。

Q：预览画面黑屏？

预览依赖项目自带的浏览器预览服务（默认端口 7456）。检查地址栏状态：显示「未启动」时点击遮罩上的「重试」，或确认编辑器已开启预览服务。

Q：关闭停靠的预览窗口后画面残留？

最新版已修复：关闭窗口会自动清理游戏画面并停止引擎。

Q：手机外壳和灵动岛怎么开？

在「游戏实况」面板分辨率里选择手机机型（如 Redmi 8），画面自动套上手机外壳、灵动岛和底部指示条。

九、反馈

遇到问题或想提建议，把以下信息发给开发者：

• 插件版本（日志栏第一行有显示）
• 编辑器版本
• 复现步骤
• 面板日志内容（底部日志窗口可直接复制）

感谢使用 YYKA 运行时检查器！