Godot项目组织基础：用一套专家蓝图，把 Godot 4 项目结构一次做对
- 它是什么：
godot-project-foundations（Godot项目组织基础）是一份面向 Godot 4 的「项目组织专家蓝图」，把基于特征的文件夹结构、命名约定、版本控制卫生固化成可执行的规则与脚本。 - 核心主张：按特征（
/player、/enemies、/ui）而不是按文件类型（/scripts、/sprites）组织项目；文件用snake_case、节点用PascalCase、频繁访问的节点用%SceneUniqueNames。 - 自带脚本：提供
project_bootstrapper.gd（脚手架）、scene_naming_validator.gd（命名扫描）、dependency_auditor.gd（循环依赖审计）、feature_scaffolder.gd（特征文件夹生成）四个实用脚本。 - 最适合谁：刚开新项目的独立开发者、需要统一多人协作规范的团队、以及想要重构「越写越乱」旧项目的开发者。
- 一句话结论：它不能替你写游戏玩法，但能帮你在项目还只有三个文件的时候就避开未来 90% 的结构性麻烦。
该技能叫什么？如何一键安装 AI 技能提升开发效率？
技能中文名：Godot项目组织基础Skill 技能英文名：godot-project-foundations 技能ID：13304
它解决的问题非常具体：Godot 项目在前期几乎怎么写都能跑，但一旦场景数量上去、团队人数变多，按文件类型分组的 /scripts、/sprites、/sounds 目录就会变成维护噩梦；PlayerController.gd 和 player_controller.gd 混用会让检索和代码审查变得痛苦；把 .godot/ 提交进仓库就是 100MB+ 的体积膨胀加无休止的合并冲突；硬编码的 get_node("../../../Player/Sprite2D") 在场景重新设置父节点时直接报错。这个技能的作用，就是把这些"踩过坑才知道"的经验，前置成一套 AI 能直接执行的规范。
一键安装的思路与步骤
「一键安装 AI 技能」的本质，是把你所在的 AI 编程助手（如支持 Skill 机制的开发工具）接入这个技能包，之后你在对话里提出"帮我搭一个 Godot 项目结构"，助手就会自动按这套蓝图执行，而不是凭感觉生成一堆文件夹。
- 确认安装前提：你需要在本地已有一个可用的 AI 编程助手环境，并具备 Godot 4 项目（已有或即将创建）。技能运行时会生成
.gd脚本与目录，因此需要对应的项目写入权限。 - 在技能市场/技能列表中检索：使用技能英文名
godot-project-foundations或技能ID13304进行检索与安装。具体的安装命令、市场入口地址、是否支持离线导入等细节，请以官方说明为准。 - 安装后验证是否生效：新建或打开一个 Godot 4 项目，向助手发出指令，例如「用 godot-project-foundations 帮我初始化项目结构」，观察助手是否正确调用
project_bootstrapper.gd或按"基于特征"的规则创建entities/、ui/、levels/、common/等目录并生成.gitignore。如果助手只是泛泛而谈而没有引用脚本与规范，说明技能未被正确加载。 - 按提示阅读强制脚本：技能详情中明确标注，对于新项目，在搭建脚手架之前应先阅读
project_bootstrapper.gd，它会自动生成特征文件夹与.gitignore。这是唯一被标注为"强制"的前置动作，建议不要跳过。 - 不要过度加载：
dependency_auditor.gd只在排查加载错误或审计大型项目时才需要，日常搭建阶段无需加载，避免干扰。
该技能的主要功能和特点
- 四个可直接复用的脚本：
project_bootstrapper.gd负责专家级项目脚手架，自动生成特征文件夹和.gitignore；scene_naming_validator.gd扫描整个项目查找snake_case/PascalCase违规，适合在提 PR 前运行；dependency_auditor.gd检测循环场景依赖与耦合问题，对超过 50 个场景的项目尤为关键；feature_scaffolder.gd生成完整的特征文件夹（含基础场景、脚本和子文件夹）。 - 三套明确的命名约定：文件与文件夹统一
snake_case（如player_controller.gd、main_menu.tscn），唯一例外是 C# 脚本使用PascalCase以匹配类名；节点名称统一PascalCase（如PlayerSprite、CollisionShape2D）；频繁访问的节点使用%SceneUniqueNames，替代脆弱的get_node()长路径。 - 基于特征的组织范式：技能直接给出可对照的目标结构——
/common放全局资源、主题与共享脚本，/entities/player下同时放player.tscn、player.gd、player_sprite.png，/ui/main_menu、/levels、/addons各自归位。判断标准是"按什么（特征）分，而不是按怎么做的（类型）分"。 - 版本控制卫生：强制附带 Godot 专用
.gitignore（忽略.godot/文件夹与导入工件），并在 Godot 不应扫描的目录（如原始设计源文件）放置.gdignore，避免.psd、.blend被误导入。 - 明确的"绝不做"清单：不按文件类型分组、不混用命名风格、不忘
.gitignore、不用硬编码get_node()路径、不为原始资源跳过.gdignore。这五条是技能最有辨识度的部分——它不只告诉你"该怎么做"，还明确告诉你"哪些做法一定会后悔"。 - 与普通模板的区别：普通模板仓库给你一堆空文件夹，你得自己记住规则；这个技能把规则连同校验脚本一起交给 AI，让规范在生成阶段就被执行、在 PR 之前被扫描出来。
如何使用该技能？
步骤 1：明确你的目标类型 先判断属于哪一类：A. 新项目启动；B. 旧项目结构重构；C. 提交前规范检查；D. 大型项目依赖排障。不同类型对应不同脚本，不要一上来就全量加载。
步骤 2：初始化新项目（类型 A） 输入示例：
「帮我用 godot-project-foundations 初始化一个新的 Godot 4 项目，项目名叫 NeonRunner。」
预期输出：助手会先参考 project_bootstrapper.gd，然后确认 project.godot 存在，创建 entities/、ui/、levels/、common/ 四个核心文件夹，生成 Godot 专用 .gitignore，并写一个 README.md 解释基于特征的结构。这正是技能中"工作流程：搭建新项目"规定的四步。
步骤 3：生成具体特征模块 输入示例：
「用 feature_scaffolder.gd 帮我生成一个 player 特征文件夹，包含基础场景和脚本。」
预期输出：在 entities/player/ 下生成 player.tscn、player.gd 及子文件夹，命名符合 snake_case 文件、PascalCase 节点规则。
步骤 4：重构旧项目（类型 B） 输入示例：
「我的项目现在是 /scripts、/sprites、/sounds 三个文件夹，帮我按特征重新组织，并给出迁移映射表。」
预期输出：一份"旧路径 → 新路径"的对照清单，以及调整后的目录树。建议先在分支上执行，逐特征迁移并跑一遍游戏，避免一次性大搬家。
步骤 5：提交前做规范扫描（类型 C） 输入示例：
「运行 scene_naming_validator.gd 扫描整个项目，列出所有 snake_case / PascalCase 违规。」
预期输出：违规文件与节点清单。这是技能里明确建议"在 PR 之前运行"的动作，适合加进团队的提交前检查流程。
步骤 6：大型项目依赖审计（类型 D） 当项目场景超过 50 个、出现加载错误或耦合混乱时，输入：
「用 dependency_auditor.gd 检测循环场景依赖。」
预期输出：循环依赖链路与耦合热点。注意技能特别提示：除非在排查加载错误或审计大型项目，否则不要加载此脚本。
步骤 7：补齐 .gitignore 与 .gdignore
输入示例：
「检查我的 .gitignore 是否忽略了 .godot/ 和导入工件；美术源文件目录帮我加 .gdignore。」
同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| godot-project-foundations（本技能） | 面向 AI 助手的项目组织专家蓝图 | 四个组织类脚本 + 命名约定 + 基于特征的结构 + 版本控制规则，AI 可直接执行 | 需接入支持 Skill 的 AI 助手并安装技能；具体入口以官方说明为准 | 新项目启动、结构重构、PR 前检查、大型项目依赖审计 | 优势：规范可执行、带校验脚本、明确"绝不做"清单，AI 生成即合规；不足：偏结构规范，不涉及具体玩法与性能优化 |
| Godot 官方最佳实践文档 | 权威参考文档 | 项目组织与场景组织的官方建议 | 零门槛，直接阅读网页 | 想理解"为什么这样组织"的学习场景 | 优势：权威、免费、体系完整；不足：纯文档，不生成代码，执行全靠自觉，也无自动校验 |
| GitHub 上的 Godot 项目模板仓库 | 现成骨架 | 提供一份可直接 clone 的目录结构与基础场景 | 需要自行挑选可信模板并 clone，改造成本因模板质量而异 | 快速起一个能跑的骨架 | 优势：开箱即用；不足：模板质量参差、更新滞后，团队成员仍要靠记忆遵守规则，无违规检测 |
| GDScript 代码格式化与静态检查工具 | 代码层面的规范工具 | 格式化与 lint，处理缩进、风格等代码问题 | 需单独安装与配置，有一定命令行门槛 | 代码风格统一、CI 集成 | 优势：自动化程度高、可进 CI；不足：关注"代码怎么写"，不关注"文件夹怎么放、场景怎么连"，覆盖不到结构与依赖问题 |
可以看到，本技能的差异化在于把"项目组织"这件通常靠口头约定和新人踩坑来传递的事，变成了 AI 可执行、可校验的动作。官方文档告诉你规则，模板仓库给你结果，而它是"规则 + 执行 + 检查"打包在一起。
该技能的典型应用场景与实际体验情况
场景一：独立开发者的新项目启动
角色：一个人做完整游戏的独立开发者。痛点：每次开新项目都要重新想目录怎么分，做着做着就变成 /scripts 大杂烩，回头找一个敌人 AI 脚本要翻三遍。使用方式：开项目第一句话就让助手按 project_bootstrapper.gd 搭骨架。实际体验：上手几乎零成本，因为不需要学新工具，只是把"帮我建个 Godot 项目"换成了带技能名的说法；效果最明显的是 .gitignore 从一开始就是对的，不用等仓库涨到几百 MB 才补救。注意事项：脚本生成的目录是空骨架，记得让助手同时补 README.md 说明结构，否则三个月后自己也会忘。
场景二：多人协作团队的 PR 前检查
角色：3-5 人小团队的 Tech Lead。痛点：成员命名风格各异，PlayerController.gd 和 player_controller.gd 同时存在；审查时靠肉眼抓违规，效率极低。使用方式：把"运行 scene_naming_validator.gd 扫描违规"写进提交前清单。实际体验：把主观的风格争论变成了客观的清单输出，评审讨论成本明显下降。注意事项：扫描结果是清单，重命名仍需人工确认，建议小批量处理，避免一次改几十个文件导致 diff 爆炸。
场景三：中型项目的依赖排障
角色：维护一个已有 60+ 场景项目的开发者。痛点：场景之间互相引用，某次改完出现加载错误，怀疑是循环依赖但找不到链路。使用方式：按技能提示，此时才加载 dependency_auditor.gd 做依赖审计。实际体验：它的价值恰在于"平时不用、用时能定位"，避免了日常对话里塞入无关的重型脚本。注意事项：技能本身已提示非必要不加载，遵循这一点能让 AI 对话更聚焦。
场景四：美术源文件导致的导入污染
角色：带美术合作的开发者。痛点：把 .psd、.blend 源文件丢进项目根目录，Godot 全部导入，项目体积暴涨、导入变慢。使用方式：请助手在源文件目录添加 .gdignore，并检查 .gitignore。实际体验：这是技能里最"一次到位、长期受益"的一条，属于典型的低成本高回报操作。注意事项：.gdignore 只是让 Godot 不扫描，源文件本身仍需要自己管理版本与备份策略。
该技能能为用户带来的价值
结构决策成本降到接近零。 新项目最耗神的往往不是写代码，而是"这个脚本该放哪"。技能给出了明确的判断标准——按特征分组，/player 下同时放场景、脚本和贴图。有了标准，就不再需要每次纠结。
协作摩擦显著降低。 命名约定与校验脚本把"风格之争"转成"清单核对"。文件用 snake_case、节点用 PascalCase、C# 脚本例外用 PascalCase，规则一次讲清楚，之后由 scene_naming_validator.gd 在 PR 前把关。
避免高代价的结构性返工。 硬编码 get_node() 路径在场景重新设置父节点时直接崩；.godot/ 入库带来百兆级膨胀与合并冲突。这两类问题的修复成本随项目规模增长而急剧上升，而技能在项目第一天就把它们规避掉——早一步做对，等于省下后期数倍的重构时间。
让"老手经验"变成可复用资产。 五个"绝不做"条目，本质上是从真实事故里提炼的教训清单。它以技能形式沉淀下来，新人不必再靠踩坑来获得同样的认知，团队的知识传递也从口头叮嘱变成了可执行规范。
长期价值在于可维护性。 一个按特征组织、命名一致、依赖清晰、版本控制干净的项目，在半年后重新打开时仍然"看得懂"。这才是项目组织真正的复利所在。
常见问题 FAQ
Q1：这个技能怎么安装？需要付费吗？
A：在支持 Skill 机制的 AI 编程助手中，通过技能英文名 godot-project-foundations 或技能 ID 检索并安装。具体安装命令、入口地址与是否收费，以官方说明为准。安装后的验证方式是：让助手"用 godot-project-foundations 初始化项目结构"，看它是否调用内置脚本并生成基于特征的目录。
Q2：它只适用于 Godot 4 吗？Godot 3 的项目能用吗？
A：技能描述明确是「Godot 4 项目组织的专家蓝图」，围绕 Godot 4 的 %SceneUniqueNames、.godot/ 目录等特性设计，建议在 Godot 4 项目中使用。Godot 3 项目在命名约定与特征分组思想上可部分借鉴，但脚本与目录约定不完全对应，需要自行判断。
Q3：我的项目已经很乱了，还能用它重构吗？
A：可以，这也是它的典型用途之一（“启动新项目或重构结构”）。建议做法是：先让助手输出"旧路径 → 新路径"的迁移映射表，在独立分支上逐特征迁移，每迁完一个模块就跑一次游戏验证，最后再统一运行 scene_naming_validator.gd 清收命名违规。不要一次性全部搬家。
Q4：和直接用官方文档 / 现成模板仓库比，它的优势在哪？ A：官方文档告诉你规则，但不生成代码、也不做检查；模板仓库给你一个结果，但团队成员仍要靠记忆遵守规则，且模板质量参差。这个技能的差异是把"规则 + 执行脚本 + 检查脚本"打包交给 AI，生成阶段就合规、提交前还能扫一遍。如果你的需求只是"看一眼目录长什么样"，官方文档就够了。
Q5：四个脚本我要全都跑一遍吗？
A：不需要。新项目优先用 project_bootstrapper.gd（技能标注为强制先读）和 feature_scaffolder.gd；提 PR 前用 scene_naming_validator.gd；dependency_auditor.gd 只在排查加载错误或审计大型项目（如超过 50 个场景）时加载，日常不必启用。按需调用反而效果更好。