dominusleo/tic_tac_toe_3d

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.