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, namin

Project Foundations Feature based organization, consistent naming, and version control hygiene define professional Godot projects. Available Scripts Core Scaffolding (Stateful / Persistent) [project bootstrapper.gd](scripts/project bootstrapper.gd) : Auto generates feature folders and .gitignore. [runtime configurator.gd](scripts/runtime configurator.gd) : Applies high performance profiles and saves override.cfg . [managed autoload.gd](scripts/managed autoload.gd) : Advanced Singleton pattern with RefCounted delegation. [global event bus.gd](scripts/global event bus.gd) : MANDATORY for decoupled global signals — do not re inline EventBus samples in chat. [node pooling system.gd](scripts/node pooling system.gd) : Thread safe Object Pool for high frequency scene instantiation. [async resource loader.gd](scripts/async resource loader.gd) : MANDATORY for threaded scene transitions — do not re inline SceneManager samples. Runtime Utilities (Stateless / Lightweight) [base data resource.gd](scripts/base data resource.gd) : Reactive Resource foundation using emit changed() . [advanced telemetry logger.gd](scripts/advanced telemetry logger.gd) : Custom OS level Logger for crash reporting. [threaded task worker.gd](scripts/threaded task worker.gd) : Robust WorkerThreadPool implementation. [action buffer input.gd](scripts/action buffer input.gd) : Foundational unhandled input buffer. [build metadata provider.gd](scripts/build metadata provider.gd) : Native extraction of version and build metadata. [feature scaffolder.gd](scripts/feature scaffolder.gd) / [scene naming validator.gd](scripts/scene naming validator.gd) : Feature folder + naming gates. Do NOT Load dependency auditor.gd unless troubleshooting loading errors. NEVER Do (Expert Anti Patterns) Global Architecture NEVER group by file type — /scripts , /sprites folders. Nightmare maintainability. Use feature based: /player , /ui . NEVER mix snake case and PascalCase in files — Standard: snake case for files, PascalCase for nodes. NEVER use hardcoded get node() paths — Brittle on reparenting. Use %SceneUniqueNames for stable references. NEVER use monolithic Autoloads — Avoid managers that hold visual node references; keep singletons focused on pure data or RefCounted delegation. Resource Management NEVER forget .gitignore — Committing .godot/ folder = 100MB+ bloat + conflicts. NEVER skip .gdignore for raw assets — Design source files ( .psd , .blend ) in root will be imported unless ignored. NEVER modify globally shared Resources directly — Strictly call duplicate(true) for unique instances with independent state. Performance & Threading NEVER block the main thread with load() — Strictly use ResourceLoader.load threaded request() for async scene transitions. NEVER modify the SceneTree from a background thread — Strictly use call deferred() for thread to main thread synchronization. NEVER skip Mutex locking during pooled access — Strictly ensure thread safety when using a shared WorkerThreadPool or Object Pool. NEVER use process() for precise input — Tied to visual framerate. Strictly use unhandled input() to capture exact, frame independent events. Ownership decision tree Need Prefer Avoid Everything for one feature (player, HUD panel) Feature folder scene module Type folders ( /scripts , /sprites ) Cross scene service with lifecycle (save, audio bus) Autoload via managed autoload.gd Stuffing UI nodes into singletons Many publishers/subscribers, no ownership EventBus → MANDATORY global event bus.gd Autoload that imports half the game One scene's private wiring Scene local node + %UniqueName Global bus for parent→child calls 1. Naming Conventions Files & Folders : snake case (C exception: PascalCase class match). Node Names : PascalCase . Exports : snake case ; Inspector Title Cases them. Private : leading on members and virtuals ( ready , process ). Signals : past tense snake case ( health changed ). Unique Names : %SceneUniqueNames over brittle get node() paths. 2. Feature Based Organization Group by feature ( /entities/player , /ui/main menu ), not by file type. Keep /common , /levels , /addons . 3. Version Control Godot aware .gitignore (ignore .godot/ ) + .gdignore on raw design sources. Workflow: Scaffolding a New Project 1. Ensure project.godot exists → run project bootstrapper.gd / create entities/ , ui/ , levels/ , common/ . 2. Setup Git .gitignore + document feature based layout in README.md . 3. Register lean Autoloads only after the ownership decision tree says so. Typed GDScript strictness (foundations only) Full typed GDScript migration lives in [godot gdscript mastery](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot gdscript mastery/SKILL.md). For new foundations projects: Project Settings → Debug → GDScript → Untyped Declaration = Warn or Error . Expert Foundation Architectures Scene transitions MANDATORY load [ async resource loader.gd ](scripts/async resource loader.gd) — threaded ResourceLoader with progress. Do not paste SceneManager samples here. Global Event Bus MANDATORY load [ global event bus.gd ](scripts/global event bus.gd) for typed global signals. Do not paste EventBus samples here. Project Metadata Use [ build metadata provider.gd ](scripts/build metadata provider.gd) / [ base data resource.gd ](scripts/base data resource.gd) for version/build flags instead of ad hoc JSON. Deep dive (load on demand) Full naming table, typed GDScript migration, EventBus/SceneManager/metadata samples — [references/foundations deep.md](references/foundations deep.md). Reference Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice. Official Documentation [Project organization](https://docs.godotengine.org/en/stable/tutorials/best practices/project organization.html) — Feature based folders, .gdignore , and VCS hygiene that keep imports and repos maintainable. [Scene organization](https://docs.godotengine.org/en/stable/tutorials/best practices/scene organization.html) — Ownership boundaries and why %SceneUniqueNames beat brittle get node() paths. [GDScript style guide](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/gdscript styleguide.html) — Canonical snake case files / PascalCase nodes / past tense signals used by this skill’s validators. [GDScript warning system](https://docs.godotengine.org/en/stable/tutorials/scripting/gdscript/warning system.html) — Enforce typed declarations ( Untyped Declaration → Warn/Error) when migrating foundations to GDScript 2.0. [Singletons (Autoload)](https://docs.godotengine.org/en/stable/tutorials/scripting/singletons autoload.html) — How to register lean global services that survive scene changes. [Autoloads versus regular nodes](https://docs.godotengine.org/en/stable/tutorials/best practices/autoloads versus regular nodes.html) — When a Managed Autoload / EventBus is justified vs scene local ownership. [Background loading](https://docs.godotengine.org/en/stable/tutorials/io/background loading.html) — ResourceLoader.load threaded patterns for non blocking scene transitions. [Resources](https://docs.godotengine.org/en/stable/tutorials/scripting/resources.html) — Shared vs duplicated Resource instances and why global mutation breaks feature modules. [Nodes and scene instances](https://docs.godotengine.org/en/stable/tutorials/scripting/nodes and scene instances.html) — Instantiation, pooling, and scene as module boundaries for feature folders. [Using SceneTree](https://docs.godotengine.org/en/stable/tutorials/scripting/scene tree.html) — Tree lifetime, deferred calls, and thread→main synchronization rules. [File paths in Godot projects](https://docs.godotengine.org/en/stable/tutorials/io/data paths.html) — res:// / user:// conventions for scaffolded folders and saved override.cfg / metadata. [ProjectSettings](https://docs.godotengine.org/en/stable/classes/class projectsettings.html) — Runtime profiles, version strings, and settings keys used by configurators and build metadata. Related Skills Prerequisites [godot gdscript mastery](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot gdscript mastery/SKILL.md) — Typed GDScript, style, and warning system fluency before enforcing naming and scaffold conventions. Complements [godot version migration](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot version migration/SKILL.md) — When opening or scaffolding a project on an older engine version, hop to the library target before enforcing current foundations. [godot autoload architecture](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot autoload architecture/SKILL.md) — Boot order and ownership rules for Managed Autoload / EventBus singletons registered from a clean project root. [godot composition](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot composition/SKILL.md) — Feature folders become composable scene modules; parents wire children instead of growing monolithic managers. [godot resource data patterns](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot resource data patterns/SKILL.md) — Extends BaseDataResource style reactive Resources into full data driven catalogs without shared mutation. [godot signal architecture](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot signal architecture/SKILL.md) — Typed EventBus signals and connect lifetime once Autoloads and scene ownership are in place. [godot scene management](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot scene management/SKILL.md) — Threaded loaders and scene swaps build on this skill’s async ResourceLoader boilerplate. [godot input handling](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot input handling/SKILL.md) — Deepens unhandled input buffering into full action maps and device routing. Downstream / consumers [godot export builds](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot export builds/SKILL.md) — Export presets and feature tags assume a clean folder layout, .gitignore , and build metadata hooks. [godot testing patterns](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot testing patterns/SKILL.md) — Feature based scenes and deterministic Autoloads make unit/integration harnesses easier to mount. [godot debugging profiling](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot debugging profiling/SKILL.md) — Custom Logger telemetry and dependency audits feed editor time diagnostics once structure is stable. [godot performance optimization](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot performance optimization/SKILL.md) — Node pools, WorkerThreadPool, and runtime profiles escalate here when foundations hit CPU/memory ceilings. Master [godot master](https://github.com/thedivergentai/gd agentic skills/blob/main/skills/godot master/SKILL.md) — Library router and mirrored module entry; open when discovering which Domain Skill owns a cross cutting architecture concern.

godot-project-foundations