游戏跑不起来？Godot AI 的 project_run、logs_read 与运行时错误诊断实战

游戏跑不起来？Godot AI 的 project_run、logs_read 与运行时错误诊断实战

【免费下载链接】godot-aiProduction-grade MCP server and AI tools for the Godot engine. A Snap to install. Totally free and fun.项目地址: https://gitcode.com/gh_mirrors/go/godot-ai

用 Godot AI 写游戏时，你大概率遇到过这种情况：代码写完了，一点运行却闪退，或者游戏窗口根本没反应——游戏跑不起来，而你只能去输出面板里人肉翻日志。Godot AI 的project_run和logs_read两个工具正是为解决这个问题而设计的：让 AI 助手替你运行 Godot 游戏、读取运行日志、并直接定位到出错的脚本和行号。本文带你走完这条运行时错误诊断的完整链路。

上方这类由 Godot AI 协助构建的游戏，运行排错同样适用本文流程

为什么要用 project_run 手动跑游戏

传统方式下，"运行游戏 → 看报错 → 定位脚本"这步必须由开发者亲自完成，AI 助手看不到运行结果。Godot AI 打破了这个盲区：

• project_run：让 AI 直接在编辑器里"按下播放键"，并短暂等待游戏"活过来"（liveness 检查）
• logs_read：读取插件、游戏、编辑器三类日志缓冲区，把红色/黄色的报错行直接喂给 AI

两者组合，形成了"运行 → 观察 → 诊断 → 修复 → 再运行"的自动化闭环。工具定义可以查阅 project_run 源码 与 logs_read 源码，完整工具清单见 docs/TOOLS.md。

project_run：一键运行并获取"游戏健康报告"

调用project_run后，不只是"点了播放"，响应里会附带一份健康报告：

几个关键状态的诊断含义：

• live🟢：游戏正常运行，助手已注册，可以开始截图、读日志
• not_live🟡：游戏启动了但没"活"过来——通常意味着启动阶段就有解析/加载错误，响应会直接点名出错的脚本
• break🔴：游戏进程被调试断点"冻住"。启动期出现该状态基本等于GDScript 解析/加载错误，而且插件会从断点信息中合成一条错误记录，告诉你是哪个脚本挂的
• no_helper⚪：项目没有_mcp_game_helper自动加载项（某些无头/自定义主循环项目会这样），游戏其实还在跑

💡 实用技巧：project_run支持mode参数，默认"main"运行主场景，也可以"current"运行当前打开的场景，或"custom"+scene路径运行指定场景——排查某个关卡崩了，直接指定那个.tscn运行即可。

logs_read：三路日志源，精准锁定错误源头

logs_read的source参数决定读哪条日志流，这是运行时错误诊断的核心：

两个进阶参数值得记住：

1. include_details=true：返回完整错误元数据——错误类型、源码位置（文件+行号）、调用栈，等同于 Debugger 面板 Errors 标签页的信息。定位错误时几乎总要用上它
2. since_run_id/since_cursor：游戏日志按run_id归档，每次运行独立保存；编辑器日志支持游标增量读取，只拿"上次之后的新日志"，适合长时间运行观察

这张由 Godot AI 构建的 HUD 演示里有专门的 System Log 面板——logs_read(source="game")读到的正是这类运行期日志

实战：游戏跑不起来的诊断三步法

假设你对 AI 说"运行一下我的游戏"，但游戏黑屏闪退。诊断链路如下：

第 1 步：运行并检查状态

AI 调用project_run(mode="main")，拿到game_status.status = "not_live"且recent_errors非空——启动就有问题。

第 2 步：读取编辑器侧详细日志

按提示调用logs_read(source="editor", include_details=true)。注意一个容易踩的坑：启动期的解析错误发生在游戏助手接管日志之前，永远不会出现在source="game"里。此时若 game 日志"干干净净"却带着editor_errors_hint提示，恰恰说明这次运行丢了脚本，而不是启动正常。

第 3 步：修复后重跑验证

AI 根据日志中给出的脚本路径和行号修复script_patch，再次project_run，确认状态变为live。至此闭环完成，全程无需人工去翻 Godot 输出面板。

类似这个带存档系统的方块世界游戏，就是由几条提示词加自动排错构建出来的

常见状态速查表

延伸阅读

• 全部 46 个工具与 120+ 操作说明：docs/TOOLS.md
• 插件架构与安全模型：docs/plugin-architecture.md
• 编辑器侧日志缓冲实现：editor_log_buffer.gd
• 游戏助手（日志采集端）：game_helper.gd
• 配套测试框架（写游戏顺便写测试）：docs/testing.md

掌握project_run+logs_read这对组合后，"游戏跑不起来"就从人肉排错的苦差事，变成了 AI 几秒内就能定位并修复的常规操作。

【免费下载链接】godot-aiProduction-grade MCP server and AI tools for the Godot engine. A Snap to install. Totally free and fun.项目地址: https://gitcode.com/gh_mirrors/go/godot-ai