# magotoolivesource/winwpi_framework architecture

> Architecture diagram of the GitHub repository magotoolivesource/winwpi_framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/magotoolivesource/winwpi_framework
- Repository: https://github.com/magotoolivesource/winwpi_framework

## Overview

#### Purpose and Deliverables
A native Windows 2D game framework built on WinAPI and GDI+, plus a Plants-vs.-Zombies-style sample game (“PVSZ”). The solution is `FrameWork_2DAPI.sln`; framework and game are separate Visual C++ projects: `FrameWork_2DAPI/FrameWork_2DAPI.vcxproj` and `PVSZ/PVSZ.vcxproj`.

#### Application Entry and Runtime Loop
Each executable is a WinAPI desktop application, with likely entry sources `FrameWork_2DAPI/FrameWork_2DAPI.cpp` and `PVSZ/PVSZ.cpp`. `BaseGame` owns the current scene, input, timer, GDI+ lifecycle, update, and rendering loop. Windows messages are translated into input state before per-frame simulation and draw.
- `FrameWork_2DAPI/BaseGame.h`
- `FrameWork_2DAPI/BaseGame.cpp`
- `PVSZ/InGame_PVSZ.h`

#### Entity-Component Scene Model
`Scene` owns `GameObject` instances; each object owns type-indexed component instances and always exposes a `Transform`. Scene lifecycle propagates `Start`, `Update(dt)`, and `Render(HDC)` to objects, then components. This is the central boundary between game-specific composition and framework execution.
- `FrameWork_2DAPI/Scene/Scene.h`
- `FrameWork_2DAPI/Core/GameObject.h`
- `FrameWork_2DAPI/Compoment/Component.h`

#### Spatial, Rendering, and Asset Pipeline
`Transform` provides local/world position, rotation, scale, parent-child hierarchy, cached matrices, and depth. Renderable components draw through WinAPI device contexts using GDI+ images; camera and viewport transform/cull world content. `ImageManager` caches loaded `Gdiplus::Image` assets, sourced from each project’s `Assets/Images`.
- `FrameWork_2DAPI/Compoment/Transform.h`
- `FrameWork_2DAPI/Compoment/ImageComponent.h`
- `FrameWork_2DAPI/Manager/ImageManager.h`
- `FrameWork_2DAPI/Compoment/Camera.h`

#### Input, Time, Physics, and Debug Services
`InputManager` receives keyboard/mouse messages and exposes frame-readable state. `TimerManager` supplies delta and total time. Collider and rigidbody components are coordinated by collision/physics managers; debug-object facilities provide visual diagnostics. These are framework-wide services, largely singleton-style through `SingletonT`.
- `FrameWork_2DAPI/Core/InputManager.h`
- `FrameWork_2DAPI/Core/TimerManager.h`
- `FrameWork_2DAPI/Manager/CollisionManager.h`
- `FrameWork_2DAPI/Manager/PhysicsManager.h`

#### UI Boundary
UI is implemented as components sharing the same object/transform lifecycle. Buttons query input and execute callbacks; text, rich text, and input fields render via GDI+ and manage presentation/input state. Game UI composes these primitives for plant selection and top panels.
- `FrameWork_2DAPI/UICompoment/Button.h`
- `FrameWork_2DAPI/UICompoment/RichTextAndInputFieldComponent.h`
- `PVSZ/UI_TopSelectPanelCom.h`

#### PVSZ Gameplay Layer
PVSZ specializes the framework with a stage-driven game loop: `Stage01` defines the level, `StageWaveManager` consumes wave data, and `ZombieFactoryManager` creates actors. Plants, zombies, peas, suns, movement, and actor state are components/actors orchestrated through game data and pooling. Object pooling separates frequent projectile/effect lifecycle from scene allocation.
- `PVSZ/Stage01.h`
- `PVSZ/StageWaveManager.h`
- `PVSZ/ZombieFactoryManager.h`
- `PVSZ/ObjectPoolManager.h`
- `PVSZ/Actor_State_Com.h`

#### External Platform Dependencies
Primary runtime dependencies are Windows/WinAPI (`HDC`, window messages, resources) and GDI+ (`Gdiplus::Image`, matrices, fonts, drawing). No networked services or external backend are indicated. Asset delivery is filesystem-based under framework and PVSZ asset directories.
- `FrameWork_2DAPI/framework.h`
- `FrameWork_2DAPI/FrameWork_2DAPI.rc`
- `PVSZ/PVSZ.rc`

Main entry points: [`PVSZ/InGame_PVSZ.h`](https://github.com/magotoolivesource/winwpi_framework/blob/main/PVSZ/InGame_PVSZ.h) (PVSZ game scene), [`FrameWork_2DAPI/BaseGame.cpp`](https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/BaseGame.cpp) (BaseGame runtime loop), [`FrameWork_2DAPI/Compoment/Camera.h`](https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/Compoment/Camera.h) (Camera & image rendering), [`FrameWork_2DAPI/Core/GameObject.h`](https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/Core/GameObject.h) (GameObject)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_framework["2D Framework"]
  node_framework_entry["Framework executable<br/>WinAPI entry"]
  node_base_game["BaseGame runtime loop<br/>game loop<br/>[BaseGame.cpp]"]
  node_scene["Scene<br/>[Scene.h]"]
  node_game_object["GameObject<br/>entity<br/>[GameObject.h]"]
  node_component["Component model<br/>ECS component<br/>[Component.h]"]
  node_transform["Transform<br/>spatial component<br/>[Transform.h]"]
  node_rendering["Camera &amp; image rendering<br/>render components<br/>[Camera.h]"]
  node_image_manager[("ImageManager<br/>asset cache<br/>[ImageManager.h]")]
  node_runtime_services["Input, time &amp; physics<br/>singleton services<br/>[InputManager.h]"]
  node_ui["UI components<br/>UI layer<br/>[Button.h]"]
end

subgraph group_game["PVSZ Game"]
  node_pvsz_entry["PVSZ executable<br/>WinAPI entry<br/>[PVSZ.cpp]"]
  node_pvsz_game["PVSZ game scene<br/>game composition<br/>[InGame_PVSZ.h]"]
  node_stage["Stage01 &amp; waves<br/>level flow<br/>[Stage01.h]"]
  node_zombie_factory["ZombieFactoryManager<br/>actor factory"]
  node_actor_system["Actor state<br/>gameplay components<br/>[Actor_State_Com.h]"]
  node_object_pool["ObjectPoolManager<br/>object pool"]
  node_game_ui["Top selection UI<br/>game UI"]
end

node_winapi{{"Windows / WinAPI<br/>platform API<br/>[framework.h]"}}
node_gdiplus{{"GDI+<br/>graphics API"}}

node_framework_entry -->|"starts"| node_base_game
node_pvsz_entry -->|"starts"| node_pvsz_game
node_pvsz_game -->|"uses runtime"| node_base_game
node_winapi -->|"messages and HDC"| node_base_game
node_base_game -->|"owns current scene"| node_scene
node_base_game -->|"updates services"| node_runtime_services
node_scene -->|"owns entities"| node_game_object
node_game_object -->|"owns typed components"| node_component
node_game_object -->|"includes"| node_transform
node_component -->|"implements rendering"| node_rendering
node_transform -->|"world transforms"| node_rendering
node_rendering -->|"loads cached images"| node_image_manager
node_rendering -->|"draws through"| node_gdiplus
node_ui -->|"reads input"| node_runtime_services
node_pvsz_game -->|"runs level"| node_stage
node_stage -->|"spawns waves"| node_zombie_factory
node_zombie_factory -->|"creates actors"| node_actor_system
node_actor_system -->|"reuses transient objects"| node_object_pool
node_pvsz_game -->|"composes UI"| node_game_ui
node_game_ui -->|"uses primitives"| node_ui
node_pvsz_game -->|"composes objects"| node_scene

click node_winapi "https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/framework.h"
click node_framework_entry "https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/FrameWork_2DAPI.cpp"
click node_base_game "https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/BaseGame.cpp"
click node_scene "https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/Scene/Scene.h"
click node_game_object "https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/Core/GameObject.h"
click node_component "https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/Compoment/Component.h"
click node_transform "https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/Compoment/Transform.h"
click node_rendering "https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/Compoment/Camera.h"
click node_image_manager "https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/Manager/ImageManager.h"
click node_runtime_services "https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/Core/InputManager.h"
click node_ui "https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/UICompoment/Button.h"
click node_pvsz_entry "https://github.com/magotoolivesource/winwpi_framework/blob/main/PVSZ/PVSZ.cpp"
click node_pvsz_game "https://github.com/magotoolivesource/winwpi_framework/blob/main/PVSZ/InGame_PVSZ.h"
click node_stage "https://github.com/magotoolivesource/winwpi_framework/blob/main/PVSZ/Stage01.h"
click node_zombie_factory "https://github.com/magotoolivesource/winwpi_framework/blob/main/PVSZ/ZombieFactoryManager.h"
click node_actor_system "https://github.com/magotoolivesource/winwpi_framework/blob/main/PVSZ/Actor_State_Com.h"
click node_object_pool "https://github.com/magotoolivesource/winwpi_framework/blob/main/PVSZ/ObjectPoolManager.h"
click node_game_ui "https://github.com/magotoolivesource/winwpi_framework/blob/main/PVSZ/UI_TopSelectPanelCom.h"

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_framework_entry,node_base_game,node_scene,node_game_object,node_component,node_transform,node_rendering,node_image_manager,node_runtime_services,node_ui toneBlue
class node_pvsz_entry,node_pvsz_game,node_stage,node_zombie_factory,node_actor_system,node_object_pool,node_game_ui toneAmber
class node_winapi,node_gdiplus toneNeutral
```

## Components

### 2D Framework

Reusable WinAPI and GDI+ runtime.

- [Framework executable](https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/FrameWork_2DAPI.cpp): WinAPI entry · `FrameWork_2DAPI/FrameWork_2DAPI.cpp`
- [BaseGame runtime loop](https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/BaseGame.cpp): game loop · Owns scene, frame update, rendering, and GDI+ lifecycle. · `FrameWork_2DAPI/BaseGame.cpp`
- [Scene](https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/Scene/Scene.h): scene lifecycle · Propagates Start, Update, and Render to game objects. · `FrameWork_2DAPI/Scene/Scene.h`
- [GameObject](https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/Core/GameObject.h): entity · Owns components and always exposes a Transform. · `FrameWork_2DAPI/Core/GameObject.h`
- [Component model](https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/Compoment/Component.h): ECS component · `FrameWork_2DAPI/Compoment/Component.h`
- [Transform](https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/Compoment/Transform.h): spatial component · Provides hierarchy, cached transforms, and depth. · `FrameWork_2DAPI/Compoment/Transform.h`
- [Camera & image rendering](https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/Compoment/Camera.h): render components · Transforms, culls, and draws world content to HDC. · `FrameWork_2DAPI/Compoment/Camera.h`
- [ImageManager](https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/Manager/ImageManager.h): asset cache · Caches GDI+ image assets. · `FrameWork_2DAPI/Manager/ImageManager.h`
- [Input, time & physics](https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/Core/InputManager.h): singleton services · Converts messages to input and coordinates timing and collision/physics. · `FrameWork_2DAPI/Core/InputManager.h`
- [UI components](https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/UICompoment/Button.h): UI layer · Buttons, rich text, and fields share object lifecycle. · `FrameWork_2DAPI/UICompoment/Button.h`

### PVSZ Game

Plants-vs.-Zombies-style game layer.

- [PVSZ executable](https://github.com/magotoolivesource/winwpi_framework/blob/main/PVSZ/PVSZ.cpp): WinAPI entry · `PVSZ/PVSZ.cpp`
- [PVSZ game scene](https://github.com/magotoolivesource/winwpi_framework/blob/main/PVSZ/InGame_PVSZ.h): game composition · Specializes the framework runtime for gameplay. · `PVSZ/InGame_PVSZ.h`
- [Stage01 & waves](https://github.com/magotoolivesource/winwpi_framework/blob/main/PVSZ/Stage01.h): level flow · Defines the level and consumes wave data. · `PVSZ/Stage01.h`
- [ZombieFactoryManager](https://github.com/magotoolivesource/winwpi_framework/blob/main/PVSZ/ZombieFactoryManager.h): actor factory · Creates zombie actors for stage waves. · `PVSZ/ZombieFactoryManager.h`
- [Actor state](https://github.com/magotoolivesource/winwpi_framework/blob/main/PVSZ/Actor_State_Com.h): gameplay components · Coordinates plants, zombies, projectiles, suns, and movement. · `PVSZ/Actor_State_Com.h`
- [ObjectPoolManager](https://github.com/magotoolivesource/winwpi_framework/blob/main/PVSZ/ObjectPoolManager.h): object pool · Reuses frequent projectile and effect objects. · `PVSZ/ObjectPoolManager.h`
- [Top selection UI](https://github.com/magotoolivesource/winwpi_framework/blob/main/PVSZ/UI_TopSelectPanelCom.h): game UI · Composes plant selection and top-panel presentation. · `PVSZ/UI_TopSelectPanelCom.h`

### Other components

- [Windows / WinAPI](https://github.com/magotoolivesource/winwpi_framework/blob/main/FrameWork_2DAPI/framework.h): platform API · Desktop window, messages, device contexts, and resources. · `FrameWork_2DAPI/framework.h`
- **GDI+**: graphics API · Images, matrices, fonts, and drawing.

## Connections

- Framework executable → BaseGame runtime loop: starts
- PVSZ executable → PVSZ game scene: starts
- PVSZ game scene → BaseGame runtime loop: uses runtime
- Windows / WinAPI → BaseGame runtime loop: messages and HDC
- BaseGame runtime loop → Scene: owns current scene
- BaseGame runtime loop → Input, time & physics: updates services
- Scene → GameObject: owns entities
- GameObject → Component model: owns typed components
- GameObject → Transform: includes
- Component model → Camera & image rendering: implements rendering
- Transform → Camera & image rendering: world transforms
- Camera & image rendering → ImageManager: loads cached images
- Camera & image rendering → GDI+: draws through
- UI components → Input, time & physics: reads input
- PVSZ game scene → Stage01 & waves: runs level
- Stage01 & waves → ZombieFactoryManager: spawns waves
- ZombieFactoryManager → Actor state: creates actors
- Actor state → ObjectPoolManager: reuses transient objects
- PVSZ game scene → Top selection UI: composes UI
- Top selection UI → UI components: uses primitives
- PVSZ game scene → Scene: composes objects