How swarm-game/swarm works
Project type and purpose
• This is a full-stack, multi-component Haskell “monorepo” implementing:
– A 2D programming game engine (Swarm)
– A domain-specific language (DSL) for robot programs
– Scenario and topography libraries to describe worlds
– Multiple front-ends (CLI game, TUI, web UI, tournament server)
– Developer tools (doc generator, editor plugins, scripts)
• The README describes Swarm as a 2D resource-gathering game with programmable robots.
Break down the file structure into logical components
A. Core libraries (in src/)
• swarm-util: shared utilities (JSON/YAML, graph, lens, etc.)
• swarm-scenario: scenario definitions, parsing, validation
• swarm-topography: world layout, navigation, structure recognition
• swarm-engine: heart of the game loop, robot execution, achievements, scoring
• swarm-lang: DSL for writing robot programs (parser, typechecker, LSP)
• swarm-doc: documentation generator for commands & schema
• swarm-tournament: back-end logic for tournament server (REST API, DB)
• swarm-tui: terminal UI front-end
• swarm-web: web UI rendering & server
B. Executables (in app/)
• app/game: the main Swarm game CLI (invokes engine + UI layer)
• app/tournament: tournament server front end
• app/scene, app/doc: support tools (scene renderer, doc CLI)
C. Static assets and data
• data/: YAML scenario files, JSON schemas, text resources, images
• web/, tournament/web/: static HTML/JS/CSS for front-end UIs
D. Developer tooling
• scripts/: build, test, CI automation, normalization scripts
• editors/: Emacs, Vim, VSCode integrations
• test/: unit, integration, benchmark suites
Inter-component relationships
• Core libraries form a layered dependency graph:
swarm-util ← swarm-scenario ← swarm-engine ← app/game
swarm-util ← swarm-scenario ← swarm-lang ← app/game
swarm-util ← swarm-scenario ← swarm-topography ← swarm-engine
…and so on for doc, tournament, tui, web
• Data files (YAML, JSON) are loaded at runtime by swarm-scenario or engine.
• app/game chooses a UI: TUI (via swarm-tui) or web UI (via swarm-web).
• Tournament server (app/tournament) exposes REST endpoints, persists to SQLite.
• Editor plugins and LSP server (in swarm-lang) communicate via Language Server Protocol.
Key architectural patterns and principles
• Modular library design: small focused Haskell packages, each with clear responsibilities
• Layered dependencies: util → scenario → language/engine → front ends
• Data-driven world definitions: YAML scenarios + JSON schemas
• Pluggable UIs: swap TUI, web, or headless modes
• CLI + server executables all composed from core libraries
Diagramming conventions
• Libraries (e.g., blue rectangles)
• Executables/servers (e.g., green)
• Data stores/files (e.g., yellow)
• Scripts/plugins (e.g., gray)