# mechanicalflower/marble architecture

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

- Interactive diagram: https://gitdiagram.com/mechanicalflower/marble
- Repository: https://github.com/mechanicalflower/marble

## Overview

##### Overall Project Type and Purpose
- This project is a Godot mini-game focused on marble racing. It is a standalone game with both gameplay logic (e.g., race logic, explosion mode, ranking) and build/distribution pipelines.
- Its purpose is to provide an engaging marble race experience with procedural races, different race modes, and real-time ranking, while supporting multiple distribution formats (e.g., Snap, AppImage, native binaries).

##### Break Down the Main Components
– Game Engine:
- Godot Engine as the core runtime environment. This is external but central to the functioning of the game.
– Scenes and Assets:
- “scenes” directory: Contains different game scenes – main scene, race, GUI (menu, countdown, overlay), camera setups, and specialized block scenes (race track components).
- “assets” directory: Stores 3D models for blocks, textures, fonts, sounds, etc. It feeds the visual and audio elements of the game.
- “resources”: Assets that define default settings such as environmental and material resources.
– Scripts and Logic:
- “scripts” directory: Contains the GDScript files divided into subfolders – blocks, camera, GUI, constants, framework, and utilities. Each group represents a functional aspect of the game (e.g., handling marble movement, camera control, collision settings, UI transitions).
– Addons and Plugins:
- “addons” directory: Includes extensions like “gd-plug” and “export-build-info” which provide additional functionality or integration hooks for the Godot project.
– Packaging and Deployment:
- “public/packaging”: Contains build recipes for AppImage, Snap, Flatpak, etc., pointing to the project’s multi-platform deployment method.
– Development Tools and Configuration:
- Configuration files for .git, .env, pre-commit hooks, just command recipes, and CI/CD workflows in “.github/workflows” show the integration of development practices and automation (build, linting, packaging).

##### Relationships and Interactions
- Scenes & Assets: Illustrate that these scenes make use of assets and resources.
- Scripts: Show directional dependency from scenes to scripts, with scripts managing the game logic (e.g., race management, marble behavior, and UI controls). Indicate sub-modules for camera controllers, UI interactions, and game constants.
- Addons/Plugins: Connect to the Godot Engine, indicating that they extend functionality (e.g., exporting build info, managing plugins).
- Packaging: Connect outward from the core game to external packaging/deployment components (AppImage, Snap, Flatpak) and CI/CD pipelines (GitHub workflows).
- For example, from “assets” and “resources” to “scenes”, and from “scenes” interacting with “scripts” for game logic.
- That packaging workflows (in “public/packaging”) take the core game build and wrap it for distribution.

##### Architectural Patterns
– Modular Scene Composition:
- Use labels to show that game scenes are composed of various subcomponents (blocks, camera, GUI).
– Separation of Concerns:
- Separate directories for assets, logic (scripts), and configuration/addons. This mirrors a modular design approach where presentation, game logic, and development tools are decoupled.
– Integration of Development Tools:
- Use of “just” for command automation and pre-commit hooks for quality assurance, indicating a CI/CD mindset.
– Noting Godot’s Scene System:
- A note that the scene tree hierarchy (from “scenes/”) is central to the project’s runtime structure within the Godot engine.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Godot Engine"]:::engine
    C["Assets"]:::asset
    D["Resources"]:::resource
    B["Scenes"]:::scene
    E["Scripts and Logic"]:::script
    E1["Blocks"]:::scriptSub
    E2["Camera"]:::scriptSub
    E3["Constants"]:::scriptSub
    E4["Framework"]:::scriptSub
    E5["GUI"]:::scriptSub
    E6["Utilities"]:::scriptSub
    F["Addons/Plugins"]:::addon
    G["Packaging/Deployment"]:::packaging
    H["Development Tools & Config"]:::devtools
    H1["CI/CD Workflows"]:::devtoolsSub
    H2["Justfile"]:::devtoolsSub
    H3["Pre-commit Hooks"]:::devtoolsSub
    H4["Env & Git Config"]:::devtoolsSub

    %% Relationships
    %% Assets and Resources feed into Scenes
    C -->|"feeds"| B
    D -->|"provides"| B

    %% Scenes trigger game logic in Scripts
    B -->|"triggers"| E

    %% Scripts sub-components
    E --> E1
    E --> E2
    E --> E3
    E --> E4
    E --> E5
    E --> E6

    %% Scripts control core game behavior
    E -->|"controls"| A

    %% Addons extend the Godot Engine functionality
    F -->|"extends"| A

    %% Packaging receives built game from Godot Engine
    A -->|"builds for"| G

    %% Development tools support packaging & build pipeline
    H -->|"automates"| G

    %% Position Development Tools separately connected to core as well
    H -->|"supports"| A

    %% Styles
    classDef engine fill:#AEDFF7,stroke:#0078D7,stroke-width:2px
    classDef scene fill:#FFF9B1,stroke:#E1C699,stroke-width:2px
    classDef asset fill:#C7E9FF,stroke:#2B8CBE,stroke-width:2px
    classDef resource fill:#D2E9B7,stroke:#7FBF7F,stroke-width:2px
    classDef script fill:#B4EEB4,stroke:#3CB371,stroke-width:2px
    classDef scriptSub fill:#E5F5E0,stroke:#74C476,stroke-width:1px
    classDef addon fill:#E7CAF1,stroke:#D291BC,stroke-width:2px
    classDef packaging fill:#C1DFF0,stroke:#8FB3D2,stroke-width:2px
    classDef devtools fill:#F4E1A1,stroke:#D4AA00,stroke-width:2px
    classDef devtoolsSub fill:#FDEBD0,stroke:#F5B041,stroke-width:1px

    %% Click Events
    click A "https://github.com/mechanicalflower/marble/blob/main/project.godot"
    click B "https://github.com/mechanicalflower/marble/tree/main/scenes/"
    click C "https://github.com/mechanicalflower/marble/tree/main/assets/"
    click D "https://github.com/mechanicalflower/marble/tree/main/resources/"
    click E "https://github.com/mechanicalflower/marble/tree/main/scripts/"
    click E1 "https://github.com/mechanicalflower/marble/tree/main/scripts/blocks"
    click E2 "https://github.com/mechanicalflower/marble/tree/main/scripts/camera"
    click E3 "https://github.com/mechanicalflower/marble/tree/main/scripts/constants"
    click E4 "https://github.com/mechanicalflower/marble/tree/main/scripts/framework"
    click E5 "https://github.com/mechanicalflower/marble/tree/main/scripts/gui"
    click E6 "https://github.com/mechanicalflower/marble/tree/main/scripts/utilities"
    click F "https://github.com/mechanicalflower/marble/tree/main/addons/"
    click G "https://github.com/mechanicalflower/marble/tree/main/public/packaging/"
    click H1 "https://github.com/mechanicalflower/marble/tree/main/.github/workflows/"
    click H2 "https://github.com/mechanicalflower/marble/tree/main/Justfile"
    click H3 "https://github.com/mechanicalflower/marble/blob/main/.pre-commit-config.yaml"
    click H4 "https://github.com/mechanicalflower/marble/blob/main/.env"
```
