Swarm: a Haskell game where you program robots to gather resources

Programs as objects you place in a world, not code you run

Swarm is described as a 2D programming and resource gathering game. The short version of the loop is that you program your robots to explore the world and collect resources, which in turn allows you to build upgraded robots that can run more interesting and complex programs.

That is the whole design in one sentence, and it is worth unpacking, because the game is not a programming language tutorial with a wrapper around it. The robots are entities in a world. They execute the program you give them. The program is the thing that decides what happens when the robot encounters a tree, a log, a resource or another robot.

The tutorial image in the project documentation shows a world after scanning a tree and making a log, which tells you what the first loop looks like: move, perceive, act on what was perceived, and the world changes as a result.

The progression is what gives the game a spine. Resources gathered early let you build upgraded robots, and upgraded robots can run programs that would be pointless for the starting robot. So a level that asks you to gather wood is teaching you the mechanics, and the later levels are teaching you to compose the same primitives into something more capable.

The audience is people who enjoy programming as a puzzle. The language the player writes is a small, purpose-built game language rather than a general purpose one, which is what makes the puzzles solvable and the programs short enough to read on screen.

The example scripts are the fastest way to read the language

The example/ directory is the most useful part of the repository for anyone who wants to understand the language quickly, because it contains small complete programs that each demonstrate one idea.

Reading them tells you a lot about what the language is for. BFS-clear and dfs are classic traversal problems, which means the language supports recursion and queues. Fact is the smallest possible recursion exercise. List and rectypes deal with the shape of data, and recursive-containers suggests that the language supports containers of containers. Omega points at the fixed point combinator, so recursion is a first class concern rather than an afterthought.

Wander and cat are the behavioural ones, where the program reacts to what a robot senses. Pilotmode is the one to look at if you want to know how a robot can be driven semi-automatically rather than purely by program, and multi-key-handler covers input handling in a world where several things can be pressed at once.

There is also an example/long_import/ directory, which by name suggests a program split across several files, a hint that the language has an import mechanism and that larger programs are expected to be modular.

Because these are files rather than documentation snippets, they are also runnable. The most efficient way to learn the language is to open one, change a constant, and see what the world does differently.

A Haskell codebase with the usual quality tooling wired in

The primary language of the repository is Haskell and the build is a Cabal package, with swarm.cabal at the root. The project also publishes to Hackage, and the badge points at the swarm package there.

The root directory carries the tooling you would expect in a serious Haskell project, and the file names say a lot about the standards being applied.

There is fourmolu.yaml, which configures the Fourmolu formatter, the successor to Ormolu for Haskell formatting. There is .hlint.yaml, configuring HLint, the linter that finds suspicious code patterns rather than style issues. There is .stan.toml for Stan, a static analysis tool for Haskell, and weeder.toml for Weeder, which finds unused code and exports by running the program and observing what it actually uses.

Weeder is the interesting one to see in a game project, because it answers the question that matters for a large Haskell codebase: is this module still needed? It works by instrumenting the program and watching which functions get called, so a module nobody exercises shows up as dead. That kind of check is what keeps a project with an extensive content directory from accumulating unused content code.

There is also a .stan.toml, a .git-blame-ignore-revs file for keeping history clean when a large reformat lands, .vscode/ for editor configuration, and a .all-contributorsrc that generates the contributors table in the readme.

The CI runs through a haskell-ci workflow, named haskell-ci.yml in the build badge. That tool generates the matrix of compiler and dependency combinations, which for a Haskell project means the build is verified across a range of GHC versions rather than one, and that is a meaningful guarantee for anyone depending on the package.

Content, editors, web and the tournament directory

The repository layout shows that Swarm is more than a game engine with a bit of content.

There is a data/ directory, which holds the game content, and a scenarios directory for the puzzle definitions. There is app/ for the application layer and src/ for the library code, so the game engine is a library and the executable sits on top of it, which is the right split for something that also runs headless for tests.

The editors/ directory suggests editor integration, and with a tournament/ directory alongside it, the project has competitive infrastructure as well. A tournament directory in a programming game is a strong signal about intent: it means there is a way to run submissions headlessly and compare them, which is what makes the game a serious practice platform rather than a toy.

There is a web/ directory and a scripts/ directory, and the project documentation lives at swarm-game.github.io. The docs/ directory holds the documentation sources, and DESIGN.md at the root holds the design document, which is the file to read if you want the author's reasoning rather than the user-facing description. COMMUNITY.md sits next to it and presumably describes how the community works, which is unusual to find at the root of a game repository and suggests the project treats its contributors and players as a community with rules.

The contributor table in the readme is generated by the all-contributors tool and lists people against roles such as bug reports, code, design, documentation, ideas, infrastructure, research, tests and tutorials. Brent Yorgey appears with the widest set of roles, spanning design, maintenance and research as well as code and tutorials.

For an open source game, that role breakdown is the real signal about what kind of project this is. Content authoring and design are treated as contributions on a par with writing Haskell.

Release cadence, licence and what the readme does not tell you

The release history shows a steady version series with three components per release: 0.6.0.0 on 2024-07-15, 0.7.0.0 on 2025-06-07 and 0.8.0.0 on 2025-11-16. The four-part version numbers are the Haskell convention for a Cabal package, where the components encode major, minor, patch and a further level used when the package's own API changes.

The last push was on 2026-10-17, so the tree is being worked on even though the newest tagged release in the list is from November 2025. That gap is normal for a project that works continuously and tags releases when a version is worth cutting, and it does mean the running game and the released package are not always the same thing.

The licence field on the repository says Other, a custom licence GitHub cannot classify, with a pointer to the LICENSE file. There is also a NOTICE file at the root, which usually accompanies an attribution obligation or records third-party content. For a project with a large content directory, a NOTICE file often means that level content carries its own terms, so anyone planning to reuse the content separately from the code should read both files. This is not legal advice.

What the visible documentation does not say is as important as what it does. There is no install command, no build instruction and no mention of the GHC version required. The readme points to the website for more information and links CONTRIBUTING.md for the various ways to contribute, which is where the setup detail presumably lives. So before trying to build from source, the site and that file are the places to look, and the Hackage package is the more predictable starting point if you want to use the library rather than run the game.

For a Haskell library consumer, the split between src/ and app/ is the thing to check. If the engine is exposed as a library on Hackage, you could build tools on the world model. If it is not, then the realistic use is running the game.

Where Swarm is the wrong tool

There are two clear cases where this is the wrong choice, and one where it is merely unusual.

The first wrong choice is using it as a general Haskell library. It is a game with a game-specific language, a content directory and a custom licence. Nothing about the package suggests it is intended as a foundation for other software, and depending on it the way you would depend on a parsing library is a misreading of what it is.

The second wrong choice is expecting a production-grade engine. The build badge covers compiler and dependency combinations, which tells you the code compiles broadly, but the visible documentation says nothing about performance characteristics, memory behaviour under large scenarios, or whether the world format is stable across versions. The scenario format in particular is the kind of thing that changes when the game design changes, and a scenario file written for 0.7 may not load in 0.9. Anyone building tooling around the scenario format should assume it will need adjusting.

The unusual case is playing it as a general audience game. Swarm is a programming game, so its audience is people who are comfortable reading and writing small programs. The visual style is a 2D world of tiles and entities rather than a rendered 3D or illustrated world, and the interaction model is typing a program and watching what a robot does. That is a deliberate choice for a teaching tool, and it works well for that purpose, but it is not what someone looking for a story game is looking for.

What it does replace is worth stating as a contrast. A conventional puzzle game gives you a sequence of puzzles. Swarm gives you a machine that executes the programs you write, which means the puzzles have to be written in terms of the machine's actual capabilities, and a solution that works in one level may behave differently in another because the robot is the same robot. That is the difference in kind, not in polish.

Editorial conclusion

Swarm suits a Haskell developer who wants a playful way to think about programs as behaviour, or a teacher who needs a small language with an obvious visual payoff, and the example scripts give you a working starting point in a dozen lines each. It does not suit someone looking for a production Haskell library, since the package is a game with a custom licence, and the visible documentation says nothing about how to install and run it beyond pointing at the website and Hackage. Before committing to it, read the DESIGN.md and COMMUNITY.md files in the repository root, because they describe the game's own model and its community expectations more clearly than the short readme does.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. swarm-game/swarm on GitHub