hexo/QWEN.md

Project Context: hexo

Project Overview

hexo is an educational game project - a clone of DiceWars. The project is in early development stage.

Game Concept

A strategy dice game played on a hexagonal grid where players command armies of dice and battle to conquer territories.

Core Game Mechanics

Map System

• Generatable hexagonal grid map (20x20 cells)
• Each cell can be either playable or blocked/impassable
• Each field can hold up to 8 dice
• Each player-owned field provides +1 supply unit to the player

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, calculated during gameplay)

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

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

Technology Stack

• Runtime: Node.js (inferred from jsdom usage)
• Core Library: 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

Building and Running

TODO: Build and run commands are not yet defined. The project is in initial setup phase.

Expected setup once development begins:

# Install dependencies
npm install

# Run the game (TBD)
npm start

# Run tests (TBD)
npm test

Development Conventions

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