Modularity System
Relevant source files
The following files were used as context for generating this wiki page:
The Modularity System represents the architectural approach of BandaStation to handle dynamic content, customizable equipment, and variable environments. It enables developers to extend the game through discrete, swappable components such as MODsuit themes and modules, modular map fragments, and procedural generation modules.
This system ensures that complex objects and station environments can be modified without altering the core codebase, utilizing configuration files, template datums, and specific object hierarchies to achieve flexibility.
MODsuit Customization
The MODsuit system provides a framework for creating highly specialized powered armor through themes, skins, and functional modules. Themes define the base statistics, while modules provide the active and passive utility of the suit.
Suit Architecture
A MODsuit is composed of a theme datum that dictates mechanical limits and a set of modules that consume suit resources.
The diagram shows the relationship between a MODsuit instance, its defining theme, and the modules it contains.
Sources: code/modules/mod/adding_new_mod.md:5-40, tgui/packages/tgui/interfaces/MODsuit.tsx:55-85
Theme and Skin Definition
Themes set the baseline for energy usage and complexity limits. Skins handle the visual representation and protective flags for specific suit parts like the helmet, gloves, and boots.
- Complexity: Defines the total "cost" of modules that can be installed.
- Charge Drain: Sets the passive power consumption of the suit.
- Variants: Maps specific clothing parts (head, suit, gloves, shoes) to visual icons and environmental protection flags (e.g.,
STOPSPRESSUREDAMAGE,THICKMATERIAL).
Sources: code/modules/mod/adding_new_mod.md:43-100
Functional Modules
Modules are categorized by how they interact with the wearer and the suit's power supply.
| Module Type | Description |
|---|---|
| Passive | Provides a continuous effect without manual activation. |
| Togglable | Can be turned on or off, usually consuming idle power. |
| Usable | Provides a one-time effect on demand with a cooldown. |
| Active | Grants a special click effect; only one can be active at a time. |
Sources: code/modules/mod/adding_new_mod.md:144-153
Modular Map Loading
The Modular Map Loader allows for the generation of maps with random variants by selecting pre-made .dmm modules. This system uses a root-and-connector logic to align fragments correctly within a main map.
Loading Logic
The process relies on a TOML configuration file to map string keys to specific map files.
This flowchart illustrates the sequence from root initialization to the final placement of a map module.
Sources: code/modules/mapping/modular_map_loader/README.md:10-35
Key Components
- /obj/modular_map_root: The placeholder object on the main map. It contains the
keyused to lookup modules and theconfig_filepath. - /obj/modular_map_connector: A marker placed inside a module map. The loader aligns this object's coordinates with the root object's coordinates.
- TOML Configuration: Defines the
directoryfor map files and tables mapping keys to arrays of filenames.
Sources: code/modules/mapping/modular_map_loader/README.md:9-55
Procedural Mapping System
Procedural mapping utilizes master datums and modules to generate content algorithmically within defined regions. It is often used for nature generation or filling large areas with specific patterns.
Generator Architecture
- mapGenerator: A master datum that syncs and executes a list of
mapGeneratorModules. - mapGeneratorModule: Defines what atoms or turfs to spawn and the clustering logic (how close objects can be to each other).
The diagram shows how the generator iterates through modules to populate a region while respecting clustering constraints.
Sources: code/modules/procedural_mapping/README.md:7-60
Clustering and Placement
Clustering logic prevents or encourages the grouping of similar types using bitflags.
| Flag | Effect |
|---|---|
CLUSTER_CHECK_NONE | No checks; maximum clustering. |
CLUSTER_CHECK_SAME_ATOMS | Prevents atoms of the same type from being near each other. |
CLUSTER_CHECK_DIFFERENT_TURFS | Prevents different turf types from clustering. |
CLUSTER_CHECK_ALL | Disallows all clustering in the region. |
Sources: code/modules/procedural_mapping/README.md:105-120
User Interface Modularity (TGUI)
The TGUI framework enables modular interface design through React components. Interfaces like the MODsuitContent are built by composing standard layout blocks, sections, and interactive components.
- Dynamic Sections: UIs like
MODsuit.tsxuse conditional rendering to show or hide modules based on suit power and state. - Data Binding: The backend provides a
MODsuitDataobject, which the frontend uses to populate progress bars for health, charge, and radiation. - Interactive Components: Use
act()functions to send signals back to the DM code, such asdeployfor suit parts orconfigurefor module settings.
Sources: tgui/packages/tgui/interfaces/MODsuit.tsx:55-120, tgui/README.md:180-200
Summary
The Modularity System serves as the foundation for extensible gameplay in BandaStation. By separating functional logic (modules/generators) from data definitions (themes/TOML), the system allows for high variability in equipment and environments. Whether through the installation of a "neuron healer" module in a MODsuit or the random selection of a vault module in a space ruin, these systems work together to create a dynamic, unpredictable experience.