Adding Custom Chapter Icons
Relevant source files
The following files were used as context for generating this wiki page:
Custom chapter icons allow players to personalize their Space Marine chapters by providing unique heraldry. These icons are integrated into the game through specific file naming conventions and directory structures within the local application data.
The system supports both pre-defined icons associated with existing chapters and user-provided "custom" icons that can be assigned during chapter creation or through JSON configuration files.
Technical Requirements for Icon Files
Icons must adhere to specific formatting and dimensional constraints to be correctly rendered by the engine.
- File Format: All icons must be saved as
.pngfiles. - Dimensions: Minimum size of 141x141 pixels. Non-square icons will be "smooshed" or scaled to fit the square display area.
- Software Compatibility: While MS Paint can save as PNG, its encoding is often incompatible with the game engine. Users must use alternative image editing software to ensure the files are readable.
Sources: datafiles/README.md:5-11, datafiles/images/creation/instructions.txt:2-3
Icon Storage and Directory Structure
The game distinguishes between core assets and user-provided custom files. Custom icons are stored in the local AppData directory to ensure they persist across updates.
| Icon Type | Directory Path |
|---|---|
| Custom Icons | C:\Users\<UserName>\AppData\Local\ChapterMaster\Custom Files\Custom Icons\ |
| Core Icons | \images\creation\chapters\splash\ (Internal structure) |
Sources: datafiles/README.md:13-16, datafiles/main/chapters/37.json:11
Custom Icon Naming Convention
Custom icons must follow a specific numerical naming format to be recognized by the internal loading logic:
custom*.png (where * is a number from 1 to 99).
Sources: datafiles/README.md:16
Integration with Chapter Data
Chapter icons are linked to specific chapters through the icon_name and splash fields in the chapter's JSON configuration files.
Configuration Fields
| Field | Description | Example Value |
|---|---|---|
icon_name | The internal string identifier for the icon asset. | "raptors" |
splash | An integer ID referencing the image number in the creation splash folder. | 36 |
Sources: datafiles/main/chapters/36.json:10-11, datafiles/main/chapters/37.json:10-11
Data Flow for Icon Assignment
The following diagram illustrates how the game associates a chapter configuration with its visual icon asset:
The game engine looks up the icon_name string in the asset library, which includes both hardcoded chapter symbols and any files found in the custom AppData directory.
Sources: datafiles/main/chapters/37.json:10-11, datafiles/README.md:16
Implementation Example
To add a new icon for a custom chapter, one would typically define the chapter's data and ensure the icon name matches the file or reference.
{
"chapter": {
"id": 37,
"name": "Consecrators",
"splash": 1,
"icon_name": "consecrators"
}
}
Sources: datafiles/main/chapters/37.json:3-12
Summary of Component Relationships
| Component | Role | File Reference |
|---|---|---|
| README.md | Defines user paths and hardware constraints. | datafiles/README.md |
| Chapter JSON | Links chapter identity to icon assets via icon_name. | datafiles/main/chapters/33.json |
| Instructions | Details sprite sheet/sub-image requirements for UI icons. | datafiles/images/creation/instructions.txt |
Conclusion
Adding custom icons is a straightforward process involving placing correctly formatted PNG files into the AppData folder and referencing them within the chapter's JSON configuration. By adhering to the 141x141 pixel minimum and the custom*.png naming convention, users can extend the visual variety of the chapters within the game.