# harmonyhoney/rota architecture

> Architecture diagram of the GitHub repository harmonyhoney/rota, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harmonyhoney/rota
- Repository: https://github.com/harmonyhoney/rota

## Overview

#### Purpose and Runtime
ROTA: Bend Gravity is a gravity-bending puzzle platformer built in Godot 3.6.1. It targets Linux, Windows, macOS, Web, and Android, with Steam distribution/integration. Godot project and export entry configuration are in `project.godot` and `export_presets.cfg`.

#### Application Entry and Global Services
Godot starts from the scene configured in `project.godot`; persistent cross-scene behavior is organized as autoload scene/scripts. These provide shared game state, UI, camera, audio/music, transitions, touch input, and cheat handling:
- `src/autoload/Shared.gd`
- `src/autoload/UI.gd`
- `src/autoload/Cam.gd`
- `src/autoload/Audio.gd`
- `src/autoload/Wipe.gd`

This is the principal boundary between level-local nodes and application-wide state/presentation services.

#### Game Flow: Menu, Save Slots, and Options
The menu subsystem owns boot/title flow, file selection/deletion/opening, pause state, attract/demo behavior, player makeover, and input/display/audio settings. Save-oriented data abstractions are centered on `src/class/SaveDict.gd`, while menu screens operate through:
- `src/menu/MenuBoot.gd`
- `src/menu/MenuTitle.gd`
- `src/menu/MenuFile.gd`
- `src/menu/MenuPause.gd`
- `src/menu/options/MenuOptions.gd`

Control transitions from menus into a selected game world/level; pause/options return control to the active play state.

#### World and Level Composition
Playable content is scene-driven. World directories contain hub scenes and numbered stages, allowing door-based navigation among a large campaign:
- `src/map/worlds/0/0_hub.tscn`
- `src/map/worlds/1/0_hub.tscn`
- `src/map/worlds/3B/8.tscn`

Levels compose reusable actors, environmental details, tile maps, and shaders. Collision/solid terrain and hazard layout are encapsulated in:
- `src/stage/SolidTileMap.gd`
- `src/stage/SpikeMap.gd`
- `src/stage/tileset/TileSet0.tres`

#### Core Puzzle Gameplay Actors
The player and interactive objects implement the gravity-platforming puzzle loop: movement/gravity control, pushable boxes, hazards, collectibles/goals, NPC guidance/chat, and doors. Door nodes form the main level/world transition boundary:
- `src/actor/Player.gd`
- `src/actor/Box.gd`
- `src/actor/Spike.gd`
- `src/actor/Goal.gd`
- `src/actor/door/Door.gd`

Cutscenes coordinate milestone effects such as game start, gem collection, door unlocks, and goal presentation rather than embedding those sequences in level scenes:
- `src/cutscene/Cutscene.gd`
- `src/cutscene/GemCollect.gd`
- `src/cutscene/DoorUnlock.gd`

#### Arcade Subgame Boundary
A distinct arcade subsystem has its own wrapper, player, game logic, cabinet/screen presentation, audio behavior, and map set. It is embedded into the broader game but maintains separate gameplay scenes:
- `src/arcade/Arcade.gd`
- `src/arcade/ArcadeGame.gd`
- `src/arcade/Wrapper.gd`
- `src/arcade/maps/0.tscn`

#### Rendering, Assets, and Platform Integrations
Godot scenes consume packaged sprites, audio, fonts, tile textures, and custom shaders from `media/` and `src/shader/`; audio buses are defined by `default_bus_layout.tres`. Steam is a native GDNative addon with macOS dynamic libraries and Steam-facing scripts:
- `addons/steam_api/plugin.gd`
- `addons/steam_api/steam.gd`
- `addons/steam_api/libsteamsdk-godot.dylib`

Distribution automation includes Godot and Flatpak GitHub workflows, Linux desktop/metainfo packaging, and platform export helper scripts:
- `.github/workflows/godot.yml`
- `.github/workflows/flatpak.yml`
- `linux/net.hhoney.rota.yml`

Main entry points: [`src/map/worlds/0/0_hub.tscn`](https://github.com/harmonyhoney/rota/blob/master4/src/map/worlds/0/0_hub.tscn) (Campaign worlds), [`project.godot`](https://github.com/harmonyhoney/rota/blob/master4/project.godot) (Godot project entry), [`src/menu/MenuBoot.gd`](https://github.com/harmonyhoney/rota/blob/master4/src/menu/MenuBoot.gd) (Menu flow), [`src/actor/door/Door.gd`](https://github.com/harmonyhoney/rota/blob/master4/src/actor/door/Door.gd) (Doors)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Godot Runtime"]
  node_project["Godot project entry<br/>project config<br/>[project.godot]"]
  node_shared["Shared state<br/>autoload<br/>[Shared.gd]"]
  node_ui["UI service<br/>autoload<br/>[UI.gd]"]
  node_camera["Camera service<br/>autoload<br/>[Cam.gd]"]
  node_audio["Audio service<br/>autoload<br/>[Audio.gd]"]
  node_wipe["Scene transitions<br/>autoload<br/>[Wipe.gd]"]
  node_assets["Media &amp; shaders<br/>packaged assets"]
end

subgraph group_flow["Menu &amp; Persistence"]
  node_save[("Save data<br/>save abstraction<br/>[SaveDict.gd]")]
  node_menus["Menu flow<br/>menu screens<br/>[MenuBoot.gd]"]
end

subgraph group_gameplay["World Gameplay"]
  node_worlds["Campaign worlds<br/>Godot scenes<br/>[0_hub.tscn]"]
  node_doors["Doors<br/>world transition actor<br/>[Door.gd]"]
  node_player["Player<br/>gameplay actor<br/>[Player.gd]"]
  node_puzzleactors["Puzzle actors<br/>gameplay actors<br/>[Box.gd]"]
  node_terrain["Terrain &amp; hazards<br/>stage composition<br/>[SolidTileMap.gd]"]
  node_cutscenes["Cutscene coordinator<br/>sequence system<br/>[Cutscene.gd]"]
end

subgraph group_arcade["Arcade Subgame"]
  node_arcadewrapper["Arcade wrapper<br/>embedded subsystem<br/>[Wrapper.gd]"]
  node_arcadegame["Arcade game<br/>separate gameplay loop<br/>[ArcadeGame.gd]"]
  node_arcademaps["Arcade maps<br/>Godot scenes<br/>[0.tscn]"]
end

subgraph group_delivery["Platform &amp; Delivery"]
  node_steam{{"Steam integration<br/>GDNative addon<br/>[plugin.gd]"}}
  node_exports["Build &amp; packaging<br/>CI and distribution<br/>[godot.yml]"]
end

node_project -->|"autoloads"| node_shared
node_project -->|"autoloads"| node_ui
node_project -->|"autoloads"| node_camera
node_project -->|"autoloads"| node_audio
node_project -->|"autoloads"| node_wipe
node_project -->|"starts flow"| node_menus
node_menus -->|"reads and updates"| node_save
node_menus -->|"loads selected play state"| node_worlds
node_worlds -->|"composes"| node_player
node_worlds -->|"composes"| node_puzzleactors
node_worlds -->|"composes"| node_terrain
node_worlds -->|"composes"| node_doors
node_player -->|"interacts with"| node_puzzleactors
node_doors -->|"loads destination"| node_worlds
node_puzzleactors -->|"triggers milestones"| node_cutscenes
node_doors -->|"triggers unlock sequence"| node_cutscenes
node_arcadewrapper -->|"hosts"| node_arcadegame
node_arcadegame -->|"loads"| node_arcademaps
node_worlds -->|"embeds"| node_arcadewrapper
node_shared -.->|"supplies state"| node_worlds
node_ui -.->|"presents"| node_menus
node_audio -.->|"provides audio"| node_arcadegame
node_assets -.->|"resources"| node_worlds
node_steam -.->|"platform integration"| node_project
node_exports -->|"builds and exports"| node_project

click node_project "https://github.com/harmonyhoney/rota/blob/master4/project.godot"
click node_shared "https://github.com/harmonyhoney/rota/blob/master4/src/autoload/Shared.gd"
click node_ui "https://github.com/harmonyhoney/rota/blob/master4/src/autoload/UI.gd"
click node_camera "https://github.com/harmonyhoney/rota/blob/master4/src/autoload/Cam.gd"
click node_audio "https://github.com/harmonyhoney/rota/blob/master4/src/autoload/Audio.gd"
click node_wipe "https://github.com/harmonyhoney/rota/blob/master4/src/autoload/Wipe.gd"
click node_save "https://github.com/harmonyhoney/rota/blob/master4/src/class/SaveDict.gd"
click node_menus "https://github.com/harmonyhoney/rota/blob/master4/src/menu/MenuBoot.gd"
click node_worlds "https://github.com/harmonyhoney/rota/blob/master4/src/map/worlds/0/0_hub.tscn"
click node_doors "https://github.com/harmonyhoney/rota/blob/master4/src/actor/door/Door.gd"
click node_player "https://github.com/harmonyhoney/rota/blob/master4/src/actor/Player.gd"
click node_puzzleactors "https://github.com/harmonyhoney/rota/blob/master4/src/actor/Box.gd"
click node_terrain "https://github.com/harmonyhoney/rota/blob/master4/src/stage/SolidTileMap.gd"
click node_cutscenes "https://github.com/harmonyhoney/rota/blob/master4/src/cutscene/Cutscene.gd"
click node_arcadewrapper "https://github.com/harmonyhoney/rota/blob/master4/src/arcade/Wrapper.gd"
click node_arcadegame "https://github.com/harmonyhoney/rota/blob/master4/src/arcade/ArcadeGame.gd"
click node_arcademaps "https://github.com/harmonyhoney/rota/blob/master4/src/arcade/maps/0.tscn"
click node_steam "https://github.com/harmonyhoney/rota/blob/master4/addons/steam_api/plugin.gd"
click node_exports "https://github.com/harmonyhoney/rota/blob/master4/.github/workflows/godot.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_project,node_shared,node_ui,node_camera,node_audio,node_wipe,node_assets toneBlue
class node_save,node_menus toneAmber
class node_worlds,node_doors,node_player,node_puzzleactors,node_terrain,node_cutscenes toneMint
class node_arcadewrapper,node_arcadegame,node_arcademaps toneRose
class node_steam,node_exports toneIndigo
```

## Components

### Godot Runtime

- [Godot project entry](https://github.com/harmonyhoney/rota/blob/master4/project.godot): project config · Defines startup scene, autoloads, and export targets. · `project.godot`
- [Shared state](https://github.com/harmonyhoney/rota/blob/master4/src/autoload/Shared.gd): autoload · Cross-scene game state service. · `src/autoload/Shared.gd`
- [UI service](https://github.com/harmonyhoney/rota/blob/master4/src/autoload/UI.gd): autoload · `src/autoload/UI.gd`
- [Camera service](https://github.com/harmonyhoney/rota/blob/master4/src/autoload/Cam.gd): autoload · `src/autoload/Cam.gd`
- [Audio service](https://github.com/harmonyhoney/rota/blob/master4/src/autoload/Audio.gd): autoload · `src/autoload/Audio.gd`
- [Scene transitions](https://github.com/harmonyhoney/rota/blob/master4/src/autoload/Wipe.gd): autoload · `src/autoload/Wipe.gd`
- **Media & shaders**: packaged assets · Sprites, audio, fonts, textures, and shaders.

### Menu & Persistence

- [Save data](https://github.com/harmonyhoney/rota/blob/master4/src/class/SaveDict.gd): save abstraction · `src/class/SaveDict.gd`
- [Menu flow](https://github.com/harmonyhoney/rota/blob/master4/src/menu/MenuBoot.gd): menu screens · Boot, title, file, pause, and options screens. · `src/menu/MenuBoot.gd`

### World Gameplay

- [Campaign worlds](https://github.com/harmonyhoney/rota/blob/master4/src/map/worlds/0/0_hub.tscn): Godot scenes · Hub-and-stage scene hierarchy. · `src/map/worlds/0/0_hub.tscn`
- [Doors](https://github.com/harmonyhoney/rota/blob/master4/src/actor/door/Door.gd): world transition actor · Moves players between levels and worlds. · `src/actor/door/Door.gd`
- [Player](https://github.com/harmonyhoney/rota/blob/master4/src/actor/Player.gd): gameplay actor · Movement and gravity-bending control. · `src/actor/Player.gd`
- [Puzzle actors](https://github.com/harmonyhoney/rota/blob/master4/src/actor/Box.gd): gameplay actors · Boxes, spikes, and goals define puzzle interactions. · `src/actor/Box.gd`
- [Terrain & hazards](https://github.com/harmonyhoney/rota/blob/master4/src/stage/SolidTileMap.gd): stage composition · Tile collision and spike layout. · `src/stage/SolidTileMap.gd`
- [Cutscene coordinator](https://github.com/harmonyhoney/rota/blob/master4/src/cutscene/Cutscene.gd): sequence system · Coordinates milestone presentations and unlock effects. · `src/cutscene/Cutscene.gd`

### Arcade Subgame

- [Arcade wrapper](https://github.com/harmonyhoney/rota/blob/master4/src/arcade/Wrapper.gd): embedded subsystem · Boundary between campaign and arcade mode. · `src/arcade/Wrapper.gd`
- [Arcade game](https://github.com/harmonyhoney/rota/blob/master4/src/arcade/ArcadeGame.gd): separate gameplay loop · `src/arcade/ArcadeGame.gd`
- [Arcade maps](https://github.com/harmonyhoney/rota/blob/master4/src/arcade/maps/0.tscn): Godot scenes · `src/arcade/maps/0.tscn`

### Platform & Delivery

- [Steam integration](https://github.com/harmonyhoney/rota/blob/master4/addons/steam_api/plugin.gd): GDNative addon · Native Steam API bridge and scripts. · `addons/steam_api/plugin.gd`
- [Build & packaging](https://github.com/harmonyhoney/rota/blob/master4/.github/workflows/godot.yml): CI and distribution · Godot exports plus Flatpak and Linux packaging. · `.github/workflows/godot.yml`

## Connections

- Godot project entry → Shared state: autoloads
- Godot project entry → UI service: autoloads
- Godot project entry → Camera service: autoloads
- Godot project entry → Audio service: autoloads
- Godot project entry → Scene transitions: autoloads
- Godot project entry → Menu flow: starts flow
- Menu flow → Save data: reads and updates
- Menu flow → Campaign worlds: loads selected play state
- Campaign worlds → Player: composes
- Campaign worlds → Puzzle actors: composes
- Campaign worlds → Terrain & hazards: composes
- Campaign worlds → Doors: composes
- Player → Puzzle actors: interacts with
- Doors → Campaign worlds: loads destination
- Puzzle actors → Cutscene coordinator: triggers milestones
- Doors → Cutscene coordinator: triggers unlock sequence
- Arcade wrapper → Arcade game: hosts
- Arcade game → Arcade maps: loads
- Campaign worlds → Arcade wrapper: embeds
- Shared state → Campaign worlds: supplies state
- UI service → Menu flow: presents
- Audio service → Arcade game: provides audio
- Media & shaders → Campaign worlds: resources
- Steam integration → Godot project entry: platform integration
- Build & packaging → Godot project entry: builds and exports