企业官网建设流程全解析

• 人工智能
• AI Agent
• 游戏开发
• AI 技能
• 媒体生成

本文是 Godogen 项目中engines/godot.md引擎指南的深度解读。它服务于一个核心场景：让 Claude Code / Codex 这样的编码 Agent 在一个只含"运行时清单 + 引擎指南 + 资产技能"的瘦仓库里，从头搭建一个可运行的 Godot 4（.NET 构建）C# 游戏项目，并最终产出可证明运行结果的视频。读完本文，你将掌握 Godot 侧工程布局的硬性约束、用 C#SceneTree脚本在构建期生成.tscn场景的完整套路、几类"编译通过但运行时静默失败"的陷阱清单，以及用--write-movie+ ffmpeg 产出确定性证明视频的完整命令链。

这份指南在 Godogen 中的角色：引擎即渲染期选择

Godogen 不是游戏本身，而是"生成游戏的生成器"：godogen -> 游戏仓库 -> 游戏。源仓库本身刻意保持单薄——只维护一个引擎无关的运行时清单 prompts/runtime.md、一个跨引擎的资产生成技能 asset-gen/SKILL.md，以及三份按引擎区分的指南 engines/godot.md、engines/babylon.md、engines/bevy.md。

引擎和宿主 Agent（Claude 还是 Codex）是发布期的渲染选项，而非相互独立的源码树。由 publish.sh 在发布时把对应引擎指南原样拷贝进新游戏仓库：

./publish.sh --engine godot --agent claude --out ~/my-game # 生成 CLAUDE.md + .claude/skills/ ./publish.sh --engine godot --agent codex --out ~/my-game # 生成 AGENTS.md + .agents/skills/

以 Godot 为例，发布产物包括：运行时清单（CLAUDE.md或AGENTS.md，由 prompts/runtime.md 渲染，其中指明"读取godot.md获取引擎指导"）、godot.md引擎指南原文（见 publish.sh 的cp "$REPO_ROOT/engines/$ENGINE.md" "$TARGET/$ENGINE_GUIDE_FILE"）、以及asset-gen技能目录。同时 publish.sh 还会为 Godot 目标写入专用.gitignore：assets、screenshots、.godot、*.import、bin/、obj/均不入库。

设计哲学（见 AGENTS.md）是"不给显而易见的指导"：指南只承载模型无法快速推断或发现的东西——技术栈与布局骨架、静默失败陷阱、捕获配方。游戏脚手架、业务代码全部由 Agent 依据这份短指南自行重建。

技术栈与项目形态：硬性约束一览

Godot 引擎指南锁定的技术栈是Godot 4（.NET / Mono 构建）+ C#，且所有 Godot C# 类必须声明为partial。这是从 CHANGELOG.md 记载的 2026-04-06 C# 迁移事件延续下来的既定路线：全部技能与生成代码从 GDScript 迁移到 C# / .NET，dotnet build取代了原先按文件逐个--check-only的校验循环。迁移动机在 docs/gdscript-vs-csharp.md 中有完整论述：GDScript 的:=类型推断在instantiate()、多态数学函数、数组/字典元素访问等约 15 类 API 上会静默返回 Variant，形成"温水煮青蛙"式的类型错误流；而 C# 泛型与类型推断（如GD.Load<PackedScene>(...)）让同类错误在编译期就被拦截。

标准项目骨架

构建门禁（Build Gate）

每次改动后按固定顺序通过三道关卡，保证用户本地运行（godot --path .或编辑器）始终反映当前状态：

dotnet build # 1. 编译门禁 godot --headless --import # 2. 资产变更后重新导入 godot --headless --quit # 3. 冒烟退出

其中 headless 退出时出现的 RID 泄漏警告是良性的，可忽略。用户在侧观看时是自己运行项目的，因此"保持构建与导入干净"是持续要求而非一次性动作。

场景是构建期生成的，不是手写的

Godot 引擎指南的核心主张：场景以 C#SceneTree脚本在构建期生成，而非手工编辑。每个场景对应一个一次性 headless 构建脚本：

godot --headless --script scenes/BuildX.cs

Builder 负责：构建节点层级、设置属性、挂接脚本、打包（pack），最后Quit()。它不含任何运行时逻辑——没有_Ready/_Process、信号或游戏状态。构建顺序遵循"先叶子场景、后父场景"，因为父场景需要引用已就绪的叶子。

序列化三规则：都是静默失败

下面的规则全是"静默失败"型：编译照常通过，但保存出的.tscn要么丢节点、要么文件膨胀。指南给出三条铁律：

1. Owner 链：每个节点都必须把Owner设为场景根，否则不会被序列化。构建完成后遍历整棵树，对所有后代设置child.Owner = root——但绝不递归进实例化的 GLB /.tscn节点（这些节点SceneFilePath非空）。若误递归进 GLB，其全部网格会被内联成文本，产生 100MB+ 的.tscn。

2. 校验打包结果：打包前统计节点数，打包后用Instantiate()实例化并再次统计，比对一致才放行ResourceSaver.Save()。否则一次静默丢节点会伪装成"成功"。

3. SetScript()会释放 C# 包装对象：脚本必须最后设置（层级建完再挂）。对于根节点，先把它加进一个临时Node，设置脚本后通过temp.GetChild(0)重新取回再打包。这个"临时父节点"模式在 docs/gdscript-vs-csharp.md 中有对应说明——它是 C# 迁移后新增的唯一重大怪癖：调用SetScript()后原 C# 变量已死（ObjectDisposedException），一旦写进模板，实践中就再也不会踩到。

共享保存路径的代码骨架（引擎指南原文，可直接落进任意 Builder）：

void PackAndSave(Node root, string path) { SetOwnerRecursive(root, root); // skip nodes with SceneFilePath set int expected = CountNodes(root); var packed = new PackedScene(); if (packed.Pack(root) != Error.Ok) { Quit(1); return; } var test = packed.Instantiate(); int got = CountNodes(test); test.Free(); if (got < expected) { GD.PushError("nodes dropped"); Quit(1); return; } // serialization failed silently ResourceSaver.Save(packed, path); Quit(0); }

GLB 模型接入规则

对于 GLB 模型：实例化其PackedScene，测量MeshInstance3D的 AABB 来决定缩放，碰撞形状必须用基于 AABB 的图元（Box/Sphere/Capsule）。严禁对导入网格调用CreateTrimeshShape()/CreateConvexShape()——那会把帧率打到 1 FPS 以下。

值得记住的怪癖（静默失败清单）

引擎指南认为模型已经熟知多数 Godot 行为，但下面这几类失败不会报任何错误，必须主动规避：

• macOS 上致命错误表现为挂起而非退出：Godot 会把错误放进一个NSAlert模态框，--headless无法关闭它，于是进程以 0% CPU 空转（缺主场景也会这样）。对策：每次godot调用都包在timeout下运行，退出码 124 即视为失败。如果输出停在.NET: Initializing module...，说明GodotSharp/未被找到——PATH上的godot是符号链接而非包装脚本。
• ArrayMesh.GenerateNormals()是程序化网格接收阴影的必要条件：不调用（或把CullMode.Disabled当作"安全网"）都会让阴影静默消失——正确做法是修缠绕顺序。
• MultiMeshInstance3D+ GLB 打包/保存时会丢网格：改用独立实例。GLB 内部节点上的MaterialOverride同样无法序列化（owner 被跳过）——需要自定义材质时改用程序化ArrayMesh。
• 射线对ConcavePolygonShape3D（trimesh）命中不可靠：改用形状查询（shape query），或对地形高度做解析采样。
• .gdignore会让导入器静默跳过整个目录：只有screenshots/目录允许放它，assets/永远不要。
• C# 枚举名不可靠：训练数据偏向 GDScript，LLM 猜出的 C# 枚举名常常是错的（如BGMode.Sky而非BGModeEnum.Sky）。对策是直接对照已安装 Godot 验证——阅读 Godot 文档/程序集中的 C# API，而不是靠记忆猜测。这一点在 docs/gdscript-vs-csharp.md 中被列为 C# 迁移后仅剩的三个痛点之一。
• 与帧率无关的阻尼公式：speed *= Mathf.Exp(-rate * delta)，而不是每帧speed *= (1 - drag)。

捕获证明视频：确定性录制的完整配方

Godogen 的交付铁律是"用运行中的游戏证明结果，而不是用一次干净编译"（见 prompts/runtime.md）。对 Godot 而言，这条铁律落地的载体就是硬件 Vulkan（macOS 上用 Metal）驱动的 Godot 电影写入器：

• 硬件 GPU 渲染正确且是录视频的硬性前提；软件 Vulkan（llvmpipe/lavapipe）还能出静态帧，但必须跳过视频并向用户说明。
• macOS 没有xvfb，捕获在真实窗口中进行；此时给--write-movie追加--headless会直接中止（报Parameter "t" is null）。

捕获由test/下的专用捕获SceneTree脚本驱动（如Presentation.cs），完整命令链如下（Linux 无头机器上在xvfb-run内执行，优先使用硬件 Vulkan ICD）：

# 前置：xvfb-run -a -s '-screen 0 1920x1080x24'；优先硬件 Vulkan ICD godot --headless --import godot --write-movie screenshots/result/frame.png --fixed-fps 30 --quit-after 450 --script test/Presentation.cs ffmpeg -y -framerate 30 -pattern_type glob -i 'screenshots/result/frame*.png' \ -c:v libx264 -pix_fmt yuv420p -movflags +faststart screenshots/result/video.mp4

要点逐条拆解：

• --fixed-fps 30使运动确定性化：450 帧 @ 30fps 正好 15 秒，满足 prompts/runtime.md 要求的 15–20 秒证明视频时长。
• 镜头必须提前摆好：在 Builder 或_Initialize中预置摄像机位置——电影写入器第一帧在_Process之前就会渲染。
• 捕获期输入由脚本驱动，不要依赖实时按键，否则每一帧都是人为不确定因素。
• 成片质量要求：片段必须展示行为在全窗口范围内持续推进——没有死时间，没有单帧循环。

从指南到交付：一份文档贯穿全流程

把整条链路串起来看：用户给出游戏描述 → Agent 依据 prompts/runtime.md 读入godot.md→ 按"技术栈 + 项目形态"搭好 C# 工程 → 用构建期SceneTree脚本按三条序列化铁律生成场景 → 用 asset-gen/SKILL.md 生成贴图、GLB 与精灵动画（Godot 侧运行时资产统一放assets/，见 publish.sh 对RUNTIME_ASSET_DIR的赋值）→ 用硬件 Vulkan 的电影写入器录下确定性的 15 秒证明视频 → 自己回放确认行为正确后再交付。用户在场时则以godot --path .的实时窗口替代视频，Agent 在品味/范围/成本决策点征求确认（这两种模式的分流逻辑同样写在 prompts/runtime.md 中）。

整套设计隐含一个取舍：引擎指南不追求全面覆盖 Godot API（那超出单页容量，也会与已安装版本脱节），而是把文字预算全部花在"模型无法快速推断"的三类知识上——项目骨架的硬约束、序列化的静默失败规则、确定性捕获配方。任何想复用这套工作流的读者，都可以直接把本文中的PackAndSave骨架、构建门禁三步命令与--write-movie+ ffmpeg 配方照搬进自己的 Godot 4 C# 项目，让"可运行的游戏"与"可回放的证明"同时成立。

• 人工智能
• AI Agent
• 游戏开发
• AI 技能
• 媒体生成