Icon Texture Configuration

Configure HUD icon textures — health hearts, oxygen bubbles, armor indicators, and custom mod icons.

Icons are HUD images displayed during gameplay — health hearts, oxygen bubbles, armor indicators, and any custom icons added by mods. They come in two categories:

• Atlas icons — packed into a shared atlas and rendered together as a group (e.g. health hearts, oxygen bar). These must be declared in a specific order.
• Individual icons — drawn independently and can be placed anywhere on the HUD via the Lua API (e.g. flat armor, percent armor indicators).

File Location

Icons are declared in:

mods/<your-mod>/assets/textures/icons/icons.yaml

Texture images go in the same folder:

mods/<your-mod>/assets/textures/icons/<icon-name>.png

The file name must match the icon’s name field exactly (case-sensitive), with spaces kept as spaces in the file name.

Minimal Example

textures:
  - name: my_icon

This registers an icon named my_icon from my_icon.png. It will be available as YourMod:my_icon anywhere an icon name is expected.

Full Field Reference

textures:
  - name: my_icon          # Required. Registered as YourMod:my_icon
    atlas-group: status_icons  # Optional. Add to a shared atlas (see below)
    frame-width: 16        # Width of a single frame in pixels
    frame-height: 16       # Height of a single frame in pixels
    sprites:               # Optional. Enables looping animation
      - name: my_icon      # informational; a one-row sprite sheet
        frame-count: 5       # Number of frames in the sprite strip
        frame-time-ms: 200  # Default milliseconds per frame
        frame-durations-ms:  # Optional. Per-frame timing override (see below)
          - count: 3
            duration-ms: 80
          - count: 2
            duration-ms: 200

Sprite Strip Format

Animated icons use a horizontal sprite strip — all frames are laid out left-to-right in a single image:

[ frame 0 ][ frame 1 ][ frame 2 ][ frame 3 ][ frame 4 ]

The total image width must equal frame-width × frame-count. All frames must be the same size.

Atlas Icons

Icons with an atlas-group are packed into a shared atlas for their group and rendered together. This is how the health bar and oxygen bar work.

Important: a group’s slots are filled in mod load order, and the HUD reads the health and oxygen icons by fixed slot index. Creation loads before any mod that depends on it, so its four status_icons entries always occupy the first four slots:

Your own status_icons entries append after these, which is harmless. To change how one of these HUD icons looks, don’t add an entry to the group — use icon-overrides, which substitutes your pixels into the original’s slot and leaves the indices alone.

Animated Atlas Icons

Animated atlas icons work the same as individual animated icons. Declare sprites alongside atlas-group:

textures:
  - name: heart
    atlas-group: status_icons
    frame-width: 16
    frame-height: 16
    sprites:
      - name: heart
        frame-count: 5
        frame-time-ms: 200

The animation advances automatically.

Per-Frame Timing

By default all frames in an animation display for the same duration (frame-time-ms). To give individual frames different hold times, add frame-durations-ms to the sprite entry.

Two entry formats are supported and can be mixed freely in the same list:

Flat — one integer per frame:

sprites:
  - name: my_icon
    frame-count: 5
    frame-time-ms: 200  # fallback if list is missing
    frame-durations-ms: [80, 80, 120, 120, 200]

Batch — a duration applied to several consecutive frames at once:

sprites:
  - name: my_icon
    frame-count: 5
    frame-time-ms: 200
    frame-durations-ms:
      - count: 3
        duration-ms: 80
      - count: 2
        duration-ms: 200

Both produce the same result: frames 0–2 last 80 ms each, frames 3–4 last 200 ms each.

Note: If frame-durations-ms is present, the total number of entries (after expanding batches) must equal frame-count exactly. If the counts do not match, frame-durations-ms is ignored and the uniform frame-time-ms is used for all frames instead.

Individual Icons

Icons without an atlas-group are rendered independently and can be displayed anywhere on the HUD using the Lua API. They support the same sprites animation as atlas icons.

textures:
  - name: flat_armor
  - name: percent_armor
    frame-width: 16
    frame-height: 16
    sprites:
      - name: percent_armor
        frame-count: 3
        frame-time-ms: 150

Tool Icons

Icons assigned to the tool_icons atlas group are used as cursor overlays in tools such as the structure editor eraser. When the corresponding tool is active, its icon is drawn centred on the mouse cursor.

Tool icons support an optional tool-options block that fine-tunes the cursor alignment:

textures:
  - name: my_tool_icon
    atlas-group: tool_icons
    frame-width: 40
    frame-height: 27
    tool-options:
      x-offset-px: 5    # horizontal pixel offset from cursor centre (positive = right)
      y-offset-px: 5    # vertical pixel offset from cursor centre (positive = down)

Both fields are optional. Omitting tool-options entirely is valid and leaves the icon exactly centred on the cursor.

Icon Overrides

Your mod can replace the texture used for any icon from another mod without touching that mod’s files. Add an icon-overrides section:

icon-overrides:
  Creation:heart: YourMod:my_heart_icon
  Creation:oxygen: YourMod:my_oxygen_icon

The key is the full mod-namespaced name of the icon to replace. The value is the full mod-namespaced name of your replacement texture (which must also be declared under textures in your icons.yaml).

Overrides work for atlas icons too, including the health bar hearts — they just resolve at a different moment. An individual icon is resolved each time it’s drawn. An atlas icon is resolved once, after every mod has loaded, when the atlas is built: your PNG’s pixels are baked into the original’s existing slot, so the slot index — and everything that reads it — is unchanged.

Two things to get right when overriding an atlas icon:

• Declare your replacement without atlas-group. It only needs to exist under textures: for its pixels to be registered. Giving it a group would additionally append it to that atlas as a slot of its own, which is not what you want.
• Match the original’s pixel dimensions. An atlas sizes its cells to the largest texture in the group, so an oversized replacement enlarges every cell in that group.

Your replacement supplies its own frame count and timing, so an animated icon can replace a static one. If either name fails to resolve, the original is kept and a warning naming both is logged at startup. Names are matched exactly — Creation:HEART will not find Creation:heart.

Overrides

An individual texture entry can take over another mod’s registered icon at load time by adding override with that icon’s full mod-namespaced name:

textures:
  - name: heart
    override: Creation:heart
    frame-width: 16
    frame-height: 16

• The name field is still required — it locates your replacement PNG in your mod’s folder.
• Your entry replaces the target’s registered texture, so redeclare any settings (such as frame-width, frame-height, or sprites) you want to keep.

This per-entry override replaces one specific named icon texture at load time. It is distinct from the top-level icon-overrides map, which remaps a HUD icon key to a texture at render time.

Complete Example

textures:
  # Replaces the HUD's full heart — an atlas icon — with an animated one. No
  # `atlas-group`: the override bakes these pixels into Creation's existing slot.
  # 16x16 matches the icon being replaced, so the atlas cell size is unchanged.
  - name: fancy_heart
    frame-width: 16
    frame-height: 16
    sprites:
      - name: fancy_heart
        frame-count: 4
        frame-time-ms: 120
        frame-durations-ms:
          - duration-ms: 80
            count: 2
          - duration-ms: 200
            count: 1
          - 80
  # Replaces an individually drawn icon — same syntax, resolved at draw time.
  - name: fancy_armor
    frame-width: 18
    frame-height: 18
    sprites:
      - name: fancy_armor
        frame-count: 2
        frame-time-ms: 300

icon-overrides:
  Creation:heart: YourMod:fancy_heart
  Creation:flat_armor: YourMod:fancy_armor