item-blueprint

item-blueprint is a config-driven, extensible item parser for PaperMC. It turns YAML into fully-built ItemStacks - material or player-head bases, common fields (name, lore, amount, custom model data), and an open-ended set of namespaced components (enchantments, attributes, armor trims, dyed leather, banner patterns, potions, and your own) applied in order.

---

Overview

item-blueprint focuses on doing one thing well: describing items in config without hardcoding a text format, a menu library, or a fixed set of item features into your plugin. It's built on Configurate, has no dependency on any GUI/menu library, and produces plain ItemStack's - so it works equally well for shop menus, kits, /give commands, or reward systems.

---

If you need help, join the discord server.

---

Features

• Material and player-head (skull) bases out of the box — player, base64 and texture-id sources.
• Common fields with sane defaults: name, lore, amount, custom-model-data, glow, unbreakable, hide-flags.
• Extensible, namespaced components: system — enchantments, attributes, armor trims, dyed leather, banner patterns, potions and a generic custom-data escape hatch, all built in.
• Register your own bases and components via a simple SPI — no fork required.
• Pluggable text formatting: MiniMessage, legacy & codes, plain text, or your own TextSerializer.
• Typed, path-aware parse errors (BlueprintResponse) instead of exceptions — a broken YAML edit never has to crash your plugin.
• Placeholder resolution ({key}) decoupled from any specific player/menu context.
• No external database, no menu dependency — a single-purpose library.

---

Requirements

Dependency	Version
Java	21+
PaperMC	1.21+
Configurate	4.2.0 (pulled in transitively)

---

Installation

Add the Bytephoria repository and the dependency to your build.gradle.kts:

repositories {
    maven("https://repo.bytephoria.team/releases")
}

dependencies {
    implementation("team.bytephoria:item-blueprint:1.0.0")
}

Quick example

material: NETHERITE_SWORD
name: "<gradient:#ff0000:#ffaa00>Phoenix Sword"
lore:
  - "<gray>Reborn from the ashes."
glow: true

components:
  enchantments:
    - id: fire_aspect
      level: 2

final ItemBlueprintRegistry registry = ItemBlueprintRegistry.create();
final ItemBlueprint blueprint = registry.compile(itemNode).orElseThrow();
final ItemStack itemStack = blueprint.build();

---

Contributing

1. Fork the repository.
2. Create a branch: git checkout -b feature/my-feature or git checkout -b fix/my-fix
3. Commit your changes and open a Pull Request.

Please follow the existing code style:

• Use this. for all instance field references.
• Use final on parameters, local variables and fields wherever applicable.
• Respect the module boundaries — base/component stay parsing-only, no menu or plugin-specific logic.
• No breaking changes to existing SPI interfaces (ItemBase, ItemComponent, TextSerializer) without prior discussion.

Library Philosophy

item-blueprint is designed to be a general-purpose item parser, not a menu framework or a plugin-specific tool. Pull requests that push the library toward a specific use case — inventory/GUI rendering, click handling, economy hooks, or similar — will be automatically rejected; that's what layout and layout-ui are for. If you need those kinds of features, you have two supported paths:

• Register your own base/component via the SPI. The library is built specifically to be extended without touching its core.
• Fork the project if your use case requires tighter integration or custom behavior.

---

License

This project is released under the MIT License. You are free to use, modify, and distribute it with attribution.