Module guide

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: miscellaneous utilities
• swarm-lang: parsing, typechecking, etc. for the Swarm language
• swarm-topography: working with locations in 2D (sub-)worlds
• swarm-scenario: scenario/world descriptions, parsing, & processing
• swarm-engine: game simulation
• swarm-doc: generating documentation
• swarm-tui: textual user interface
• swarm-web: web interface

swarm-util

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

• Control.Carrier.Accum.FixedStrict: this is a vendored version of Control.Carrier.Accum.Strict from the fused-effects library that works around a bug.
• Data.BoolExpr.Simplify: some additional functionality on top of the boolexpr library.
• Swarm.Failure: data type and utilities for representing system failures.
• Swarm.Pretty: generic pretty-printing infrastructure.
• Swarm.ResourceLoading: infrastructure for locating and loading data files.
• Swarm.Util: a collection of useful generic functions which are not specific to Swarm but not found elsewhere.
• Swarm.Util.*: various more specialized utilities.

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.

• 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:
    • Swarm.Effect.Unify: definition of a unification effect and some operations it supports.
    • Swarm.Effect.Unify.Common: common definitions (mostly re: substitution) used in implementations of unification.
    • Swarm.Effect.Unify.Naive: a slow-but-obviously-correct implementation of unification.
    • Swarm.Effect.Unify.Fast: a faster implementation of unification.
• 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

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.

• Swarm.Constant: miscellaneous constants, e.g. URLs
• Swarm.Util.Content: utilities for extracting content (terrain and entities) from the world map.

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.*
• Achievement.Definitions
• Scenarios
  • Scenario
  • Scenario.*

swarm-engine

swarm-doc

swarm-tui

swarm-web