How jakubmularczyk/projekt_symulacja_miasto works
1. Project type and runtime
- This is a C++ console simulation of a medieval city, built around a turn-based engine.
- The repository is organized as a classic layered OO application: core simulation, domain entities, managers/services, factories, random events, and tests.
- Build system is CMake (CMakeLists.txt, CMakeSettings.json), suggesting a native desktop/server-style executable rather than a web or mobile app.
2. Top-level architecture
- The main runtime path is: main.cpp → Engine → City and subsystem managers.
- The simulation state is split into three main domains:
- Population: citizens and their professions
- Buildings: infrastructure that affects productivity/security
- Resources: food, gold, wood, stone, and likely derived city stats such as health/security
- This separation makes the code diagram friendly: the engine orchestrates, while managers mutate domain state.
3. Core simulation loop
- The README describes a fixed turn sequence:
1. start new turn
2. each resident acts
3. buildings modify citizen efficiency
4. food is consumed
5. a random event may occur
6. health/hunger/security are updated
7. collapse conditions are checked
8. a turn report is displayed
- Architecturally, the engine is the workflow coordinator, while the actual logic is delegated to managers and event objects.
4. City as the central state aggregate
- City is the main shared state object (src/core/City.*), likely holding the current resource pool, population, buildings, and status counters.
- The city appears to be the boundary object between all systems: managers and events operate on it, and the engine reads from it for reports and end-state checks.
- The collapse rules in the README are city-level constraints:
- food ≤ 0 for 3 turns
- gold ≤ 0 for 3 turns
- security ≤ 0 for 3 turns
- That implies the city tracks per-resource failure counters in addition to raw values.
5. Population subsystem
- The population model is centered on an abstract/base Citizen class with concrete professions:
- Farmer, Guard, Merchant, Woodcutter, Stonecutter
- PopulationManager likely owns or coordinates the citizen list, triggering each citizen’s turn action and applying city/building effects.
- PopulationFactory creates profession-specific citizens, which keeps creation logic out of the engine and supports extension with new roles.
6. Building subsystem
- Buildings are modeled with a base Building class and concrete types such as:
- Farm, Barracks, Marketplace, Quarry, Sawmill
- BuildingManager likely stores constructed buildings and applies their modifiers each turn.
- BuildingFactory is the creation boundary for building objects, matching the same extensibility pattern used for population.
- The presence of both resource-producing and modifier-style buildings suggests the buildings influence either production rates, security, or trade efficiency.
7. Resource subsystem
- ResourceManager and Resources represent the economic state of the city.
- Based on the README and class names, resources are probably the shared quantitative layer for:
- food
- gold
- wood
- stone
- possibly derived values such as health/security or reserve counters
- This subsystem is important because it is the common output/input boundary for both population actions and events.
8. Random event subsystem
- Random events are modeled as a base RandomEvent with concrete event types:
- BanditAttackEvent
- DroughtEvent
- FireEvent
- PlagueEvent
- RiotsEvent
- NoEvent
- RandomEventManager likely selects one event per turn and applies it to the city state.
- This is a clear plug-in style boundary: events encapsulate transient external shocks without hard-coding them into the engine.
9. Data flow between subsystems
- The main data flow is:
- Engine advances the turn
- PopulationManager invokes individual citizen actions
- BuildingManager applies infrastructure effects
- ResourceManager updates consumables and production outcomes
- RandomEventManager injects stochastic disruptions
- City consolidates the results and checks survival rules
- This is a mostly top-down orchestration with shared mutable city state model, not an event bus or actor system.
10. Extensibility pattern
- The README explicitly says the system is “very easy to extend” through abstract classes.
- The repo structure confirms that pattern:
- abstract base types in src/Include
- concrete implementations in src/population, src/buildings, src/events
- factories to decouple construction
- For an architecture diagram, this means the main extension points are new citizen types, new building types, and new random events.
11. Testing boundary
- The tests/ folder contains unit tests for:
- citizens
- city
- events
- population manager
- resource manager
- This suggests the domain logic is designed to be testable in isolation, especially around turn effects and failure conditions.
- Tests likely validate the simulation rules rather than UI behavior, since no UI layer appears in the tree.
12. Repository organization
- Headers are centralized under src/Include, while implementations are grouped by domain:
- src/core
- src/population
- src/buildings
- src/events
- src/factories
- src/managers
- That layout reflects the architecture itself: interface/contracts separated from concrete behavior.
- config.txt likely stores initial simulation parameters, matching the README’s note that the user provides starting values before the simulation begins.
Main entry points: RandomEventManager.cpp EventMgr · Engine.cpp Engine · PopulationFactory.cpp PopulationFactory · BuildingFactory.cpp BuildingFactory
Components 34
Core runtime
Entry point, engine, and shared city state
- main.cpp · Starts the simulation executable
src/main.cpp - Engine · Runs the turn loop and orchestrates subsystem updates
src/core/Engine.cpp - City · Central simulation state for population, buildings, resources, and collapse rules
src/core/City.cpp - Logger · Shared logging/reporting support
src/Include/Logger.h
Population
Citizens and population management
- PopulationMgr · Coordinates resident actions and population-wide updates
src/managers/PopulationManager.cpp - Citizen · Abstract citizen behavior shared by all professions
src/population/Citizen.cpp - Farmer · Produces food through population actions
src/population/Farmer.cpp - Guard · Supports city security
src/population/Guard.cpp - Merchant · Contributes to gold and trade flow
src/population/Merchant.cpp - Woodcutter · Produces wood
src/population/Woodcutter.cpp - Stonecutter · Produces stone
src/population/Stonecutter.cpp
Buildings
Infrastructure and building management
- BuildingMgr · Stores buildings and applies infrastructure effects
src/managers/BuildingManager.cpp - Building · Abstract building behavior and shared modifiers
src/buildings/Building.cpp - Farm · Improves food production
src/buildings/Farm.cpp - Barracks · Improves defense and security
src/buildings/Barracks.cpp - Marketplace · Improves economic efficiency
src/buildings/Marketplace.cpp - Quarry · Supports stone production
src/buildings/Quarry.cpp - Sawmill · Supports wood production
src/buildings/Sawmill.cpp
Resources
Economic state and resource updates
- ResourceMgr · Updates resources, consumption, and derived city stats
src/managers/ResourceManager.cpp - Resources · Food, gold, wood, stone, and related city quantities
src/Include/Resources.h
Events
Random event selection and effects
- EventMgr · Selects and applies a random event each turn
src/managers/RandomEventManager.cpp - RandomEvent · Abstract event interface for transient disruptions
src/events/RandomEvent.cpp - Bandits · Threatens gold and security
src/events/BanditAttackEvent.cpp - Drought · Reduces food availability
src/events/DroughtEvent.cpp - Fire · Damages city resources or structures
src/events/FireEvent.cpp - Plague · Harms population health
src/events/PlagueEvent.cpp - Riots · Destabilizes the city
src/events/RiotsEvent.cpp - NoEvent · Represents a calm turn without disruption
src/events/NoEvent.cpp
Factories
Object creation boundaries
- PopulationFactory · Builds profession-specific citizens
src/factories/PopulationFactory.cpp - BuildingFactory · Builds concrete building types
src/factories/BuildingFactory.cpp
Tests
Unit tests for simulation rules
- City tests · Validates city state and collapse rules
tests/CityTest.cpp - Citizen tests · Validates citizen behavior
tests/CitizenTest.cpp - Event tests · Validates event effects and selection
tests/EventsTest.cpp - Population tests · Validates population manager turn logic
tests/PopulationManagerTest.cpp
Connections 33
- main.cpp → Engine: starts · Executable hands control to the turn engine
- Engine → City: owns state · Engine advances and inspects the shared city aggregate
- Engine → PopulationMgr: turn step · Runs resident actions each turn
- Engine → BuildingMgr: turn step · Applies infrastructure effects during the turn
- Engine → ResourceMgr: turn step · Updates consumption and resource outcomes
- Engine → EventMgr: turn step · Selects and applies a random event
- Engine → Logger: reports · Produces turn output and status messages
- PopulationMgr → Citizen: uses base · Coordinates the shared citizen abstraction
- PopulationMgr → PopulationFactory: creates · Requests profession-specific citizens
- PopulationFactory → Farmer: instantiates · Creates farmer citizens
- PopulationFactory → Guard: instantiates · Creates guard citizens
- PopulationFactory → Merchant: instantiates · Creates merchant citizens
- PopulationFactory → Woodcutter: instantiates · Creates woodcutter citizens
- PopulationFactory → Stonecutter: instantiates · Creates stonecutter citizens
- BuildingMgr → Building: uses base · Coordinates the shared building abstraction
- BuildingMgr → BuildingFactory: creates · Requests concrete buildings
- BuildingFactory → Farm: instantiates · Creates farm buildings
- BuildingFactory → Barracks: instantiates · Creates barracks buildings
- BuildingFactory → Marketplace: instantiates · Creates marketplace buildings
- BuildingFactory → Quarry: instantiates · Creates quarry buildings
- BuildingFactory → Sawmill: instantiates · Creates sawmill buildings
- ResourceMgr → Resources: updates · Mutates city resources and derived counters
- EventMgr → RandomEvent: uses base · Selects from the event hierarchy
- EventMgr → Bandits: chooses · Can apply a bandit attack
- EventMgr → Drought: chooses · Can apply drought effects
- EventMgr → Fire: chooses · Can apply fire effects
- EventMgr → Plague: chooses · Can apply plague effects
- EventMgr → Riots: chooses · Can apply riots effects
- EventMgr → NoEvent: chooses · Can resolve to no event
- City tests → City: covers · Checks city rules and collapse conditions
- Citizen tests → Citizen: covers · Checks citizen behavior
- Event tests → EventMgr: covers · Checks event selection and effects
- Population tests → PopulationMgr: covers · Checks turn logic and resident actions