Update documentation for multi-player and AI features

QWEN.md

@@ -2,19 +2,27 @@
 
 ## Project Overview
 
-**hexo** is an educational game project - a clone of [DiceWars](https://www.gamedesign.jp/games/dicewars/). The project is in early development stage.
+**hexo** is an educational game project - a clone of [DiceWars](https://www.gamedesign.jp/games/dicewars/).
 
 ### Game Concept
 
 A strategy dice game played on a hexagonal grid where players command armies of dice and battle to conquer territories.
 
+### Features
+
+- **2-4 Players**: Support for multiple human and/or AI players
+- **AI Bots**: Computer-controlled players with smart move selection
+- **Hexagonal Grid**: 20×20 map with proper adjacency
+- **Dice Combat**: Roll-based battle system
+- **Solid Territory Supply**: Supply = size of largest connected territory
+
 ### Core Game Mechanics
 
 #### Map System
 - Generatable hexagonal grid map (20x20 cells)
-- Each cell can be either playable or blocked/impassable
+- Each cell can be passable or blocked/impassable
 - Each field can hold up to 8 dice
-- Each player-owned field provides +1 supply unit to the player
+- Cells are connected to 6 neighbors (hexagonal adjacency)
 
 #### Dice System
 - Standard 6-sided dice
@@ -25,75 +33,74 @@ A strategy dice game played on a hexagonal grid where players command armies of
   Where:
   - `cnt` = number of dice on the field
   - `full_dice` = maximum die value (6)
-  - `current_dice` = top die current value (1-6, calculated during gameplay)
+  - `current_dice` = top die current value (1-6)
 
 #### Game Rules
-1. **Setup**: Multiple dice are placed on the map for each player at the start
-2. **Movement Conditions**: A user can move a unit if its strength > 1
-   - When moving: strength-1 transfers to target cell, strength 1 remains on source cell
-3. **Combat**: When attacking a cell with enemy dice, both players roll:
-   - **Attacker**: `F_attack = rnd(F-1)` (random value less than original strength minus 1)
-   - **Defender**: `F_defence = current_strength` (full field strength)
-   - **Victory**: If `F_attack > F_defence`, attacker wins; otherwise defender repels the attack
-   - **On Victory**: Attacker leaves strength 1 on source cell, transfers `F_attack-1` to target
-   - **On Defeat**: Defender retains `F_defence - F_attack` (minimum 1)
-4. **Supply Phase**: After all players have moved, each receives supply:
-   - `S = sum(Cell)` where Cell = supply value from each player-owned cell
-   - Maximum per cell: `8 * full_dice` (48 dice points)
-   - If all cells already have maximum strength, no supply is added
+1. **Setup**: Each player starts with dice on their starting position
+2. **Movement**: Can move if strength > 1
+   - Source cell left with 1, target receives strength-1
+3. **Combat**: Both sides roll dice (1 to their strength)
+   - **Attacker wins**: Takes cell with attack_roll-1, source becomes 1
+   - **Defender wins**: Attacker reduced to 1, defender keeps defense_roll-attack_roll (min 1)
+4. **Supply**: After turn ends, player receives supply = largest connected territory size
+   - Distributed 1 by 1 to random non-max cells
+   - Max per cell: 48 (8 dice × 6)
+
+#### AI Bot Logic
+- Evaluates all possible moves
+- Prioritizes: winning attacks > expansion to empty > reinforcement
+- Includes thinking delay for natural gameplay
 
 ## Directory Structure
 
 ```
 hexo/
-├── README.md           # Game specifications and rules (in Russian)
-├── QWEN.md             # This file - project context for AI assistance
-├── .gitignore          # Git ignore rules (Python-focused template)
-├── jsdom-pkg/          # Local copy of jsdom library
-│   └── package/
-│       └── lib/
-│           ├── api.js              # Main jsdom API entry point
-│           └── jsdom/              # jsdom core implementation
-│               ├── browser/        # Browser emulation (Window, parser, resources)
-│               ├── living/         # DOM living standard implementations
-│               ├── generated/      # Auto-generated Web IDL bindings
-│               └── ...             # Various DOM/CSS/SVG/XHR implementations
-└── node_modules/
-    └── jsdom/          # Installed jsdom dependency
+├── README.md           # Game rules and documentation (Russian)
+├── QWEN.md             # This file - project context
+├── package.json        # NPM configuration
+├── server.js           # Simple HTTP server for development
+├── .gitignore          # Git ignore rules
+├── jsdom-pkg/          # Local jsdom library copy
+├── public/             # Web application files
+│   ├── index.html      # Main HTML page with start screen
+│   ├── styles.css      # Game UI styles
+│   ├── game.js         # Main game logic and rendering
+│   ├── map.js          # HexMap module (browser version)
+│   └── ai-bot.js       # AI bot player logic
+├── src/                # Server-side modules
+│   ├── index.js        # Console demo entry point
+│   └── map.js          # HexMap module (Node.js version)
+└── test/               # Unit tests
+    └── map.test.js     # Map and cell tests
 ```
 
 ## Technology Stack
 
-- **Runtime**: Node.js (inferred from jsdom usage)
-- **Core Library**: [jsdom](https://github.com/jsdom/jsdom) - JavaScript implementation of DOM and HTML standards
-  - Provides browser-like environment for server-side JavaScript
-  - Enables DOM manipulation, event handling, and web API emulation
-
-## Development Status
-
-**Early Stage**: The project currently contains:
-- Game design documentation (README.md)
-- jsdom library setup (both local copy and node_modules installation)
-- No main game source files yet
+- **Runtime**: Node.js
+- **Frontend**: Vanilla JavaScript (ES Modules), HTML5 Canvas, CSS3
+- **Backend**: Simple HTTP server (server.js)
+- **Testing**: Node.js built-in test runner (`node --test`)
 
 ## Building and Running
 
-> **TODO**: Build and run commands are not yet defined. The project is in initial setup phase.
-
-Expected setup once development begins:
 ```bash
-# Install dependencies
-npm install
+# Start web server (http://localhost:8080)
+npm run serve
 
-# Run the game (TBD)
+# Run console demo
 npm start
 
-# Run tests (TBD)
+# Run tests
 npm test
 ```
 
 ## Development Conventions
 
+- ES Modules for browser code (`import`/`export`)
+- CommonJS for Node.js code (`require`/`module.exports`)
+- Map module exports both ES and CommonJS for compatibility
+- Tests use Node.js built-in `node:test` module
+
 > **TODO**: Coding standards and testing practices are not yet established.
 
 ### Inferred Practices (based on jsdom usage)