Give items

Every piece is identified by two strings: the set id and the piece key. Run /nxe list in game to see them.

Give one piece

api.createItem("forest_warden", "helmet")
   .ifPresent(item -> player.getInventory().addItem(item));

Give several

api.createItem("forest_warden", "helmet", 3)
   .ifPresent(item -> player.getInventory().addItem(item));

Handle the piece not existing

Optional<ItemStack> maybe = api.createItem("forest_warden", "helmet");
if (maybe.isEmpty()) {
    sender.sendMessage("No such piece.");
    return;
}
player.getInventory().addItem(maybe.get());

Put it straight into an armour slot

api.createItem("forest_warden", "chestplate")
   .ifPresent(item -> player.getInventory().setChestplate(item));

Give a whole set

api.set("forest_warden").ifPresent(set -> {
    for (EquipmentPiece piece : set.pieces()) {
        api.createItem(piece).ifPresent(item ->
            player.getInventory().addItem(item));
    }
});

Give it from a single string

Useful for config files, where you'd write forest_warden:helmet:

EquipmentId.parse("forest_warden:helmet")
    .flatMap(api::piece)
    .flatMap(api::createItem)
    .ifPresent(item -> player.getInventory().addItem(item));

Create items on the main thread. On Folia, use the region thread that owns the player. Looking things up (sets(), piece(), readId()) is safe from any thread — only createItem has this rule.

All four ways to create

Call	Gives you
`createItem(setId, pieceKey)`	One item
`createItem(setId, pieceKey, amount)`	`amount` items
`createItem(piece)`	One item, from an `EquipmentPiece`
`createItem(piece, amount)`	`amount` items, from an `EquipmentPiece`

All four return an empty Optional if the piece doesn't exist or fails to build. An amount below 1 throws IllegalArgumentException.