PROJECT_STRUCTURE.md

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