godot-project-foundations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Foundations

项目基础

Feature-based organization, consistent naming, and version control hygiene define professional Godot projects.

基于功能的组织方式、一致的命名规范和版本控制规范是专业Godot项目的核心。

Available Scripts

可用脚本

MANDATORY - For New Projects: Before scaffolding, read
project_bootstrapper.gd
- Auto-generates feature folders and .gitignore.

新项目必备：在搭建项目前，请阅读
project_bootstrapper.gd
——它可自动生成功能文件夹和.gitignore文件。

project_bootstrapper.gd

Expert project scaffolding tool for auto-generating feature folders and .gitignore.

专业的项目搭建工具，可自动生成功能文件夹和.gitignore文件。

scene_naming_validator.gd

Scans entire project for snake_case/PascalCase violations. Run before PRs.

扫描整个项目，检查是否存在snake_case/PascalCase命名违规情况。请在提交PR前运行该脚本。

dependency_auditor.gd

Detects circular scene dependencies and coupling issues. Critical for projects >50 scenes.

检测场景循环依赖和耦合问题。对于包含50个以上场景的项目至关重要。

feature_scaffolder.gd

Generates complete feature folders with base scenes, scripts, and subfolders.

Do NOT Load dependency_auditor.gd unless troubleshooting loading errors or auditing large projects.

生成完整的功能文件夹，包含基础场景、脚本和子文件夹。

请勿加载 dependency_auditor.gd，除非你在排查加载错误或审计大型项目。

NEVER Do in Project Organization

项目组织中的禁忌

NEVER group by file type —
```
/scripts
```
,
```
/sprites
```
,
```
/sounds
```
folders? Nightmare maintainability. Use feature-based:
```
/player
```
,
```
/enemies
```
,
```
/ui
```
.
NEVER mix snake_case and PascalCase in files —
```
PlayerController.gd
```
vs
```
player_controller.gd
```
? Pick one. Official standard: snake_case for files, PascalCase for nodes.
NEVER forget .gitignore — Committing
```
.godot/
```
folder = 100MB+ bloat + merge conflicts. ALWAYS include Godot-specific .gitignore.
NEVER use hardcoded get_node() paths —
```
get_node("../../../Player/Sprite2D")
```
breaks on scene reparenting. Use
```
%SceneUniqueNames
```
for stable references.
NEVER skip .gdignore for raw assets — Design source files (
```
.psd
```
,
```
.blend
```
) in project root = Godot imports them. Add
```
.gdignore
```
to exclude from import process.

切勿按文件类型分组——比如
```
/scripts
```
、
```
/sprites
```
、
```
/sounds
```
这类文件夹？维护起来简直是噩梦。请使用基于功能的分组：
```
/player
```
、
```
/enemies
```
、
```
/ui
```
。
切勿在文件中混合使用snake_case和PascalCase——比如
```
PlayerController.gd
```
和
```
player_controller.gd
```
共存？请统一命名方式。官方标准：文件使用snake_case，节点使用PascalCase。
切勿忘记添加.gitignore——提交
```
.godot/
```
文件夹会导致100MB+的冗余文件以及合并冲突。务必添加针对Godot的专属.gitignore。
切勿使用硬编码的get_node()路径——
```
get_node("../../../Player/Sprite2D")
```
会在场景重父化后失效。请使用
```
%SceneUniqueNames
```
来实现稳定的节点引用。
切勿不为原始资源添加.gdignore——项目根目录中的设计源文件（如
```
.psd
```
、
```
.blend
```
）会被Godot导入。请添加
```
.gdignore
```
以排除这些文件的导入流程。

1. Naming Conventions

1. 命名规范

Files & Folders: Always use
```
snake_case
```
. (e.g.,
```
player_controller.gd
```
,
```
main_menu.tscn
```
).
- Exception: C# scripts should use
```
PascalCase
```
  to match class names.
Node Names: Always use
```
PascalCase
```
(e.g.,
```
PlayerSprite
```
,
```
CollisionShape2D
```
).
Unique Names: Use
```
%SceneUniqueNames
```
for frequently accessed nodes to avoid brittle
```
get_node()
```
paths.

文件与文件夹：始终使用
```
snake_case
```
命名。（例如：
```
player_controller.gd
```
、
```
main_menu.tscn
```
）。
- 例外：C#脚本应使用
```
PascalCase
```
  ，以匹配类名。
节点名称：始终使用
```
PascalCase
```
（例如：
```
PlayerSprite
```
、
```
CollisionShape2D
```
）。
唯一名称：对频繁访问的节点使用
```
%SceneUniqueNames
```
，避免脆弱的
```
get_node()
```
路径。

2. Feature-Based Organization

2. 基于功能的组织方式

Instead of grouping by type (e.g.,

/scripts

/sprites

), group by feature (the "What", not the "How").

Correct Structure:

/project.godot
/common/           # Global resources, themes, shared scripts
/entities/
    /player/       # Everything related to player
        player.tscn
        player.gd
        player_sprite.png
    /enemy/
/ui/
    /main_menu/
/levels/
/addons/           # Third-party plugins

不要按类型分组（如

/scripts

、

/sprites

），而应按功能分组（关注“是什么”，而非“怎么做”）。

正确结构：

/project.godot
/common/           # 全局资源、主题、共享脚本
/entities/
    /player/       # 与玩家相关的所有内容
        player.tscn
        player.gd
        player_sprite.png
    /enemy/
/ui/
    /main_menu/
/levels/
/addons/           # 第三方插件

3. Version Control

3. 版本控制

Always include a
```
.gitignore
```
tailored for Godot (ignoring
```
.godot/
```
folder and import artifacts).
Use
```
.gdignore
```
in folders that Godot should not scan/import (e.g., raw design source files).

始终添加针对Godot的专属
```
.gitignore
```
（忽略
```
.godot/
```
文件夹和导入产物）。
在Godot不应扫描/导入的文件夹中使用
```
.gdignore
```
（例如原始设计源文件所在的文件夹）。

Workflow: Scaffolding a New Project

工作流程：搭建新项目

When asked to "Setup a project" or "Start a new game":

Initialize Root: Ensure
```
project.godot
```
exists.
Create Core Folders:
- ```
entities/
```
- ```
ui/
```
- ```
levels/
```
- ```
common/
```
Setup Git: Create a comprehensive
```
.gitignore
```
.
Documentation: Create a
```
README.md
```
explaining the feature-based structure.

当需要“设置项目”或“启动新游戏”时：

初始化根目录：确保
```
project.godot
```
已存在。
创建核心文件夹：
- ```
entities/
```
- ```
ui/
```
- ```
levels/
```
- ```
common/
```
配置Git：创建全面的
```
.gitignore
```
文件。
文档编写：创建
```
README.md
```
，说明基于功能的项目结构。

Reference

参考资料

Official Docs:

tutorials/best_practices/project_organization.rst

Official Docs:

tutorials/best_practices/scene_organization.rst

官方文档：

tutorials/best_practices/project_organization.rst

官方文档：

tutorials/best_practices/scene_organization.rst

godot-project-foundations

Original

Translation

Project Foundations

项目基础

Available Scripts

可用脚本

project_bootstrapper.gd

project_bootstrapper.gd

scene_naming_validator.gd

scene_naming_validator.gd

dependency_auditor.gd

dependency_auditor.gd

feature_scaffolder.gd

feature_scaffolder.gd

NEVER Do in Project Organization

项目组织中的禁忌

1. Naming Conventions

1. 命名规范

2. Feature-Based Organization

2. 基于功能的组织方式

3. Version Control

3. 版本控制

Workflow: Scaffolding a New Project

工作流程：搭建新项目

Reference

参考资料

Related

相关内容