{"id":14240631,"url":"https://github.com/cryptocode/terminal-doom","last_synced_at":"2026-04-26T21:03:24.547Z","repository":{"id":249684876,"uuid":"832216942","full_name":"cryptocode/terminal-doom","owner":"cryptocode","description":"Play DOOM in modern terminals","archived":false,"fork":false,"pushed_at":"2026-01-27T11:10:48.000Z","size":14166,"stargazers_count":376,"open_issues_count":2,"forks_count":15,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-01-27T23:14:01.936Z","etag":null,"topics":["doom","game","terminal","zig"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cryptocode.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"licenses/LICENSE-gpl","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-07-22T14:55:50.000Z","updated_at":"2026-01-27T11:10:53.000Z","dependencies_parsed_at":"2024-07-22T19:10:51.614Z","dependency_job_id":"7c1f4036-df2f-46b0-b0db-8ffa61db35fd","html_url":"https://github.com/cryptocode/terminal-doom","commit_stats":null,"previous_names":["cryptocode/terminal-doom"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/cryptocode/terminal-doom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptocode%2Fterminal-doom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptocode%2Fterminal-doom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptocode%2Fterminal-doom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptocode%2Fterminal-doom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cryptocode","download_url":"https://codeload.github.com/cryptocode/terminal-doom/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cryptocode%2Fterminal-doom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32312507,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T19:15:34.056Z","status":"ssl_error","status_checked_at":"2026-04-26T19:15:15.467Z","response_time":129,"last_error":"SSL_read: 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":["doom","game","terminal","zig"],"created_at":"2024-08-21T10:01:29.902Z","updated_at":"2026-04-26T21:03:24.541Z","avatar_url":"https://github.com/cryptocode.png","language":"C","readme":"![terminaldoom](https://github.com/user-attachments/assets/c39a2764-4147-464e-9517-64f352cebbc0)\n\nTerminal Doom enables Doom-based games to play smoothly in modern terminals with original graphics and sound. It also works\nover fast ssh connections.\n\nDemo with sound:\n\n[![Demo]](https://github.com/user-attachments/assets/8ca127d7-23f6-45cd-82e9-49c51c4cdc42)\n\n## Building\nThere are no system dependencies. Just clone and build with Zig v0.16:\n\n`zig build -Doptimize=ReleaseFast`\n\nRun with `zig-out/bin/terminal-doom`\n\nTo build with older versions of Zig, please use the corresponding git tag.\n\nTerminal Doom uses the [libvaxis Zig library](https://github.com/rockorager/libvaxis) to render and handle keyboard and mouse events.\nIf you ever want to make a TUI app, I highly recommend this library. \n\n### Sound support\nSound is enabled by default. Add the `-Dsound=false` if you want to compile without sound support (like when running on a remote server via ssh)\n\nAll sound effects are included, and a few music tracks. You can download and add additional music tracks (mp3) yourself.\nTerminal Doom will automatically pick them up from the `sound` directory. See the sound section for naming.\n\n### Where does it run?\nTested on macOS and Linux. Compiles on Windows as well, but no terminal there seems to run it (WezTerm likely gets closest in ssh local mode)\n\nCurrently works best in [Ghostty](https://ghostty.org/) and [Kitty](https://sw.kovidgoyal.net/kitty/) as these have solid implementations of the required specs. [WezTerm](https://wezfurlong.org/wezterm/index.html) works if you use 'f' instead of ctrl keys for firing the gun.\n\n## Playing\nYou can play keyboard-only (recommended) or in combination with a mouse. You can disable/enable mouse at any time by pressing `m`. This is useful when playing with keyboard on a laptop to avoid spurious input from the trackpad.\n\nWhen using a mouse, make sure you adjust sensitivity in the Options menu if it's too fast or slow. Also try adjusting sensitivity on your mouse if it has buttons for this. Once sensitivity is right, playing with a mouse/keyboard combo is pretty efficient.\n\nKeep in mind that mouse support in terminals comes with limitations, as apps are not able to capture the mouse.\n\n| Action                    | Keys/Mouse Actions                  |\n|---------------------------|-------------------------------------|\n| Menu                      | ESC to open/close, Enter to select  |\n| Walk / rotate             | Arrow keys or mouse. `j`, `l` also rotates.|\n| Walk / strafe             | `wasd`                              | \n| Fire                      | `f`, `i`, control keys, mouse click |\n| Use/open                  | Spacebar, right mouse click         |\n| Strafe left/right         | Alt+arrow keys, `a`, `d`            |\n| Quit                      | `Ctrl+c`                            |\n| Disable/enable mouse      | `m`                                 |\n| Disable/enable scaling    | `u`                                 |\n\nMost other Doom keys should work as well, such as Tab for map and F5 for adjusting detail level.\n\n## How it works\n\n## Rendering\nWhile the Kitty graphics protocol is primarily intended to display images, modern terminals and\ncomputers are *fast*, with high memory bandwidth, SIMD support, and discrete GPUs. There's plenty\nof juice available to run this classic game smoothly over a text protocol.\n\nHere's how it works: on every frame, doomgeneric calls `DG_DrawFrame`. Our job is now to turn\nthe pixel data into a base64 encoded payload. This payload is then split into 4K chunks,\neach chunk wrapped by the Kitty protocol envelope. Actually, some terminals work without\nchunking, which is even faster, but that's not spec compliant and e.g. Kitty itself fails\nwithout chunking (thanks to rockorager for pointing this out)\n\nWith the encoded message ready, we now:\n\n1. Set synchronized output (mode 2026)\n2. Clear the screen\n3. Display the frame by sending the Kitty graphics message\n4. Reset synchronized output to flush updates to screen\n5. Handle any keyboard input\n\nWith the latest version, all of this is outsourced to libvaxis.\n\nThis sequence repeats for every frame. While this is enough to run Doom smoothly in a modern terminal, there are many optimizations that can be done, including SIMDifying pixel encoding.\n\n## Sound\nThe history of Doom has many interesting facets, and its sound library is no different. You can read about it [here](https://doomwiki.org/wiki/Origins_of_Doom_sounds)\n\nTerminal Doom's sound support originally worked by calling out to SDL2, but that had a couple of problems. First of all, the implementation\nfrom doomgeneric was complicated and large. Second, depending on SDL2 made building harder on some systems.\n\nThis is the solution I came up with:\n\n1. Ditch all the complex midi sequencing and mixing logic.\n2. Make the wav and mp3 files part of the project\n3. Outsource playback to *miniaudio*\n\nWhile large, miniaudio is a single header file, it's portable, and has a straightforward API.\n\n### Adding additional music tracks\nTerminal Doom ships with a few tracks, such as for the intro and the first level.\nYou can add additional mp3's to the `sound` directory. For Terminal Doom to pick these up, they must be named\naccording to the Doom convention:\n\n```\nd_e1m1.mp3\nd_e1m2.mp3\nd_e1m3.mp3\nd_e1m4.mp3\nd_e1m5.mp3\nd_e1m6.mp3\nd_e1m7.mp3\nd_e1m8.mp3\nd_e1m9.mp3\nd_inter.mp3\nd_intro.mp3\nd_victor.mp3\n```\n\nThe actual content of these can obviously be anything you want, not just the orginal music.\n\n## Supported games\n`doom1.wad` is included in the repository and other wad files are available on various online sites.\n\nThese should all work:\n\n```\ndoom2.wad\nplutonia.wad\ntnt.wad\ndoom.wad\ndoom1.wad\nchex.wad\nhacx.wad\nfreedm.wad\nfreedoom2.wad\nfreedoom1.wad\n```\n\n## Credits\n* The engine is based on the amazing [doomgeneric](https://github.com/ozkl/doomgeneric) project\n* Rendering and input is handled by [libvaxis](https://github.com/rockorager/libvaxis), a TUI library written in Zig\n* Sound is handled by [miniaudio](https://miniaud.io/), a single-file sound playback library\n* Build system (and the main input/rendering loop) is all [Zig](https://ziglang.org/)\n* Testing and debugging in Ghostty's terminal inspector, Kitty, and WezTerm\n\n## LICENSE\nAs Terminal Doom is based on the doomgeneric project, the project as a whole is licensed under GPL2.\n\nThe Zig-based renderer/handler, build file, and miniaudio bridge are licensed under MIT.\n","funding_links":[],"categories":["C","\u003ca name=\"games\"\u003e\u003c/a\u003eGames"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcryptocode%2Fterminal-doom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcryptocode%2Fterminal-doom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcryptocode%2Fterminal-doom/lists"}