gitwtfhub

wtf is doomql?

petergpt/doomql — explained in plain English

Analysis updated 2026-05-18

54PythonAudience · developerComplexity · 2/5LicenseSetup · easy

TL;DR

DOOMQL is a terminal first-person shooter game where SQL queries, not a game engine, calculate movement, combat, and every pixel drawn on screen.

Mindmap

mindmap
  root((doomql))
    What it does
      Terminal FPS game
      SQL renders every pixel
      Python only transports input
      Live SQL audit tool
    Tech stack
      Python
      SQLite
      SQL
      Make
    Use cases
      Play the game
      Study SQL as an engine
      Watch live query audit
    Audience
      Developers
      SQL enthusiasts

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Why would anyone build with this?

REASON 1

Play a Doom-like first-person shooter directly in a terminal window.

REASON 2

Study an unusual example of using SQL as a full game engine and renderer.

REASON 3

Watch a live, read-only SQL audit tool alongside gameplay to see exactly what queries produced each frame.

What's in the stack?

PythonSQLiteSQLMake

How it stacks up

petergpt/doomqlforsy-ai/forsy-trace-skilluseknockout/api
Stars545454
LanguagePythonPythonPython
Setup difficultyeasyeasyeasy
Complexity2/52/52/5
Audiencedeveloperresearcherdeveloper

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · easy Time to first run · 5min

Needs Python 3.11+, a recent SQLite version, and a terminal with 24-bit color and Unicode support.

Use freely for any purpose, including commercial use, as long as you keep the copyright notice.

Wtf does this do

DOOMQL is a playable, first-person shooter game that runs in your terminal, built around one strange idea: the game logic and every pixel on screen are produced by SQL queries running inside SQLite, not by a traditional game engine. Python is only used to read your keyboard input and print the finished picture to the screen, it does not draw anything or decide what happens in the game. Each frame of the game is generated by SQL statements that calculate player movement, collisions, enemy behavior, combat, doors, pickups, and even the exact color of every pixel. A second SQL query turns those pixel values into colored blocks that your terminal can display. The project includes a companion tool called an inspector, which opens a read-only view of the same live database so you can watch, in real time, the exact SQL statements responsible for what is happening on screen as you play, without affecting the game itself. To play, you need a Unix-like system such as macOS or Linux, or Windows using WSL, along with Python 3.11 or newer, a recent version of SQLite, and a terminal that supports 24-bit color and Unicode characters. There are no other software dependencies to install. You start the game with a single command from the project folder, and the objective is to find a token, unlock a gate, defeat an enemy, and reach a portal, while fighting off other enemies along the way. The project describes itself as an original Doom-like game rather than a port of the real Doom, and it contains none of that game's original code, data, or artwork. It includes a fairly large test suite covering gameplay, rendering accuracy, and the boundary rule that the Python code must never contain game logic. DOOMQL is released under the MIT License, which is a permissive open source license that allows free use, including commercial use.

Yoink these prompts

Prompt 1
Explain how DOOMQL uses SQL queries to calculate movement, collisions, and pixel colors instead of a traditional game engine.
Prompt 2
Walk me through setting up DOOMQL on macOS or Linux, including the Python and SQLite version requirements.
Prompt 3
How does the DOOMQL inspector tool show a live SQL audit without changing the running game state?
Prompt 4
Write a summary of the sql/tick.sql and sql/003_render.sql files and what each one is responsible for.

Frequently asked questions

wtf is doomql?

DOOMQL is a terminal first-person shooter game where SQL queries, not a game engine, calculate movement, combat, and every pixel drawn on screen.

What language is doomql written in?

Mainly Python. The stack also includes Python, SQLite, SQL.

What license does doomql use?

Use freely for any purpose, including commercial use, as long as you keep the copyright notice.

How hard is doomql to set up?

Setup difficulty is rated easy, with roughly 5min to a first successful run.

Who is doomql for?

Mainly developer.

View the repo → Decode another repo

This repo across BitVibe Labs

Don't trust strangers blindly. Verify against the repo.