Healthbar Texture Configuration

Configure layered healthbar textures that display an entity's current health during gameplay.

Healthbars display an entity’s current health as an overlay during gameplay. Each healthbar is built from one or more layers drawn on top of each other — typically a static background and an animated fill layer that shrinks as health decreases.

Current engine limitation: The boss healthbar drawn for mobs flagged with display-boss-healthbar is currently hardcoded to the healthbar named Creation:healthbar_1. There is not yet a config field that selects a healthbar by name, so defining additional healthbar entries — or naming yours anything other than healthbar_1 in the Creation mod — will register a texture that nothing draws. Edit the existing healthbar_1 entry to restyle the boss healthbar.

File Location

Healthbar textures are declared in:

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

Texture images go in the same folder:

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

The file name must match the layer’s name field exactly (case-sensitive).

Minimal Example

textures:
  - name: my_healthbar
    layers:
      - name: my_healthbar_background
        frame-count: 1
        frame-width: 128
        frame-height: 32
      - name: my_healthbar_fill
        frame-count: 1
        frame-width: 128
        frame-height: 32
        health-fill-layer: true

This registers a healthbar named my_healthbar, namespaced as YourMod:my_healthbar, with a static background and a static fill layer. (See the engine-limitation note above: only Creation:healthbar_1 is actually drawn today.)

Full Field Reference

textures:
  - name: my_healthbar          # Required. Registered as YourMod:my_healthbar
    layers:                     # Required. One or more visual layers
      - name: my_healthbar_background   # Required. Base name of the PNG file
        frame-count: 1          # Required. Number of frames in the sprite strip
        frame-width: 128        # Required. Width of one frame in pixels
        frame-height: 32        # Required. Height of one frame in pixels
        frame-time-ms: 100      # Optional. Milliseconds per frame (default: 100)
        frame-durations-ms:     # Optional. Per-frame timing override (see below)
          - count: 2
            duration-ms: 80
          - count: 2
            duration-ms: 2000
        health-fill-layer: false  # Optional. Whether this layer acts as the health fill (default: false)

Top-level fields

Layer fields

Sprite Sheet Format

Each layer is a single PNG containing all animation frames in a horizontal strip:

[ frame 0 ][ frame 1 ][ frame 2 ] …

• Total image width = frame-width × frame-count
• Total image height = frame-height
• Frames are read left to right during playback

For a static layer (frame-count: 1), the image is just the single full-size frame.

Per-Frame Timing

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

Two entry formats are supported and can be mixed freely:

Flat — one value per frame:

frame-durations-ms: [80, 80, 2000, 2000]

Batch — a duration applied to several consecutive frames:

frame-durations-ms:
  - count: 2
    duration-ms: 80
  - count: 2
    duration-ms: 2000

Both produce the same result: frames 0–1 display for 80 ms each, frames 2–3 hold for 2 seconds each.

Note: 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 frame-time-ms is used for all frames instead.

Health Fill Layer

A layer marked health-fill-layer: true is automatically cropped horizontally to represent the entity’s current health as a fraction of its maximum. At full health the layer is fully visible; at zero health it is completely hidden.

The fill layer can be animated like any other layer. This lets you create effects such as a pulsing glow or a shifting color gradient on the health bar that plays continuously regardless of the current health value.

Typical two-layer setup:

textures:
  - name: my_healthbar
    layers:
      - name: my_healthbar_background   # Static empty-bar graphic
        frame-count: 1
        frame-width: 128
        frame-height: 32
      - name: my_healthbar_fill         # Animated fill graphic
        frame-count: 4
        frame-width: 128
        frame-height: 32
        frame-time-ms: 120
        health-fill-layer: true

Both PNGs must be the same frame-width and frame-height. The background should represent the bar at empty or the decorative frame. The fill layer should represent the bar at full health — the engine crops it to the correct width automatically.

Multiple Layers

A healthbar can have any number of layers. They are drawn from bottom to top in declaration order. This allows compositing effects such as:

• A background frame behind the fill
• An animated fill
• A gloss or highlight overlay on top of the fill

textures:
  - name: my_healthbar
    layers:
      - name: my_healthbar_background
        frame-count: 1
        frame-width: 128
        frame-height: 32
      - name: my_healthbar_fill
        frame-count: 4
        frame-width: 128
        frame-height: 32
        frame-time-ms: 120
        health-fill-layer: true
      - name: my_healthbar_gloss
        frame-count: 1
        frame-width: 128
        frame-height: 32

The gloss layer renders over the fill but is not cropped — it stays at full width regardless of health.

Overrides

Your mod can replace the texture used for any healthbar from another mod without changing that mod’s files. Add override with the full mod-namespaced name of the healthbar to replace:

textures:
  - name: healthbar_1
    override: Creation:healthbar_1
    layers:
      - name: healthbar_1_background
        frame-count: 1
        frame-width: 128
        frame-height: 32
      - name: healthbar_1_fill
        frame-count: 1
        frame-width: 128
        frame-height: 32
        health-fill-layer: true

• The name field is still required — each layer’s replacement PNG is located by its name in your mod’s folder, as usual.
• Your override entry fully replaces the target’s registered texture, so redeclare every layer you want to keep.

Complete Example

A healthbar with a static background, an animated fill with mixed timing, and a static gloss overlay:

textures:
  - name: fancy_healthbar
    layers:
      - name: fancy_healthbar_background
        frame-count: 1
        frame-width: 256
        frame-height: 48
      - name: fancy_healthbar_fill
        frame-count: 4
        frame-width: 256
        frame-height: 48
        frame-time-ms: 100
        frame-durations-ms:
          - count: 2
            duration-ms: 80
          - count: 2
            duration-ms: 1500
        health-fill-layer: true
      - name: fancy_healthbar_gloss
        frame-count: 1
        frame-width: 256
        frame-height: 48

The fill cycles through four frames: the first two tick quickly (80 ms each) and the last two linger (1.5 s each), giving a shimmer effect that periodically pauses.