# kommand-lib マイグレーションガイド

旧バージョンから最新の Brigadier ネイティブ対応バージョンへの移行方法。

---

## 変更の概要

### 主な変更点

1. **`coordinates()` の型変更** (破壊的変更)
   - `Coordinates3` → `io.papermc.paper.math.Position`
   - `coords.resolve(base)` → `position.toLocation(world)`

2. **内部処理の改善**
   - Player/Entity セレクターの安定性向上
   - Bukkit CommandMap → Brigadier Lifecycle API

---

## マイグレーション手順

### 1. 依存関係の確認

Paper API 1.21 以降が必要です。

```kotlin
dependencies {
    compileOnly("io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT")
}
```

### 2. coordinates の修正

#### Before
```kotlin
coordinates("point") {
    executes {
        val coords = argument<Coordinates3>("point")
        val location = coords.resolve(player.location)
    }
}
```

#### After
```kotlin
import io.papermc.paper.math.Position

coordinates("point") {
    executes {
        val position = argument<Position>("point")
        val location = position.toLocation(player.world)
    }
}
```

### 3. ビルド確認

```bash
./gradlew build
```

---

## Position API

```kotlin
val position = argument<Position>("pos")

// 座標取得
val x = position.x()
val y = position.y()
val z = position.z()

// Location 変換
val location = position.toLocation(world)
```

---

## トラブルシューティング

### `Coordinates3` が見つからない

`Coordinates3` は存在しません。`Position` を使用してください。

```kotlin
// ❌ 間違い
argument<Coordinates3>("pos")

// ✅ 正しい
argument<Position>("pos")
```

### `resolve()` メソッドが見つからない

`Position` には `resolve()` はありません。`toLocation(world)` を使用してください。

```kotlin
// ❌ 間違い
position.resolve(baseLocation)

// ✅ 正しい
position.toLocation(world)
```

---

## FAQ

**Q: 相対座標 (`~`) は使えますか？**  
A: はい、`Position` は相対座標を完全にサポートしています。

**Q: 旧バージョンとの互換性は？**  
A: `coordinates()` の型が変更されているため互換性はありません。他の引数（`player()`, `players()` など）は互換性があります。

**Q: 段階的な移行は可能？**  
A: `coordinates()` を使用している場合は一度にすべて移行する必要があります。