hexo/QWEN.md

Project Context: hexo

Project Overview

hexo is an educational game project - a clone of 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

# 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