Advancement Viewer Reference

Every setting the advancement viewer accepts. The iframe shell and the JavaScript API expose the same settings under different names, listed side by side below.

For task-shaped guidance, see Embedding with iframe and JavaScript API.

Settings

JavaScript option	Query parameter	Type	Default
bundleUrl	bundle	URL	required
assetBase	assetBase	URL ending in /	assets/ beside the widget module
coreAssetBase	coreAssetBase	URL ending in /	the value of assetBase
scale	scale	1, 2, 3, 4, or auto	auto
langUrls	lang	array of URLs, parameter repeatable	none
font	font	CSS font family	the bundled pixel font
fontUrl	fontUrl	URL of a font file	none
showHidden	showHidden	boolean	false
touchPan	touchPan	widget or page-first	widget
progressUrl	progressUrl	URL	none

bundleUrl

The bundle.json produced by the preprocessor. See Building Advancement Bundles.

Relative values resolve against the page that runs the widget, which for an iframe embed is embed.html on the embed host, not your page.

Every icon and background path inside the bundle resolves against the bundle's own URL, so the bundle directory can move as a unit. Paths starting with http:, https:, data:, or blob: are used as written.

assetBase

Where the widget's own textures and its default font live. The widget appends textures/gui/advancements/ and fonts/ to this value, so the URL must end with a slash. A value without a trailing slash gets one added.

It defaults to the assets/ directory beside the widget module, so every layout that keeps the two together needs no value. That covers the embed host, a copied .host/ tree, and the built dist/.

Set it when you have separated the module from its assets, which in practice means you ran the widget through your own bundler.

The window frame and the tooltip box are nine-sliced from these files before the first frame is drawn, so a base that does not serve them fails the mount with a Could not load sprite error. An asset directory on another origin must send Access-Control-Allow-Origin, because these sprites are loaded with crossOrigin="anonymous" so they can be cropped.

coreAssetBase

Overrides where the default pixel font comes from, and nothing else for this widget. It defaults to assetBase, because the widget ships its own copy of the font.

Set it only to point several widgets at one shared copy. A font that does not load never fails the mount, so a wrong value shows up as text in the browser's own face rather than as an error.

scale

GUI scale, in the game's sense: one Minecraft pixel becomes this many screen pixels. auto picks the largest whole number that fits the container. Values below 1 or above 4 are clamped, and fractions are rounded down. Nothing is ever drawn at a fractional scale.

A forced scale that does not fit shrinks the visible window rather than clipping it.

langUrls and lang

JSON files of translation keys, applied in order, with later files overriding earlier ones. The widget ships no language file, so a bundle built without baked-in text renders raw keys until you supply one here. See Text and Fonts.

In a query string the parameter repeats: &lang=base.json&lang=overrides.json.

font and fontUrl

font is a CSS font family. fontUrl loads a font file and uses it. Given both, the family acts as the fallback while the file loads. See Text and fonts.

showHidden

Renders advancements marked "hidden": true in the datapack before they are completed. The game keeps those invisible until a player earns them, because the server never sends them, so the default matches the game.

Turn it on when the embed is a guide and the point is to show the whole tree.

In a query string, any value other than 0 turns it on: &showHidden=1.

touchPan

How much of a one-finger touch the tree claims on a phone or tablet.

widget is the default. The tree pans under the finger, and once the tree reaches its edge the swipe carries on into the host page. A full-width embed stays escapable.

page-first never takes a vertical swipe, which suits a widget sitting in the middle of a long article. In exchange, one-finger vertical panning of the tree becomes unreachable, because a scroll container cannot be handed an axis its own touch rules deny. Horizontal swipes still pan.

Under both values, an axis the tree cannot scroll goes to the page untouched, and two-finger gestures stay with the browser.

progressUrl

A JSON file marking advancements as completed. A completed advancement gets the obtained frame and box, and its tooltip carries the n/m progress line.

{
  "minecraft:story/mine_stone": true,
  "minecraft:story/smelt_iron": { "criteria": { "iron": true } }
}

true completes the advancement outright. The criteria form counts completed criteria toward the advancement's requirement groups, which drives the n/m progress text. Bundles carry the number of requirement groups but not their membership, so each completed criterion counts as one group. For advancements with a single group the count is exact.

Keys are advancement ids. Ids not present in the bundle are ignored. A file that fails to load leaves everything uncompleted and does not fail the mount.

What the reader can do

• Hover an advancement to see its title and description.
• Hover a tab to see the tab's title.
• Drag inside the window to pan the tree. Scroll or use the wheel to pan.
• Click a tab to switch trees.
• On touch, drag to pan and tap an advancement to pin its tooltip.

Tooltips may overflow the window and reach the edge of the container, exactly as they do in the game.

Sizes

The window is 252 by 140 GUI pixels at minimum, the size of the in-game screen. A bundle with two or more tabs raises that to 280 by 168, because the tab strip reserves a 28 pixel band on each edge it uses.

Larger containers get a larger window rather than a stretched one: the window texture is nine-sliced and the tab strip re-flows to the available edges.

The container needs an explicit width and height. See JavaScript API for the container rules.