godot-project-templates

项目模板（导航）

搭建架构，然后调整——切勿将类型教程原封不动地塞进项目。

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

目录与脚手架

• 切勿在几十个调用点硬编码场景路径——使用 AutoLoad 常量或场景注册表。
• 切勿在导入流程之外放置设计师提供的资源文件时，跳过 .gdignore。
• 切勿原样复制粘贴模板——先理解结构，再进行调整（见下方清单）。

架构与生命周期

• 切勿在没有按处理模式分组的情况下使用 get_tree().paused——暂停菜单需要 PROCESS_MODE_ALWAYS。**原因：**暂停场景树也会冻结菜单节点上的 _process，因此按钮永远无法接收输入；通过 base_menu.gd 或在暂停根节点上显式设置 process_mode，将游戏玩法设为 INHERIT（暂停），将菜单/HUD 设为 ALWAYS。
• 切勿跳过基类的虚拟生命周期钩子——优先使用 _initialize_*()，而不是脆弱的 _ready() 重写。
• 切勿依赖臃肿的上帝单例——使用信号总线或子系统定位器。

平台与 UI

• 切勿在 FPS 脚手架中跳过 Input.MOUSE_MODE_CAPTURED——选择 FPS 类型路径时设置。
• 切勿使用浮点常量进行 UI 布局——使用锚点/容器。
• 切勿忽略 i18n 翻译上下文——在 tr() / 上下文中消除字符串歧义。

性能

• 切勿同步加载大型关卡——使用 ResourceLoader.load_threaded_request()。

---

黄金路径

0. 引导——必须使用 bootstrap_config.gd：先配置网络，再配置音频/UI（不要依赖偶然的 AutoLoad 顺序）。
1. 从下方选择一个类型行 → 仅加载列出的脚本。
2. 重命名项目，注册定位器/引导配置，并配置 Input Map。
3. 打开使用方的 godot-genre-* 技能，了解游戏玩法系统。

**平台跳跃游戏端到端流程：**第 1 行脚本 → godot-genre-platformer（使用 advanced_platformer_controller.gd 实现移动；使用模板 base_level + 状态机处理场景流程）。切勿粘贴此技能中的 FPS/物品栏方案。

类型路由器 → 脚本

MANDATORY：选择一个类型对应的行，加载列出的脚本，然后打开用于玩法系统的使用方 godot-genre-* 技能。不要凭记忆粘贴内联 FPS 控制器或背包管理器。

类型意图	加载这些模板脚本（MANDATORY）	通过以下技能填充玩法
2D 平台游戏	base_game_manager.gd、base_level.gd、base_actor.gd、scene_state_machine.gd、state_machine_node.gd	godot-genre-platformer
俯视角 / 动作 RPG	同上基础脚本 + subsystem_locator.gd、base_menu.gd	godot-genre-action-rpg
3D FPS / 射击游戏	基础脚本 + multi_platform_input.gd、platform_feature_config.gd	godot-genre-shooter-fps
任意类型 + DLC 包	modular_dlc_loader.gd	类型技能 + godot-export-builds
跨平台输入 / 功能	multi_platform_input.gd、platform_feature_config.gd	godot-input-handling
多线程关卡流式加载	level_steamer_manager.gd	godot-scene-management
无障碍 TTS	accessibility_tts_manager.gd	项目基础 / UI 技能

按功能划分的文件夹骨架（适用于所有类型）：entities/<name>/、levels/ 或 maps/、ui/、autoloads/ 或通过定位器注册的系统、resources/。详情请参阅类型使用方技能——不要在此重复。

---

架构差异（保留在此技能中）

Subsystem Locator 与 God Autoload

模块化注册优先使用 subsystem_locator.gd；仅保留精简的引导 Autoload。

引导顺序

MANDATORY bootstrap_config.gd（或等效实现）：在音频 / UI 之前初始化关键系统（配置 / 网络）。不要仅依赖 Project Settings Autoload 中偶然的顺序。

暂停模式

玩法树暂停；UI / 暂停菜单节点使用 PROCESS_MODE_ALWAYS。通过 base_menu.gd 配置。

PCK / DLC

MANDATORY 使用 modular_dlc_loader.gd 挂载 ProjectSettings.load_resource_pack()——切勿在玩法代码中自行编写路径变通方案。

功能标签

MANDATORY 使用 platform_feature_config.gd 处理 OS.has_feature() / 导出标签分支（mobile、low_end、dedicated_server）。

---

适配而非照搬清单

编写玩法代码前，先将每个模板组件映射到一项用户技能：

模板组件	适配为
base_actor / 状态机节点	类型移动/战斗技能（godot-genre-*）+ godot-state-machine-advanced
base_game_manager 信号	godot-autoload-architecture / godot-signal-architecture
关卡流式加载器	godot-scene-management
输入/功能配置	godot-input-handling + 平台技能
菜单/HUD 外壳	godot-ui-containers
导出/CI/PCK	godot-export-builds

**用法：**选择类型行 → 加载脚本 → 重命名项目 → 注册 locator/bootstrap → 配置 Input Map → 打开类型技能了解系统 — 不要照搬本技能中的 FPS/库存预制方案。

深入了解（按需加载）

平台游戏/RPG/FPS 目录树、输入映射模板、CI 导出 YAML、PCK 挂载、bootstrap 优先级 — references/genre-template-scaffolds.md。

参考

渐进式披露：仅在研究特定 API 时打开官方文档链接；在转到同级领域时加载相关技能 — 不要预加载整个技能网络。

官方文档

• 项目组织 — 功能文件夹布局、.gdignore 和版本控制系统（VCS）规范，这些都应从一开始就纳入各类游戏模板。
• 场景组织 — entities/、levels/ 和 UI 场景的所有权边界，确保模板便于安全重构。
• 单例（Autoload） — 注册精简的 GameManager / Audio / SceneTransitioner 服务，使其在场景切换后仍能运行。
• Autoload 与常规节点的区别 — 何时使用子系统定位器或场景局部节点，而不是庞大的 God 单例。
• 后台加载 — 关卡流式加载模板使用的 ResourceLoader.load_threaded_* 模式。
• 暂停游戏 — 设置处理模式，确保游戏暂停时暂停菜单仍能运行。
• 多种分辨率 — 拉伸模式／宽高比默认值（canvas_items / expand），每个新项目模板都应记录。
• 功能标签 — 在平台配置模板中使用 OS.has_feature() 配置移动端／PC／服务器的覆盖设置。
• 导出资源包（PCK） — 通过 ProjectSettings.load_resource_pack() 挂载模块化 DLC／补丁。
• 使用控制器和游戏手柄 — 多平台模板的默认 Input Map 操作和死区调节。
• 文本转语音 — 用于搭建无障碍管理器框架的 DisplayServer TTS 接口。
• 游戏国际化 — 设置翻译上下文，避免菜单／HUD 中的 UI 字符串使用含义模糊的键。

相关技能

前置条件

• godot-project-foundations — 将某类游戏的骨架复制到实际代码库之前，先了解文件夹规范、命名和导入基础知识。
• godot-gdscript-mastery — 本文所有模板脚本使用的类型化基类、虚拟钩子和信号风格。

补充内容

• godot-autoload-architecture — 当 BootstrapConfig / GameManager Autoload 脱离模板阶段后，介绍启动顺序和所有权规则。
• godot-scene-management — 介绍生产环境中的场景切换和加载队列，以扩展关卡流送样板代码。
• godot-input-handling — 介绍完整的操作映射、设备路由和重新映射，超越 MultiPlatformInput 脚手架的基础内容。
• godot-state-machine-advanced — 介绍层级式 / 可视化 FSM 模式，扩展 SceneStateMachine 和 StateMachineNode。
• godot-export-builds — 介绍 Standard-Export-Presets 模板所需的导出预设、VRAM 压缩和 CI 无头模式标志。
• godot-signal-architecture — 当模板不再局限于直接使用 GameManager 信号时，介绍强类型 EventBus 模式。
• godot-ui-containers — 介绍 BaseMenu 和 HUD 场景的锚点 / 容器布局，避免浮点像素偏移。
• godot-adapt-desktop-to-mobile — 介绍 PlatformFeatureConfig 仅提供空壳的触控、安全区域和移动端功能标签配置。

下游 / 使用方

• godot-genre-platformer — 为 2D 平台游戏目录骨架补充移动、土狼时间和关卡流程。
• godot-genre-action-rpg — 补充可接入俯视角 RPG 模板文件夹的战斗、库存和任务系统。
• godot-genre-shooter-fps — 在 3D FPS 玩家脚手架上增加武器、命中检测和镜头手感。

主模块

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。