godot-project-foundations

项目基础

基于功能组织、一致的命名和良好的版本控制习惯，是专业 Godot 项目的基础。

可用脚本

核心脚手架（有状态／持久化）

• project_bootstrapper.gd：自动生成特性文件夹和 .gitignore。
• runtime_configurator.gd：应用高性能配置，并保存 override.cfg。
• managed_autoload.gd：通过 RefCounted 委托实现高级 Singleton 模式。
• 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，除非正在排查加载错误。

绝对不要做（专家级反模式）

全局架构

• 绝不要按文件类型分组——例如 /scripts、/sprites 文件夹。这会让维护变得噩梦般困难。请按功能组织：/player、/ui。
• 绝不要在文件名中混用 snake_case 和 PascalCase——标准做法：文件名使用 snake_case，节点使用 PascalCase。
• 绝不要使用硬编码的 get_node() 路径——重新设置父节点时容易出错。请使用 %SceneUniqueNames 实现稳定引用。
• 绝不要使用庞大的 Autoload——避免使用持有视觉节点引用的管理器；让单例专注于纯数据或 RefCounted 委托。

资源管理

• 绝不要忘记 .gitignore——提交 .godot/ 文件夹会导致 100MB 以上的膨胀和冲突。
• 绝不要跳过原始资源的 .gdignore——如果不忽略，根目录中的设计源文件（.psd、.blend）会被导入。
• 绝不要直接修改全局共享的 Resources——必须调用 duplicate(true)，创建拥有独立状态的唯一实例。

性能与线程

• 绝不要用 load() 阻塞主线程——异步场景切换必须使用 ResourceLoader.load_threaded_request()。
• 绝不要从后台线程修改 SceneTree——线程与主线程同步必须使用 call_deferred()。
• 绝不要在访问对象池时跳过 Mutex 锁定——使用共享的 WorkerThreadPool 或对象池时，必须确保线程安全。
• 绝不要使用 _process() 处理精确输入——它与视觉帧率绑定。必须使用 _unhandled_input() 捕获精确且不受帧影响的事件。

---

所有权决策树

需求	优先选择	避免
单个功能的全部内容（玩家、HUD 面板）	特性文件夹场景模块	类型文件夹（/scripts、/sprites）
有生命周期的跨场景服务（存档、音频总线）	通过 managed_autoload.gd 使用 Autoload	将 UI 节点塞进单例
多个发布者／订阅者，且无所有权关系	EventBus → 必备 global_event_bus.gd	导入半个游戏的 Autoload
单个场景的私有连线	场景本地节点 + %UniqueName	使用全局总线进行父节点→子节点调用

---

1. 命名约定

• 文件与文件夹：snake_case（C# 例外：类名匹配时使用 PascalCase）。
• 节点名称：PascalCase。
• 导出项：snake_case；Inspector 会将其转换为标题式大小写。
• 私有成员：成员和虚方法前加 _（_ready、_process）。
• 信号：使用过去时的 snake_case（health_changed）。
• 唯一名称：优先使用 %SceneUniqueNames，而非脆弱的 get_node() 路径。

2. 按功能组织

按功能分组（/entities/player、/ui/main_menu），而非按文件类型分组。保留 /common、/levels、/addons。

3. 版本控制

使用适配 Godot 的 .gitignore（忽略 .godot/），并为原始设计源文件添加 .gdignore。

工作流：搭建新项目

1. 确保 project.godot 存在 → 运行 project_bootstrapper.gd / 创建 entities/、ui/、levels/、common/。
2. 配置 Git .gitignore + 在 README.md 中说明按功能划分的目录结构。
3. 仅在所有权决策树给出建议后，才注册精简的 Autoload。

GDScript 严格类型（仅基础设置）

完整的强类型 GDScript 迁移指南位于 godot-gdscript-mastery。 对于新的基础项目：Project Settings → Debug → GDScript → Untyped Declaration = 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。

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；在转向相关领域时加载相关技能——不要预先加载整个知识体系。

官方文档

• 项目组织 — 基于功能的文件夹、.gdignore 和版本控制系统（VCS）规范，有助于保持导入内容和代码仓库易于维护。
• 场景组织 — 所有权边界，以及为什么 %SceneUniqueNames 优于脆弱的 get_node() 路径。
• GDScript 风格指南 — 本技能的验证器采用的标准 snake_case 文件名、PascalCase 节点名和过去时信号命名规范。
• GDScript 警告系统 — 将基础架构迁移到 GDScript 2.0 时，强制使用类型声明（Untyped Declaration → Warn/Error）。
• 单例（Autoload） — 如何注册精简的全局服务，使其在场景切换后仍然存在。
• Autoload 与常规节点的区别 — 何时适合使用 Managed Autoload / EventBus，而不是由场景局部管理所有权。
• 后台加载 — 用于实现非阻塞场景切换的 ResourceLoader.load_threaded_* 模式。
• 资源 — 共享与重复创建的 Resource 实例，以及为什么全局修改会破坏功能模块。
• 节点和场景实例 — 实例化、对象池，以及为功能文件夹划分场景即模块的边界。
• 使用 SceneTree — 树的生命周期、延迟调用，以及线程与主线程之间的同步规则。
• Godot 项目中的文件路径 — 脚手架文件夹和保存的 override.cfg / 元数据所用的 res:// / user:// 约定。
• ProjectSettings — 配置器和构建元数据使用的运行时配置、版本字符串和设置键。

相关技能

前置条件

• godot-gdscript-mastery — 在强制执行命名和脚手架规范前，熟练掌握带类型的 GDScript、代码风格和警告系统。

补充技能

• godot-version-migration — 在较旧的引擎版本上打开或搭建项目时，应先切换到库所针对的版本，再应用当前的基础规范。
• godot-autoload-architecture — 从干净的项目根目录注册 Managed Autoload / EventBus 单例时的启动顺序和所有权规则。
• godot-composition — 将功能文件夹变为可组合的场景模块；由父节点连接子节点，而不是不断扩展成单体管理器。
• godot-resource-data-patterns — 将 BaseDataResource 风格的响应式 Resource 扩展为完整的数据驱动目录，同时避免共享状态被修改。
• godot-signal-architecture — 在 Autoload 和场景所有权就位后，处理类型化 EventBus 信号及连接生命周期。
• godot-scene-management — 线程化加载器和场景切换以本技能的异步 ResourceLoader 样板代码为基础。
• godot-input-handling — 将 _unhandled_input 缓冲扩展为完整的操作映射和设备路由。

下游 / 使用方

• godot-export-builds — 导出预设和功能标签依赖整洁的文件夹布局、.gitignore 和构建元数据钩子。
• godot-testing-patterns — 基于功能的场景和确定性的 Autoload 让单元 / 集成测试框架更容易挂载。
• godot-debugging-profiling — 自定义 Logger 遥测和依赖项审计可在结构稳定后用于编辑器时诊断。
• godot-performance-optimization — 当基础架构触及 CPU / 内存上限时，可在此深入了解节点池、WorkerThreadPool 和运行时性能分析。

主技能

• godot-master — 库路由器和镜像模块入口；探索哪个领域技能负责跨领域架构问题时，请打开此项。