FotiaEnchantment - AI-Friendly Config-Driven Custom Enchantments for Paper / Leaf

Server Software: Paper / Leaf Minecraft Version: 1.21.x Java Version: Java 21 License: MIT GitHub: https://github.com/Ti-Avanti/FotiaEnchantment

---

Create New Enchantments with AI

If you are not familiar with writing enchantment configs, you can download VIBEDOC.md or VIBEDOC.en.md from the GitHub repository.

VIBEDOC is a guide designed for AI tools to understand the FotiaEnchantment configuration format. You can give it to ChatGPT, Codex, Claude, or other AI assistants, then describe the enchantment you want in natural language. The AI can generate usable enchantment YAML configs and language entries for FotiaEnchantment.

For example:

“Create an armor enchantment that has a chance to heal the player and grant Resistance when damaged. Higher levels should make the effect stronger.”

The AI can generate the required config files based on VIBEDOC. After that, place the files into the plugin folder and run /fe reload.

What is FotiaEnchantment?

FotiaEnchantment is a config-driven custom enchantment plugin for Paper and Leaf servers.

It is not just a simple lore-based enchantment plugin. FotiaEnchantment provides a complete configurable enchantment system, including triggers, conditions, effects, language files, GUIs, enchantment books, enchanting table integration, disenchanting items, codex gameplay, and custom enchantment items.

Server owners can create and expand custom enchantments through YAML files without modifying Java code.

---

AI-Friendly Enchantment Creation

One of the main ideas behind FotiaEnchantment is making custom enchantment creation easier with AI.

The plugin provides a dedicated VIBEDOC guide that can be read by AI tools such as ChatGPT, Codex, Claude, and others. You can describe the enchantment you want in natural language, and the AI can generate:

• Enchantment YAML configuration
• Chinese language entries
• English language entries
• Dynamic descriptions for chance, level, duration, range, and values
• Suggested file paths for the plugin structure

For example, you can ask:

Create an armor enchantment that has a 10% to 18% chance to heal the player and grant Resistance when damaged. Higher levels should make the effect stronger.

The AI can then generate valid FotiaEnchantment configuration and language entries based on the plugin format.

---

Core Features

Config-Driven Enchantments

Each enchantment is defined in its own YAML file.

You can configure:

• Enchantment name and multilingual descriptions
• Maximum level
• Rarity and color
• Enchantment type and group
• Supported item types
• Conflicting enchantments
• Enchanting table weight
• Obtain methods
• Triggers
• Conditions
• Effects
• Cooldowns
• Chances
• Durations
• Range and value formulas

Values can scale dynamically with enchantment level, making it easy to create progression-based effects.

---

Trigger / Condition / Effect Pipeline

Enchantments are executed through a configurable pipeline:

Player event -> Find item enchantments -> Match trigger -> Check conditions -> Run effects

This allows you to create gameplay such as:

• Extra damage on attack
• Chance-based healing when damaged
• Buffs after kills
• Vein mining
• Drop multiplication
• Auto smelting
• Fire damage resistance triggers
• Movement, jumping, sprinting, underwater, or low-health effects

All of these can be built through configuration.

---

Enchanting Table Integration

Custom enchantments can appear in the vanilla enchanting table.

Players can naturally obtain custom enchantments through the normal enchanting process instead of only receiving them through commands or shops.

FotiaEnchantment handles:

• Enchanting table preview synchronization
• Custom enchantment rolling
• Mixed vanilla and custom enchantments
• Maximum enchantment count limits
• Conflict restrictions

---

Clean Client-Side Lore Display

With PacketEvents installed, FotiaEnchantment can rewrite enchantment lore displayed to the client.

It supports:

• Hiding default vanilla enchantment lines
• Displaying enchantment names in the plugin format
• Showing rarity colors
• Highlighting curse enchantments
• Showing detailed dynamic effect descriptions
• Managing vanilla enchantment display as well

PacketEvents is optional. The plugin can still run without it, but advanced client-side lore control will be limited.

---

Built-In GUI System

FotiaEnchantment includes multiple configurable GUIs:

• Enchantment codex GUI
• Admin enchantment management GUI
• Fragment crafting GUI
• Codex opening GUI
• Disenchanting GUI

GUI layouts, slots, buttons, item names, lore, background items, and model data can be customized through configuration files.

---

Enchantment Codex

Players can use:

/fe gui

to open the enchantment codex and view available enchantments on the server.

The codex can show:

• Enchantment name
• Rarity
• Type
• Group
• Maximum level
• Supported items
• Detailed effect descriptions

This allows players to understand the server's enchantments directly in-game.

---

Admin GUI

Admins can use:

/fe gui admin

to open the admin management interface.

It supports:

• Viewing all enchantments
• Filtering by category
• Enabling or disabling enchantments
• Quickly obtaining enchantment books
• Viewing enchantment details
• Keeping disabled states after reload

This is useful for testing, balancing, and maintaining enchantments.

---

Codex, Fragments, and Disenchanting Items

FotiaEnchantment includes custom item gameplay such as:

• Starlight fragments
• Enchantment codex items
• Disenchanting crystals

Players can collect fragments, craft codex items, open them to receive random enchantment books, or use disenchanting crystals to remove enchantments from items.

These items can also be customized through configuration.

---

Multilingual Support

The plugin includes multilingual language folders:

• zh_cn
• zh_tw
• en_us
• ja_jp
• ko_kr

If a player's client language is not available, the plugin falls back to the default language.

---

Commands

Command	Description
/fe gui	Open the player enchantment codex
/fe gui admin	Open the admin enchantment GUI
/fe list [category] [page]	View the enchantment list
/fe info <enchant_id>	View enchantment details
/fe enchant <enchant_id> <level>	Apply an enchantment to the held item
/fe give <player> <enchant_id> <level>	Apply an enchantment to a player's held item
/fe giveitem <player> <item_type> [amount] [rarity]	Give custom plugin items
/fe reload	Reload plugin configuration

Commands support tab completion.

---

Recommended For

FotiaEnchantment is suitable for:

• RPG survival servers
• Magic enchantment servers
• Gear progression servers
• Dungeon servers
• Class-based servers
• Random enchantment book systems
• Servers that want AI-assisted enchantment creation
• Servers looking for a more advanced alternative to simple lore enchantment plugins

---

Requirements

• Java 21
• Minecraft 1.21.x
• Paper / Leaf

Optional dependencies:

• PacketEvents
• PlaceholderAPI
• WorldGuard
• AuraSkills
• mcMMO
• MythicMobs
• CraftEngine

---

Installation

1. Download the latest FotiaEnchantment-*.jar.
2. Place it into your server's plugins/ folder.
3. Start the server to generate configuration files.
4. Edit the configuration files as needed.
5. Run /fe reload to reload the plugin.

---

Open Source

GitHub Repository: https://github.com/Ti-Avanti/FotiaEnchantment

Latest Release: https://github.com/Ti-Avanti/FotiaEnchantment/releases/latest

License: MIT