# metadata

PracticeBot metadata lets addons attach namespaced runtime data to active bots.

## Good metadata use cases

* arena ID
* queue ID
* match ID
* wave counter
* reward state
* addon ownership marker
* temporary flags
* debug labels for your addon

## Namespaced keys

Always use your plugin as the namespace owner:

```java
NamespacedKey key = new NamespacedKey(this, "match-id");
```

## Supported metadata types

| Type      | Java value type                                       |
| --------- | ----------------------------------------------------- |
| `STRING`  | `String` or any value converted with `String.valueOf` |
| `BOOLEAN` | `Boolean`                                             |
| `INTEGER` | `Integer`                                             |
| `LONG`    | `Long`                                                |
| `DOUBLE`  | `Double`                                              |
| `UUID`    | `UUID`                                                |

## Write metadata

```java
bot.setMetadata(key, PracticeBotMetadataType.STRING, "arena-1");
```

## Read metadata

```java
String arenaId = bot.getMetadata(key)
        .filter(value -> value.type() == PracticeBotMetadataType.STRING)
        .map(PracticeBotMetadataValue::value)
        .map(String.class::cast)
        .orElse("unknown");
```

## Remove metadata

```java
bot.removeMetadata(key);
```

## Snapshot all metadata

```java
Map<NamespacedKey, PracticeBotMetadataValue> all = bot.getMetadataSnapshot();
```

## Threading note

Metadata read methods are detached from Bukkit/Citizens state and may be read off-thread. Metadata mutation methods remain main-thread only.

## Persistence note

Metadata is runtime state. If your addon needs persistence across restarts, save your own data separately and re-attach it when bots are created.


---

# Agent Instructions: 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:

```
GET https://edelweiss-network.gitbook.io/practicebot/metadata.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.