Mapmerge & Map Collision Tooling
Relevant source files
The following files were used as context for generating this wiki page:
The Mapmerge and Map Collision tooling consists of a suite of Python scripts and shell utilities that maintain map files in a Git-friendly format. These tools prevent and resolve merge conflicts by rewriting DreamMaker map files into the TGM format, which minimizes textual differences between versions while preserving gameplay changes.
The tooling includes automated Git hooks, manual conflict resolvers, path update scripts, and tile aggregators to ensure map data integrity across the repository.
Sources: tools/mapmerge2/README.md:3-8, tools/mapmerge2/README.md:23-28
Map Merge System Architecture
The Map Merge system uses a reference-based rewriting process. It compares a new version of a map with a reference version to generate a TGM-formatted output that emphasizes actual changes over formatting noise.
The diagram shows the data flow from raw map files through the Map Merger tool to Git integration.
Sources: tools/mapmerge2/README.md:23-28, tools/mapmerge2/README.md:43-46
Core Components
| Component | File Path | Function |
|---|---|---|
| Map Merger | mapmerge.py | Implements the core logic for rewriting and merging map files. |
| Merge Driver | merge_driver.py | Provides a three-way merge implementation for Git conflict resolution. |
| DMM Module | dmm.py | Contains the map reader and writer for parsing BYOND map formats. |
| Precommit Hook | precommit.py | Automatically merges new versions with old versions in the Git index. |
| Frontend | frontend.py | Provides common CLI code and environment variable handling. |
Sources: tools/mapmerge2/README.md:37-46
Three-Way Merge Logic
The merge_driver.py script implements a three_way_merge function to resolve conflicts at the coordinate level. The tool attempts to merge tiles by checking three versions: Base, Ours (Left), and Theirs (Right).
Merge Strategy Levels
- Whole Tile Merge: If both sides agree or one side remains identical to the base, the tool selects the modified side.
- Split Group Merge: If the whole tile conflicts, the tool attempts to merge three independent groups: Movables, Turfs, and Areas.
- Conflict Marker: If atom groups conflict, the tool inserts a
/obj/merge_conflict_markerat the specific coordinates for manual review.
Sources: tools/mapmerge2/merge_driver.py:35-58, tools/mapmerge2/merge_driver.py:65-74
This flowchart illustrates the hierarchical decision logic used when two branches modify the same map coordinates.
Sources: tools/mapmerge2/merge_driver.py:43-70
UpdatePaths Tooling
UpdatePaths replaces outdated object or turf paths within map files using transformation scripts. This tool is critical when refactoring code to prevent the DreamMaker map editor from discarding unknown paths.
Script Syntax and Features
- Path Swapping: Uses
OldPath : NewPath{@OLD}to replace paths while retaining variable edits via the{@OLD}tag. - Deletion: Uses
@DELETEto remove a path and its associated variables entirely. - Filtering: Supports targeting specific instances using property filtration (e.g.,
/mob{name="Tom"}). - Subtype Handling: Uses the
@SUBTYPESparameter to apply changes to a base path and all its inherited types.
Sources: tools/UpdatePaths/readme.md:16-24, tools/UpdatePaths/readme.md:65-68, tools/UpdatePaths/readme.md:95-98
Map Tile Aggregator
The Map Tile Aggregator simplifies complex map keys by "flattening" multiple turf decals into a single optimized type. It scans .dmm files and converts separate decal objects into combined contrasted subtypes.
The diagram demonstrates how the tool reduces map key complexity by merging overlapping or adjacent decal definitions.
Sources: tools/MapTileAggregator/readme.md:5-24
Automated Validation (CI)
The repository uses tools/ci/check_grep.sh to enforce map standards during Continuous Integration. The script validates that maps adhere to the following rules:
- TGM Format: Detects non-TGM formatted maps and requires conversion via Map Merger.
- Comments: Flags unexpected commented lines in map files, excluding specific tool headers.
- Invalid Procs: Blocks the use of unsupported procs like
new(),icon(), orsound()within map variables. - Empty Variables: Identifies and requires the removal of empty curly brackets
{}in map keys.
Sources: tools/ci/check_grep.sh:42-55, tools/ci/check_grep.sh:225-230
Usage Summary
For manual map maintenance, use the provided batch or shell scripts:
- Preparation: Run
Prepare Maps.batto back up current map states before editing. - Conversion: Use
tgm2dmm.batordmm2tgm.batto switch formats for editor compatibility. - Conflict Resolution: Run
Resolve Map Conflicts.batwhen Git signals a merge conflict. - Cleaning: Run
MapTileAggregator.batto optimize turf decals and automatically trigger MapMerge.
Sources: tools/mapmerge2/README.md:15-20, tools/MapTileAggregator/readme.md:32-35
The Mapmerge & Map Collision tooling provides a robust infrastructure for multi-developer mapping. By enforcing the TGM format and providing automated three-way merging, the system significantly reduces the technical debt associated with BYOND's native map format.