# 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

```
src/
├── assets/
│   ├── data/
│   │   ├── classes/          # Character class definitions (JSON)
│   │   ├── missions/          # Mission configurations
│   │   └── narrative/         # Dialogue sequences
│   └── 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
├── 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/
│   ├── MissionManager.js    # Mission progression and objectives
│   ├── NarrativeManager.js  # Dialogue and story sequences
│   ├── RosterManager.js     # Character roster management
│   └── 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
└── 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

## 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

Planned features:

- 🔄 Turn-based combat system
- 🔄 AI behavior
- 🔄 Skill tree implementation
- 🔄 Equipment system
- 🔄 Additional biomes and missions

## License

ISC