Skip to main content
The background field on root advancements controls what is drawn behind the advancement tree in the tab panel. Custom Advancements extends this field beyond vanilla’s plain resource-location string to accept a typed JSON object with a type property. This allows you to use scaled images, tiled textures, solid colors, or gradient fills — all without touching a resourcepack.
The background field is only rendered for root advancements, i.e. those that have no parent field. Placing a background on a child advancement has no visual effect and is silently ignored.
Vanilla Minecraft expects background to be a plain resource-location string. Custom Advancements intercepts this field on its own advancements before passing the data to vanilla and replaces the value internally with a placeholder string (customadvancements:fake_texture_location). The actual background rendering is handled entirely by the mod’s client-side renderer.

​
Background Types

Renders no background. The tab panel is left empty (transparent or showing Minecraft’s default dark overlay).
​
string
required
Must be "NONE".
Use this when you want to suppress any background for a root tab, for example if another layer already provides a backdrop via a resourcepack.[INSERT IMAGE: A root advancement tab with NONE background, showing the empty/default panel]
Renders a single image scaled to fill the tab area. This is the most visually rich option and is used in the bundled root.json example. The image is drawn according to the object_fit rule — it does not tile.
​
string
required
Must be "IMAGE".
​
string
required
Resource location of the image file, e.g. customadvancements:textures/screenshot.png. The file must exist as a registered texture. Place custom image files in customadvancements/data/textures/ — see Textures for details.
​
string
Controls how the image is scaled to fit the available tab area. Passed to TextureInfo.fromJson internally. Common values include "COVER" (scale to fill, cropping edges if needed) and "CONTAIN" (scale to fit fully within bounds, potentially leaving empty space).
"COVER" is the best choice for full-bleed screenshots or artwork where you want the image to fill the entire tab without letterboxing.
[INSERT IMAGE: A root advancement tab using the IMAGE type with a full-bleed screenshot background]
Tiles a 16×16 texture across the full tab area, repeating it in both axes — the classic vanilla advancement background style. This matches how Minecraft renders its own advancement backgrounds (e.g. stone.png).
As a convenience, you can also pass the location as a plain string instead of an object:
​
string
required
Must be "TEXTURE" when using the object form.
​
string
required
Resource location of the texture to tile. Can reference any texture registered in the game, including vanilla textures and those from other mods. For custom textures, place the file in customadvancements/data/textures/ and reference it as customadvancements:textures/<filename>.png.
The plain-string shorthand ("background": "namespace:path") is the vanilla format and is fully supported by Custom Advancements. It behaves identically to { "type": "TEXTURE", "location": "namespace:path" }.
[INSERT IMAGE: A root advancement tab using the TEXTURE type, showing the classic tiled vanilla-style background]
Fills the entire tab area with a solid color. Useful for minimalist designs or when you want a branded background without needing an image asset.
​
string
required
Must be "COLOR".
​
string | integer | object
required
The fill color. Three formats are accepted:Comma-separated RGBA string — four integers for red, green, blue, and alpha channels, each in the range 0–255:
Integer — a packed 32-bit ARGB integer:
Object — separate named channel fields:
[INSERT IMAGE: A root advancement tab filled with a solid COLOR background]
Fills the tab area with a linear gradient that blends between two or more colors along a straight line at a configurable angle.
​
string
required
Must be "LINEAR_GRADIENT".
​
number
default:"0"
The angle of the gradient in degrees, measured clockwise from the top. 0 is top-to-bottom, 90 is left-to-right, 135 is top-left to bottom-right.
​
array
required
An array of GradientColor objects parsed by GradientColor.fromJson from the companion mc_libs library. Each element represents a color stop along the gradient. Supply two or more stops; they are applied in the order they appear in the array. Consult the mc_libs documentation for the exact field names and color formats accepted by GradientColor.fromJson.
[INSERT IMAGE: A root advancement tab with a LINEAR_GRADIENT background blending between two colors]
Fills the tab area with a radial gradient that blends outward from the center of the tab to its edges.
​
string
required
Must be "RADIAL_GRADIENT".
​
array
required
An array of GradientColor objects in the same format as LINEAR_GRADIENT. Parsed by GradientColor.fromJson from the mc_libs library. Consult the mc_libs documentation for the exact field names and color formats supported.

​
Placing Custom Texture Files

When using IMAGE or TEXTURE with a custom file, place the image inside customadvancements/data/textures/. The mod reads textures from that folder and syncs them to connected clients. A file at customadvancements/data/textures/screenshot.png is referenced as customadvancements:textures/screenshot.png in the location field. See Textures for the full guide on supported formats and file placement.