> For the complete documentation index, see [llms.txt](https://wiki.microtus.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.microtus.dev/feature/advancements.md).

# Advancements

The advancement API is based around `AdvancementTab`s which represent a tree of `Advancement`s for one or more players. Each player viewing a single `AdvancementTab` will see the same progress as all of the others. If per player `Advancement`s are needed, individual `AdvancementTab`s will need to be created.

`Advancement`s represent a completable advancement in an `AdvancementTab`.

## AdvancementTab

`AdvancementTab`s can be created and retrieved from the `AdvancementManager`.

```java
// Create
AdvancementManager#createTab(String /* namespaced id */, AdvancementRoot);

// Retrieve
AdvancementManager#getTab(String /* namespaced id */);
```

> Namespaced IDs follow the format of `namespace:id`, and may not have any upper case letters.

An `AdvancementRoot` is the origin `Advancement` for a tab, and has the same creation method as a regular `Advancement` (see below) with the exception of the background. A background is a reference to a texture file on the client, for example `minecraft:textures/block/stone.png` for stone block.

```java
AdvancementRoot#<init>(Component, Component, Material, FrameType, int, int, String /* background */);
```

Once created, an `AdvancementTab` may be added and removed from players as follows:

```java
AdvancementTab#addViewer(Player);
AdvancementTab#removeViewer(Player);
```

## Advancement

`Advancement`s can be created with their constructor and added to an `AdvancementTab` with an associated parent.

```java
Advancement#<init>(Component /* title */, Component /* description */, Material, FrameType, int /* x */, int /* y */);

AdvancementTab#createAdvancement(String /* namespaced id */, Advancement /* to add */, Advancement /* parent */);
```

> The parent of an `Advancement` may not be null, and it must have been added to the tab already. The `AdvancementRoot` is a valid parent.

Once an `Advancement` is registered, it can be completed.

```java
Advancement#setAchieved(Boolean);
```

> To make an advancement show a toast, use `Advancement#showToast(Boolean)` before setting it to achieved.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://wiki.microtus.dev/feature/advancements.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.