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:

• doom1.wad from ibiblio
• Or use your own DOOM.WAD / DOOM2.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

• id Software for the original DOOM source release
• doomgeneric for the portable DOOM implementation
• OpenTUI for the terminal rendering framework

🤝 Contributing

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