aether-shards/README.md

# Aether Shards

A tactical turn-based roguelike strategy game built with Three.js, featuring procedurally generated voxel worlds, squad-based combat, and a narrative-driven campaign system.

## Overview

**Aether Shards** is a tactical roguelike where players lead a squad of explorers through procedurally generated 3D voxel environments. The game combines turn-based tactical combat with roguelike progression, featuring a class-based unit system, mission objectives, and persistent campaign progression.

## Key Features

### 🎮 Core Gameplay

- **Turn-Based Tactical Combat**: Strategic positioning and action point management on a 3D voxel grid
- **Squad Management**: Build and customize teams from multiple character classes (Vanguard, Aether Weaver, Scavenger, Tinker, Custodian, and more)
- **Procedural Generation**: Multiple biome generators (Caves, Ruins, Crystal Spires) create unique levels each run
- **Mission System**: Campaign progression with objectives, narrative sequences, and rewards
- **Deployment Phase**: Pre-battle unit placement on designated spawn zones

### 🏗️ Technical Architecture

- **3D Voxel Rendering**: Three.js-powered voxel grid system with custom texture generators
- **Modular Class System**: JSON-defined character classes with skill trees, stats, and equipment
- **State Management**: Persistent save system using IndexedDB for campaign progress
- **Component-Based UI**: Lit-based web components for HUD, team builder, and dialogue systems
- **Input System**: Keyboard and gamepad support with cursor-based grid navigation

### 🎨 Game Systems

- **Unit Classes**: 10+ character classes with unique roles (Tank, DPS, Healer, Utility, Tech)
- **Skill Trees**: Active and passive abilities per class
- **Equipment System**: Gear that modifies unit stats and capabilities
- **Narrative System**: Dialogue sequences and story integration
- **Objective Tracking**: Mission goals with real-time progress monitoring

## Tech Stack

- **Rendering**: Three.js (WebGL)
- **UI Framework**: Lit (Web Components)
- **Build Tool**: esbuild
- **Testing**: Web Test Runner
- **Language**: JavaScript (ES Modules)

## Project Structure

```
specs/                     # Detailed feature specifications and design docs
src/
├── assets/
│   ├── data/
│   │   ├── classes/          # Character class definitions (JSON)
│   │   ├── effects/          # Status effects and abilities
│   │   ├── missions/         # Mission configurations
│   │   ├── narrative/        # Dialogue sequences
│   │   ├── skill_trees/      # Class skill tree templates
│   │   └── skills/           # Individual skill definitions
│   └── images/               # Character portraits and assets
├── core/
│   ├── GameLoop.js           # Main game loop and Three.js setup
│   ├── GameStateManager.js   # Application state management
│   ├── InputManager.js       # Input handling (keyboard/gamepad)
│   └── Persistence.js        # Save/load system
├── factories/
│   └── SkillTreeFactory.js   # Skill tree generation logic
├── generation/
│   ├── BaseGenerator.js      # Base class for world generators
│   ├── CaveGenerator.js      # Cave biome generator
│   ├── RuinGenerator.js      # Ruin biome generator
│   └── textures/             # Procedural texture generators
├── grid/
│   ├── VoxelGrid.js          # 3D voxel grid data structure
│   └── VoxelManager.js       # Voxel rendering and mesh management
├── managers/
│   ├── InventoryManager.js   # Equipment and inventory
│   ├── ItemRegistry.js       # Item definitions
│   ├── MarketManager.js      # Shop and trading logic
│   ├── MissionManager.js     # Mission progression and objectives
│   ├── NarrativeManager.js   # Dialogue and story sequences
│   ├── ResearchManager.js    # Tech tree and upgrades
│   ├── RosterManager.js      # Character roster management
│   ├── SkillRegistry.js      # Skill definitions map
│   └── UnitManager.js        # Unit lifecycle and combat state
├── ui/
│   ├── deployment-hud.js     # Pre-battle deployment interface
│   ├── team-builder.js       # Squad composition screen
│   ├── game-viewport.js      # 3D game viewport component
│   └── dialogue-overlay.js   # Narrative dialogue display
├── units/
│   ├── Unit.js               # Base unit class
│   ├── Explorer.js           # Player-controlled units
│   └── Enemy.js              # Enemy AI units
├── utils/
│   ├── SeededRandom.js       # Deterministic RNG
│   └── SimplexNoise.js       # Noise generation
└── index.js                  # Application entry point
```

## Getting Started

### Prerequisites

- Node.js (v16+)
- npm

### Installation

```bash
npm install
```

### Development

Start the development server:

```bash
npm start
```

The game will be available at `http://localhost:8000`

### Building

Create a production build:

```bash
npm run build
```

### Testing

Run the test suite:

```bash
npm test
```

Run tests in watch mode:

```bash
npm run test:watch
```

## Game Flow

1. **Main Menu**: Start a new run or continue a saved game
2. **Team Builder**: Select and customize your squad from available classes
3. **Mission Selection**: Choose a mission (currently starts with tutorial)
4. **Deployment Phase**: Place units on designated spawn zones
5. **Tactical Combat**: Turn-based combat with action points, movement, and abilities
6. **Mission Completion**: Complete objectives to earn rewards and progress the campaign

## Game Mechanics

### Units

- **Action Points (AP)**: Units spend AP to move, attack, and use abilities
- **Charge Meter**: Dynamic initiative system (0-100) determines turn order
- **Stats**: Health, Attack, Defense, Magic, Speed, Willpower, Movement, Tech
- **Status Effects**: Buffs and debuffs that modify unit capabilities

### World Generation

- **Seeded Random**: Deterministic procedural generation for consistent runs
- **Biomes**: Different environment types with unique generation rules
- **Spawn Zones**: Designated areas for player and enemy deployment
- **Cover System**: Destructible objects provide tactical positioning

### Missions

- **Objectives**: Primary goals (e.g., eliminate all enemies, reach location)
- **Rewards**: XP and currency (Aether Shards) for completion
- **Narrative**: Intro and outro sequences that advance the story
- **Campaign Progression**: Unlock new missions as you complete objectives

## Documentation

For detailed specifications of game systems, please see the `specs/` directory:
- [Character Sheet](specs/Character_Sheet.spec.md)
- [Combat System](specs/CombatState.spec.md)
- [Skill Trees](specs/Skill_Tree.spec.md)
- [Inventory](specs/Inventory.spec.md)
- [Procedural Missions](specs/Procedural_Missions.spec.md)

## Development Status

This is an active development project. Current features include:

- ✅ Core game loop and rendering
- ✅ Voxel grid system
- ✅ Team builder UI
- ✅ Deployment phase
- ✅ Mission system foundation
- ✅ Basic world generation
- ✅ Save/load system
- ✅ Turn-based combat system
- ✅ AI behavior
- ✅ Skill tree implementation
- ✅ Equipment system

Planned features / In Progress:

- 🔄 Additional biomes (Crystal Spires)
- 🔄 Advanced AI behavior (Pack tactics, Retreat)
- 🔄 Endgame campaign content

## License

ISC