AgentSkillsCN

godot-project-foundations

针对 Godot 4 项目组织的专家级蓝图（基于功能的文件夹、命名规范、版本控制）。强制使用 snake_case 文件名、PascalCase 节点名称、%SceneUniqueNames，以及 .gitignore 最佳实践。在启动新项目，或重构项目结构时使用。关键词：project organization、命名规范、snake_case、PascalCase、feature-based、.gitignore、.gdignore。

SKILL.md
--- frontmatter
name: godot-project-foundations
description: "Expert blueprint for Godot 4 project organization (feature-based folders, naming conventions, version control). Enforces snake_case files, PascalCase nodes, %SceneUniqueNames, and .gitignore best practices. Use when starting new projects or refactoring structure. Keywords project organization, naming conventions, snake_case, PascalCase, feature-based, .gitignore, .gdignore."

Project Foundations

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

Available Scripts

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

project_bootstrapper.gd

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

scene_naming_validator.gd

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

dependency_auditor.gd

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

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.

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.

1. Naming Conventions

  • •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.

2. Feature-Based Organization

Instead of grouping by type (e.g., /scripts, /sprites), group by feature (the "What", not the "How").

Correct Structure:

code
/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

3. Version Control

  • •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).

Workflow: Scaffolding a New Project

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

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

Reference

  • •Official Docs: tutorials/best_practices/project_organization.rst
  • •Official Docs: tutorials/best_practices/scene_organization.rst

Related