> ## Documentation Index
> Fetch the complete documentation index at: https://items.lodemc.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Config and assets API

> Read any entry of the items folder as written, let owners configure your plugin in the same YAML with your own keys and types, and find the files next to it.

Owners describe everything in YAML under `plugins/LodeItems/items/`, with textures and models beside the YAML. Your plugin can use the same files:

* **Read any entry** as the owner wrote it, with its file and line, as a `ContentEntry`.
* **Add your own keys** to Lode Items entries, such as `mana-cost:` on an item.
* **Add your own `type:`**, such as `type: spell`, so owners define your content in the same folders.
* **Find the files** an entry names, with the same path rules Lode Items uses for `texture:` and `model:`.

Combined with the [resource pack API](https://items.lodemc.net/api/pack.md), this lets you build whole new kinds of content on top of Lode Items' loading.

## Reading entries

Entry methods are static methods on `org.lodemc.api.LodeItemsApi`. Only entries that loaded without errors are included.

**entries()** `List\<ContentEntry\>`

Every entry of the last load, in load order, whatever its type: items, blocks, props, glyphs, sounds, recipes, and types registered by plugins.

**entries(String type)** `List\<ContentEntry\>`

The entries of one `type:`, such as `item`, `block`, `prop` or a type you registered. Entries without a `type:` are `item`.

**entry(Key id)** `ContentEntry`

The entry with id `id`, or `null`. Also takes the id as a `String`. Glyphs, sounds and other types that don't give an item only need ids unique within their own type, so if several entries share an id this returns the one that gives an item.

**entry(String type, Key id)** `ContentEntry`

The entry of `type` with id `id`, or `null`.

## ContentEntry

One entry as written. Values come back as plain Java: `Map<String, Object>` for sections, `List<Object>` for lists, and `String`, `Long`, `Double` or `Boolean` for values.

| Method | Returns | What it is |
| - | - | - |
| `getId()` | `Key` | Its id |
| `getType()` | `String` | Its `type:` in lower case, `item` when it doesn't say |
| `getFile()` | `Path` | The YAML file it's in |
| `getPath()` | `String` | That file relative to `items/`, such as `weapons/fire_staff.yml` |
| `getLine()` | `int` | The line the entry starts on, counted from 1 |
| `getConfig()` | `Map<String, Object>` | Every key at the top of the entry, in the order written |
| `getKeys()` | `Set<String>` | The top-level keys |
| `has(String key)` | `boolean` | Whether a top-level key is there |
| `get(String path)` | `Object` | The value at `path`, or `null`. Dots go into sections: `crop.speed`. |
| `getString(String path, String fallback)` | `String` | A value as text |
| `getInt(String path, int fallback)` | `int` | A whole number |
| `getDouble(String path, double fallback)` | `double` | A number |
| `getBoolean(String path, boolean fallback)` | `boolean` | `true`, `yes` and `on` count as true |
| `getList(String path)` | `List<Object>` | A list. A single value counts as a list of one; missing is an empty list. |
| `getStringList(String path)` | `List<String>` | A list as text |
| `getSection(String path)` | `Map<String, Object>` | A section, or `null` |
| `resolveAsset(String written)` | `Path` | The file an owner named, see below |

The `fallback` is optional on every getter.

### Finding files next to the YAML

`resolveAsset` finds a file the way Lode Items finds `texture:` and `model:` files:

* `fireball.png` or `icons/fireball.png`: relative to the folder of the entry's YAML file
* `/shared/fireball.png`: from the `items/` root

It returns `null` for a `namespace:path` resource location, for a path that leads outside `items/`, and for a file that doesn't exist. Unlike `texture:`, it doesn't add an extension for you.

```java theme={null}
ContentEntry entry = LodeItemsApi.entry("spell", Key.key("lodeitems", "fireball"));
Path icon = entry.resolveAsset(entry.getString("icon", ""));
if (icon == null) getLogger().warning(entry.getPath() + ":" + entry.getLine() + ": icon not found");
```

## Your own config

Register keys and types in your plugin's **`onLoad`**. Lode Items loads its content after every plugin's `onLoad`, so the first load already knows about them. Both are removed when your plugin disables.

**registerConfigKey(Plugin plugin, String key)** `void`

Lets owners write `key` at the top of any entry. Without it, Lode Items warns about it as an unknown option ("Unknown option 'mana-cost' - it is ignored"). Lode Items itself ignores the value; read it with `ContentEntry.get`. Only top-level keys are covered: put everything else in a section under your key.

**registerType(Plugin plugin, String type)** `void`

Makes `type: <type>` a valid entry type that belongs to your plugin. Type names use lower case letters, digits, `_` and `-`. Lode Items builds nothing from these entries and doesn't check their keys; it only loads them as `ContentEntry`s for you. They follow every other rule of the `items/` folder: any file at any depth, one id per entry, friendly errors for broken YAML.

**reload()** `void`

Reads `items/` again and rebuilds the resource pack, like `/lodeitems reload`. The pack is sent again to online players if it changed. It's heavy, so call it only when your own content changed.

## Example: a new kind of content

A spells plugin lets owners define spells in `items/`, each with an icon beside its YAML, and ships the icons in Lode Items' resource pack.

```yaml items/spells/fire/fireball.yml theme={null}
fireball:
  type: spell
  damage: 4.5
  cooldown: 3
  icon: fireball.png       # right beside this file
```

```java theme={null}
public final class SpellsPlugin extends JavaPlugin implements Listener {
    private final Map<Key, Spell> spells = new HashMap<>();

    @Override
    public void onLoad() {
        LodeItemsApi.registerType(this, "spell");
        // Put every spell's icon in the pack as myspells:item/<id>
        LodePack.addContributor(this, files -> {
            for (ContentEntry entry : LodeItemsApi.entries("spell")) {
                Path icon = entry.resolveAsset(entry.getString("icon", ""));
                if (icon == null) continue;
                Key texture = files.texture(Key.key("myspells", "item/" + entry.getId().value()), icon);
                Key model = files.model(texture, "{\"parent\":\"minecraft:item/generated\",\"textures\":{\"layer0\":\"" + texture.asString() + "\"}}");
                files.itemModel(Key.key("myspells", entry.getId().value()), model);
            }
        });
    }

    @Override
    public void onEnable() {
        getServer().getPluginManager().registerEvents(this, this);
        loadSpells();
    }

    @EventHandler
    public void onLodeItemsLoad(LodeItemsLoadEvent event) {
        loadSpells();      // owners ran /lodeitems reload
    }

    private void loadSpells() {
        spells.clear();
        for (ContentEntry entry : LodeItemsApi.entries("spell")) {
            spells.put(entry.getId(), new Spell(entry.getDouble("damage", 1), entry.getInt("cooldown", 0)));
        }
    }
}
```

A stack with the `item_model` component set to `myspells:fireball` then shows the spell's icon. See [Resource pack](https://items.lodemc.net/api/pack.md) for the file helpers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.