UI & Custom Images
Relevant source files
The following files were used as context for generating this wiki page:
The UI and Custom Images system in Chapter Master facilitates the visual representation of Space Marine chapters through a combination of static assets, dynamic color mapping (liveries), and user-provided external files. This system allows for the extensive customization of chapter aesthetics, ranging from UI icons to complex armor patterns for different ranks within a chapter.
The system relies on specific file formats and directory structures within the user's local application data and the project's game files. It integrates JSON-based configuration with PNG image assets to define the visual identity of both canon and custom chapters.
Custom Icon Integration
Users can extend the game's visual library by adding custom chapter icons. These icons must be saved in the .png format and adhere to specific sizing and naming conventions to be recognized by the game engine.
Icon Specifications
- Dimensions: Icons must be at least 141x141 pixels. Non-square images are automatically scaled ("smooshed") to fit the UI requirements.
- File Format: Standard
.pngis required. Note that certain encoders, such as those used by MS Paint, are known to be incompatible with the game's reader. - Storage Path:
%AppData%\Local\ChapterMaster\Custom Files\Custom Icons\ - Naming Convention: Files must follow the pattern
custom*.png, where*is a numeric value between 1 and 99.
Sources: datafiles/README.md:3-13
UI Asset Structure
The game utilizes specialized image sheets for the chapter creation interface and general UI. These are organized into subimages within specific PNG files.
| Asset Name | Dimensions | Purpose |
|---|---|---|
creation_icons.png | 3243 x 141 px | Contains 23 subimages for various creation-phase icons. |
main[1-9].png | 374 x 713 px | Standard UI panels and backgrounds. |
existing[1-7].png | 374 x 713 px | UI elements for selecting existing chapters. |
slate[1-2].png | 850 x 860 px | Large background or information slates. |
Sources: datafiles/images/creation/instructions.txt:6-25
Livery and Color Systems
The visual identity of a chapter is programmatically defined via JSON configuration files. This includes base colors and "Complex Livery Data" which specifies how colors are applied to different armor components based on the marine's rank.
Livery Configuration Mapping
The system maps numeric color IDs or named strings to specific armor parts. This allows for distinctive looks for Sergeants, Captains, and Veterans compared to standard battle-brothers.
The diagram shows how the JSON structure decomposes into general chapter colors and specific rank-based livery overrides.
Sources: datafiles/main/chapters/37.json:44-96, datafiles/main/chapters/33.json:52-104
Full Livery Arrays
For chapters with highly specific visual requirements (like the Deathwatch or Raptors), the system supports full_liveries. This is an array of objects where every individual armor piece (e.g., left_leg_upper, right_pauldron, eye_lense) is assigned a specific color value.
| Armor Component | Description | Example Value |
|---|---|---|
pauldron_l | Left shoulder armor color. | "Silver" / 1.0 |
pauldron_r | Right shoulder armor color. | "Black" / 8.0 |
metallic_trim | Specific ID for metallic surface rendering. | 20.0 |
eye_lense | Color ID for the helmet optics. | 9.0 |
weapon_primary | Color for the main handheld armament. | 11.0 |
Sources: datafiles/main/chapters/33.json:490-520, datafiles/main/chapters/36.json:422-452
Splash and Icon References
Each chapter definition links to specific visual assets used in the UI during chapter selection and gameplay.
- Splash Images: Referenced by the
splashID, these images are stored in\images\creation\chapters\splash. For example, ID1represents Dark Angels assets, while ID33is assigned to Deathwatch. - Icon Names: The
icon_namestring (e.g., "consecrators", "raptors") tells the engine which icon asset to pull from the internal library.
Sources: datafiles/main/chapters/37.json:11-12, datafiles/main/chapters/33.json:11-12, datafiles/main/chapters/35.json:11-12
Data Flow for Chapter Visualization
The following sequence illustrates how the game engine assembles the UI and chapter visuals upon loading a chapter profile.
The sequence shows the priority of data loading and the integration of internal assets with external user customizations.
Sources: datafiles/main/chapters/37.json:1-96, datafiles/README.md:3-13
Summary
The UI & Custom Images system provides a robust framework for chapter representation. By separating the mechanical data (JSON) from the visual assets (PNG), the project allows for both high-fidelity preset chapters and flexible user-generated content. The system's reliance on standardized paths in AppData and specific file patterns ensures that the community can easily contribute new iconography while maintaining compatibility with the core engine's rendering logic.