Godot Project Foundations

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

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. For new foundations projects: Project Settings → Debug → GDScript → Untyped Declaration = Warn or Error.

Expert Foundation Architectures

Scene transitions

MANDATORY load `async_resource_loader.gd` — threaded ResourceLoader with progress. Do not paste SceneManager samples here.

Global Event Bus

MANDATORY load `global_event_bus.gd` for typed global signals. Do not paste EventBus samples here.

Project Metadata

Use `build_metadata_provider.gd` / `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.

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 — Feature-based folders, .gdignore, and VCS hygiene that keep imports and repos maintainable.
• Scene organization — Ownership boundaries and why %SceneUniqueNames beat brittle get_node() paths.
• GDScript style guide — Canonical snake_case files / PascalCase nodes / past-tense signals used by this skill’s validators.
• GDScript warning system — Enforce typed declarations (Untyped Declaration → Warn/Error) when migrating foundations to GDScript 2.0.
• Singletons (Autoload) — How to register lean global services that survive scene changes.
• Autoloads versus regular nodes — When a Managed Autoload / EventBus is justified vs scene-local ownership.
• Background loading — ResourceLoader.load_threaded_* patterns for non-blocking scene transitions.
• Resources — Shared vs duplicated Resource instances and why global mutation breaks feature modules.