⌨️ typense

A minimalist, real-time typing survival game for the terminal.

Overview

typense is a fast-paced typing survival game built entirely for the command line. Inspired by classics like The Typing of the Dead, words fall from the top of your terminal, and you must type them correctly to destroy them before they breach your defenses.

It is built in Go with a strict adherence to simplicity, utilizing a custom low-level terminal engine to deliver smooth, real-time gameplay without the bloat of heavy TUI frameworks.

Features

• Real-time Engine: Frame-independent movement using Delta Time ensures smooth gameplay regardless of your terminal's refresh rate.
• Smart Target Locking: Automatically locks onto the most dangerous enemy matching your first keystroke.
• Dynamic Difficulty: Spawn rates and movement speeds ramp up dynamically as you survive.
• Combo System: String together perfect keystrokes to multiply your score.
• Terminal-Native UX: Gracefully handles terminal resizing with an auto-pause mechanic, and warns if the window is too small.
• Custom Dictionaries: Play with bundled themes or load your own wordlists via CLI flags.

Installation

You can download the pre-built binary file here or build from source:

git clone https://github.com/yourusername/typense.git
cd typense
go build -o typense

Usage

Start the game with the default programming dictionary:

./typense

CLI Options:

# List all built-in dictionary themes
./typense --list

# Play with a specific bundled theme
./typense --theme=networking

# Play with your own wordlist (one word per line)
./typense --use=/path/to/words

Controls:

• [A-Z]: Type to lock onto and destroy incoming words.
• Backspace: Cancel your current target lock.
• ESC: Cancel your current target lock, or Pause the game if no target is locked.
• Ctrl+C: Force quit the game.

Architecture

The codebase is structured around a classic, strictly decoupled Game Loop paradigm:

• state.go: The single source of truth. Defines the GameState and entities (like Enemy). It stores pure data without any behavioral logic.
• main.go: The entry point. Parses CLI flags, initializes the TUI backend, and runs the real-time Delta Time for loop.
• input.go: The controller. Listens for keystrokes, calculates "target locks", tracks combo streaks, and manages UI menu navigation.
• logic.go: The physics engine. Computes frame-by-frame entity movement, collision detection (base defense), and dynamic difficulty ramping.
• renderer.go: The view layer. Translates the abstract GameState into physical ANSI characters, colors, modal overlays, and visual effects (like screen flashing).

Design Philosophy

• Minimalism: The game does exactly one thing and does it well. No unnecessary visual clutter or sprawling feature creep.
• Data-Oriented: We favor flat structs and procedural logic over deep OOP abstraction layers. State is mutated linearly.
• Suckless: Built on top of a highly minimal TUI engine (ttbox). We skip the heavy dependencies (like bubbletea or tview) to retain raw performance and absolute control over the render cycle.
• Readability: The codebase is heavily documented and designed to be read top-to-bottom. It serves as an educational reference for building real-time terminal applications in Go.

Contributing

Contributions are welcome! Whether it's a bug fix, a new built-in dictionary, or a performance tweak, feel free to open a Pull Request.

Please ensure your code aligns with the project's minimalist design philosophy: keep dependencies at zero and avoid over-engineering.

License

This project is licensed under the MIT License - see the LICENSE file for details.