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

npm install

Development

Start the development server:

npm start

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

Building

Create a production build:

npm run build

Testing

Run the test suite:

npm test

Run tests in watch mode:

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
• Combat System
• Skill Trees
• Inventory
• Procedural Missions

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