# victor-wybenga/culminating-game architecture

> Architecture diagram of the GitHub repository victor-wybenga/culminating-game, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/victor-wybenga/culminating-game
- Repository: https://github.com/victor-wybenga/culminating-game

## Overview

1. This is a Godot 2D factory-puzzle game. The repository is organized around three main layers: data assets in `Resources/`, reusable scene prefabs in `Scenes/`, and gameplay logic in `Scripts/`. That separation is the key to the architecture.

2. The game is heavily data-driven. `Resources/Items`, `Resources/Recipes`, `Resources/Machines`, and `Resources/Tiles` contain `.tres` definitions for all craftables, machine types, floor tiles, and recipe variants. These are the authoritative game definitions; the scenes and scripts appear to consume them rather than hardcoding content.

3. There are generic resource templates in `Resources/Templates` for core object types such as assembler, belt, power source, and recipe. This suggests a composition pattern: specific content like “Smelter” or “coalGen” is built from shared resource schemas, not bespoke logic per item.

4. The scene hierarchy is split between world content and menus. `Scenes/Levels/*` contains individual level scenes, while `Scenes/machines/`, `Scenes/placeables/`, and top-level scenes like `belt.tscn`, `goalpost.tscn`, `miner.tscn`, `recipeMenu.tscn`, and `ui.tscn` provide reusable in-game objects and interface panels. `main.tscn`, `main_menu.tscn`, `level_selector.tscn`, and `end_screen.tscn` handle the meta flow.

5. Core simulation logic lives in a small set of controllers. `mapController.gd`, `buildingManager.gd`, `beltController.gd`, `powerManager.gd`, and `machines.gd` likely coordinate placement, grid occupancy, item movement, power distribution, and machine behavior. These are the backbone systems that other entities plug into.

6. Item transport is modeled separately from machines. `beltItem.gd`, `beltController.gd`, `Scenes/placeables/belt.tscn`, and `Scenes/spliter.tscn` indicate a conveyor network where items are entities moving along belts and through splitters. This is a distinct data flow from machine processing: output items leave machines, enter belts, then get routed to other inputs or goals.

7. Production buildings are specialized but probably share common interfaces. `miner.gd`, `generators.gd`, `powerPoles.gd`, and the machine scenes for assembler, smelter, and coal generator imply multiple machine categories: extractors, processors, and power infrastructure. The README confirms the intended progression from simple miners/smelters to more complex fluid- and byproduct-based machines.

8. Power is a separate network subsystem rather than just another item chain. The presence of `powerManager.gd`, `powerPoles.gd`, `GenericPowerSource.tres`, and `coalGen.tres` suggests a graph or coverage model where generators feed consumers through poles. The README also frames power as a bottleneck that becomes more complex in later tiers.

9. Level objectives are explicit gameplay nodes. `goalpost.gd`, `Scenes/goalpost.tscn`, and the README’s “submit a certain amount of items/power” mechanic indicate that levels end by delivering required outputs to a goal structure. `level_1.tscn` through `level_5.tscn` and the “level selector” scene show a progression-based campaign structure.

10. The UI layer handles selection, recipes, and configuration. `recipeSelectorMenu.gd`, `make_panel_buttons.gd`, `make_level_buttons.gd`, `ui_button.gd`, `rotate_button.gd`, `options_page.gd`, and `ui.tscn` support in-game build menus, level selection, and settings. The README’s planned glossary/recipe book fits this same interface layer.

11. The player is a placement-and-management actor rather than a combat unit. `player.gd` and the build-related scenes suggest a character that moves around, places machines, and interacts with menus. This means the main loop is about layout optimization and routing, not action gameplay.

12. The repository also includes content-production assets: `Assets/2d Assets/*` for sprites and animations, plus `buildings and recipes.pdf` as design reference material. Those files are support artifacts for the game’s content pipeline, not runtime systems.

13. Architecturally, the important boundaries are: content definitions in `.tres` resources, scene prefabs in `.tscn`, and runtime orchestration in `.gd` scripts. If you draw the system, the data flows should show resources feeding scenes, scenes instantiating world objects, and controllers moving items/power between machines and level goals.

Main entry points: [`Scenes`](https://github.com/victor-wybenga/culminating-game/tree/main/Scenes) (World prefabs), [`Scenes/Levels`](https://github.com/victor-wybenga/culminating-game/tree/main/Scenes/Levels) (Levels), [`Resources/Templates`](https://github.com/victor-wybenga/culminating-game/tree/main/Resources/Templates) (Templates), [`Scripts/buildingManager.gd`](https://github.com/victor-wybenga/culminating-game/blob/main/Scripts/buildingManager.gd) (Building manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_resources["Resources"]
  node_resources_items["Items<br/>tres catalog"]
  node_resources_recipes["Recipes<br/>tres catalog"]
  node_resources_machines["Machines<br/>tres catalog"]
  node_resources_tiles["Tiles<br/>tres catalog"]
  node_resources_templates["Templates<br/>tres schema"]
end

subgraph group_scenes["Scenes"]
  node_scenes_levels["Levels<br/>scene set"]
  node_scenes_world["World prefabs<br/>scene prefabs"]
  node_scenes_ui["UI scenes<br/>interface scenes<br/>[ui.tscn]"]
  node_scenes_flow["Meta flow<br/>menu scenes<br/>[main.tscn]"]
end

subgraph group_scripts["Scripts"]
  node_scripts_resources["Resource types<br/>gdscript classes"]
  node_scripts_map["Map control<br/>world controller<br/>[mapController.gd]"]
  node_scripts_building["Building manager<br/>placement controller<br/>[buildingManager.gd]"]
  node_scripts_belts["Belt system<br/>transport controller<br/>[beltController.gd]"]
  node_scripts_power["Power grid<br/>network controller<br/>[powerManager.gd]"]
  node_scripts_machines["Machine logic<br/>production logic<br/>[machines.gd]"]
  node_scripts_goal["Goal post<br/>objective logic<br/>[goalpost.gd]"]
  node_scripts_player["Player<br/>interaction actor<br/>[player.gd]"]
  node_scripts_ui["UI logic<br/>interface logic"]
end

node_resources_templates -->|"schema"| node_resources_machines
node_resources_templates -->|"schema"| node_resources_recipes
node_resources_items -->|"inputs/outputs"| node_resources_recipes
node_resources_machines -->|"instantiate"| node_scenes_world
node_resources_tiles -->|"terrain"| node_scenes_levels
node_resources_items -->|"display"| node_scenes_ui
node_scripts_map -->|"supports"| node_scripts_building
node_scripts_building -->|"places"| node_scenes_world
node_scripts_belts -->|"drives"| node_scenes_world
node_scripts_machines -->|"controls"| node_scenes_world
node_scripts_power -->|"powers"| node_scenes_world
node_scripts_goal -->|"objective"| node_scenes_levels
node_scripts_player -->|"places"| node_scripts_building
node_scripts_ui -->|"drives"| node_scenes_ui
node_scripts_ui -->|"navigates"| node_scenes_flow
node_scenes_flow -->|"enters"| node_scenes_levels
node_scenes_levels -->|"contains"| node_scenes_world
node_scenes_world -->|"uses"| node_scripts_belts
node_scenes_world -->|"uses"| node_scripts_power
node_scenes_world -->|"uses"| node_scripts_machines
node_scenes_world -->|"uses"| node_scripts_goal
node_scenes_world -->|"interacts"| node_scripts_player
node_scripts_resources -->|"defines"| node_resources_templates

click node_resources_items "https://github.com/victor-wybenga/culminating-game/tree/main/Resources/Items"
click node_resources_recipes "https://github.com/victor-wybenga/culminating-game/tree/main/Resources/Recipes"
click node_resources_machines "https://github.com/victor-wybenga/culminating-game/tree/main/Resources/Machines"
click node_resources_tiles "https://github.com/victor-wybenga/culminating-game/tree/main/Resources/Tiles"
click node_resources_templates "https://github.com/victor-wybenga/culminating-game/tree/main/Resources/Templates"
click node_scenes_levels "https://github.com/victor-wybenga/culminating-game/tree/main/Scenes/Levels"
click node_scenes_world "https://github.com/victor-wybenga/culminating-game/tree/main/Scenes"
click node_scenes_ui "https://github.com/victor-wybenga/culminating-game/blob/main/Scenes/ui.tscn"
click node_scenes_flow "https://github.com/victor-wybenga/culminating-game/blob/main/Scenes/main.tscn"
click node_scripts_resources "https://github.com/victor-wybenga/culminating-game/tree/main/Scripts/Resourse"
click node_scripts_map "https://github.com/victor-wybenga/culminating-game/blob/main/Scripts/mapController.gd"
click node_scripts_building "https://github.com/victor-wybenga/culminating-game/blob/main/Scripts/buildingManager.gd"
click node_scripts_belts "https://github.com/victor-wybenga/culminating-game/blob/main/Scripts/beltController.gd"
click node_scripts_power "https://github.com/victor-wybenga/culminating-game/blob/main/Scripts/powerManager.gd"
click node_scripts_machines "https://github.com/victor-wybenga/culminating-game/blob/main/Scripts/machines.gd"
click node_scripts_goal "https://github.com/victor-wybenga/culminating-game/blob/main/Scripts/goalpost.gd"
click node_scripts_player "https://github.com/victor-wybenga/culminating-game/blob/main/Scripts/player.gd"
click node_scripts_ui "https://github.com/victor-wybenga/culminating-game/blob/main/Scripts/recipeSelectorMenu.gd"

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_resources_items,node_resources_recipes,node_resources_machines,node_resources_tiles,node_resources_templates toneBlue
class node_scenes_levels,node_scenes_world,node_scenes_ui,node_scenes_flow toneAmber
class node_scripts_resources,node_scripts_map,node_scripts_building,node_scripts_belts,node_scripts_power,node_scripts_machines,node_scripts_goal,node_scripts_player,node_scripts_ui toneMint
```

## Components

### Resources

Authoritative game data: items, recipes, machines, tiles, and templates.

- [Items](https://github.com/victor-wybenga/culminating-game/tree/main/Resources/Items): tres catalog · Tiered item definitions used by crafting, logistics, and objectives. · `Resources/Items`
- [Recipes](https://github.com/victor-wybenga/culminating-game/tree/main/Resources/Recipes): tres catalog · Crafting and processing recipes, including builder variants. · `Resources/Recipes`
- [Machines](https://github.com/victor-wybenga/culminating-game/tree/main/Resources/Machines): tres catalog · Machine definitions for assemblers, smelters, and power generation. · `Resources/Machines`
- [Tiles](https://github.com/victor-wybenga/culminating-game/tree/main/Resources/Tiles): tres catalog · Tile and floor definitions for map terrain. · `Resources/Tiles`
- [Templates](https://github.com/victor-wybenga/culminating-game/tree/main/Resources/Templates): tres schema · Generic resource templates that standardize core object types. · `Resources/Templates`

### Scenes

Reusable prefabs, levels, and menu scenes.

- [Levels](https://github.com/victor-wybenga/culminating-game/tree/main/Scenes/Levels): scene set · Campaign level scenes and level-specific backgrounds. · `Scenes/Levels`
- [World prefabs](https://github.com/victor-wybenga/culminating-game/tree/main/Scenes): scene prefabs · Reusable in-world objects such as belts, machines, miners, poles, and goals. · `Scenes`
- [UI scenes](https://github.com/victor-wybenga/culminating-game/blob/main/Scenes/ui.tscn): interface scenes · Menus and interface panels for recipes, options, buttons, and HUD. · `Scenes/ui.tscn`
- [Meta flow](https://github.com/victor-wybenga/culminating-game/blob/main/Scenes/main.tscn): menu scenes · Main menu, level selector, and end screen scenes. · `Scenes/main.tscn`

### Scripts

Runtime controllers, resource types, and gameplay logic.

- [Resource types](https://github.com/victor-wybenga/culminating-game/tree/main/Scripts/Resourse): gdscript classes · Custom resource classes for items, machines, recipes, and tiles. · `Scripts/Resourse`
- [Map control](https://github.com/victor-wybenga/culminating-game/blob/main/Scripts/mapController.gd): world controller · Grid, placement, and occupancy management for the playable map. · `Scripts/mapController.gd`
- [Building manager](https://github.com/victor-wybenga/culminating-game/blob/main/Scripts/buildingManager.gd): placement controller · Coordinates building placement, rotation, and structure ownership. · `Scripts/buildingManager.gd`
- [Belt system](https://github.com/victor-wybenga/culminating-game/blob/main/Scripts/beltController.gd): transport controller · Conveyor logic and moving item entities on belts and splitters. · `Scripts/beltController.gd`
- [Power grid](https://github.com/victor-wybenga/culminating-game/blob/main/Scripts/powerManager.gd): network controller · Power distribution and generator/consumer coordination. · `Scripts/powerManager.gd`
- [Machine logic](https://github.com/victor-wybenga/culminating-game/blob/main/Scripts/machines.gd): production logic · Behavior for assemblers, smelters, miners, and generators. · `Scripts/machines.gd`
- [Goal post](https://github.com/victor-wybenga/culminating-game/blob/main/Scripts/goalpost.gd): objective logic · End-condition handling for item and power submission goals. · `Scripts/goalpost.gd`
- [Player](https://github.com/victor-wybenga/culminating-game/blob/main/Scripts/player.gd): interaction actor · Movement and placement-facing player controller. · `Scripts/player.gd`
- [UI logic](https://github.com/victor-wybenga/culminating-game/blob/main/Scripts/recipeSelectorMenu.gd): interface logic · Recipe menus, level buttons, options, and general UI wiring. · `Scripts/recipeSelectorMenu.gd`

## Connections

- Templates → Machines: schema · Machine definitions are composed from generic machine templates.
- Templates → Recipes: schema · Recipes reuse generic recipe templates and builder variants.
- Items → Recipes: inputs/outputs · Recipes consume and produce item definitions.
- Machines → World prefabs: instantiate · Machine scenes are built from machine resource definitions.
- Tiles → Levels: terrain · Level scenes use tile definitions for map layout.
- Items → UI scenes: display · UI panels present item and recipe data to the player.
- Map control → Building manager: supports · Placement logic depends on map/grid state.
- Building manager → World prefabs: places · Building manager spawns and positions world prefabs.
- Belt system → World prefabs: drives · Belt controller powers transport scenes and moving items.
- Machine logic → World prefabs: controls · Machine logic runs attached world machine scenes.
- Power grid → World prefabs: powers · Power manager coordinates generators, poles, and consumers.
- Goal post → Levels: objective · Goal logic determines level completion conditions.
- Player → Building manager: places · Player interacts with building placement and rotation.
- UI logic → UI scenes: drives · UI logic populates and reacts to interface scenes.
- UI logic → Meta flow: navigates · Menu scripts handle level selection and screen flow.
- Meta flow → Levels: enters · Meta flow leads into campaign levels.
- Levels → World prefabs: contains · Levels embed reusable world prefabs and objectives.
- World prefabs → Belt system: uses · Belt-related scenes rely on transport controller behavior.
- World prefabs → Power grid: uses · Power infrastructure scenes rely on the power network controller.
- World prefabs → Machine logic: uses · Machine and miner scenes rely on production logic.
- World prefabs → Goal post: uses · Goal post scene relies on objective logic.
- World prefabs → Player: interacts · Player can place and manage world objects.
- Resource types → Templates: defines · Custom resource classes define the template-backed data model.