# nv5466/matrix-game. architecture

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

- Interactive diagram: https://gitdiagram.com/nv5466/matrix-game.
- Repository: https://github.com/nv5466/matrix-game.

## Overview

#### Purpose and Entry Points
This is an early C++ terminal-game prototype for a turn-based D&D-style dungeon game. Its intended core is procedurally generated matrix rooms: `0` denotes walkable space, `1` walls, and player/NPC values encode facing direction. There is no single confirmed application entry point; the executable experiments appear to be separate `.cpp` programs.

#### World and Room Generation
Room layouts are generated as 2D matrix grids, likely with perimeter/interior wall handling and randomized blocks. The generation work is split across:
- `worldGeneration.cpp`
- `Room+Mazegen.cpp`
- `Maze blocks rand code.cpp`
- `Testing maze generation.cpp`

These files define the primary world-model boundary: generated numeric matrices become the authoritative representation for room geometry.

#### Maze/Connectivity Stage
Maze-oriented generation is distinct from generic randomized room blocks. `Room+Mazegen.cpp` likely combines room construction with maze generation, while `Maze blocks rand code.cpp` focuses on placing randomized maze obstacles. This is the key stage that must preserve navigable empty cells for later spawning and movement.

#### Entity State, Movement, and Orientation
The README defines tile values for an entity’s facing state: default `2`, up `3`, right `4`, down `5`, left `6`. Movement updates both matrix position and facing. The likely prototypes for this behavior are:
- `Attributes.cpp`
- `Testing class sel.cpp`

The architecture currently appears to store entity state directly in the same grid that stores terrain, creating an important boundary between static room tiles (`0`/`1`) and dynamic actor markers (`2`–`6`).

#### Encounter and Combat Logic
Combat is an independent gameplay subsystem, presumably invoked after movement or NPC detection:
- `Fighting code.cpp`
- `Testing(dice, loading).cpp`

The dice/loading test suggests randomized combat or character initialization mechanics. Combat should consume actor attributes and encounter state rather than directly owning maze generation.

#### Spawning, Sight, and Distance Rules
NPC/player placement must choose valid empty tiles and avoid immediate encounters. The README specifies Manhattan/taxicab distance, `abs(y2-y1) + abs(x2-x1)`, with a minimum separation target of at least two tiles. Sight is planned as a generated range value and will depend on grid geometry, actor position, orientation, and wall occlusion.

Relevant model experimentation may reside in:
- `Attributes.cpp`
- `worldGeneration.cpp`

#### Runtime and Infrastructure
The project is native C++ and currently targets terminal/Visual Studio-style output rather than a graphical runtime. No build system, package manager, database, network service, or external API is represented in the repository tree. `Launch.json config` indicates editor/debug-launch configuration rather than game infrastructure.

#### Main Control Flow
A coherent game loop implied by the prototypes is: generate world/room matrix → validate connectivity and empty tiles → spawn player and NPCs with distance constraints → accept turn input → update movement/facing → evaluate sight/encounters → run combat → render the updated matrix in the terminal. The central integration risk is coordinating currently separate generation, attributes, movement, and combat experiments into one shared grid/entity model.

Main entry points: [`Attributes.cpp`](https://github.com/nv5466/matrix-game./blob/main/Attributes.cpp) (Actor Attributes), [`Room+Mazegen.cpp`](https://github.com/nv5466/matrix-game./blob/main/Room%2BMazegen.cpp) (Room + Maze Generation), [`Fighting code.cpp`](https://github.com/nv5466/matrix-game./blob/main/Fighting%20code.cpp) (Combat Logic), [`worldGeneration.cpp`](https://github.com/nv5466/matrix-game./blob/main/worldGeneration.cpp) (World Grid Generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Room Generation"]
  node_world_generation["World Grid Generator<br/>C++ prototype"]
  node_room_maze["Room + Maze Generation<br/>C++ prototype<br/>[Room+Mazegen.cpp]"]
  node_maze_blocks["Random Maze Blocks<br/>C++ prototype"]
  node_maze_test["Maze Generation Test<br/>C++ prototype"]
  node_room_grid[("Room Matrix<br/>world model")]
  node_connectivity{{"Connectivity Validation<br/>generation stage"}}
end

subgraph group_gameplay["Turn Gameplay"]
  node_spawning{{"Spawn Rules<br/>gameplay rule"}}
  node_attributes["Actor Attributes<br/>C++ prototype<br/>[Attributes.cpp]"]
  node_class_test["Class Selection Test<br/>C++ prototype"]
  node_actor_markers[("Actor Grid Markers<br/>entity model")]
  node_turn_input["Turn Input<br/>terminal input"]
  node_movement{{"Movement + Facing<br/>turn system"}}
  node_sight{{"Sight + Encounter Check<br/>gameplay rule"}}
  node_combat["Combat Logic<br/>C++ prototype<br/>[Fighting code.cpp]"]
  node_dice_loading["Dice / Loading Test<br/>C++ prototype"]
end

node_terminal["Terminal Runtime<br/>native runtime"]
node_rendering["Matrix Renderer<br/>terminal output"]
node_launch_config["Debug Launch Config<br/>editor configuration<br/>[Launch.json config]"]

node_world_generation -->|"generates"| node_room_grid
node_room_maze -->|"generates"| node_room_grid
node_maze_blocks -->|"supplies obstacles"| node_room_maze
node_maze_test -.->|"validates"| node_room_maze
node_room_grid -->|"validates"| node_connectivity
node_connectivity -->|"provides empty tiles"| node_spawning
node_spawning -->|"places actors"| node_actor_markers
node_attributes -->|"defines actor state"| node_actor_markers
node_class_test -.->|"experiments with"| node_attributes
node_room_grid -->|"shares grid"| node_actor_markers
node_turn_input -->|"selects action"| node_movement
node_actor_markers -->|"updates"| node_movement
node_movement -->|"writes position/facing"| node_actor_markers
node_movement -->|"triggers check"| node_sight
node_room_grid -->|"wall geometry"| node_sight
node_actor_markers -->|"positions and facing"| node_sight
node_sight -->|"starts encounter"| node_combat
node_attributes -->|"actor stats"| node_combat
node_dice_loading -.->|"randomization experiment"| node_combat
node_actor_markers -->|"renders actors"| node_rendering
node_room_grid -->|"renders terrain"| node_rendering
node_rendering -->|"prints"| node_terminal
node_launch_config -.->|"debug launch"| node_terminal

click node_world_generation "https://github.com/nv5466/matrix-game./blob/main/worldGeneration.cpp"
click node_room_maze "https://github.com/nv5466/matrix-game./blob/main/Room%2BMazegen.cpp"
click node_maze_blocks "https://github.com/nv5466/matrix-game./blob/main/Maze%20blocks%20rand%20code.cpp"
click node_maze_test "https://github.com/nv5466/matrix-game./blob/main/Testing%20maze%20generation.cpp"
click node_attributes "https://github.com/nv5466/matrix-game./blob/main/Attributes.cpp"
click node_class_test "https://github.com/nv5466/matrix-game./blob/main/Testing%20class%20sel.cpp"
click node_combat "https://github.com/nv5466/matrix-game./blob/main/Fighting%20code.cpp"
click node_dice_loading "https://github.com/nv5466/matrix-game./blob/main/Testing(dice%2C%20loading).cpp"
click node_launch_config "https://github.com/nv5466/matrix-game./blob/main/Launch.json%20config"

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_world_generation,node_room_maze,node_maze_blocks,node_maze_test,node_room_grid,node_connectivity toneBlue
class node_spawning,node_attributes,node_class_test,node_actor_markers,node_turn_input,node_movement,node_sight,node_combat,node_dice_loading toneAmber
class node_terminal,node_rendering,node_launch_config toneNeutral
```

## Components

### Room Generation

Procedural matrix construction experiments.

- [World Grid Generator](https://github.com/nv5466/matrix-game./blob/main/worldGeneration.cpp): C++ prototype · Generates authoritative numeric room matrices. · `worldGeneration.cpp`
- [Room + Maze Generation](https://github.com/nv5466/matrix-game./blob/main/Room%2BMazegen.cpp): C++ prototype · Combines room construction and maze layout. · `Room+Mazegen.cpp`
- [Random Maze Blocks](https://github.com/nv5466/matrix-game./blob/main/Maze%20blocks%20rand%20code.cpp): C++ prototype · Places randomized obstacle blocks. · `Maze blocks rand code.cpp`
- [Maze Generation Test](https://github.com/nv5466/matrix-game./blob/main/Testing%20maze%20generation.cpp): C++ prototype · `Testing maze generation.cpp`
- **Room Matrix**: world model · 0 is walkable space and 1 is wall terrain.
- **Connectivity Validation**: generation stage · Keeps navigable empty cells available for play.

### Turn Gameplay

Shared-grid entity and encounter behavior.

- **Spawn Rules**: gameplay rule · Chooses empty tiles with Manhattan-distance separation.
- [Actor Attributes](https://github.com/nv5466/matrix-game./blob/main/Attributes.cpp): C++ prototype · Experiments with player and NPC state. · `Attributes.cpp`
- [Class Selection Test](https://github.com/nv5466/matrix-game./blob/main/Testing%20class%20sel.cpp): C++ prototype · `Testing class sel.cpp`
- **Actor Grid Markers**: entity model · Values 2–6 encode actor position and facing in the room matrix.
- **Turn Input**: terminal input
- **Movement + Facing**: turn system · Updates grid position and orientation.
- **Sight + Encounter Check**: gameplay rule · Uses geometry, orientation, range, and wall occlusion.
- [Combat Logic](https://github.com/nv5466/matrix-game./blob/main/Fighting%20code.cpp): C++ prototype · Consumes encounter and actor state. · `Fighting code.cpp`
- [Dice / Loading Test](https://github.com/nv5466/matrix-game./blob/main/Testing(dice%2C%20loading).cpp): C++ prototype · Randomized combat or character-initialization experiment. · `Testing(dice, loading).cpp`

### Other components

- **Terminal Runtime**: native runtime · Separate C++ executable experiments write to the terminal.
- **Matrix Renderer**: terminal output · Renders the updated room matrix.
- [Debug Launch Config](https://github.com/nv5466/matrix-game./blob/main/Launch.json%20config): editor configuration · Visual Studio-style debug launch setup. · `Launch.json config`

## Connections

- World Grid Generator → Room Matrix: generates
- Room + Maze Generation → Room Matrix: generates
- Random Maze Blocks → Room + Maze Generation: supplies obstacles
- Maze Generation Test → Room + Maze Generation: validates
- Room Matrix → Connectivity Validation: validates
- Connectivity Validation → Spawn Rules: provides empty tiles
- Spawn Rules → Actor Grid Markers: places actors
- Actor Attributes → Actor Grid Markers: defines actor state
- Class Selection Test → Actor Attributes: experiments with
- Room Matrix → Actor Grid Markers: shares grid
- Turn Input → Movement + Facing: selects action
- Actor Grid Markers → Movement + Facing: updates
- Movement + Facing → Actor Grid Markers: writes position/facing
- Movement + Facing → Sight + Encounter Check: triggers check
- Room Matrix → Sight + Encounter Check: wall geometry
- Actor Grid Markers → Sight + Encounter Check: positions and facing
- Sight + Encounter Check → Combat Logic: starts encounter
- Actor Attributes → Combat Logic: actor stats
- Dice / Loading Test → Combat Logic: randomization experiment
- Actor Grid Markers → Matrix Renderer: renders actors
- Room Matrix → Matrix Renderer: renders terrain
- Matrix Renderer → Terminal Runtime: prints
- Debug Launch Config → Terminal Runtime: debug launch