Skip to content

Module guide

Jump to bottom Edit New page
Brent Yorgey edited this page Oct 27, 2025 · 41 revisions

The Swarm codebase has gotten large enough to be quite intimidating at first glance (currently, as of May 2024, 28K SLOC across 224 modules). This page contains a (work-in-progress) guide to help orient developers to the codebase.

To help with organization and enforce modularity, the codebase is first broken into a number of sublibraries, listed below. Click on a sublibrary to jump to the section outlining its contents.

swarm-util

The swarm-util sublibrary contains various miscellaneous utilities which are used throughout the Swarm codebase.

swarm-lang

The swarm-lang library contains definitions and tools for working with the Swarm programming language. Unless otherwise noted all module names listed below begin with Swarm.Language.

graph

  • Syntax
    • Types: Swarm language types and utilities for working with them.
    • Direction: directions (right, left; north, south; etc.)
    • Syntax: the main module defining the abstract syntax of the Swarm language.
  • Parsing
    • Parser: defines top-level function readTerm for parsing an expression of the Swarm language, returning an AST annotated with source locations and comments.
    • Parser.*: various components of the parser:
      • Util: parsing utilities
      • Core: core parser definitions + utilities
      • Lex: lexing/tokenizing
      • Record: parsing records at both the type and term level
      • Type: parsing Swarm language types
      • Term: parsing Swarm language terms
      • Comment: re-inserting comments into the parsed AST
    • Key: data type, parsing + pretty printing for keys (i.e. key presses).
  • Checking
    • Context: mappings from variables to information about them (types, requirements, ...)
    • Module: a module is a typechecked term together with a context of names defined in that term.
    • Capability: definition of capabilities needed to use certain commands or language features.
    • Requirement: type and functions for dealing with requirements, i.e. what is needed to be able to build a robot executing a certain program. Includes capabilities as well as inventory.
    • Typed: values packaged together with their type and requirements.
    • Typecheck: the main type checking + inference algorithm.
    • unification, i.e. solving equations between types:
  • Elaborate: term elaboration that happens after type checking.
  • Pipeline: the entire term processing pipeline: parse -> type check -> requirements analysis -> elaborate.
  • Pretty: pretty-printing for the Swarm language.
  • Value: runtime values.
  • LSP.*: implementation of the Language Server Protocol.

swarm-topography

  • Location: Types and utilities for representing user-facing (x,y) locations and headings.
  • Universe: Types and utilities for working with "universal locations", i.e. locations together with a particular "subworld". Scenarios can have multiple "subworlds", each with its own independent 2D coordinate system.
  • World.Coords: Types and utilities for working with internal world coordinates, which are stored in (row, column) order and used to internally address things like load tiles and view chunks.
  • Scenario.Topography.*: code for defining and working with scenario topography, including structures and waypoints.

swarm-scenario

graph

This package has a lot of code for describing scenarios, including maps, entities, terrain, and robots. Scenarios have lots of optional features, so there is a lot of stuff here.

First, some miscellaneous modules.

All the rest of the modules live under the Swarm.Game namespace.

  • Entities + terrain:
    • Display: A Display tracks information needed to render terrain and entities in a single cell.
    • Terrain: Each cell in the world has an inherent terrain type (rock, ice, grass, etc.). This module has code for dealing with terrain: terrain types, terrain maps, and parsing + loading terrain data.
    • Entity: An Entity represents an object that exists in the world. Each entity has a way to be displayed, some metadata such as a name and description, some properties, and possibly an inventory of other entities. This module also defines the Inventory type, since the two types are mutually recursive (an inventory contains entities, which can have inventories).
    • Device: A "device" is an entity that provides one or more capabilities. This module defines types and utilities for keeping track of which entities provide which capability and vice versa.
    • Ingredients, Recipe: A recipe represents some kind of process for transforming some input entities into some output entities.
    • Land: Puts together terrain + entities.
  • Cosmetic.*: describing the appearance of things: colors, attributes, Display records, and texels.
  • State.Config: a record containing information needed when creating a new GameState at the start of a scenario.
  • State.Landscape: all information about the world tracked during play: multiple parallel worlds, terrain, entities, structure recognizer automata, etc.
  • Robots
    • Robot: the main data type to represent robots.
    • Robot.Walk: robot-specific exceptions to what can and cannot be walked on.
  • World
    • World.DSL.*: Code to parse, typecheck, and interpret the world map description DSL.
    • World.*: Code to represent worlds as functions from coordinates to terrain + entities, to lookup and update information in worlds, and for loading + storing worlds by tiles.
  • Achievement.Definitions: types to represent achievements.
  • Scenarios
    • Scenario: definition of Scenario record type + related types, and code for parsing + loading scenarios from disk.
    • Scenario.*: various subrecords of the Scenario record type.

swarm-engine

This package defines the runtime game simulation code.

  • Swarm.Log: log messages, for both robot logs and the system log.

All the rest of the modules live in the Swarm.Game.* namespace:

  • Tick: type and utility functions for in-game tick counts
  • Achievement.*: in-game achievements: types, descriptions, and serializing to/from disk.
  • Popup: Popup notifications (for things like achievements, unlocked recipes or commands, etc.).
  • Value: Utilities for converting native Haskell values to corresponding Swarm.Language.Value values.
  • Exception: Runtime swarm-language exceptions.
  • CESK: CESK machines which form the basis of the Swarm robot runtime system.
  • Robot.Activity: tracking monitoring statistics (tick budget, step count, command histogram, etc.) for running robots.
  • Robot.Concrete: concrete, instantiated (as opposed to template) robots.
  • ScenarioInfo: saving and loading info about scenarios (status, path, etc.) as well as recursively loading scenario collections.
  • Scenario.*: various runtime scenario processing code: checking win conditions, scoring, tracking play status.
  • State: the GameState record which tracks all runtime game state. A new GameState is created every time the player starts a new scenario.
    • State.Initialize: creating an initial GameState record when starting a scenario.
    • State.Redraw: Keeping track of which parts of the world view need to be redrawn.
    • State.Robot: dealing with runtime sets of robots (active, inactive, waiting, etc.) + other related things.
    • State.Robots.Internal: GameState subrecord storing all the robots, along with some lenses that break internal invariants.
    • State.Substate: Various subrecords of GameState, split out into a separate module.
    • State.ViewCenter.Internal: The "view center" keeps track of what the user is viewing, i.e. where we should center the world viewport.
    • State.Runtime: The RuntimeState record is not part of the GameState, but stores non-UI-specific, persistent state (i.e. state that persists across multiple scenarios).
  • Step: this module is way too large, and contains code for stepping robot CESK machines along with a bunch of other related things. Stepping the CESK machine is in turn broken down into a number of submodules:
    • Step.Const: the biggest submodule, which primarily contains a giant function (execConst) for interpreting all the built-in constants.
    • Step.Util.Command: helper functions used in Step.Const.
    • Step.Arithmetic: Interpreting comparison and arithmetic functions.
    • Step.Combustion: Interpreting the ignite command + creating system robots to carry out + spread combustion.
    • Step.Flood: Implementation of the volume command via flood fill.
    • Step.Path.*: Implementation and utilities for the path command, which does pathfinding.
    • Step.Util: Other utilities. Honestly not sure of the distinction between this module and Step.Util.Command.
    • Step.Validate: Running scenarios to completion and checking for win conditions + errors.

swarm-doc

This package defines code for generating external documentation, such as wiki pages / cheat sheets and editor configuration. All modules live in the Swarm.Doc.* namespace.

  • Command: Generate an abstract matrix of command attributes, for use in generating documentation.
  • Keyword: Collect + generate information on keywords, to be used in generating documentation and testing.
  • Pedagogy: Ensure the tutorials are pedagogically sound, in the sense of introducing commands before they are used.
  • Schema.*: Processing JSON schema files for scenario format.
  • Wiki.*: Generating stuff for the Swarm wiki.
  • Gen: Main module for auto-generating various forms of documentation.

swarm-tui

This package implements the textual user interface (TUI) for the game. All modules live in the Swarm.TUI.* namespace.

  • Border: custom border drawing code that can place labels various places around the border.
  • Panel: custom panel widgets for the UI.
  • List: custom list event handler that skips over separators.
  • Controller
  • Controller.*
  • Editor.*
  • Inventory.*
  • Launch.*
  • Model
  • Model.*
  • View
  • View.*

swarm-web

This package implements the Swarm web service, which can serve various static information about a running game.

Add a custom footer
Add a custom sidebar
Clone this wiki locally