hcu-items/docs/creating_new_content.md

Content Creation Guide

日本語 (Japanese)

This project provides a framework for adding new items and features (components) using the HcuItems plugin.

Event Handling Architecture

The event system has been fully refactored to be dynamic. The EventListener collects event interests from all registered items and components via their getEventHandlers() method and dynamically registers the necessary Bukkit listeners.

When an event occurs:

1. EventListener receives the event.
2. It determines the context (e.g., extracting the ItemStack from PlayerInteractEvent).
3. It dispatches the event to the appropriate AbstractItem or CustomComponent handler if the item matches.

1. Creating an AbstractItem (Custom Item)

Use this when creating an item with completely unique behavior.

Steps

1. Create a new class that inherits from the AbstractItem class.
2. Specify a unique ID in the constructor.
3. Implement the buildItem method to define the item's appearance.
4. Implement getEventHandlers to define which events this item handles.
5. Register by calling ItemRegistry.register(YourItem()) in App.kt's onEnable.

Example

class MyCustomItem : AbstractItem("my_custom_item") {
    
    // Define item appearance
    override fun buildItem(tier: Tier): ItemStack {
        return ItemStack(Material.DIAMOND_SWORD).apply {
            // ... meta ...
        }
    }

    // Register Event Handlers
    override fun getEventHandlers(): Map<KClass<out Event>, ComponentEventHandler<*>> {
        return mapOf(
            // Handle Player Interact
            PlayerInteractEvent::class to { event, item ->
                val e = event as PlayerInteractEvent
                e.player.sendMessage("You used the custom item!")
            },
            // Handle Entity Damage
            EntityDamageEvent::class to { event, item ->
                val e = event as EntityDamageEvent
                e.damage *= 2.0 // Double damage
            }
        )
    }
    
    // Lifecycle method (Not a Bukkit event) - safe to override directly
    override fun onTick(player: Player, item: ItemStack) {
        // Run logic every tick (or configured interval)
    }
}

2. Creating a CustomComponent

Use this to add shared behavior (like a "Double Jump" ability) to multiple items.

Steps

1. Create a class that inherits from AbstractComponent and implements CustomComponent.
2. Implement getEventHandlers to define event logic.
3. Register in App.kt.

Example

class MyComponent(plugin: App) : AbstractComponent(plugin, "my_component") {

    override fun getEventHandlers(): Map<KClass<out Event>, ComponentEventHandler<*>> {
        return mapOf(
            PlayerToggleSneakEvent::class to { event, item ->
                val e = event as PlayerToggleSneakEvent
                if (e.isSneaking) {
                    e.player.sendMessage("Component activated by sneaking!")
                }
            }
        )
    }
}

3. Configuration Management

Use the Config object to manage values.

val cooldown = Config.myFeatureCooldown