hcu-items/docs/creating_new_content_ja.md

コンテンツ作成ガイド

English

HcuItemsプラグインを使用して新しいアイテムや機能（コンポーネント）を追加するためのガイドです。

イベントハンドリングのアーキテクチャ

イベントシステムは動的登録方式にリファクタリングされました。 EventListener は、登録されたすべてのアイテムとコンポーネントの getEventHandlers() メソッドから「どのイベントに興味があるか」という情報を収集し、必要なBukkitリスナーを動的に登録します。

イベント発生時の流れ:

1. EventListener がイベントを受け取ります。
2. イベントのコンテキスト（例: PlayerInteractEvent から ItemStack を取得）を解決します。
3. アイテムIDやコンポーネントIDが一致する場合、対応する AbstractItem や CustomComponent のハンドラーを実行します。

1. AbstractItem (カスタムアイテム) の作成

独自の挙動を持つ新しいアイテムを作成する場合に使用します。

手順

1. AbstractItem クラスを継承した新しいクラスを作成します。
2. コンストラクタでユニークIDを指定します。
3. buildItem メソッドでアイテムの外見（マテリアル、名前、説明文など）を定義します。
4. getEventHandlers を実装し、このアイテムが処理するイベントを定義します。
5. App.kt の onEnable で ItemRegistry.register(YourItem()) を呼び出して登録します。

実装例

class MyCustomItem : AbstractItem("my_custom_item") {
    
    // アイテムの外見定義
    override fun buildItem(tier: Tier): ItemStack {
        return ItemStack(Material.DIAMOND_SWORD).apply {
            // ... meta設定 ...
        }
    }

    // イベントハンドラーの登録
    override fun getEventHandlers(): Map<KClass<out Event>, ComponentEventHandler<*>> {
        return mapOf(
            // プレイヤーのクリックイベント
            PlayerInteractEvent::class to { event, item ->
                val e = event as PlayerInteractEvent
                e.player.sendMessage("カスタムアイテムを使用しました！")
            },
            // ダメージイベント
            EntityDamageEvent::class to { event, item ->
                val e = event as EntityDamageEvent
                e.damage *= 2.0 // ダメージ2倍
            }
        )
    }
    
    // ライフサイクルメソッド (Bukkitイベントではない) - 直接オーバーライド可能
    override fun onTick(player: Player, item: ItemStack) {
        // 定期実行ロジック
    }
}

2. CustomComponent (コンポーネント) の作成

「ダブルジャンプ」のような、複数のアイテムに共通して付与できる機能を作成する場合に使用します。

手順

1. AbstractComponent を継承し、CustomComponent インターフェースを実装するクラスを作成します。
2. getEventHandlers を実装してロジックを記述します。
3. App.kt で登録します。

実装例

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("スニークでコンポーネント発動！")
                }
            }
        )
    }
}

3. 設定管理 (Configuration)

Config オブジェクトを使用して設定値を管理します。

val cooldown = Config.myFeatureCooldown