How xpmatteo/auto-cca works
Project Type and Purpose
• This is a browser-based educational AI application for exploring Monte-Carlo Tree Search on a complex board game.
• It consists of a game engine (model), multiple AI players (MCTS, greedy, open-loop), a graphical front-end, test suites, scripts for batch runs and visualization, and CI integration.
Top-Level Structure
• index.html
• src/
• view/ (canvas drawing, asset loader)
• model/ (game state, phases, commands)
• ai/ (player implementations, MCTS, score functions)
• lib/ (utility modules: random, combinatorial, hex math)
• interactive_game.js (Controller tying UI ↔ model ↔ AI)
• main.js (entry point)
• config.js (AI parameters)
• script/ (CLI helpers: arena simulation, timed runs, tree generation)
• doc/ (Graphviz templates)
• images/ (game graphics)
• tests and snapshots (Jest-based)
• CI config (.github/workflows/ci.yml) and Makefile
Core Components and Their Roles
• View Layer (src/view + index.html + images)
• Draws board, units, UI controls
• Emits user events (“End phase”, “AI continue”)
• Controller Layer (interactive_game.js, main.js)
• Initializes game, wires UI events to model updates
• Invokes AI when it’s the AI’s turn
• Model Layer (src/model)
• Encodes game rules, commands, phases, scenarios
• Maintains current game state
• AI Layer (src/ai)
• Implements GreedyPlayer, OpenLoopMctsPlayer, macro-move sampling
• Queries model to simulate playouts and pick next command
• Utility Modules (src/lib)
• Provide common functions used by model and AI
• Configuration (src/config.js)
• Sets iteration counts, delays, thresholds, scenario keys
• Scripts & Tools
• Batch simulation (script/arena.js)
• Tree visualization (script/tree_main.js + doc/close-combat.dot)
• Test runners (Makefile, jest.config.mjs, script/test.sh)
• CI Pipeline (GitHub Actions)
• Lints, runs tests on each PR
Component Interactions
• User clicks UI button → Controller receives event
• Controller calls Model.applyCommand() → Model updates state
• If it’s AI’s turn → Controller calls AI.selectCommand(modelState)
• AI consults Model via simulate playouts → returns a Command
• Controller applies AI’s Command → Model updates
• View renders updated board
Architectural Patterns and Principles
• MVC-style separation: Model (game rules), View (graphics), Controller (event orchestration)
• Modular design: each subsystem in its own folder, easy to stub/mock in tests
• Dependency inversion: Controller depends on interfaces of Model and AI
• Flyweight (planned) for commands to reduce object churn in MCTS
Technologies and Frameworks
• JavaScript ES modules (Node & Browser)
• HTML5 Canvas API for rendering
• Jest for unit tests and snapshots
• NPM & Makefile for builds and scripts
• GitHub Actions for CI