How mechanicalflower/marble works
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.