How d1nary/city_sim works
1. This is a native C++ simulation project built with CMake. The source tree is organized as a small engine plus game/domain layer, and the build artifacts show a compiled executable named city_sim. The repository also vendors GLFW through CMake’s _deps, so there is at least a window/input layer dependency for the desktop runtime.
2. The highest-level runtime entry point is src/main.cpp, which likely boots core::Application. application appears to own the main loop and coordinate the major subsystems rather than letting them talk to each other directly.
3. The core subsystem is the cross-cutting foundation. time suggests simulation timing or fixed-step update support, while config.hpp likely centralizes tunable constants. This is the layer other systems should depend on, not the reverse.
4. The world model lives under src/world and is split into World, Grid, and Tile. That indicates a tile/grid-based simulation space where World owns the map state, Grid provides spatial indexing or layout, and Tile is the atomic cell used by rendering, pathing, or placement logic.
5. Entities are managed separately from the world geometry in src/entities. Entity is the base abstraction, Npc is a concrete simulated actor, and EntityManager owns lifecycle and update iteration. This is the main gameplay-state boundary for movable agents.
6. Behavior is factored out into src/behaviors via an IBehavior interface and concrete WanderBehavior and WorkBehavior implementations. This suggests a behavior-driven NPC system where entities delegate decision-making to interchangeable behaviors instead of hard-coding logic into Npc.
7. Buildings are another domain subsystem under src/buildings. Building is the shared base, House is a concrete building type, and BuildingManager owns placement or lifecycle management. This is likely tied to the world grid and to NPC behavior, especially the work/home relationship.
8. The renderer is isolated in src/renderer and contains renderer, camera, and DebugUI. This implies a dedicated visualization layer with a movable view and an overlay for inspecting simulation state. The renderer probably consumes world/entity/building state but does not own it.
9. The main data flow is probably: application initializes core timing, world, managers, and renderer; the simulation updates entities and buildings against the world grid; then the renderer reads the resulting state each frame and draws it through the camera. The debug UI sits alongside rendering as an inspection/control layer.
10. The main architectural boundary is between simulation state and presentation. World/entities/buildings/behaviors are the model and update logic; renderer/camera/DebugUI are the view and diagnostics. That separation is what to preserve in an architecture diagram.
11. From the file naming, this looks like an object-oriented, single-process desktop simulation rather than a client-server or data-pipeline system. The important external dependency is GLFW for windowing/input; everything else appears to be internal C++ modules built into one executable.
Main entry points: application.cpp Application · renderer.cpp Renderer · BuildingManager.cpp BuildingManager · world.cpp World
Components 20
Runtime
Program entry and orchestration
- main · Program startup and handoff to the application
src/main.cpp - Application · Owns initialization and the main loop
src/core/application.cpp
Core
Shared simulation foundation
Simulation
World state and gameplay logic
- World · Owns the overall map and simulation space
src/world/world.cpp - Grid · Tile layout and spatial indexing
src/world/grid.cpp - Tile · Atomic world cell used by simulation logic
src/world/tile.hpp - EntityManager · Owns entity update and lifetime management
src/entities/EntityManager.cpp - Entity · Shared abstraction for simulated actors
src/entities/entity.cpp - Npc · Concrete simulated character
src/entities/npc.cpp - IBehavior · Pluggable decision-making contract
src/behaviors/IBehavior.hpp - Wander · Idle or roaming NPC behavior
src/behaviors/WanderBehavior.cpp - Work · Task-oriented NPC behavior
src/behaviors/WorkBehavior.cpp - BuildingManager · Owns building placement and update flow
src/buildings/BuildingManager.cpp - Building · Shared abstraction for constructed structures
src/buildings/building.cpp - House · Concrete residential building
src/buildings/house.cpp
Presentation
Rendering and diagnostics
External
Third-party runtime dependency
- GLFW · External desktop windowing and input dependency
build/_deps/glfw-build/src/glfw3Config.cmake
Connections 25
- main → Application: starts · Main hands control to application startup
- Application → Time: ticks · Application drives simulation timing
- Application → World: owns · Application coordinates world state
- Application → EntityManager: updates · Application advances entity manager each frame
- Application → BuildingManager: updates · Application advances building manager each frame
- Application → Renderer: drives · Application triggers rendering after simulation update
- Application → Config: reads · Application uses shared configuration
- Application → GLFW: uses · Desktop runtime depends on GLFW for windowing and input
- World → Grid: contains · World owns spatial layout
- Grid → Tile: stores · Grid is composed of tiles
- EntityManager → Entity: manages · Manager owns entity lifecycle
- Entity → Npc: specializes · NPC is a concrete entity type
- Npc → IBehavior: delegates · NPC behavior is driven through the interface
- IBehavior → Wander: implements · Wander behavior is one implementation
- IBehavior → Work: implements · Work behavior is one implementation
- BuildingManager → Building: manages · Manager owns building lifecycle
- Building → House: specializes · House is a concrete building type
- Renderer → Camera: uses · Renderer uses camera for framing
- Renderer → DebugUI: overlays · Debug UI is shown alongside rendering
- Renderer → World: reads · Renderer consumes world state
- Renderer → EntityManager: reads · Renderer consumes entity state
- Renderer → BuildingManager: reads · Renderer consumes building state
- BuildingManager → World: places in · Buildings are positioned against world grid
- EntityManager → World: operates in · Entities update within the world context
- Npc → BuildingManager: interacts with · NPC behavior may depend on buildings such as homes or work sites