chore: added structure markdown
This commit is contained in:
134
PROJECT_STRUCTURE.md
Normal file
134
PROJECT_STRUCTURE.md
Normal file
@@ -0,0 +1,134 @@
|
|||||||
|
# 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
|
||||||
|
|
||||||
|
1. Create a new folder under `Experiments/YourExperimentName/`
|
||||||
|
2. Add the standard subfolders: `Scenes/`, `Scripts/`, `Assets/`
|
||||||
|
3. Add a `UI/` folder if the experiment needs one
|
||||||
|
4. Add an entry in `main.tscn` to open it
|
||||||
|
5. 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 release
|
||||||
|
- `sonar.yml` — code quality analysis
|
||||||
|
|
||||||
|
Web export output is in `dist/` and should be in `.gitignore` if you do not want to commit build artifacts.
|
||||||
Reference in New Issue
Block a user