Capítulo 5.4: Formato ImageSet
Inicio | << Anterior: Credits.json | ImageSet Format | Siguiente: Server Configuration Files >>
Resumen: ImageSets define named sprite regions within a texture atlas. They are DayZ's primary mechanism for referencing icons, UI graphics, and sprite sheets from layout files and scripts. Instead of loading hundreds of individual image files, you pack all icons into a single texture and describe each icon's position and size in an imageset definition file.
Tabla de Contenidos
- Overview
- How ImageSets Work
- DayZ Native ImageSet Format
- XML ImageSet Format
- Registering ImageSets in config.cpp
- Referencing Images in Layouts
- Referencing Images in Scripts
- Image Flags
- Multi-Resolution Textures
- Creating Custom Icon Sets
- Font Awesome Integration Pattern
- Real Examples
- Common Mistakes
Descripción General
A texture atlas is a single large image (typically in .edds format) containing many smaller icons arranged in a grid or freeform layout. An imageset file maps human-readable names to rectangular regions within that atlas.
For example, a 1024x1024 texture might contain 64 icons at 64x64 pixels each. The imageset file says "the icon named arrow_down is at position (128, 64) and is 64x64 pixels." Your layout files and scripts reference arrow_down by name, and the engine extracts the correct sub-rectangle from the atlas at render time.
This approach is efficient: one GPU texture load serves all icons, reducing draw calls and memory overhead.
How ImageSets Work
The data flow:
- Texture atlas (
.eddsfile) --- a single image containing all icons - ImageSet definition (
.imagesetfile) --- maps names to regions in the atlas - config.cpp registration --- tells the engine to load the imageset at startup
- Layout/script reference --- uses
set:name image:iconNamesyntax to render a specific icon
Once registered, any widget in any layout file can reference any image from the set by name.
DayZ Native ImageSet Format
The native format uses the Enfusion engine's class-based syntax (similar to config.cpp). This is the format used by the vanilla game and most established mods.
Structure
ImageSetClass {
Name "my_icons"
RefSize 1024 1024
Textures {
ImageSetTextureClass {
mpix 1
path "MyMod/GUI/imagesets/my_icons.edds"
}
}
Images {
ImageSetDefClass icon_name {
Name "icon_name"
Pos 0 0
Size 64 64
Flags 0
}
}
}Top-Level Fields
| Campo | Descripción |
|---|---|
Name | The set name. Used in the set: part of image references. Must be unique across all loaded mods. |
RefSize | Reference dimensions of the texture (width height). Used for coordinate mapping. |
Textures | Contains one or more ImageSetTextureClass entries for different resolution mip levels. |
Texture Entry Fields
| Campo | Descripción |
|---|---|
mpix | Minimum pixel level (mip level). 0 = lowest resolution, 1 = standard resolution. |
path | Path to the .edds texture file, relative to the mod root. Can use Enfusion GUID format ({GUID}path) or plain relative paths. |
Image Entry Fields
Each image is an ImageSetDefClass inside the Images block:
| Campo | Descripción |
|---|---|
| Class name | Must match the Name field (used for engine lookups) |
Name | The image identifier. Used in the image: part of references. |
Pos | Top-left corner position in the atlas (x y), in pixels |
Size | Dimensions (width height), in pixels |
Flags | Tiling behavior flags (see Image Flags) |
Full Example (DayZ Vanilla)
ImageSetClass {
Name "dayz_gui"
RefSize 1024 1024
Textures {
ImageSetTextureClass {
mpix 0
path "{534691EE0479871C}Gui/imagesets/dayz_gui.edds"
}
ImageSetTextureClass {
mpix 1
path "{C139E49FD0ECAF9E}Gui/imagesets/dayz_gui@2x.edds"
}
}
Images {
ImageSetDefClass Gradient {
Name "Gradient"
Pos 0 317
Size 75 5
Flags ISVerticalTile
}
ImageSetDefClass Expand {
Name "Expand"
Pos 121 257
Size 20 20
Flags 0
}
}
}XML ImageSet Format
An alternative XML-based format exists and is used by some mods. It is simpler but offers fewer features (no multi-resolution support).
Structure
<?xml version="1.0" encoding="utf-8"?>
<imageset name="mh_icons" file="MyMod/GUI/imagesets/mh_icons.edds">
<image name="icon_store" pos="0 0" size="64 64" />
<image name="icon_cart" pos="64 0" size="64 64" />
<image name="icon_wallet" pos="128 0" size="64 64" />
</imageset>XML Attributes
<imageset> element:
| Atributo | Descripción |
|---|---|
name | The set name (equivalent to native Name) |
file | Path to the texture file (equivalent to native path) |
<image> element:
| Atributo | Descripción |
|---|---|
name | Image identifier |
pos | Top-left position as "x y" |
size | Dimensions as "width height" |
When to Use Which Format
| Característica | Native Format | XML Format |
|---|---|---|
| Multi-resolution (mip levels) | Yes | No |
| Tiling flags | Yes | No |
| Enfusion GUID paths | Yes | Yes |
| Simplicity | Lower | Higher |
| Used by vanilla DayZ | Yes | No |
| Used by Expansion, MyMod, VPP | Yes | Occasionally |
Recommendation: Use the native format for production mods. Use the XML format for quick prototyping or simple icon sets that do not need tiling or multi-resolution support.
Registering ImageSets in config.cpp
ImageSet files must be registered in your mod's config.cpp under the CfgMods > class defs > class imageSets block. Without this registration, the engine never loads the imageset and your image references fail silently.
Syntax
class CfgMods
{
class MyMod
{
// ... other fields ...
class defs
{
class imageSets
{
files[] =
{
"MyMod/GUI/imagesets/my_icons.imageset",
"MyMod/GUI/imagesets/my_other_icons.imageset"
};
};
};
};
};Real Example: MyMod Core
MyMod Core registers seven imagesets including Font Awesome icon sets:
class defs
{
class imageSets
{
files[] =
{
"MyFramework/GUI/imagesets/prefabs.imageset",
"MyFramework/GUI/imagesets/CUI.imageset",
"MyFramework/GUI/icons/thin.imageset",
"MyFramework/GUI/icons/light.imageset",
"MyFramework/GUI/icons/regular.imageset",
"MyFramework/GUI/icons/solid.imageset",
"MyFramework/GUI/icons/brands.imageset"
};
};
};Real Example: VPP Admin Tools
class defs
{
class imageSets
{
files[] =
{
"VPPAdminTools/GUI/Textures/dayz_gui_vpp.imageset"
};
};
};Real Example: DayZ Editor
class defs
{
class imageSets
{
files[] =
{
"DayZEditor/gui/imagesets/dayz_editor_gui.imageset"
};
};
};Referencing Images in Layouts
In .layout files, use the image0 property with the set:name image:imageName syntax:
ImageWidgetClass MyIcon {
size 32 32
hexactsize 1
vexactsize 1
image0 "set:dayz_gui image:icon_refresh"
}Syntax Breakdown
set:SETNAME image:IMAGENAMESETNAME--- theNamefield from the imageset definition (e.g.,dayz_gui,solid,brands)IMAGENAME--- theNamefield from a specificImageSetDefClassentry (e.g.,icon_refresh,arrow_down)
Multiple Image States
Some widgets support multiple image states (normal, hover, pressed):
ImageWidgetClass icon {
image0 "set:solid image:circle"
}
ButtonWidgetClass btn {
image0 "set:dayz_gui image:icon_expand"
}Examples from Real Mods
image0 "set:regular image:arrow_down_short_wide" -- MyMod: Font Awesome regular icon
image0 "set:dayz_gui image:icon_minus" -- MyMod: vanilla DayZ icon
image0 "set:dayz_gui image:icon_collapse" -- MyMod: vanilla DayZ icon
image0 "set:dayz_gui image:circle" -- MyMod: vanilla DayZ shape
image0 "set:dayz_editor_gui image:eye_open" -- DayZ Editor: custom iconReferencing Images in Scripts
In Enforce Script, use ImageWidget.LoadImageFile() or set image properties on widgets:
LoadImageFile
ImageWidget icon = ImageWidget.Cast(layoutRoot.FindAnyWidget("MyIcon"));
icon.LoadImageFile(0, "set:solid image:circle");The 0 parameter is the image index (corresponding to image0 in layouts).
Multiple States via Index
ImageWidget collapseIcon;
collapseIcon.LoadImageFile(0, "set:regular image:square_plus"); // Normal state
collapseIcon.LoadImageFile(1, "set:solid image:square_minus"); // Toggled stateSwitch between states using SetImage(index):
collapseIcon.SetImage(isExpanded ? 1 : 0);Using String Variables
// From DayZ Editor
string icon = "set:dayz_editor_gui image:search";
searchBarIcon.LoadImageFile(0, icon);
// Later, change dynamically
searchBarIcon.LoadImageFile(0, "set:dayz_gui image:icon_x");Image Flags
The Flags field in native-format imageset entries controls tiling behavior when the image is stretched beyond its natural size.
| Bandera | Valor | Descripción |
|---|---|---|
0 | 0 | No tiling. The image stretches to fill the widget. |
ISHorizontalTile | 1 | Tiles horizontally when the widget is wider than the image. |
ISVerticalTile | 2 | Tiles vertically when the widget is taller than the image. |
| Both | 3 | Tiles in both directions (ISHorizontalTile + ISVerticalTile). |
Usage
ImageSetDefClass Gradient {
Name "Gradient"
Pos 0 317
Size 75 5
Flags ISVerticalTile
}This Gradient image is 75x5 pixels. When used in a widget taller than 5 pixels, it tiles vertically to fill the height, creating a repeating gradient stripe.
Most icons use Flags 0 (no tiling). Tiling flags are primarily for UI elements like borders, dividers, and repeating patterns.
Multi-Resolution Textures
The native format supports multiple resolution textures for the same imageset. This allows the engine to use higher-resolution artwork on high-DPI displays.
Textures {
ImageSetTextureClass {
mpix 0
path "Gui/imagesets/dayz_gui.edds"
}
ImageSetTextureClass {
mpix 1
path "Gui/imagesets/dayz_gui@2x.edds"
}
}mpix 0--- low resolution (used on low-quality settings or distant UI elements)mpix 1--- standard/high resolution (default)
The @2x naming convention is borrowed from Apple's Retina display system but is not enforced --- you can name the file anything.
In Practice
Most mods only include mpix 1 (a single resolution). Multi-resolution support is primarily used by the vanilla game:
Textures {
ImageSetTextureClass {
mpix 1
path "MyFramework/GUI/icons/solid.edds"
}
}Creating Custom Icon Sets
Step-by-Step Workflow
1. Create the Texture Atlas
Use an image editor (Photoshop, GIMP, etc.) to arrange your icons on a single canvas:
- Choose a power-of-two size (256x256, 512x512, 1024x1024, etc.)
- Arrange icons in a grid for easy coordinate calculation
- Leave some padding between icons to prevent texture bleeding
- Save as
.tgaor.png
2. Convert to EDDS
DayZ uses .edds (Enfusion DDS) format for textures. Use the DayZ Workbench or Mikero's tools to convert:
- Import your
.tgainto DayZ Workbench - Or use
Pal2PacE.exeto convert.paato.edds - The output must be an
.eddsfile
3. Write the ImageSet Definition
Map each icon to a named region. If your icons are on a 64-pixel grid:
ImageSetClass {
Name "mymod_icons"
RefSize 512 512
Textures {
ImageSetTextureClass {
mpix 1
path "MyMod/GUI/imagesets/mymod_icons.edds"
}
}
Images {
ImageSetDefClass settings {
Name "settings"
Pos 0 0
Size 64 64
Flags 0
}
ImageSetDefClass player {
Name "player"
Pos 64 0
Size 64 64
Flags 0
}
ImageSetDefClass map_marker {
Name "map_marker"
Pos 128 0
Size 64 64
Flags 0
}
}
}4. Register in config.cpp
Add the imageset path to your mod's config.cpp:
class imageSets
{
files[] =
{
"MyMod/GUI/imagesets/mymod_icons.imageset"
};
};5. Use in Layouts and Scripts
ImageWidgetClass SettingsIcon {
image0 "set:mymod_icons image:settings"
size 32 32
hexactsize 1
vexactsize 1
}Font Awesome Integration Pattern
MyMod Core (inherited from DabsFramework) demonstrates a powerful pattern: converting Font Awesome icon fonts into DayZ imagesets. This gives mods access to thousands of professional-quality icons without creating custom artwork.
How It Works
- Font Awesome icons are rendered to a texture atlas at a fixed grid size (64x64 per icon)
- Each icon style gets its own imageset:
solid,regular,light,thin,brands - Icon names in the imageset match Font Awesome icon names (e.g.,
circle,arrow_down,discord) - The imagesets are registered in config.cpp and available to any layout or script
MyMod Core / DabsFramework Icon Sets
MyFramework/GUI/icons/
solid.imageset -- Filled icons (3648x3712 atlas, 64x64 per icon)
regular.imageset -- Outlined icons
light.imageset -- Light-weight outlined icons
thin.imageset -- Ultra-thin outlined icons
brands.imageset -- Brand logos (Discord, GitHub, etc.)Usage in Layouts
image0 "set:solid image:circle"
image0 "set:solid image:gear"
image0 "set:regular image:arrow_down_short_wide"
image0 "set:brands image:discord"
image0 "set:brands image:500px"Usage in Scripts
// DayZ Editor using the solid set
CollapseIcon.LoadImageFile(1, "set:solid image:square_minus");
CollapseIcon.LoadImageFile(0, "set:regular image:square_plus");Why This Pattern Works Well
- Massive icon library: Thousands of icons available without any artwork creation
- Consistent style: All icons share the same visual weight and style
- Multiple weights: Choose solid, regular, light, or thin for different visual contexts
- Brand icons: Ready-made logos for Discord, Steam, GitHub, etc.
- Standard names: Icon names follow Font Awesome conventions, making discovery easy
The Atlas Structure
The solid imageset, for example, has a RefSize of 3648x3712 with icons arranged at 64-pixel intervals:
ImageSetClass {
Name "solid"
RefSize 3648 3712
Textures {
ImageSetTextureClass {
mpix 1
path "MyFramework/GUI/icons/solid.edds"
}
}
Images {
ImageSetDefClass circle {
Name "circle"
Pos 0 0
Size 64 64
Flags 0
}
ImageSetDefClass 360_degrees {
Name "360_degrees"
Pos 320 0
Size 64 64
Flags 0
}
...
}
}Ejemplos Reales
VPP Admin Tools
VPP packs all admin tool icons into a single 1920x1080 atlas with freeform positioning (not a strict grid):
ImageSetClass {
Name "dayz_gui_vpp"
RefSize 1920 1080
Textures {
ImageSetTextureClass {
mpix 1
path "{534691EE0479871E}VPPAdminTools/GUI/Textures/dayz_gui_vpp.edds"
}
}
Images {
ImageSetDefClass vpp_icon_cloud {
Name "vpp_icon_cloud"
Pos 1206 108
Size 62 62
Flags 0
}
ImageSetDefClass vpp_icon_players {
Name "vpp_icon_players"
Pos 391 112
Size 62 62
Flags 0
}
}
}Referenced in layouts as:
image0 "set:dayz_gui_vpp image:vpp_icon_cloud"MyMod Weapons
Weapon and attachment icons packed into large atlases with varied icon sizes:
ImageSetClass {
Name "SNAFU_Weapons_Icons"
RefSize 2048 2048
Textures {
ImageSetTextureClass {
mpix 1
path "{7C781F3D4B1173D4}SNAFU_Guns_01/gui/Imagesets/SNAFU_Weapons_Icons.edds"
}
}
Images {
ImageSetDefClass SNAFUFGRIP {
Name "SNAFUFGRIP"
Pos 123 19
Size 300 300
Flags 0
}
ImageSetDefClass SNAFU_M14Optic {
Name "SNAFU_M14Optic"
Pos 426 20
Size 300 300
Flags 0
}
}
}This shows that icons do not need to be uniform size --- inventory icons for weapons use 300x300 while UI icons typically use 64x64.
MyMod Core Prefabs
UI primitives (rounded corners, alpha gradients) packed into a small 256x256 atlas:
ImageSetClass {
Name "prefabs"
RefSize 256 256
Textures {
ImageSetTextureClass {
mpix 1
path "{82F14D6B9D1AA1CE}MyFramework/GUI/imagesets/prefabs.edds"
}
}
Images {
ImageSetDefClass Round_Outline_TopLeft {
Name "Round_Outline_TopLeft"
Pos 24 21
Size 8 8
Flags 0
}
ImageSetDefClass "Alpha 10" {
Name "Alpha 10"
Pos 0 15
Size 1 1
Flags 0
}
}
}Notable: image names can contain spaces when quoted (e.g., "Alpha 10"). However, referencing these in layouts requires the exact name including the space.
MyMod Market Hub (XML Format)
A simpler XML imageset for the market hub module:
<?xml version="1.0" encoding="utf-8"?>
<imageset name="mh_icons" file="DayZMarketHub/GUI/imagesets/mh_icons.edds">
<image name="icon_store" pos="0 0" size="64 64" />
<image name="icon_cart" pos="64 0" size="64 64" />
<image name="icon_wallet" pos="128 0" size="64 64" />
<image name="icon_vip" pos="192 0" size="64 64" />
<image name="icon_weapons" pos="0 64" size="64 64" />
<image name="icon_success" pos="0 192" size="64 64" />
<image name="icon_error" pos="64 192" size="64 64" />
</imageset>Referenced as:
image0 "set:mh_icons image:icon_store"Errores Comunes
Forgetting config.cpp Registration
The most common issue. If your imageset file exists but is not listed in class imageSets { files[] = { ... }; }; in config.cpp, the engine never loads it. All image references will fail silently (widgets appear blank).
Set Name Collisions
If two mods register imagesets with the same Name, only one is loaded (the last one wins). Use a unique prefix:
Name "mymod_icons" -- Good
Name "icons" -- Risky, too genericWrong Texture Path
The path must be relative to the PBO root (how the file appears inside the packed PBO):
path "MyMod/GUI/imagesets/icons.edds" -- Correct if MyMod is the PBO root
path "GUI/imagesets/icons.edds" -- Wrong if the PBO root is MyMod/
path "C:/Users/dev/icons.edds" -- Wrong: absolute paths do not workMismatched RefSize
The RefSize must match the actual pixel dimensions of your texture. If you specify RefSize 512 512 but your texture is 1024x1024, all icon positions will be off by a factor of two.
Pos Coordinates Off by One
Pos is the top-left corner of the icon region. If your icons are at 64-pixel intervals but you accidentally offset by 1 pixel, icons will have a thin slice of the adjacent icon visible.
Using .png or .tga Directly
The engine requires .edds format for texture atlases referenced by imagesets. Raw .png or .tga files will not load. Always convert to .edds using DayZ Workbench or Mikero's tools.
Spaces in Image Names
While the engine supports spaces in image names (e.g., "Alpha 10"), they can cause issues in some parsing contexts. Prefer underscores: Alpha_10.
Mejores Prácticas
- Always use a unique, mod-prefixed set name (e.g.,
"mymod_icons"instead of"icons"). Set name collisions between mods cause one set to silently overwrite the other. - Use power-of-two texture dimensions (256x256, 512x512, 1024x1024). Non-power-of-two textures work but may have reduced rendering performance on some GPUs.
- Add 1-2 pixels of padding between icons in the atlas to prevent texture bleeding at the edges, especially when the texture is displayed at non-native sizes.
- Prefer the native
.imagesetformat over XML for production mods. It supports multi-resolution textures and tiling flags that XML format lacks. - Verify
RefSizematches the actual texture dimensions exactly. A mismatch causes all icon coordinates to be wrong by a proportional factor.
Teoría vs Práctica
What the documentation says versus how things actually work at runtime.
| Concepto | Teoría | Realidad |
|---|---|---|
| config.cpp registration is required | ImageSets must be listed in class imageSets | Correct, and this is the most common source of "blank icon" bugs. The engine gives no error if the registration is missing -- widgets simply render empty |
RefSize maps coordinates | Coordinates are in RefSize space | RefSize must match actual texture pixel dimensions. If your texture is 1024x1024 but RefSize says 512x512, all Pos values are interpreted at double scale |
| XML format is simpler | Fewer features but works the same | XML imagesets cannot specify tiling flags or multi-resolution mip levels. For icons this is fine, but for repeating UI elements (borders, gradients) you need the native format |
Multiple mpix entries | Engine selects by quality setting | In practice, most mods ship only mpix 1. The engine falls back gracefully if only one mip level is provided -- no visual glitch, just no high-DPI optimization |
| Image names are case-sensitive | "MyIcon" and "myicon" are different | True in the imageset definition, but LoadImageFile() in script performs case-insensitive lookup on some engine builds. Always match case exactly to be safe |
Compatibilidad e Impacto
- Multi-Mod: Set name collisions are the main risk. If two mods both define an imageset named
"icons", only one is loaded (last PBO wins). All references toset:iconsin the losing mod break silently. Always use a mod-specific prefix. - Performance: Each unique imageset texture is one GPU texture load. Consolidating icons into fewer, larger atlases reduces draw calls. A mod with 10 separate 64x64 textures performs worse than one 512x512 atlas with 10 icons.
- Version: The native
.imagesetformat andset:name image:namereference syntax have been stable since DayZ 1.0. The XML format has been available as an alternative since early versions but is not officially documented by Bohemia.
Observado en Mods Reales
| Patrón | Mod | Detalle |
|---|---|---|
| Font Awesome icon atlases | DabsFramework / StarDZ Core | Renders Font Awesome icons to large atlases (3648x3712), providing thousands of professional icons via set:solid, set:regular, set:brands |
| Freeform atlas layout | VPP Admin Tools | Icons arranged non-uniformly on a 1920x1080 atlas with varying sizes, maximizing texture space usage |
| Per-feature small atlases | Expansion | Each Expansion sub-module has its own small imageset rather than one massive atlas, keeping PBO sizes minimal |
| 300x300 inventory icons | SNAFU Weapons | Large icon sizes for weapon/attachment inventory slots where detail matters, unlike 64x64 UI icons |
