# Repository organization

## Maintained layout

| Path | Responsibility |
|---|---|
| `scenes/main.tscn` | Startup wrapper; configured as `run/main_scene` and hosts the Stickman Editor. |
| `scenes/editors/{stickman,prop,stage}/` | Feature editor scenes. |
| `scenes/stage/` | Sandbox Stage runtime scenes. |
| `scenes/characters/stickman/` | Stickman runtime rig scenes. |
| `scenes/tools/` | Test and physics harness scenes. |
| `scenes/legacy/` | Preserved legacy rig scenes. |
| `scripts/editors/{stickman,prop,stage}/` | Editor controllers and feature-specific editing systems. |
| `scripts/{stage,characters/stickman,props,terrain,speech}/` | Runtime and domain systems grouped by feature. |
| `scripts/shared/` | Reusable UI, thumbnail, and content-path utilities. |
| `scripts/tools/` | Harness and rig-authoring scripts. |
| `content/{stickmen,props,stages}/` | Project-managed `.stk`, `.prop`, and `.scene` libraries. |
| `resources/fonts/` | Project fonts. |
| `docs/{guides,architecture,specs,plans}/` | Maintained guides, architecture references, specifications, and active plans. |
| `docs/archive/` | Older project references and completed plan drafts. |

Scripts and scenes remain separate roots, with feature-specific editor code and scenes grouped by workflow. Godot `.gd.uid` files stay beside their scripts; scene resource UIDs are retained when scenes move.

## Content path compatibility

`ContentPaths` is implemented in `scripts/shared/content_paths.gd`. Its `canonicalize(path: String) -> String` helper maps project-relative legacy paths to the new library locations:

| Legacy project path | Canonical path |
|---|---|
| `res://stickmen/<file>.stk` | `res://content/stickmen/<file>.stk` |
| `res://props/<file>.prop` | `res://content/props/<file>.prop` |
| `res://game_scenes/<file>.scene` | `res://content/stages/<file>.scene` |

Equivalent project-relative inputs (for example, `stickmen/<file>.stk`) map to relative `content/...` paths, and absolute paths under the project root keep their absolute form while their legacy directory is rewritten. `user://` paths, unrelated relative paths, unknown project folders, and absolute paths outside the project are passed through unchanged. Keep path-bearing loads, saves, persisted references, recents, and recovery metadata routed through `canonicalize()` so existing project references continue to resolve after the move.

## Serialized file compatibility

The organization change moves libraries and code without changing the `.stk`, `.prop`, or `.scene` document schemas. It adds no serialized fields and requires no format-version bump. Existing field meanings and codec migrations remain authoritative:

| Format | Current codec version | Compatibility |
|---|---|---|
| `.stk` | `1.5` | The Stickman Editor accepts `1.0`–`1.4` files and migrates them on load. |
| `.prop` | `1.0` | `PropFile` accepts version `1.0`; missing supported optional fields use codec defaults. |
| `.scene` | `1.1` | `StageSceneIO` accepts `1.0` and migrates it to `1.1` on load. |

When a stage is loaded or saved, its document path and path-valued asset references are canonicalized. A legacy reference such as `res://stickmen/basic.stk` may therefore be serialized as `res://content/stickmen/basic.stk` on the next save. This changes the stored path value only: the `.scene` field structure and version remain unchanged, with no added keys.