Skip to content

Module guide

Jump to bottom Edit New page
Brent Yorgey edited this page Sep 27, 2025 · 30 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. There are also a number of submodules which define various subparts of the GameState:
    • State.GameMetrics
    • State.Initialize
    • State.Range
    • State.Redraw
    • State.Robot
    • State.Robots.Internal
    • State.RobotNaming
    • State.Substate
    • State.ViewCenter.Internal
    • 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:
    • Step.Arithmetic
    • Step.Combuestion
    • Step.Const
    • Step.Flood
    • Step.Path.*
    • Step.RobotStepState
    • Step.Util.*
    • Step.Validate
    • Step.Arithmetic

swarm-doc

This package defines code for generating external documentation, such as wiki pages / cheat sheets and editor configuration.

swarm-tui

This package implements the textual user interface (TUI) for the game.

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