A | Getting Started & Plugin Overview

A | Getting Started & Plugin Overview

---

Table of Contents

• 1. What is FXItems?
• 2. Installation & Requirements
• 3. Folder/File Structure After First Run
• 4. Core Concepts & New Plugin Architecture
• 5. Quickstart: Making Your First Custom Item
• 6. Recommended Next Steps

---

1. What is FXItems?

FXItems is a modern, modular Spigot/Paper plugin for Minecraft that allows you to create, configure, and extend custom items, foods, commands, events, and more, all from code—no attribute files, no copy-pasting, and no boilerplate!

Highlights:

• Centralized, object-oriented API: all item data and behavior in a single Java object.
• No more attribute files—every property is set in code.
• Pluggable: create addons/plugins that register their own items, foods, or systems.
• Strong separation between the core API and implementation, making updates and maintenance easy.
• Auto-registration system: just annotate your classes, and FXItems does the rest.
• Utility APIs for cooldowns, mana, effects, projectiles, and more.
• Full support for custom recipes, rarities, one-time crafts, resource-pack models, and advanced lore.

---

2. Installation & Requirements

Server Requirements

• Minecraft: 1.18 or later (Java Edition)
• Java: 17 or higher (recommended: Java 17+)
• Server type: Spigot, Paper, or compatible fork

Installing FXItems

1. Download the latest release:
   Releases Page
2. Place the JAR in your server's plugins/ directory.
3. Start/restart your server.
   The plugin will generate its data folders and config files.
4. (Optional) Upload your resource pack for custom models to plugins/FXItems/resourcepack/

Updating FXItems

• Replace the old JAR with the new one.
• Review the Migration Guide (v1.1→v1.2+) for any breaking changes.

---

3. Folder/File Structure After First Run

Path	Purpose
/plugins/FXItems/	Main plugin folder
/plugins/FXItems/config.yml	Main configuration file
/plugins/FXItems/RarityLang.yml	Control rarity display names/colors
/plugins/FXItems/resourcepack/	Optional: Place custom resource pack files here
/plugins/FXItems/data/	Player/item data, crafting logs, etc.

---

4. Core Concepts & New Plugin Architecture

FXItems is designed around the following core systems:

4.1 Registry System

All items, foods, commands, and events are registered via the Registry API:

• Registry: Interface for all registration operations.
• RegistryAPI: The main implementation used by plugins/addons.

Why?
This enables:

• Addon/plugin developers to register content without editing FXItems itself.
• Dependency injection for advanced setups or testing.
• Safe, clear, conflict-free registration of custom content.

4.2 Utilities System

All utility and helper functions (cooldowns, mana, projectiles, effects, etc.) are accessed through the Utils API:

• Utils: Interface for utility methods.
• UtilsAPI: Main implementation.

4.3 Object-Driven Items

• No attribute files!
  Every custom item is a single FXItemDefinition object specifying all its data, lore, rarity, recipe, and behavior.
• Behavior:
  Implement the FXItemBehavior interface for custom logic (abilities, passive effects, etc.).

4.4 Auto-Registration

• Just annotate your behavior classes with @AutoRegister, and call the registrar in your plugin's onEnable.
• FXItems will scan and register everything for you—no manual registration needed for large codebases.

4.5 Addon/Plugin Support

• Write your own plugins that depend on FXItems, registering content at runtime.
• See FXItems API & Making Addons.

---

5. Quickstart: Making Your First Custom Item

5.1 Define Your Item

FXItemDefinition mySword = new FXItemDefinition(
    "mythril_sword",
    "§bMythril Sword",
    Material.DIAMOND_SWORD,
    Rarity.RARE,
    new MySwordBehavior(),
    null, // customModelData (optional)
    false, // oneTimeCraft
    true,  // unbreakable
    true,  // hideFlags
    Arrays.asList(
        "§7A sword forged from rare mythril.",
        "§fRight Click: Shoots a beam!"
    ),
    new FXItemRecipe(
        Arrays.asList(
            new ItemStack(Material.AIR),
            new ItemStack(Material.DIAMOND),
            new ItemStack(Material.AIR),
            new ItemStack(Material.IRON_BLOCK),
            new ItemStack(Material.STICK),
            new ItemStack(Material.IRON_BLOCK),
            new ItemStack(Material.AIR),
            new ItemStack(Material.STICK),
            new ItemStack(Material.AIR)
        ),
        true, // shaped
        1,    // output amount
        true  // enabled
    )
);

5.2 Register Your Item

Manual (in your plugin's onEnable):

Registry registry = new RegistryAPI();
registry.registerItem("mythril_sword", mySword);

Auto-registration (recommended for large projects):

@AutoRegister
public class MySwordBehavior implements FXItemBehavior {
    // ...implement hooks...
}

// In your main class:
@Override
public void onEnable() {
    BehaviorAutoRegistrar.registerAll(this, "your.plugin.package");
}

---

6. Recommended Next Steps

• B | The Registry System: Items, Foods, Commands, Events:
  Learn every detail of the Registry API, including all registration functions and advanced patterns.
• C | Creating Custom Items:
  Dive deep into FXItemDefinition, behaviors, advanced recipes, and more.
• S | Auto-Registration System:
  Master the annotation-based registration for big projects.
• Q | FXItems API & Making Addons:
  Build your own plugins that integrate with FXItems.
• T | Migration Guide (v1.1 → v1.2+):
  For converting old code.

---

You are ready to make anything. Explore the sidebar for the full technical manual!