# Zork-Like TUI Adventure Game — SPEC.md

## Project Overview

**Name**: Echoes of the Void  
**Type**: Text adventure / interactive fiction with modern TUI  
**Core**: A atmospheric exploration game where you navigate ancient ruins, solve puzzles, and uncover a mystery  
**Target**: Terminal enthusiasts who appreciate beautiful CLI tools

---

## Visual & Rendering Specification

### Terminal Setup
- **Dimensions**: 120x40 cells (responsive)
- **Double-buffered rendering** for flicker-free updates
- **256-color palette** (not truecolor, for maximum compatibility + speed)
- **Box-drawing characters** for UI frames
- **Custom Unicode blocks** for visual accents

### Color Palette
```
Background:     #0D0D12 (deep void)
Panel BG:       #16161E (slightly lighter)
Primary Text:   #E4E4E7 (soft white)
Accent:         #7C3AED (vivid violet)
Secondary:      #22D3EE (cyan glow)
Success:        #34D399 (emerald)
Warning:        #FBBF24 (amber)
Danger:         #F87171 (soft red)
Muted:          #525263 (dim gray)
Border:         #2E2E3A (subtle borders)
```

### Typography
- **Primary**: JetBrains Mono (monospace, ligatures disabled for TUI)
- **Headers**: Bold, uppercase, letter-spacing: 2px
- **Body**: Regular weight, line-height: 1.4

### Layout Structure
```
┌─────────────────────────────────────────────────────────────────────────────┐
│  ECHOES OF THE VOID                              ♥ 100  ⚡ 3  ◇ 12          │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  [LOCATION NAME]                              [COMPASS]                      │
│  ─────────────────                            N                             │
│  Description text here...                      W + E                        │
│  More description...                           S                             │
│                                                                             │
│  > You can see:                                                            │
│    • Ancient door (to the north)                                          │
│    • Glowing crystal (in the corner)                                       │
│                                                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│  INVENTORY: [rusty key] [torch] [torn page]                                │
├─────────────────────────────────────────────────────────────────────────────┤
│  > _                                                                      │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Visual Effects
- **Subtle pulse animation** on interactive elements
- **Smooth text reveal** (50ms per line, max 10 lines)
- **Border glow** effect using ANSI dim/bright alternation
- **Scanline overlay** (optional, subtle CRT feel)
- **Vignette** via gradient on outer edges

---

## Performance Specification

### SIMD Optimizations
- **Text rendering**: SIMD string processing with AVX2/NEON
- **Viewport culling**: Only render visible cells
- **Dirty rectangle tracking**: Only redraw changed regions
- **String interning**: Cache repeated strings
- **Batch rendering**: Group similar operations

### Architecture
```
┌─────────────────┐
│   Game State    │ (Position, Inventory, Flags, Quests)
├─────────────────┤
│   Renderer      │ (Double-buffer, SIMD text processing)
├─────────────────┤
│   Input Handler │ (Async key events, command parser)
├─────────────────┤
│   World Data    │ (Rooms, items, connections - static)
└─────────────────┘
```

### Benchmarks
- **Target**: 60 FPS rendering (16.67ms frame budget)
- **Input latency**: <5ms
- **Memory**: <5MB total

---

## Game Specification

### World Structure
- **8 interconnected rooms** forming a small dungeon
- **4 items** to collect and use
- **2 puzzles** requiring item combination/placement
- **1 win condition**: Reach the heart of the ruins

### Rooms
1. **Entrance Hall** — Starting point, torch available
2. **Collapsed Corridor** — Requires rusty key to proceed
3. **Crystal Chamber** — Contains the crystal
4. **Ancient Library** — Contains torn page with hint
5. **Flooded Passage** — Requires crystal to light the way
6. **Guardian's Rest** — Boss/enemy room (skippable with items)
7. **Shrine of Echoes** — Requires combining items
8. **Heart of the Void** — Final room, win condition

### Commands
```
Movement:  north/n, south/s, east/e, west/w, up/u, down/d
Actions:   look/l, examine/ex [object], take/get [item], drop [item]
Inventory: inventory/i, use [item], combine [item] with [item]
System:    help/h, quit/q, save, load
```

---

## Interaction Specification

### Input
- **Keyboard only** (arrow keys for movement, typing for commands)
- **Tab completion** for commands and objects
- **Command history** (up/down arrows)
- **Auto-focus** on input field

### Feedback
- **Sound**: None (pure visual TUI)
- **Haptic**: None
- **Visual**: All feedback through text styling and animations

---

## Acceptance Criteria

1. ✅ Game launches and displays beautiful TUI
2. ✅ Player can navigate all 8 rooms
3. ✅ Items can be picked up, dropped, and used
4. ✅ Puzzles are solvable
5. ✅ Win condition triggers ending sequence
6. ✅ Renders at 60 FPS on modern hardware
7. ✅ Uses SIMD for text processing
8. ✅ Responsive to terminal resize
9. ✅ < 10MB memory footprint
10. ✅ Clean shutdown on Ctrl+C