Icon Cutter & Bitmask Smoothing
Relevant source files
The following files were used as context for generating this wiki page:
Icon Cutter is a tool based on the Hypnagogic library that automates the generation of complex BYOND DreamMaker Icon (DMI) files from simple image inputs and configuration files. It specifically handles "stitched" icons where multiple states are combined from a smaller set of source frames. Sources: icons/Cutter.md:3-9, tools/icon_cutter/README.md:1-5
The primary use case for this system is bitmask smoothing. This allows world objects, such as floors or walls, to visually merge with adjacent objects by checking surrounding directions and selecting the appropriate stitched icon state. Sources: icons/Cutter.md:21-27
System Architecture
The cutter operates by transforming input resources (typically PNG files) into output DMIs based on rules defined in TOML configuration files. The build process automatically checks for modified inputs and triggers the cutter to ensure output DMIs are up to date. Sources: tools/icon_cutter/README.md:7-13, tools/icon_cutter/README.md:17-21
Data Flow Overview
The following diagram illustrates how the system processes source images into final game assets.
The Icon Cutter reads a PNG and its corresponding TOML file (often referencing a template) to produce a DMI file used by the game. Sources: icons/Cutter.md:11-19, tools/icon_cutter/README.md:7-11
Bitmask Smoothing (BitmaskSlice)
Bitmask smoothing encodes the surrounding connections of an object as a set of directions. Instead of manually creating icons for every possible connection combination, developers provide a base set of directions which the cutter slices and restitches. Sources: icons/Cutter.md:21-32
Input Requirements
For standard bitmask smoothing, the source PNG must follow specific dimensions:
- Width: 5 times the width of a single DMI state.
- Height: Equal to the height of a single DMI state.
- Animation: Additional rows below the first row represent subsequent frames. Sources: icons/Cutter.md:52-54, icons/Cutter.md:76-78
Standard Base Directions
The cutter typically expects a template containing these connection states:
- None (No connections)
- North + South
- East + West
- North + South + East + West
- All connections Sources: icons/Cutter.md:34-40
Configuration and Templates
The system uses TOML files named {name}.{input_extension}.toml. These files define the cutter mode and variables. Sources: icons/Cutter.md:14-16
Common Configuration Variables
| Variable | Description |
|---|---|
mode | Defines the operation type (e.g., BitmaskSlice, BitmaskSliceReconstruct). |
template | Path to a predefined configuration template in cutter_templates/. |
output_name | The base icon state name in the resulting DMI. |
extract | List of specific icon states to pull during reconstruction. |
delays | Frame delays for animated icons, defined in deciseconds. |
| Sources: icons/Cutter.md:14-16, icons/Cutter.md:56-58, icons/Cutter.md:76-78, cutter_templates/bitmask/restore.toml:9-11 |
Restoration Templates
Templates like restore.toml and restore_corners.toml use the BitmaskSliceReconstruct mode to extract PNGs and configs from existing DMIs. Sources: cutter_templates/bitmask/restore.toml:1-11, cutter_templates/bitmask/restore_corners.toml:1-15
Validation and Integrity
The project includes a Python-based utility (tools/icon_cutter/check.py) to verify that committed DMI files match their source templates and configuration files. Sources: tools/icon_cutter/check.py:1-5
Hashing Process
The validator uses MD5 hashes to detect changes in both the image data and the DMI metadata. It reshapes the DMI image data into tiles for granular comparison. Sources: tools/icon_cutter/check.py:44-63
The validation script ensures that all generated assets are fully committed and synchronized with their source files. Sources: tools/icon_cutter/check.py:70-117
Implementation Details (DMI Metadata)
The system relies on the standard DMI metadata format (version 4.0). This metadata is stored in the PNG "Description" chunk. Sources: tools/dmi/init.py:42-55
DMI Metadata Structure
| Key | Type | Description |
|---|---|---|
width / height | Integer | Dimensions of a single icon frame. |
state | String | Name of the icon state. |
dirs | Integer | Number of directions (e.g., 1, 4, or 8). |
frames | Integer | Number of animation frames. |
delay | CSV List | Delays between frames. |
hotspot | CSV List | X,Y coordinates for the icon anchor. |
| Sources: tools/dmi/init.py:61-83 |
Directional Constants
The tool uses bitwise flags for directional calculations:
- North: 1
- South: 2
- East: 4
- West: 8 Sources: tools/dmi/init.py:12-15
Summary
The Icon Cutter and Bitmask Smoothing system provides a scalable way to manage complex environment transitions. By defining logic in TOML and providing minimal sprite sheets, developers can generate exhaustive directional sets for tiles and walls. The automated validation scripts prevent the common issue of out-of-sync generated assets in the repository. Sources: icons/Cutter.md:18-21, tools/icon_cutter/README.md:17-21