opentui-doom

Play DOOM in your terminal using OpenTUI's framebuffer rendering and doomgeneric WASM

Comment

npm version License: MIT TypeScript Bun Alacritty CI Mentioned in Awesome OpenTUI

DOOM for OpenTUI

🎮 Play DOOM in your terminal using OpenTUI's framebuffer rendering!

✨ Features

  • Full DOOM gameplay in your terminal
  • High-resolution rendering using half-block characters (▀) for 2x vertical resolution
  • Mouse aiming - Turn and fire with your mouse (enabled by default)
  • Keyboard input support with WASD and arrow keys
  • Save/Load game support - saves persist to ~/.opentui-doom/
  • Sound effects and music via mpv
  • WebAssembly powered - DOOM compiled to WASM via Emscripten

📋 Requirements

  • Bun - JavaScript runtime
  • Emscripten SDK - For compiling DOOM to WebAssembly
  • DOOM WAD file - Game data (shareware doom1.wad is freely available)

⚡ Quick Play (via npm)

If you have Bun installed, just download a doom1.wad and run:

bunx @muhammedaksam/opentui-doom --wad ./doom1.wad

🚀 Quick Start (Development)

1. Clone the Repository

git clone https://github.com/muhammedaksam/opentui-doom.git
cd opentui-doom
bun install

2. Install Emscripten (if not already installed)

git clone https://github.com/emscripten-core/emsdk.git ~/emsdk
cd ~/emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh

3. Build DOOM WASM Module

bun run build:doom

This clones doomgeneric and compiles it to WebAssembly.

4. Get a WAD File

Download the shareware DOOM WAD:

Place the WAD file in the project root.

5. Run DOOM

bun run dev -- --wad ./doom1.wad

To disable mouse aiming:

bun run dev -- --wad ./doom1.wad --mouse false

Debug Mode

To run with debug logging enabled (outputs to debug.log):

bun run dev:debug -- --wad ./doom1.wad

🎮 Controls

Action Keys
Move Forward/Back W / S or ↑ / ↓
Turn Left/Right Mouse or ← / →
Strafe A / D
Fire Left Click or Ctrl
Use/Open Space
Run Shift
Weapons 1-7
Menu Escape
Map Tab
Quit Ctrl+C

💾 Save Games

Save games are stored in ~/.opentui-doom/ with DOOM's standard naming:

  • Slot 1: doomsav0.dsg
  • Slot 2: doomsav1.dsg
  • ... up to Slot 6: doomsav5.dsg

Saves are automatically synced every 5 seconds and on exit.

🔊 Sound

Sound effects and music require mpv to be installed:

# Ubuntu/Debian
sudo apt install mpv

# macOS
brew install mpv

# Arch
sudo pacman -S mpv

Sound files should be placed in the sound/ directory.

🖥️ Recommended Terminal Configuration

For the best experience, we recommend:

  • Alacritty terminal emulator
  • Font size: 5 (for maximum resolution)
  • Maximize your terminal window

⚠️ Known Limitations

  • Multi-key input: Terminals only send key repeat events for one key at a time. Holding W to move forward will stop when you press arrow keys to turn. This is a terminal limitation, not a bug.
  • No Kitty keyboard protocol: While OpenTUI supports the Kitty keyboard protocol for proper key release events, it didn't work as expected in my testing. Currently using timeout-based key release as a workaround.

🔧 How It Works

┌─────────────────┐    ┌──────────────────┐    ┌────────────────┐
│  doomgeneric    │───▶│  OpenTUI         │───▶│   Terminal     │
│  (WASM)         │    │  FrameBuffer     │    │   Display      │
└─────────────────┘    └──────────────────┘    └────────────────┘
         ▲                      │
         │                      │
         └──────────────────────┘
              Key Events
  1. DOOM runs as a WebAssembly module (compiled from C via Emscripten)
  2. Each frame, DOOM renders to a 1280x800 framebuffer
  3. OpenTUI reads the framebuffer and converts it to terminal cells using half-block characters
  4. Terminal keyboard input is mapped back to DOOM key codes

📁 Project Structure

opentui-doom/
├── src/
│   ├── index.ts          # Main entry point
│   ├── doom-engine.ts    # WASM module wrapper
│   ├── doom-input.ts     # Keyboard input mapping
│   └── doom-mouse.ts     # Mouse input handling
├── doom/
│   ├── doomgeneric_opentui.c  # Platform implementation
│   ├── doomgeneric/           # doomgeneric source (cloned during build)
│   └── build/                 # Compiled WASM output
├── scripts/
│   └── build-doom.sh     # Build script
├── package.json
└── README.md

📝 License

  • This project code: MIT
  • DOOM source code: GPL-2.0 (from id Software)
  • doomgeneric: GPL-2.0 (by ozkl)

🙏 Credits

🤝 Contributing

Contributions are welcome! Please submit pull requests to the develop branch.

Share this project:

Updates