Dungeon Crawl Stone Soup: what the crawl/crawl repository actually contains

What problem crawl/crawl solves, and for whom

Dungeon Crawl Stone Soup is a finished game, not a framework. The repository exists so that the game can be built from source, translated, extended with new levels, and patched by contributors. The README describes it as "a game of dungeon exploration, combat and magic, involving characters of diverse skills, worshipping deities of great power and caprice." That sentence is the whole product description; there is no library surface to integrate against.

The audience is therefore narrow and specific. Players who only want to play are told to download builds for Linux, Windows and OS X from crawl.develz.org, or to play online in a browser or over SSH. The repository is for people who want to compile the game, write vaults, add monster speech or item descriptions, draw tiles, or submit patches. The contributor's guide at crawl-ref/docs/develop/contribution-process.md is the entry point for that work, and the README warns that large changes should be discussed with the development team before a pull request is opened.

How the C++ engine, Lua vaults and data files fit together

The top level of the repository is thin: .github/, .gitignore, .gitmodules, .mailmap, LICENSE, README.md, SECURITY.md, codecov.yml and crawl-ref/. Almost everything lives under crawl-ref/, which holds the INSTALL.md file, the source directory, the docs directory and the dat directory referenced by the README.

The engine is C++ and links several third-party libraries listed in the README: Lua for in-game functionality and user macros, PCRE for regular expressions, SQLite as a database engine, SDL and SDL_image for tiles display, and libpng for tiles image loading. Lua is not only embedded for macros; the README says the game creates levels by combining hand-made, often randomised maps called vaults, and points contributors at crawl-ref/source/dat/des/arrival/simple.des for examples. That means a large part of the game's content is data, not compiled code, which is why the README claims vaults can be tested on your own system with no compiling needed.

The practical consequence is a split workflow. Changing combat or magic means editing C++ and rebuilding. Adding a level means writing a .des file and loading it. Monster speech follows a separate syntax documented in crawl-ref/docs/develop/monster_speech.txt, and item descriptions live in crawl-ref/source/dat/descript/ with a stated convention: flavour text, no numbers.

Building Dungeon Crawl Stone Soup from source

The README does not inline build steps. It says that for information on how to install the game you should visit the installation documentation, which is crawl-ref/INSTALL.md. Start there, because the dependencies differ per platform and the README only names the libraries, not the package names.

If you want to look at the repository before building anything, clone it and read the install notes first:

git clone https://github.com/crawl/crawl.git
cd crawl
sed -n '1,80p' crawl-ref/INSTALL.md

What you should see is the platform-specific installation documentation the README refers to. The repository has submodules, so a plain clone may leave .gitmodules entries unfetched; check crawl-ref/INSTALL.md for what the build expects before assuming the checkout is complete.

Once the game is running, the README gives three ways in. Pick the tutorial from the in-game menu, read crawl-ref/docs/quickstart.md, or read the full manual at crawl-ref/docs/crawl_manual.rst. There is also an in-game FAQ reachable by typing `?Q`. For item descriptions outside the game, the README points at the dat/descript/ directory; inside the game, `?/` opens the same content.

Where the repository documentation stops

The README is a contributor's front door, not a build manual or an API reference. It never states supported compiler versions, dependency versions, or the exact configure and make invocations for any platform. All of that is deferred to crawl-ref/INSTALL.md, which is not reproduced in the README at all. If you are evaluating the project from the repository page alone, you cannot tell from the README whether your toolchain will work.

The licence situation is also less tidy than the README suggests. The README says Crawl is licensed as GPLv2+ and points to LICENSE for the full text, but the repository metadata reports the licence as NOASSERTION, meaning no standard licence identifier was detected. The bundled libraries carry their own terms, listed in crawl-ref/docs/license/lualicense.txt, crawl-ref/docs/license/pcre_license.txt, the SQLite copyright page, crawl-ref/docs/license/lgpl.txt for SDL and SDL_image, and crawl-ref/docs/license/libpng-LICENSE.txt. If you plan to redistribute a build, those files are the ones to read, and the mismatch between the README's GPLv2+ statement and the repository's NOASSERTION metadata is worth resolving with the project rather than assuming.

A third gap: the README describes an in-game FAQ and a full manual, but neither is a substitute for engine documentation. There is no documented public API for the C++ side, and the README does not claim one.

It is a game, not a component: when to look elsewhere

The clearest limitation is categorical. crawl/crawl does not expose a reusable engine, a modding SDK or a stable interface. If your goal is to embed a roguelike dungeon generator in another application, or to consume procedural level generation as a service, this repository gives you no supported path to do that. You would be reading GPLv2+ C++ and extracting code yourself.

A second limitation is operational. The repository is the development tree, and the README notes that many online servers host the regularly updated development version. That is convenient for players but means the default branch moves; nothing in the README promises that master is stable. Bug reports go to the GitHub issue tracker, and the README explicitly asks that interface or gameplay ideas be discussed before an issue or pull request is opened.

Finally, the data is not plug-and-play outside the game. Vaults are written in the .des format and speech in a syntax the README calls "effective but unusual". Both are documented in the docs directory, and both assume you are loading them into Crawl's own Lua-driven level builder.

A real alternative: Linley's Dungeon Crawl and other roguelike sources

The README states that Crawl is a descendant of Linley's Dungeon Crawl, whose final alpha (v4.1) was released by Brent Ross in 2005, and that the Stone Soup team has continued development since 2006. That lineage is the honest comparison. Linley's Dungeon Crawl is the ancestor codebase, frozen at that 2005 alpha, whereas crawl/crawl is the maintained continuation with modern tiles support through SDL and SDL_image, Lua scripting, and an active contribution process documented in crawl-ref/docs/develop/contribution-process.md.

The difference in approach is not just age. In crawl/crawl, content is deliberately split between C++ and data files, which is why the README can tell vault authors they need no compiler. A project that keeps level generation entirely in code would force every map change through a build. That split is the design decision worth weighing: it lowers the barrier for content contributors and raises the number of file formats a maintainer must keep coherent.

Maintenance, releases and upgrade cost

The repository is not archived, and the last push was on 2026-09-23, one day before this writing. That is a live development tree. The release history shows 0.34.1 on 2026-03-15 as a bugfix release, 0.34.0 on 2026-02-06, and 0.33.1 on 2025-06-06, so point releases arrive between feature releases and the cadence is roughly annual for major versions with fixes in between.

For a contributor, the upgrade cost is the usual one for a long-lived C++ project: your patch has to survive the move from one development version to the next, and the README asks you to discuss large changes with the dev team first. For a player building from source, the cost is re-reading crawl-ref/INSTALL.md when dependencies or platforms change, since the README does not track that detail.

On licensing: the README states GPLv2+ and directs you to LICENSE for the full text. The bundled Lua, PCRE, SQLite, SDL, SDL_image and libpng components each carry separate licence files under crawl-ref/docs/license/. Redistributing a modified build means honouring GPLv2+ and those bundled terms together. That is a factual constraint, not legal advice; check the texts yourself.

Editorial conclusion

Adopt crawl/crawl if you want to build the game from source, write vaults or patches, or study a long-running C++ codebase with Lua data files. Do not adopt it expecting a library, a stable API or packaged binaries; the README points to the download page and INSTALL.md instead. Before you start, read crawl-ref/INSTALL.md for the platform you are on, check crawl-ref/docs/develop/coding_conventions.md before sending a patch, and confirm the GPLv2+ terms in LICENSE against your own distribution plans.

Frequently asked questions

Official sources

1. crawl/crawl on GitHub
2. Issues
3. Project website
4. README
5. Releases