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