5.2 KiB
5.2 KiB
Godot Experiments - Project Structure
Overview
One Godot project containing multiple self-contained experiments.
Each experiment lives in its own folder under Experiments/ with its own scenes, scripts, assets and UI.
Shared code and assets used across experiments live in Core/.
Folder Tree
res://
│
├── main.tscn # Project entry point / experiment selector
├── project.godot
│
├── Core/ # Shared across ALL experiments
│ ├── Components/
│ │ ├── back_to_main.gd # Navigation: return to main menu
│ │ ├── open_level_component.gd # Navigation: open a level
│ │ └── quit_game_component.gd # Navigation: quit game
│ └── Assets/
│ └── PixelPlanets/ # Shared planet sprites/textures
│
├── Experiments/
│ │
│ ├── Recuration/ # Top-down space game with solar system generation
│ │ ├── Scenes/
│ │ │ ├── Recuration.tscn # Main scene
│ │ │ ├── SolarSystem.tscn # Solar system root node
│ │ │ ├── Planet.tscn # Reusable planet scene
│ │ │ └── Star.tscn # Star scene
│ │ ├── Scripts/
│ │ │ ├── recuration_camera.gd # Top-down pan + zoom camera
│ │ │ ├── resource_component.gd # Planet resource data
│ │ │ └── solar_system_generator.gd # Procedural system generation
│ │ ├── UI/
│ │ │ ├── UI.tscn # HUD root
│ │ │ ├── ui.gd # HUD logic
│ │ │ └── planet_info_panel.tscn # Click-to-inspect planet panel
│ │ ├── Assets/
│ │ │ └── TheMoon/
│ │ │ ├── TheMoon.tscn
│ │ │ └── TheMoon.gd
│ │ └── Planning/
│ │ └── Movement 2D.svg # Design / planning diagrams
│ │
│ ├── SpaceMove/ # 2D space movement experiment
│ │ ├── Scenes/
│ │ │ ├── space_move.tscn
│ │ │ └── space_test.tscn
│ │ ├── Scripts/
│ │ │ ├── player_ship.gd
│ │ │ └── ship_ai_component.gd
│ │ └── Assets/
│ │ └── player_ship.tscn
│ │
│ ├── ThrusterCube/ # Physics thruster experiment
│ │ ├── Scenes/
│ │ │ ├── thruster_cube.tscn
│ │ │ ├── thruster_cube_collision.tscn
│ │ │ └── obstacle.tscn
│ │ ├── Scripts/
│ │ │ └── thruster_cube.gd
│ │ └── Assets/
│ │ ├── Thruster Cube.glb
│ │ └── Thruster Cube Collision.glb
│ │
│ └── PidTest/ # PID controller experiment
│ ├── Scenes/
│ │ └── pid_test.tscn
│ ├── Scripts/
│ │ └── pid_test.gd
│ └── Assets/
│ ├── PID_Spinning_Stuff.glb
│ ├── PID_Spinning_Target.glb
│ └── PID_Test_Obj.blend
│
└── dist/ # Web export output (auto-generated, do not edit)
Rules
1. Each experiment is self-contained
All scenes, scripts, assets and UI for an experiment live inside its own folder. Deleting an experiment folder should not break anything else.
2. Core is for shared things only
Only put something in Core/ if two or more experiments use it.
When in doubt, keep it inside the experiment.
3. Move files inside Godot, not in Explorer
Always use Godot's FileSystem panel to move files. This keeps UID references intact and prevents broken scene paths.
4. Naming conventions
| Type | Convention | Example |
|---|---|---|
| Folders | PascalCase |
Recuration/, ThrusterCube/ |
| Scenes | snake_case.tscn |
solar_system.tscn |
| Scripts | snake_case.gd |
recuration_camera.gd |
| Classes | PascalCase |
class_name RecurationCamera |
| Variables | snake_case |
var orbit_radius: float |
| Constants | SCREAMING_SNAKE_CASE |
const AU_TO_PIXELS := 100.0 |
| Signals | snake_case |
signal planet_clicked(planet: Planet) |
Adding a New Experiment
- Create a new folder under
Experiments/YourExperimentName/ - Add the standard subfolders:
Scenes/,Scripts/,Assets/ - Add a
UI/folder if the experiment needs one - Add an entry in
main.tscnto open it - Only move shared code to
Core/once a second experiment needs it
Gitea CI
CI workflows live in .gitea/workflows/:
release.yml— builds and publishes a releasesonar.yml— code quality analysis
Web export output is in dist/ and should be in .gitignore if you do not want to commit build artifacts.