Biome Backdrop Texture Configuration

Configure scrolling, animated background images displayed behind the world for a specific biome.

Biome backdrops are scrolling background images displayed behind the world while the player is in a particular biome. Each biome can have one or more independently animated and parallax-scrolling layers.

File Location

Biome backdrop textures are declared in:

mods/<your-mod>/assets/textures/biome-backdrops/biome-backdrops.yaml

Texture images go in the same folder:

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

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

Minimal Example

textures:
  - name: forest
    layers:
      - name: forest
        frame-count: 1
        frame-width: 1920
        frame-height: 1080

This registers a biome backdrop named forest rendered from forest.png (the PNG filename must match the name exactly, case included). It will be referred to as YourMod:forest anywhere a biome backdrop name is expected. With no animation or parallax specified, the backdrop is a static image with default scroll behavior.

Full Field Reference

textures:
  - name: forest                  # Required. Registered as YourMod:forest
    layers:                       # Required. One or more visual layers
      - name: forest        # Required. Base name of the PNG file for this layer
        frame-count: 4            # Required. Number of frames in the sprite strip
        frame-width: 1920         # Required. Width of one frame in pixels
        frame-height: 1080        # Required. Height of one frame in pixels
        frame-time-ms: 500    # 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: 3000
        parallax: 0.25            # Optional. Parallax scroll multiplier (default: 1.0)
        direction: right          # Optional. Scroll direction: LEFT or RIGHT (default: RIGHT)
        scale-resolution: 2.0     # Optional. Scale factor for the layer (default: 1.0)
        mirror-tiling: true       # Optional. Mirror every other tile (default: false)
        vertical-offset: 100      # Optional. Vertical pixel offset (default: 0)
        horizontal-offset: 0      # Optional. Horizontal pixel offset (default: 0)

Top-level fields

Field	Required	Description
`name`	Yes	Identifier for this backdrop. Registered as `ModName:name`. Must match the biome name this backdrop is associated with.
`override`	No	Full name of another mod’s biome backdrop to replace (e.g. `Creation:forest`). See Overrides.
`layers`	Yes	List of visual layers. At least one required. Layers are drawn in declaration order, bottom to top.

Layer fields

Field	Required	Default	Description
`name`	Yes	—	Base name of the PNG file. The file must be `<name>.png` in the same folder.
`frame-count`	Yes	—	How many frames the animation has. Use `1` for a static layer.
`frame-width`	Yes	—	Width of a single frame in pixels.
`frame-height`	Yes	—	Height of a single frame in pixels.
`frame-time-ms`	No	`100`	Default milliseconds per frame. Used when `frame-durations-ms` is absent or doesn’t match `frame-count`.
`frame-durations-ms`	No	—	Per-frame timing override. See Per-Frame Timing.
`parallax`	No	`1.0`	Horizontal scroll speed multiplier based on the player’s world position. `0.0` = pinned (no scroll), `1.0` = matches player movement, values in between create a parallax depth effect.
`direction`	No	`RIGHT`	Horizontal scroll direction. `LEFT` or `RIGHT`.
`scale-resolution`	No	`1.0`	Scale factor applied to the layer when rendering. Use `2.0` to display the image at twice its pixel size.
`mirror-tiling`	No	`false`	Flip every other tile horizontally. Use this when your image does not wrap — see Tiling.
`vertical-offset`	No	`0`	Vertical pixel offset applied to the backdrop. Positive values shift the image upward. Only applies in-game; the main menu always renders backdrops at offset 0.
`horizontal-offset`	No	`0`	Horizontal pixel offset applied to the backdrop before parallax scrolling is applied.

Tiling

A backdrop is repeated edge-to-edge across the viewport, so a viewport wider than one frame shows at least one join between copies. What happens at that join depends on your image:

If your image wraps — its leftmost and rightmost pixel columns are neighbours, the way a seamless texture is authored — leave mirror-tiling off. Copies repeat straight and the join is invisible.
If it does not wrap, the join is a hard content break: a thin vertical line, full-height or broken into bands depending on which rows disagree. Set mirror-tiling: true and every other copy is flipped horizontally, so each copy’s outer edge always meets a mirrored copy of that same edge column. The join disappears for any image, at the cost of a mirrored repeat — usually unnoticeable for organic scenery, more obvious for directional lighting or anything with text.

Mirroring is per layer, so a multi-layer backdrop can mirror the layers that need it and repeat the rest straight. The alternation is pinned to world position, so it does not change as you travel.

Prefer authoring a wrapping image where you can: mirroring doubles the visual period, which can read as a repeating pattern on a layer with strong landmarks.

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 backdrop (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, 3000, 3000]

Batch — a duration applied to several consecutive frames:

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

Both produce the same result: frames 0–1 last 80 ms each, frames 2–3 last 3000 ms 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.

Multiple Layers

A biome backdrop can have several layers drawn on top of each other. Layers render in declaration order (first declared = bottom). Each layer has its own animation, parallax, and direction settings, allowing complex depth-layered backgrounds.

textures:
  - name: forest
    layers:
      - name: forest_background
        frame-count: 1
        frame-width: 1920
        frame-height: 1080
        parallax: 0.1
      - name: forest_midground
        frame-count: 4
        frame-width: 1920
        frame-height: 1080
        frame-time-ms: 500
        parallax: 0.25
      - name: forest_foreground
        frame-count: 2
        frame-width: 1920
        frame-height: 1080
        frame-time-ms: 200
        parallax: 0.5
        direction: left

Overrides

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

textures:
  - name: forest
    override: Creation:forest
    layers:
      - name: forest
        frame-count: 1
        frame-width: 1920
        frame-height: 1080

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 forest biome backdrop with two layers — a static distant background and an animated foreground with mixed frame timing:

textures:
  - name: forest
    layers:
      - name: forest_background
        frame-count: 1
        frame-width: 1920
        frame-height: 1080
        parallax: 0.1
        scale-resolution: 1.0
      - name: forest
        frame-count: 4
        frame-width: 1920
        frame-height: 1080
        frame-time-ms: 500
        frame-durations-ms:
          - count: 2
            duration-ms: 80
          - count: 2
            duration-ms: 3000
        parallax: 0.25
        direction: right

The background layer scrolls very slowly (0.1×). The foreground layer has 4 frames: the first two cycle quickly at 80 ms each, and the last two hold for 3 seconds each — useful for subtle ambient animation like light rays or swaying foliage with long pauses.

Last updated Aug 17, 2026