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

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

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