How matthew12045/grow-a-garden works
1. Repository shape and runtime split
- This is a C++17/SFML 3.x game with a clear separation between simulation logic and presentation/UI.
- The runtime entry point is src/main.cpp, which feeds into either the title flow (src/title/) or the gameplay flow (src/game/ + src/core/ + src/world/).
2. Two major app states: title screen vs gameplay
- src/title/ contains the standalone title/credits experience (TitleScreenApp, TitleScreen, CreditsScreen, Button).
- src/game/ contains the actual farming game screen and overlays (GameScreen, InventoryOverlay, ShopOverlay).
- This split matters architecturally: the title screen is not just a menu widget; it is a separate application state with its own UI and navigation path into gameplay.
3. Core simulation loop
- src/core/ holds the central game state and tick orchestration: Game, Player, and TickSystem.
- Game is the hub that ties together the world, inventory/shop systems, UI, audio, and save/session state.
- TickSystem drives time-based progression for crop growth, weather timing, and offline-fast-forward behavior after loading saves.
4. World model and spatial ownership
- src/world/ models the garden as a fixed grid of Cell objects inside Garden.
- The garden is a small board (README says 5x4), and each cell can own at most one plant.
- Cell uses std::unique_ptr<Plant> ownership, which is an important boundary: plants live inside the world grid and are not shared objects.
5. Plant and mutation domain
- src/entities/ contains the crop runtime objects: Plant, Mutation, and HarvestedItem.
- Plant is the main mutable state machine for crop growth, harvestability, and regrowth behavior.
- Mutations are part of the plant domain rather than the UI or inventory domain; weather and events alter plant state, and sale value is derived from that state.
6. Items, tools, and polymorphic behavior
- src/items/ defines the item hierarchy: Item as the abstract base, with Seed, Tool, and tool subclasses like WateringCan and FertilizerTool.
- This is one of the main object-oriented seams in the project: inventory, shop, and gameplay all work through item polymorphism and cloning/value semantics.
- Tools have durability and effect-specific behavior, while seeds are consumed into plants when planted.
7. Inventory, shop, and the economy loop
- src/systems/Inventory, Shop, and src/game/ShopData.h implement the economy boundary.
- The player loop is: buy seeds/tools, plant, grow, harvest, store in basket, sell for sheckles, reinvest.
- Inventory is map-based for item counts, while harvested crops are handled separately via the harvest basket before sale.
8. Weather and random events as world modifiers
- src/world/WeatherSystem changes over time and affects growth and mutation outcomes.
- src/systems/RandomEventManager and RaccoonEvent provide the random-event layer that can disrupt the garden.
- Architecturally, weather is a deterministic time-based world system, while random events are a separate event pipeline that can mutate or remove plant state.
9. UI, rendering, and audio
- src/ui/ contains cross-cutting presentation services: UIManager, DrawUtils, and AudioManager.
- Rendering is split between game-specific render helpers like CropRenderer and general UI overlays.
- Audio is handled centrally rather than inside gameplay objects, which keeps music/FX decisions out of simulation classes and makes weather-appropriate background music a UI-layer concern.
10. Session persistence and offline progress
- src/game/SessionManager is the save/load boundary, backed by nlohmann/json.
- The saved state includes player currency, inventory, plants, mutations, tick count, initialization state, timestamp, and harvest basket.
- On load, the session manager and tick logic cooperate to compute offline progress from the saved timestamp and advance the simulation accordingly.
11. Data flow through the game
- Input starts in SFML window/UI handlers, passes through title/game screens, and ends up as actions on Game, Player, Inventory, Garden, or Shop.
- Simulation updates flow outward from TickSystem into Plant, WeatherSystem, and random events, then back into the UI through rendered state and overlays.
- This creates a clean “input → state mutation → render/audio output” loop with persistence sitting beside the core state rather than inside the UI.
12. Testing and integration boundaries
- tests/ is extensive and maps closely to the architecture: cells/garden, events, inventory/shop, items, mutations, plant logic, tools/factory, UI/audio, weather, and integration coverage.
- The presence of tests for core classes suggests the repo intentionally keeps the simulation layer testable without launching the SFML game window.
- tests/helpers/ConcreteClasses.h also implies the project uses helper concrete implementations to exercise abstract item/event behavior.
13. Build, assets, and operational concerns
- The project is built with CMake and targets Windows/Linux.
- Static assets are organized separately under assets/ for textures, audio, and fonts, and runtime behavior depends on relative asset paths from the project root.
- docs/class_diagram.puml is the primary design reference for class relationships, while GitHub Actions CI enforces the build/test pipeline.
Main entry points: Game.h Game · GameScreen.h Game Screen · SessionManager.h Session · Plant.h Plant
Components 34
Runtime
Application entry and top-level state routing
- Main · Launches the application and selects the top-level flow
src/main.cpp
Presentation
Title flow, game screens, rendering, and audio
- Title App · Owns the title-screen application flow and navigation
src/title/TitleScreenApp.h - Title Screen · Primary title screen and navigation surface
src/title/TitleScreen.h - Credits · Credits view within the title experience
src/title/CreditsScreen.h - Button · Reusable title-screen interaction control
src/title/Button.h - Game Screen · Main gameplay presentation and screen orchestration
src/game/GameScreen.h - Inventory UI · Gameplay overlay for inventory actions and counts
src/game/InventoryOverlay.h - Shop UI · Gameplay overlay for buying and selling goods
src/game/ShopOverlay.h - Crop Renderer · Draws plants and crop visual state
src/game/CropRenderer.h - UI Manager · Coordinates shared UI behavior and overlay presentation
src/ui/UIManager.h - Audio · Centralized music and sound playback
src/ui/AudioManager.h
Simulation
Core state, world model, plants, items, and systems
- Game · Central gameplay hub connecting state, systems, and persistence
src/core/Game.h - Player · Player currency and progression state
src/core/Player.h - Tick System · Advances simulation time, growth, weather, and offline progress
src/core/TickSystem.h - Garden · Fixed grid of cells that owns the garden layout
src/world/Garden.h - Cell · Single garden slot with unique plant ownership
src/world/Cell.h - Weather · Time-based weather changes that affect growth and mutations
src/world/WeatherSystem.h - Plant · Mutable crop lifecycle, harvestability, and regrowth
src/entities/Plant.h - Mutation · Plant mutation state and value-affecting modifiers
src/entities/Mutation.h - Harvested Item · Harvest result used before sale or storage
src/entities/HarvestedItem.h - Item · Polymorphic base for seeds and tools
src/items/Item.h - Seed · Plantable item converted into crops
src/items/Seed.h - Tool · Base class for farm tools with durability and effects
src/items/Tool.h - Watering Can · Watering tool used to influence crop growth
src/items/WateringCan.h - Fertilizer · Growth or yield modifying tool
src/items/FertilizerTool.h - Shovel · Digging or removal tool for the garden
src/items/ShovelTool.h - Inventory · Map-based item counts and ownership tracking
src/systems/Inventory.h - Shop · Buying and selling rules for the farm economy
src/systems/Shop.h - Events · Random event pipeline that can disrupt the garden
src/systems/RandomEventManager.h - Raccoon Event · Concrete disruptive event implementation
src/systems/RaccoonEvent.h - Session · Save and load boundary with offline progress support
src/game/SessionManager.h - Plant Factory · Builds plant instances from gameplay data
src/game/PlantFactory.h - Shop Data · Static shop configuration used by gameplay
src/game/ShopData.h - Basket · Intermediate storage for harvested crops before sale
src/game/HarvestBasket.h
Connections 43
- Main → Title App: starts · Launch path into the title flow
- Main → Game: starts · Launch path into the gameplay flow
- Title App → Title Screen: hosts · Title app presents the main title screen
- Title Screen → Credits: navigates · Title flow can open the credits screen
- Title Screen → Button: uses · Title UI is built from button controls
- Game → Player: owns · Game hub owns player progression state
- Game → Tick System: drives · Game hub advances simulation through ticks
- Game → Garden: contains · Gameplay operates on the garden world
- Game → Inventory: tracks · Game keeps item ownership and counts
- Game → Shop: economy · Game routes buy/sell interactions through shop logic
- Game → Session: persists · Save/load boundary for gameplay state
- Game → UI Manager: coordinates · Game uses shared UI coordination services
- Game → Audio: plays · Game routes music and sound through central audio
- Game Screen → Game: binds to · Main gameplay screen reflects core game state
- Game Screen → Crop Renderer: renders · Gameplay screen delegates crop drawing
- Game Screen → Inventory UI: shows · Gameplay screen presents inventory overlay
- Game Screen → Shop UI: shows · Gameplay screen presents shop overlay
- Game Screen → UI Manager: uses · Gameplay screen uses shared UI services
- Game Screen → Audio: uses · Gameplay screen triggers centralized audio
- Garden → Cell: contains · Garden is composed of owned cells
- Cell → Plant: owns · Each cell uniquely owns at most one plant
- Plant → Mutation: modifies · Plant state incorporates mutation effects
- Plant → Harvested Item: produces · Harvesting yields a crop product
- Tick System → Plant: advances · Tick updates growth and harvest state
- Tick System → Weather: updates · Tick progression drives weather changes
- Tick System → Events: triggers · Time progression can invoke random events
- Weather → Plant: affects · Weather influences growth and mutation outcomes
- Events → Raccoon Event: includes · Event manager runs concrete event types
- Inventory → Item: stores · Inventory tracks polymorphic item counts
- Seed → Item: inherits · Seeds are one item specialization
- Tool → Item: inherits · Tools are one item specialization
- Watering Can → Tool: inherits · Watering can extends tool behavior
- Fertilizer → Tool: inherits · Fertilizer extends tool behavior
- Shovel → Tool: inherits · Shovel extends tool behavior
- Shop → Shop Data: configures · Shop logic is driven by static data
- Shop → Item: trades · Shop buys and sells item instances
- Session → Player: saves · Player state is serialized for sessions
- Session → Inventory: saves · Inventory is persisted across sessions
- Session → Garden: saves · Garden and plant state are persisted
- Session → Tick System: restores · Load time is used to compute offline progress
- Session → Basket: saves · Harvest basket is part of session state
- Plant Factory → Plant: creates · Factory constructs plant instances from data
- Basket → Harvested Item: holds · Basket stores harvested crop items temporarily