130 lines
4.5 KiB
Markdown
130 lines
4.5 KiB
Markdown
# 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
|