{"id":34315059,"url":"https://github.com/muhammedaksam/opentui-doom","last_synced_at":"2026-05-11T19:02:03.312Z","repository":{"id":328008039,"uuid":"1111648523","full_name":"muhammedaksam/opentui-doom","owner":"muhammedaksam","description":"Play DOOM in your terminal using OpenTUI's framebuffer rendering and doomgeneric WASM","archived":false,"fork":false,"pushed_at":"2026-05-04T17:36:04.000Z","size":11458,"stargazers_count":42,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-04T19:31:19.747Z","etag":null,"topics":["cli","console","doom","doomgeneric","framebuffer","game","opentui","retro","terminal","tui","wasm","webassembly"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@muhammedaksam/opentui-doom","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/muhammedaksam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-07T11:25:46.000Z","updated_at":"2026-04-22T20:20:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/muhammedaksam/opentui-doom","commit_stats":null,"previous_names":["muhammedaksam/opentui-doom"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/muhammedaksam/opentui-doom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muhammedaksam%2Fopentui-doom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muhammedaksam%2Fopentui-doom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muhammedaksam%2Fopentui-doom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muhammedaksam%2Fopentui-doom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/muhammedaksam","download_url":"https://codeload.github.com/muhammedaksam/opentui-doom/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/muhammedaksam%2Fopentui-doom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32908529,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-11T17:09:15.040Z","status":"ssl_error","status_checked_at":"2026-05-11T17:08:45.420Z","response_time":120,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","console","doom","doomgeneric","framebuffer","game","opentui","retro","terminal","tui","wasm","webassembly"],"created_at":"2025-12-17T11:00:33.263Z","updated_at":"2026-05-11T19:02:03.304Z","avatar_url":"https://github.com/muhammedaksam.png","language":"TypeScript","funding_links":[],"categories":["Miscellaneous"],"sub_categories":[],"readme":"[![npm version](https://img.shields.io/npm/v/@muhammedaksam/opentui-doom.svg)](https://www.npmjs.com/package/@muhammedaksam/opentui-doom)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)\n[![Bun](https://img.shields.io/badge/Bun-000?logo=bun\u0026logoColor=fff)](https://bun.sh/)\n[![Alacritty](https://img.shields.io/badge/Alacritty-F46D01?logo=alacritty\u0026logoColor=fff)](https://alacritty.org/)\n[![CI](https://github.com/muhammedaksam/opentui-doom/workflows/CI/badge.svg)](https://github.com/muhammedaksam/opentui-doom/actions)\n[![Mentioned in Awesome OpenTUI](https://awesome.re/mentioned-badge.svg)](https://github.com/msmps/awesome-opentui)\n\n# DOOM for OpenTUI\n\n🎮 Play DOOM in your terminal using [OpenTUI](https://github.com/sst/opentui)'s framebuffer rendering!\n\n## ✨ Features\n\n- **Full DOOM gameplay** in your terminal\n- **High-resolution rendering** using half-block characters (▀) for 2x vertical resolution\n- **Mouse aiming** - Turn and fire with your mouse (enabled by default)\n- **Keyboard input support** with WASD and arrow keys\n- **Save/Load game** support - saves persist to `~/.opentui-doom/`\n- **Sound effects and music** via mpv\n- **WebAssembly powered** - DOOM compiled to WASM via Emscripten\n\n## 📋 Requirements\n\n- **Bun** - JavaScript runtime\n- **Emscripten SDK** - For compiling DOOM to WebAssembly\n- **DOOM WAD file** - Game data (shareware `doom1.wad` is freely available)\n\n## ⚡ Quick Play (via npm)\n\nIf you have [Bun](https://bun.sh/) installed, just download a [doom1.wad](https://distro.ibiblio.org/slitaz/sources/packages/d/doom1.wad) and run:\n\n```bash\nbunx @muhammedaksam/opentui-doom --wad ./doom1.wad\n```\n\n## 🚀 Quick Start (Development)\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/muhammedaksam/opentui-doom.git\ncd opentui-doom\nbun install\n```\n\n### 2. Install Emscripten (if not already installed)\n\n```bash\ngit clone https://github.com/emscripten-core/emsdk.git ~/emsdk\ncd ~/emsdk\n./emsdk install latest\n./emsdk activate latest\nsource ./emsdk_env.sh\n```\n\n### 3. Build DOOM WASM Module\n\n```bash\nbun run build:doom\n```\n\nThis clones [doomgeneric](https://github.com/ozkl/doomgeneric) and compiles it to WebAssembly.\n\n### 4. Get a WAD File\n\nDownload the shareware DOOM WAD:\n\n- [doom1.wad from ibiblio](https://distro.ibiblio.org/slitaz/sources/packages/d/doom1.wad)\n- Or use your own `DOOM.WAD` / `DOOM2.WAD`\n\nPlace the WAD file in the project root.\n\n### 5. Run DOOM\n\n```bash\nbun run dev -- --wad ./doom1.wad\n```\n\nTo disable mouse aiming:\n\n```bash\nbun run dev -- --wad ./doom1.wad --mouse false\n```\n\n### Debug Mode\n\nTo run with debug logging enabled (outputs to `debug.log`):\n\n```bash\nbun run dev:debug -- --wad ./doom1.wad\n```\n\n## 🎮 Controls\n\n| Action            | Keys               |\n| ----------------- | ------------------ |\n| Move Forward/Back | W / S or ↑ / ↓     |\n| Turn Left/Right   | Mouse or ← / →     |\n| Strafe            | A / D              |\n| Fire              | Left Click or Ctrl |\n| Use/Open          | Space              |\n| Run               | Shift              |\n| Weapons           | 1-7                |\n| Menu              | Escape             |\n| Map               | Tab                |\n| Quit              | Ctrl+C             |\n\n## 💾 Save Games\n\nSave games are stored in `~/.opentui-doom/` with DOOM's standard naming:\n\n- Slot 1: `doomsav0.dsg`\n- Slot 2: `doomsav1.dsg`\n- ... up to Slot 6: `doomsav5.dsg`\n\nSaves are automatically synced every 5 seconds and on exit.\n\n## 🔊 Sound\n\nSound effects and music require **mpv** to be installed:\n\n```bash\n# Ubuntu/Debian\nsudo apt install mpv\n\n# macOS\nbrew install mpv\n\n# Arch\nsudo pacman -S mpv\n```\n\nSound files should be placed in the `sound/` directory.\n\n## 🖥️ Recommended Terminal Configuration\n\nFor the best experience, we recommend:\n\n- **Alacritty** terminal emulator\n- **Font size: 5** (for maximum resolution)\n- Maximize your terminal window\n\n## ⚠️ Known Limitations\n\n- **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.\n- **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.\n\n## 🔧 How It Works\n\n```\n┌─────────────────┐    ┌──────────────────┐    ┌────────────────┐\n│  doomgeneric    │───▶│  OpenTUI         │───▶│   Terminal     │\n│  (WASM)         │    │  FrameBuffer     │    │   Display      │\n└─────────────────┘    └──────────────────┘    └────────────────┘\n         ▲                      │\n         │                      │\n         └──────────────────────┘\n              Key Events\n```\n\n1. **DOOM** runs as a WebAssembly module (compiled from C via Emscripten)\n2. Each frame, DOOM renders to a 1280x800 framebuffer\n3. **OpenTUI** reads the framebuffer and converts it to terminal cells using half-block characters\n4. Terminal keyboard input is mapped back to DOOM key codes\n\n## 📁 Project Structure\n\n```\nopentui-doom/\n├── src/\n│   ├── index.ts          # Main entry point\n│   ├── doom-engine.ts    # WASM module wrapper\n│   ├── doom-input.ts     # Keyboard input mapping\n│   └── doom-mouse.ts     # Mouse input handling\n├── doom/\n│   ├── doomgeneric_opentui.c  # Platform implementation\n│   ├── doomgeneric/           # doomgeneric source (cloned during build)\n│   └── build/                 # Compiled WASM output\n├── scripts/\n│   └── build-doom.sh     # Build script\n├── package.json\n└── README.md\n```\n\n## 📝 License\n\n- This project code: MIT\n- DOOM source code: GPL-2.0 (from id Software)\n- doomgeneric: GPL-2.0 (by ozkl)\n\n## 🙏 Credits\n\n- [id Software](https://github.com/id-Software/DOOM) for the original DOOM source release\n- [doomgeneric](https://github.com/ozkl/doomgeneric) for the portable DOOM implementation\n- [OpenTUI](https://github.com/sst/opentui) for the terminal rendering framework\n\n## 🤝 Contributing\n\nContributions are welcome! Please submit pull requests to the `develop` branch.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuhammedaksam%2Fopentui-doom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmuhammedaksam%2Fopentui-doom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmuhammedaksam%2Fopentui-doom/lists"}