test_tui/SPEC.md

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