| name | dayz-build-imageset |
| description | Pack PNG sprites from `<mod>/.gui-sources/<setname>/` into a DayZ imageset (`.imageset` + `.paa` atlas) at `<mod>/gui/imagesets/<setname>.{imageset,paa}`, with a 10px gutter between every sprite. Source PNGs live outside the PBO payload (in `.gui-sources/`); only the packed atlas + definition file ship. Each subfolder of `.gui-sources/` becomes one imageset. |
Path note: <skill-dir> in commands below is the absolute path of this skill's folder. When the agent loads this skill the harness exposes the skill's base directory; substitute it before running. Sibling skills are reached via <skill-dir>\..\dayz-X\.
/dayz-build-imageset
Pack a folder of PNG sprites into a DayZ imageset (atlas + .imageset definition file). Source images stay in .gui-sources/ (kept out of the mod payload); only the packed .paa atlas and .imageset file land under gui/imagesets/ where the engine expects them.
Layout convention:
<mod-root>/
.gui-sources/
my_icons/
hud_health.png
hud_stamina.png
hud_thirst.png
main_menu/
...
gui/
imagesets/
my_icons.imageset <- generated
my_icons.paa <- generated
main_menu.imageset
main_menu.paa
Follow .claude/skills/_shared/dayz-conventions.md.
How to run
python "<skill-dir>\build_imageset.py" [<mod-root>] [--mod-name <name>]
| Argument | Required? | Notes |
|---|
<mod-root> | no | Folder containing .gui-sources/. Defaults to current directory. |
--mod-name <name> | no | Name used in the path field of the .imageset (<name>\gui\imagesets\<setname>.paa). Defaults to the basename of <mod-root>. |
What it does
- Preflight gate (DayZ Tools needed for
ImageToPAA.exe).
- Resolve
ImageToPAA.exe from DayZ Tools.
- For each subfolder of
<mod-root>/.gui-sources/:
- Collect all
.png files in that subfolder. Each file becomes one named sprite (the file's stem becomes the ImageSetDefClass name).
- Sort sprites by height descending and shelf-pack into the smallest power-of-two atlas that fits (each dimension picked from 256 / 512 / 1024 / 2048 / 4096; rectangular atlases allowed; ordered by area, square preferred at equal area), with a 10px gutter on all sides of every sprite.
- If everything fits in one atlas: emit
<setname>.{paa,imageset}.
- If sprites won't fit in a single 4096x4096 atlas: greedily split into multiple atlases and emit
<setname>_1.{paa,imageset}, <setname>_2.{paa,imageset}, etc. Each part is its own self-contained imageset.
- Compose each atlas as PNG via Pillow, convert to
.paa via ImageToPAA.exe.
- Each
.imageset's path references its own .paa via <mod-name>\gui\imagesets\<stem>.paa.
- Report a summary; exit non-zero if any imageset failed.
Generated .imageset format
ImageSetClass {
Name "my_icons"
RefSize 512 512
Textures {
ImageSetTextureClass {
mpix 0
path "MyMod\gui\imagesets\my_icons.paa"
}
}
Images {
ImageSetDefClass hud_health {
Name "hud_health"
Pos 10 10
Size 64 64
Flags 0
}
...
}
Groups {
}
}
Pos is the sprite's top-left in atlas pixels (after gutter); Size is the sprite's own dimensions (gutter is NOT included in Size).
Refuses to run if
/dayz-preflight returns non-zero.<mod-root> isn't a directory.<mod-root>/.gui-sources/ doesn't exist or has no subfolders.- A single sprite is larger than 4096x4096 minus gutter (won't fit in any allowed atlas size). Shrink it or deliver it outside an imageset.
ImageToPAA.exe is missing from DayZ Tools.
Do not
- Don't pack source PNGs into the PBO; they stay in
.gui-sources/ so the deployed mod ships only the atlas + definition.
- Don't add gutter pixels to the per-sprite
Size values; the engine reads Size as the sprite's own dimensions.
- Don't drop the 10px gutter; it prevents bleed between adjacent sprites at non-1:1 scaling.
- Don't change atlas to non-power-of-two; both width and height are POT independently (rectangular allowed). DayZ's GUI subsystem and
.paa toolchain expect POT dimensions.
