imageset-packer

README

ImageSet Packer

imageset-packer is a CLI tool for building DayZ .imageset + .edds from folders with PNG/TGA/TIFF/BMP files.

It replaces the routine manual atlas creation in Workbench: just organize your source images into folders, run pack, and you get correct placement, good atlas density, and ready-to-use files for your DayZ mod.

Typical workflow: prepare source icons in a folder tree, run one command, and get production-ready outputs:

• .edds atlas with configurable format (bgra8, dxt1, dxt5)
• .imageset descriptor with positions/sizes and optional groups
• optional mipmap chain and quality control for DXT compression
• stable output naming for automated builds and CI pipelines

What this utility gives you in practice:

• no manual sprite placement in Workbench
• deterministic atlas generation for repeatable builds
• YAML-based multi-project build mode for larger mod repositories
• conversion and unpack helpers for migration from legacy atlases

Main commands

Help for available commands

imageset-packer -h

Help for flags of a specific command

imageset-packer pack -h

pack

Packs a folder of images into a single atlas (.edds) and a .imageset description file.

Packing heuristic reference with visuals and explanations: https://github.com/WoozyMasta/atlasforge/blob/master/README.md#packing-examples

Examples:

imageset-packer pack ./icons

Packs ./icons into icons.imageset + icons.edds in the same folder.

imageset-packer pack ./icons ./out -x 3 -g 2 -f -P mod/data/images

Packing with 3 mipmap levels, 2px gap, overwrite enabled, and the texture path set in the imageset.

imageset-packer pack ./icons -F dxt5 -q 8

Packing with DXT-compressed output format and explicit encoder quality.

imageset-packer pack ./icons --skip-unchanged

Skips writing if the input files have not changed.

[!TIP]
--skip-unchanged is useful for local builds and CI. A small .imagehash file is created next to the outputs.

build

Runs multiple packing tasks from a YAML config. Useful for CI and automation.
The .imageset-packer.yaml file is recommended at the project root. A detailed example can be found here.

imageset-packer build

Builds all projects from .imageset-packer.yaml.

unpack

Migration helper. Splits an existing project .imageset + .edds into separate images.
This lets you convert an old atlas into a folder structure and switch to imageset-packer as the main tool.

# Extracts images and splits groups into subfolders.
imageset-packer unpack ui.imageset ui.edds --groups

convert

Helper utility for converting a single file between PNG/TGA/TIFF/BMP/DDS/EDDS formats.

Example:

# EDDS to PNG, file type is determined by the extension
imageset-packer convert atlas.edds atlas.png

# PNG to EDDS with explicit format/quality
imageset-packer convert icon.png icon.edds -F dxt1 -q 8 -x 1

Build automation

Simple .imageset-packer.yaml example.

# .imageset-packer.yaml
projects:
  - name: hud
    args:
      input_dir: ./images/hud
      output_dir: ./data/images
    edds_path: mod/data/images
    camel_case: true
    force: true
    skip_unchanged: true
    packing:
      gap: 2
      mipmaps: 1
      output_format: bgra8
      quality: 0
    input:
      group_dirs: true

  - name: ui
    args:
      input_dir: ./images/ui
      output_dir: ./data/images
    edds_path: mod/data/images
    camel_case: true
    force: true
    skip_unchanged: true
    packing:
      gap: 2
      mipmaps: 2
      output_format: dxt5
      quality: 8
    input:
      group_dirs: true

Detailed example file: .imageset-packer.yaml.

Advanced example with anchors and reuse (4 atlases)

# .imageset-packer.yaml
defaults: &defaults
  edds_path: mod/data/images
  camel_case: true
  force: true
  skip_unchanged: true
  packing: &packing
    gap: 2
    mipmaps: 1
    output_format: bgra8
    quality: 0
  input: &input
    group_dirs: true

projects:
  - name: chars
    args:
      input_dir: ./chars
      output_dir: ./out
    <<: *defaults

  - name: ui
    args:
      input_dir: ./ui
      output_dir: ./out
    <<: *defaults
    packing:
      <<: *packing
      mipmaps: 2

  - name: markers
    args:
      input_dir: ./markers
      output_dir: ./out
    <<: *defaults

  - name: hud
    args:
      input_dir: ./hud
      output_dir: ./out
    <<: *defaults
    packing:
      <<: *packing
      mipmaps: 2

Recommendations

• Keep a clear folder structure and stable file names.
• Supported atlas formats: bgra8, dxt1, dxt5.
• Default atlas output is bgra8 (DXGI_FORMAT_B8G8R8A8_UNORM).
• For UI icon atlases, recommended baseline is: output_format: bgra8 and mipmaps: 1.
• dxt1 is suitable for opaque assets, but it does not preserve soft alpha.
• If you need compressed output with transparency, prefer dxt5.
• DXT quality uses 0..10 (0 = library optimal default, 1 fastest, 8 high quality).
• For UI icons and UI parts, avoid long mipmap chains: usually 1-4 levels are enough.
• If the build is automated and .imageset/.edds artifacts are not in .gitignore, enable force to ensure files are overwritten.
• For frequent local runs, use skip_unchanged to avoid noisy commits. The hash is stored in .imagehash; add these files to .gitignore if desired, especially if source images are not tracked.
• For UI elements, gap is useful when mipmaps are enabled and there are many small elements. Usually 2-6 is enough, but it reduces atlas density. This option is not required, but it can help if neighboring elements bleed into the current element when scaled.

Known behavior and fixes

[!CAUTION]
--skip-unchanged considers only the contents of input files. If you change packing parameters (gap/mipmaps/path, etc.), run without --skip-unchanged or delete .imagehash.

---

[!WARNING]
Windows + MSYS2/Git Bash may require disabling path conversion for --edds-path:

MSYS2_ARG_CONV_EXCL='--edds-path;-P' go run ./cmd/imageset-packer/ pack ...

👉 Support Me