# dominusleo/tic_tac_toe_3d architecture

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

- Interactive diagram: https://gitdiagram.com/dominusleo/tic_tac_toe_3d
- Repository: https://github.com/dominusleo/tic_tac_toe_3d

## Overview

#### Purpose and entry points
This is a Python implementation of configurable 3D Tic-Tac-Toe, supporting human, bot, bot-vs-bot, and debug-driven games. The interactive runtime starts at `game_process.py`; automated bot experimentation starts at `explore_scrypts.py`. Persistent performance data is stored in `data/leaderboard.csv`.

#### Configuration and game model
`constants.py` centralizes board shape, gravity, player/bot mode, AI difficulty, debug behavior, colors, and other rule/rendering settings. The game state is a 3D board whose legal moves and win conditions depend on configured dimensions and optional gravity. Shared state conventions and supporting calculations are distributed through `utils.py` and `funcs.py`.

#### Main game orchestration
`game_process.py` owns the turn-based control flow: initialize a board, select human or bot actors from configuration, accept terminal input where applicable, apply moves, update display, test termination, and handle undo/exit behavior. It is the boundary between user interaction and the game/AI subsystems.

#### Board mechanics and rule evaluation
`funcs.py` provides core mechanics used by the loop: move application/validation, gravity-aware placement, winning-line evaluation, and likely 3D board rendering. `utils.py` supplies reusable geometric or board-analysis operations. These modules isolate board mutation and rule checks from actor selection in `game_process.py`.

#### AI decision pipeline
`bot_utils.py` implements difficulty-tiered bot policy. Bot turns consume the current board state and return a legal position for the game engine to apply. Strategy progresses from random/immediate win-block behavior to line scoring, weighted positioning, fork and dead-point analysis, forced defensive moves, and lookahead. The key control boundary is: `game_process.py` requests a move; `bot_utils.py` evaluates but should not own the authoritative game loop.

#### Visualization and runtime dependencies
Rendering is local, real-time 3D visualization via matplotlib, invoked as the board changes; NumPy supports array operations. The project also declares pandas, seaborn, sympy, and tqdm in `requirements.txt`, primarily enabling analysis, geometry, and batch-progress workflows. There is no indicated network service, database, or deployed infrastructure.

#### Batch analysis and persisted results
`explore_scrypts.py` is the experimental/batch entry point for bot comparisons and strategic analysis, likely running repeated games outside the interactive loop. `parallel_runner.py` is the concurrency-oriented execution layer for scaling such simulations. Results feed tabular artifacts such as `data/leaderboard.csv`, separating long-running evaluation from interactive play.

Main entry points: [`game_process.py`](https://github.com/dominusleo/tic_tac_toe_3d/blob/master/game_process.py) (Game process), [`bot_utils.py`](https://github.com/dominusleo/tic_tac_toe_3d/blob/master/bot_utils.py) (Bot policy), [`funcs.py`](https://github.com/dominusleo/tic_tac_toe_3d/blob/master/funcs.py) (Board mechanics), [`constants.py`](https://github.com/dominusleo/tic_tac_toe_3d/blob/master/constants.py) (Game configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interactive["Interactive Game"]
  node_game_process["Game process<br/>interactive entry point<br/>[game_process.py]"]
  node_terminal_user(("Human player<br/>terminal input"))
  node_renderer["3D board rendering<br/>matplotlib visualization<br/>[funcs.py]"]
end

subgraph group_core["Game Core"]
  node_constants["Game configuration<br/>rules and modes<br/>[constants.py]"]
  node_board_state[("3D board state<br/>authoritative game state")]
  node_mechanics["Board mechanics<br/>move and rule engine<br/>[funcs.py]"]
  node_board_utils["Board analysis utilities<br/>geometry helpers<br/>[utils.py]"]
end

subgraph group_ai["Bot AI"]
  node_bot_policy["Bot policy<br/>difficulty-tiered AI<br/>[bot_utils.py]"]
end

subgraph group_analysis["Batch Analysis"]
  node_explore["Experiment runner<br/>batch entry point<br/>[explore_scrypts.py]"]
  node_parallel_runner["Parallel simulations<br/>concurrency layer<br/>[parallel_runner.py]"]
  node_leaderboard["Leaderboard results<br/>CSV results<br/>[leaderboard.csv]"]
end

node_dependencies["Analysis and rendering deps<br/>Python dependencies<br/>[requirements.txt]"]

node_constants -->|"configures"| node_game_process
node_constants -->|"defines rules"| node_mechanics
node_constants -->|"sets difficulty"| node_bot_policy
node_terminal_user -->|"moves and commands"| node_game_process
node_game_process -->|"requests bot move"| node_bot_policy
node_game_process -->|"applies turns"| node_mechanics
node_bot_policy -->|"evaluates position"| node_board_state
node_bot_policy -->|"uses analysis"| node_board_utils
node_game_process -->|"reads state"| node_board_state
node_mechanics -->|"mutates and checks"| node_board_state
node_mechanics -->|"uses geometry"| node_board_utils
node_game_process -->|"updates display"| node_renderer
node_explore -->|"scales runs"| node_parallel_runner
node_parallel_runner -->|"runs bot games"| node_bot_policy
node_explore -->|"writes results"| node_leaderboard
node_dependencies -.->|"matplotlib and NumPy"| node_renderer
node_dependencies -.->|"analysis tooling"| node_explore

click node_game_process "https://github.com/dominusleo/tic_tac_toe_3d/blob/master/game_process.py"
click node_renderer "https://github.com/dominusleo/tic_tac_toe_3d/blob/master/funcs.py"
click node_constants "https://github.com/dominusleo/tic_tac_toe_3d/blob/master/constants.py"
click node_mechanics "https://github.com/dominusleo/tic_tac_toe_3d/blob/master/funcs.py"
click node_board_utils "https://github.com/dominusleo/tic_tac_toe_3d/blob/master/utils.py"
click node_bot_policy "https://github.com/dominusleo/tic_tac_toe_3d/blob/master/bot_utils.py"
click node_explore "https://github.com/dominusleo/tic_tac_toe_3d/blob/master/explore_scrypts.py"
click node_parallel_runner "https://github.com/dominusleo/tic_tac_toe_3d/blob/master/parallel_runner.py"
click node_leaderboard "https://github.com/dominusleo/tic_tac_toe_3d/blob/master/data/leaderboard.csv"
click node_dependencies "https://github.com/dominusleo/tic_tac_toe_3d/blob/master/requirements.txt"

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_game_process,node_terminal_user,node_renderer toneBlue
class node_constants,node_board_state,node_mechanics,node_board_utils toneAmber
class node_bot_policy toneMint
class node_explore,node_parallel_runner,node_leaderboard toneRose
class node_dependencies toneNeutral
```

## Components

### Interactive Game

- [Game process](https://github.com/dominusleo/tic_tac_toe_3d/blob/master/game_process.py): interactive entry point · Owns turn flow, actor selection, input, undo, and exit. · `game_process.py`
- **Human player**: terminal input
- [3D board rendering](https://github.com/dominusleo/tic_tac_toe_3d/blob/master/funcs.py): matplotlib visualization · Updates local real-time board display. · `funcs.py`

### Game Core

- [Game configuration](https://github.com/dominusleo/tic_tac_toe_3d/blob/master/constants.py): rules and modes · Defines board dimensions, gravity, actor modes, difficulty, and debug settings. · `constants.py`
- **3D board state**: authoritative game state · Configured board state used for legal moves and win evaluation.
- [Board mechanics](https://github.com/dominusleo/tic_tac_toe_3d/blob/master/funcs.py): move and rule engine · Validates and applies moves, handles gravity, and evaluates winning lines. · `funcs.py`
- [Board analysis utilities](https://github.com/dominusleo/tic_tac_toe_3d/blob/master/utils.py): geometry helpers · `utils.py`

### Bot AI

- [Bot policy](https://github.com/dominusleo/tic_tac_toe_3d/blob/master/bot_utils.py): difficulty-tiered AI · Selects legal moves using tactical and lookahead strategies. · `bot_utils.py`

### Batch Analysis

- [Experiment runner](https://github.com/dominusleo/tic_tac_toe_3d/blob/master/explore_scrypts.py): batch entry point · Runs repeated bot comparisons and strategic experiments. · `explore_scrypts.py`
- [Parallel simulations](https://github.com/dominusleo/tic_tac_toe_3d/blob/master/parallel_runner.py): concurrency layer · Scales batch game execution. · `parallel_runner.py`
- [Leaderboard results](https://github.com/dominusleo/tic_tac_toe_3d/blob/master/data/leaderboard.csv): CSV results · Persistent bot-performance data. · `data/leaderboard.csv`

### Other components

- [Analysis and rendering deps](https://github.com/dominusleo/tic_tac_toe_3d/blob/master/requirements.txt): Python dependencies · Provides NumPy, matplotlib, and batch-analysis libraries. · `requirements.txt`

## Connections

- Game configuration → Game process: configures
- Game configuration → Board mechanics: defines rules
- Game configuration → Bot policy: sets difficulty
- Human player → Game process: moves and commands
- Game process → Bot policy: requests bot move
- Game process → Board mechanics: applies turns
- Bot policy → 3D board state: evaluates position
- Bot policy → Board analysis utilities: uses analysis
- Game process → 3D board state: reads state
- Board mechanics → 3D board state: mutates and checks
- Board mechanics → Board analysis utilities: uses geometry
- Game process → 3D board rendering: updates display
- Experiment runner → Parallel simulations: scales runs
- Parallel simulations → Bot policy: runs bot games
- Experiment runner → Leaderboard results: writes results
- Analysis and rendering deps → 3D board rendering: matplotlib and NumPy
- Analysis and rendering deps → Experiment runner: analysis tooling