用途
Godot 项目基础（Project Foundations）是一套面向 Godot 4 的项目组织专家蓝图，用于在启动新项目或重构项目结构时，建立基于功能的组织方式、一致的命名规范与版本控制卫生习惯。其核心主张是：基于功能的组织、一致的命名和版本控制卫生共同定义了专业的 Godot 项目。
主要能力
该技能提供一组脚本，分为两类。
核心脚手架（有状态 / 持久化）：
- project_bootstrapper.gd：自动生成功能文件夹与 .gitignore。
- runtime_configurator.gd：应用高性能配置并保存 override.cfg。
- managed_autoload.gd：使用 RefCounted 委托的高级单例模式。
- global_event_bus.gd：用于解耦全局信号的强制组件，不要在对话中重新内联 EventBus 示例。
- node_pooling_system.gd：面向高频场景实例化的线程安全对象池。
- async_resource_loader.gd：用于线程化场景切换的强制组件，不要重新内联 SceneManager 示例。
运行时工具（无状态 / 轻量）：
- base_data_resource.gd：使用 emit_changed() 的响应式 Resource 基础。
- advanced_telemetry_logger.gd：用于崩溃报告的自定义 OS 级 Logger。
- threaded_task_worker.gd：健壮的 WorkerThreadPool 实现。
- action_buffer_input.gd：基础 _unhandled_input 缓冲。
- build_metadata_provider.gd：原生提取版本与构建元数据。
- feature_scaffolder.gd / scene_naming_validator.gd：功能文件夹与命名门禁。
注意：除非排查加载错误，否则不要加载 dependency_auditor.gd。
使用方式
命名规范
- 文件与文件夹：snake_case（C# 例外：与类名匹配的 PascalCase）。
- 节点名称：PascalCase。
- 导出变量：snake_case；检查器会将其显示为 Title-Case。
- 私有成员：成员与虚函数（_ready、_process）前加下划线 _。
- 信号：过去式 snake_case（如 health_changed）。
- 唯一名称：使用 %SceneUniqueNames 替代脆弱的 get_node() 路径。
基于功能的组织
按功能分组（如 /entities/player、/ui/main_menu），而非按文件类型分组。保留 /common、/levels、/addons。
版本控制
使用 Godot 感知的 .gitignore（忽略 .godot/），并在原始设计源文件上使用 .gdignore。
脚手架新项目的工作流
- 确保 project.godot 存在，然后运行 project_bootstrapper.gd，或创建 entities/、ui/、levels/、common/。
- 设置 Git .gitignore，并在 README.md 中记录基于功能的布局。
- 仅当所有权决策树支持时，才注册精简的 Autoload。
所有权决策树
- 需要一个功能的全部内容（玩家、HUD 面板）：优先使用功能文件夹场景模块，避免类型文件夹（/scripts、/sprites）。
- 具有生命周期的跨场景服务（存档、音频总线）：优先通过 managed_autoload.gd 使用 Autoload，避免将 UI 节点塞进单例。
- 多发布者/订阅者、无所有权：优先使用 EventBus，即强制的 global_event_bus.gd，避免导入半个游戏的 Autoload。
- 单个场景的私有连线：优先使用场景本地节点加 %UniqueName，避免用全局总线处理父到子调用。
类型化 GDScript 严格性（仅基础）
完整的类型化 GDScript 迁移位于 godot-gdscript-mastery。对于新的基础项目：项目设置 → 调试 → GDScript → 未类型化声明 设为 Warn 或 Error。
专家基础架构
- 场景切换：强制加载 async_resource_loader.gd，使用带进度的线程化 ResourceLoader。不要在此粘贴 SceneManager 示例。
- 全局事件总线：强制加载 global_event_bus.gd 以使用类型化全局信号。不要在此粘贴 EventBus 示例。
- 项目元数据：使用 build_metadata_provider.gd / base_data_resource.gd 处理版本/构建标志，而非临时 JSON。
深入阅读（按需加载）
完整命名表、类型化 GDScript 迁移、EventBus/SceneManager/元数据示例见 references/foundations-deep.md。
适用场景
适用于启动新的 Godot 4 项目、重构现有项目结构、建立团队命名与文件夹约定、配置版本控制忽略规则，以及搭建 Autoload、EventBus、场景切换、对象池等基础架构时。
限制与反模式
该技能明确列出不应做的事项。
全局架构：
- 绝不按文件类型分组（/scripts、/sprites 文件夹），维护性极差；应使用基于功能的方式（/player、/ui）。
- 绝不在文件中混用 snake_case 与 PascalCase；标准是文件用 snake_case、节点用 PascalCase。
- 绝不使用硬编码的 get_node() 路径，重新挂载父节点时很脆弱；应使用 %SceneUniqueNames 获得稳定引用。
- 绝不使用单体式 Autoload，避免持有可视节点引用的管理器；保持单例专注于纯数据或 RefCounted 委托。
资源管理：
- 绝不忘记 .gitignore，提交 .godot/ 文件夹会导致 100MB+ 膨胀与冲突。
- 绝不为原始资产跳过 .gdignore，根目录下的设计源文件（.psd、.blend）若未忽略会被导入。
- 绝不直接修改全局共享的 Resource，应严格调用 duplicate(true) 获得具有独立状态的唯一实例。
性能与线程：
- 绝不用 load() 阻塞主线程，应严格使用 ResourceLoader.load_threaded_request() 进行异步场景切换。
- 绝不从后台线程修改 SceneTree，应严格使用 call_deferred() 进行线程到主线程的同步。
- 绝不在池化访问时跳过 Mutex 锁定，使用共享 WorkerThreadPool 或对象池时应严格保证线程安全。
- 绝不使用 _process() 处理精确输入，它绑定视觉帧率；应严格使用 _unhandled_input() 捕获精确的、与帧率无关的事件。
参考
该技能采用渐进式披露：仅在研究特定 API 时打开官方文档链接，在路由到同级领域时加载相关技能，不要预加载整个网络。
官方文档涵盖项目组织、场景组织、GDScript 风格指南、GDScript 警告系统、单例（Autoload）、Autoload 与常规节点对比、后台加载、Resources、节点与场景实例、使用 SceneTree、Godot 项目中的文件路径、ProjectSettings。
相关技能包括前置的 godot-gdscript-mastery；互补的 godot-version-migration、godot-autoload-architecture、godot-composition、godot-resource-data-patterns、godot-signal-architecture、godot-scene-management、godot-input-handling；下游消费者 godot-export-builds、godot-testing-patterns、godot-debugging-profiling、godot-performance-optimization；以及主路由 godot-master。