ImageSet Format

---

Summary: 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.

---

Table of Contents

• 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
• Icon Font Atlas Pattern
• Worked Examples
• Common Mistakes

---

Overview

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:

1. Texture atlas (.edds file) --- a single image containing all icons
2. ImageSet definition (.imageset file) --- maps names to regions in the atlas
3. config.cpp registration --- tells the engine to load the imageset at startup
4. Layout/script reference --- uses set:name image:iconName syntax 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

Field	Description
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

Field	Description
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:

Field	Description
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="lnt_icons" file="Lantern_Core/GUI/imagesets/lnt_icons.edds">
  <image name="icon_settings" pos="0 0" size="64 64" />
  <image name="icon_player" pos="64 0" size="64 64" />
  <image name="icon_wallet" pos="128 0" size="64 64" />
</imageset>

XML Attributes

<imageset> element:

Attribute	Description
name	The set name (equivalent to native Name)
file	Path to the texture file (equivalent to native path)

<image> element:

Attribute	Description
name	Image identifier
pos	Top-left position as "x y"
size	Dimensions as "width height"

When to Use Which Format

Feature	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 content mods	Common	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"
                };
            };
        };
    };
};

Example: A Framework With Several Sets

A framework mod often splits its graphics across a few purpose-built sets --- one for standalone HUD icons, one for reusable UI primitives, and one for its icon-font atlas. The Lantern framework used throughout this wiki registers three:

class defs
{
    class imageSets
    {
        files[] =
        {
            "Lantern_Core/GUI/imagesets/lnt_icons.imageset",
            "Lantern_Core/GUI/imagesets/lnt_hud.imageset",
            "Lantern_Core/GUI/imagesets/lnt_prefabs.imageset"
        };
    };
};

Example: A Single-Atlas Mod

Most content mods ship a single atlas. One entry is all you need:

class defs
{
    class imageSets
    {
        files[] =
        {
            "NightPatrol/GUI/imagesets/np_weapon_icons.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:IMAGENAME

• SETNAME --- the Name field from the imageset definition (e.g., dayz_gui, lnt_icons, lnt_solid)
• IMAGENAME --- the Name field from a specific ImageSetDefClass entry (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"
}

Example References

image0 "set:lnt_regular image:arrow_down_short_wide"  -- icon-font regular set (custom atlas)
image0 "set:dayz_gui image:icon_minus"                -- vanilla DayZ icon
image0 "set:dayz_gui image:icon_collapse"             -- vanilla DayZ icon
image0 "set:dayz_gui image:circle"                    -- vanilla DayZ shape
image0 "set:lnt_icons image:icon_settings"            -- custom mod icon

---

Referencing 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 state

Switch between states using SetImage(index):

if (isExpanded)
{
    collapseIcon.SetImage(1);
}
else
{
    collapseIcon.SetImage(0);
}

Using String Variables

string icon = "set:lnt_icons image:icon_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.

Flag	Value	Description
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 "Lantern_Core/GUI/icons/lnt_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 .tga or .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 .tga into DayZ Workbench
• Or use Pal2PacE.exe to convert .paa to .edds
• The output must be an .edds file

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
}

---

Icon Font Atlas Pattern

A powerful pattern is to convert an existing icon font (a font whose glyphs are pictograms rather than letters) into DayZ imagesets. This gives a mod access to hundreds or thousands of consistent, professional-quality icons without hand-drawing any artwork.

How It Works

1. Each glyph in the icon font is rendered to a texture atlas at a fixed grid size (e.g. 64x64 per icon)
2. Each font weight gets its own imageset: for example lnt_solid, lnt_regular, lnt_light, lnt_brands
3. Icon names in the imageset match the font's glyph names (e.g. circle, arrow_down, gear), so the same name resolves across every weight
4. The imagesets are registered in config.cpp and become available to any layout or script

Per-Weight Icon Sets

Lantern_Core/GUI/icons/
  lnt_solid.imageset       -- Filled icons
  lnt_regular.imageset     -- Outlined icons
  lnt_light.imageset       -- Light-weight outlined icons
  lnt_brands.imageset      -- Logo glyphs

Usage in Layouts

image0 "set:lnt_solid image:circle"
image0 "set:lnt_solid image:gear"
image0 "set:lnt_regular image:arrow_down_short_wide"

Usage in Scripts

Because the glyph name is identical across weights, swapping states is just a set-name change:

collapseIcon.LoadImageFile(1, "set:lnt_solid image:square_minus");
collapseIcon.LoadImageFile(0, "set:lnt_regular image:square_plus");

Why This Pattern Works Well

• Large icon library: Hundreds of icons available without any artwork creation
• Consistent style: All icons share the same visual weight and construction
• Multiple weights: Choose solid, regular, or light for different visual contexts
• Name parity: The same glyph name resolves across every weight, so switching states is a one-word change

Licensing Note

Icon fonts carry their own licenses. Before you render one to a texture atlas and ship it inside a PBO, check the font's license and honor its terms --- some require attribution, some restrict redistribution, and some are free for any use. For example, Font Awesome Free is distributed under CC BY 4.0, which permits redistribution as long as you credit the source. Treat the atlas you generate as a redistribution of the original artwork.

The Atlas Structure

A per-weight set is simply a large atlas with icons arranged at a fixed interval. For example, a solid-weight set with icons on a 64-pixel grid:

ImageSetClass {
 Name "lnt_solid"
 RefSize 1024 1024
 Textures {
  ImageSetTextureClass {
   mpix 1
   path "Lantern_Core/GUI/icons/lnt_solid.edds"
  }
 }
 Images {
  ImageSetDefClass circle {
   Name "circle"
   Pos 0 0
   Size 64 64
   Flags 0
  }
  ImageSetDefClass gear {
   Name "gear"
   Pos 64 0
   Size 64 64
   Flags 0
  }
 }
}

---

Worked Examples

The examples below use the wiki's constructed teaching mods (Lantern, NightPatrol). They are illustrations, not dumps of any shipped mod. Every GUID is shown as {0000000000000000} --- DayZ Workbench generates a real GUID for each asset when you import it, so you never type these by hand.

Freeform Admin Atlas

A large full-screen atlas that packs admin-panel icons wherever they fit --- freeform positioning rather than a strict grid --- to maximize texture space. Note the varied positions and a non-power-of-two RefSize matched to a 1920x1080 canvas:

ImageSetClass {
 Name "lnt_admin_icons"
 RefSize 1920 1080
 Textures {
  ImageSetTextureClass {
   mpix 1
   path "{0000000000000000}Lantern_Admin/GUI/imagesets/lnt_admin_icons.edds"
  }
 }
 Images {
  ImageSetDefClass icon_cloud {
   Name "icon_cloud"
   Pos 1206 108
   Size 62 62
   Flags 0
  }
  ImageSetDefClass icon_players {
   Name "icon_players"
   Pos 391 112
   Size 62 62
   Flags 0
  }
 }
}

Referenced in layouts as:

image0 "set:lnt_admin_icons image:icon_cloud"

Weapon Inventory Icons (Varied Sizes)

A content mod's weapon and attachment icons packed into a large atlas. Inventory icons are much larger than UI icons because they show detail in the inventory grid --- this set mixes 300x300 entries, while a HUD set would typically use 64x64:

ImageSetClass {
 Name "np_weapon_icons"
 RefSize 2048 2048
 Textures {
  ImageSetTextureClass {
   mpix 1
   path "{0000000000000000}NightPatrol/GUI/imagesets/np_weapon_icons.edds"
  }
 }
 Images {
  ImageSetDefClass np_foregrip {
   Name "np_foregrip"
   Pos 123 19
   Size 300 300
   Flags 0
  }
  ImageSetDefClass np_optic_scope {
   Name "np_optic_scope"
   Pos 426 20
   Size 300 300
   Flags 0
  }
 }
}

This shows that icons do not need to be uniform size --- inventory icons use 300x300 while UI icons typically use 64x64.

UI Primitives (Spaces in Names)

UI primitives --- rounded corners and single-pixel alpha swatches used to tint panels --- packed into a small 256x256 atlas:

ImageSetClass {
 Name "lnt_prefabs"
 RefSize 256 256
 Textures {
  ImageSetTextureClass {
   mpix 1
   path "{0000000000000000}Lantern_Core/GUI/imagesets/lnt_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.

Simple Set (XML Format)

A small XML imageset for a single module:

<?xml version="1.0" encoding="utf-8"?>
<imageset name="lnt_icons" file="Lantern_Core/GUI/imagesets/lnt_icons.edds">
  <image name="icon_settings" pos="0 0" size="64 64" />
  <image name="icon_player" pos="64 0" size="64 64" />
  <image name="icon_wallet" pos="128 0" size="64 64" />
  <image name="icon_group" pos="192 0" size="64 64" />
  <image name="icon_map" 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:lnt_icons image:icon_settings"

---

Common Mistakes

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 generic

Wrong 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 work

Mismatched 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.

---

Best Practices

• 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 .imageset format over XML for production mods. It supports multi-resolution textures and tiling flags that XML format lacks.
• Verify RefSize matches the actual texture dimensions exactly. A mismatch causes all icon coordinates to be wrong by a proportional factor.

---

Theory vs Practice

What the documentation says versus how things actually work at runtime.

Concept	Theory	Reality
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

---

Compatibility & Impact

• 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 to set:icons in 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 .imageset format and set:name image:name reference 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.

---

Patterns Seen in Practice

Pattern	Detail
Icon-font atlases	An icon font is rendered to large per-weight atlases (see the Icon Font Atlas Pattern above), providing hundreds of consistent icons via sets like set:lnt_solid, set:lnt_regular
Freeform atlas layout	Icons arranged non-uniformly on a full-screen atlas with varying sizes, maximizing texture-space usage
Per-feature small atlases	Each sub-module ships its own small imageset rather than one massive atlas, keeping PBO sizes minimal
300x300 inventory icons	Large icon sizes for weapon/attachment inventory slots where detail matters, unlike 64x64 UI icons