# Project Context: hexo

## Project Overview

**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 passable or blocked/impassable
- Each field can hold up to 8 dice
- Cells are connected to 6 neighbors (hexagonal adjacency)

#### Dice System
- Standard 6-sided dice
- Unit strength calculation formula:
  ```
  F = (cnt-1) * full_dice + current_dice
  ```
  Where:
  - `cnt` = number of dice on the field
  - `full_dice` = maximum die value (6)
  - `current_dice` = top die current value (1-6)

#### Game Rules
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 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
- **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

```bash
# Start web server (http://localhost:8080)
npm run serve

# Run console demo
npm start

# 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)
- JavaScript/TypeScript expected for implementation
- DOM-based rendering likely planned (given jsdom inclusion)
- Game logic will need to implement:
  - Hexagonal grid generation
  - Dice mechanics and randomization
  - Turn-based combat system
  - Player state management

## Key Implementation Areas

When development begins, focus on these components:

1. **Map Generator**: Hexagonal grid creation with passable/impassable cells
2. **Dice Engine**: Randomization and strength calculation
3. **Combat System**: Attack/defense resolution logic
4. **Game State**: Player turns, unit positions, victory conditions
5. **UI/Rendering**: Visual representation of the game board

## Notes

- The `.gitignore` file appears to be a Python template and may need to be updated for a JavaScript project
- The `jsdom-pkg` directory contains a local copy of jsdom, possibly for offline development or custom modifications
- Game rules are documented in Russian in README.md