Skip to content

T | Migration Guide (v1.1 → v1.2 )

Jump to bottom
Sartaj Singh edited this page May 31, 2025 · 1 revision

T | Migration Guide (v1.1 → v1.2+)

Table of Contents

1. Overview

This guide helps you migrate your FXItems setup, addons, and custom content from v1.1 or earlier to v1.2+.
Version 1.2 introduces major API, utility, and registration changes for improved extensibility, stability, and performance.

2. What Changed in v1.2+?

  • New API Interfaces:
    • com.noctify.API.Registry and com.noctify.API.Utils interfaces.
    • Concrete implementations: RegistryAPI, UtilsAPI.
  • Utility Overhaul:
    • Utilities (cooldowns, mana, projectiles, entity sizing, etc.) now accessed via UtilsAPI.
  • Auto-Registration System:
    • Items, foods, events, and commands can be auto-registered by placing them in the correct package.
  • Expanded Addon Support:
    • Addons/plugins can register their own content via the new APIs.
  • Improved Permission and Command Handling:
    • Permissions and commands are now centrally registered and managed.
  • Updated Dependencies:
    • Java 17+ required, PaperMC 1.21+ recommended.
    • Optional ModelEngine and EntitySize integrations updated.

3. Breaking Changes

  • Direct Static Registration is deprecated:
    • Do NOT register items, foods, events, or commands directly to static maps or lists.
    • Use RegistryAPI for all content registration.
  • Legacy Utility Classes have moved/changed:
    • All utility access should use UtilsAPI.
  • Event and Command Classes:
    • Must be registered via the registry or be in the auto-registration package.
  • Custom Items & Foods Structure:
    • Item/food class and registration structure may require minor updates for auto-registration.

4. Required Steps for Migration

4.1 Update Your Build

  • Update your pom.xml or build.gradle to require Java 17+ and target PaperMC 1.21+.
  • Add/update dependencies for EntitySize, ModelEngine, and PlaceholderAPI as needed.

4.2 Update Registration Patterns

  • Replace any direct static registration with RegistryAPI calls.
  • Example (old): 
    ItemRegistry.registerItem("MY_ITEM", myItemDef);
    New: 
    Registry registry = new RegistryAPI();
registry.registerItem("MY_ITEM", myItemDef);

4.3 Switch to UtilsAPI

  • Replace direct calls to utility classes (e.g., CooldownUtils, ManaUtils) with UtilsAPI.
  • Example (old): 
    CooldownUtils.setCooldown(uuid, "test", 30);
    New: 
    Utils utils = new UtilsAPI();
utils.setCooldown(uuid, "test", 30);

4.4 Use Auto-Registration Where Possible

  • Move custom item/food/command/event classes into the correct com.noctify.Custom sub-packages for auto-registration.
  • Remove redundant manual registration if auto-registration is used.

4.5 Review Permissions

  • Ensure your permission nodes match those in plugin.yml.
  • Update permission checks and documentation for new commands/utilities.

4.6 Update for Optional Plugins

  • If using ModelEngine or EntitySize, check for plugin presence before using related utilities (see examples in new docs).

5. Updated Patterns & Best Practices

  • Always use the API (RegistryAPI, UtilsAPI) for all integration.
  • Place content in the correct package for auto-registration.
  • Use interfaces (Registry, Utils) for type safety and forward compatibility.
  • Test all custom content after migration, especially items/foods with unique behaviors.

6. FAQ & Troubleshooting

Q: My custom items aren’t appearing after upgrade!
A: Make sure your items are registered with RegistryAPI or are located in the correct package for auto-registration.

Q: Why do I get errors about missing methods or fields?
A: You may still be using legacy static access. Update your code to use the new APIs.

Q: Do I need to rewrite all my custom event/command/item classes?
A: No, just ensure registration and utility access match the new API patterns. Most class logic can remain unchanged.

Q: How do I update my addon?
A: Make sure your plugin.yml lists FXItems as a dependency and use the new registration/utilities patterns.

7. See Also

FXItems Wiki

Clone this wiki locally