docs: マイグレーションガイド
This commit is contained in:
parent
aab2b1169c
commit
25b40427ed
|
|
@ -1,312 +1,88 @@
|
|||
# kommand-lib マイグレーションガイド
|
||||
|
||||
このガイドでは、旧バージョンの kommand-lib から最新の Brigadier ネイティブ対応バージョンへの移行方法を説明します。
|
||||
|
||||
---
|
||||
|
||||
## 📋 目次
|
||||
|
||||
1. [変更の概要](#変更の概要)
|
||||
2. [破壊的変更](#破壊的変更)
|
||||
3. [マイグレーション手順](#マイグレーション手順)
|
||||
4. [コード例の比較](#コード例の比較)
|
||||
5. [トラブルシューティング](#トラブルシューティング)
|
||||
旧バージョンから最新の Brigadier ネイティブ対応バージョンへの移行方法。
|
||||
|
||||
---
|
||||
|
||||
## 変更の概要
|
||||
|
||||
### 🎯 主な変更点
|
||||
### 主な変更点
|
||||
|
||||
1. **Brigadier ネイティブ対応**
|
||||
- Paper 1.21 の Lifecycle API を使用したコマンド登録
|
||||
- クライアント側での構文ヒントと検証
|
||||
- より正確な型システム
|
||||
1. **`coordinates()` の型変更** (破壊的変更)
|
||||
- `Coordinates3` → `io.papermc.paper.math.Position`
|
||||
- `coords.resolve(base)` → `position.toLocation(world)`
|
||||
|
||||
2. **引数の型変更**
|
||||
- `coordinates()` の返り値が `Coordinates3` から `io.papermc.paper.math.Position` に変更
|
||||
- Player/Entity セレクターの内部処理が改善
|
||||
|
||||
3. **自動登録**
|
||||
- `kommand()` 関数の呼び出しで自動的にコマンドが登録されるように変更
|
||||
|
||||
---
|
||||
|
||||
## 破壊的変更
|
||||
|
||||
### 🔴 1. `coordinates()` 引数の型変更
|
||||
|
||||
#### 旧バージョン (動作しません)
|
||||
```kotlin
|
||||
coordinates("point") {
|
||||
executes {
|
||||
val coords = argument<Coordinates3>("point")
|
||||
val target = coords.resolve(player.location)
|
||||
// Coordinates3 型は存在しません
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 新バージョン (正しい方法)
|
||||
```kotlin
|
||||
coordinates("point") {
|
||||
executes {
|
||||
val position = argument<io.papermc.paper.math.Position>("point")
|
||||
val location = position.toLocation(player.world)
|
||||
// Position 型を使用します
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**理由**: Paper の Brigadier API は `io.papermc.paper.math.Position` を返します。これは Paper の公式 API に準拠しています。
|
||||
|
||||
---
|
||||
|
||||
### 🟡 2. Player/Entity セレクターの内部処理
|
||||
|
||||
**ユーザーコードに変更は不要です**が、内部的に以下の変更が行われました：
|
||||
|
||||
#### 内部処理の改善
|
||||
```kotlin
|
||||
// 旧: 直接キャスト (実行時エラーの原因)
|
||||
val player = context.getArgument("player", Player::class.java)
|
||||
|
||||
// 新: Resolver を使用して解決 (正しい方法)
|
||||
val resolver = context.getArgument("player", PlayerSelectorArgumentResolver::class.java)
|
||||
val player = resolver.resolve(source).firstOrNull()
|
||||
```
|
||||
|
||||
**影響**: Player/Entity 引数がより安定して動作するようになりました。
|
||||
2. **内部処理の改善**
|
||||
- Player/Entity セレクターの安定性向上
|
||||
- Bukkit CommandMap → Brigadier Lifecycle API
|
||||
|
||||
---
|
||||
|
||||
## マイグレーション手順
|
||||
|
||||
### ステップ 1: 依存関係の確認
|
||||
### 1. 依存関係の確認
|
||||
|
||||
`build.gradle.kts` で Paper API のバージョンを確認してください：
|
||||
Paper API 1.21 以降が必要です。
|
||||
|
||||
```kotlin
|
||||
dependencies {
|
||||
compileOnly("io.papermc.paper:paper-api:1.21.10-R0.1-SNAPSHOT")
|
||||
// 1.21 以降が必要です
|
||||
}
|
||||
```
|
||||
|
||||
### ステップ 2: import 文の追加
|
||||
### 2. coordinates の修正
|
||||
|
||||
`coordinates()` を使用している場合、import を追加してください：
|
||||
#### 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: コードの更新
|
||||
|
||||
以下のパターンを検索して置換してください：
|
||||
|
||||
#### パターン 1: coordinates の型指定
|
||||
|
||||
**検索**:
|
||||
```kotlin
|
||||
argument<Coordinates3>("
|
||||
```
|
||||
|
||||
**置換**:
|
||||
```kotlin
|
||||
argument<io.papermc.paper.math.Position>("
|
||||
```
|
||||
|
||||
または、import を追加して：
|
||||
```kotlin
|
||||
argument<Position>("
|
||||
```
|
||||
|
||||
#### パターン 2: coordinates の解決方法
|
||||
|
||||
**検索**:
|
||||
```kotlin
|
||||
val coords = argument<Coordinates3>("pos")
|
||||
val location = coords.resolve(baseLocation)
|
||||
```
|
||||
|
||||
**置換**:
|
||||
```kotlin
|
||||
val position = argument<Position>("pos")
|
||||
val location = position.toLocation(world)
|
||||
```
|
||||
|
||||
### ステップ 4: ビルドとテスト
|
||||
### 3. ビルド確認
|
||||
|
||||
```bash
|
||||
./gradlew build
|
||||
```
|
||||
|
||||
エラーがないことを確認してから、サーバーでテストしてください。
|
||||
|
||||
---
|
||||
|
||||
## コード例の比較
|
||||
|
||||
### 例 1: スポーン地点の設定
|
||||
|
||||
#### ❌ 旧バージョン
|
||||
```kotlin
|
||||
literal("setspawn") {
|
||||
coordinates("point") {
|
||||
executes {
|
||||
val base = (sender as? Player)?.location ?: return@executes
|
||||
val coords = argument<Coordinates3>("point")
|
||||
val target = coords.resolve(base)
|
||||
plugin.server.worlds.first().setSpawnLocation(target)
|
||||
sender.sendMessage("Spawn set to ${target.x}, ${target.y}, ${target.z}")
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### ✅ 新バージョン
|
||||
```kotlin
|
||||
literal("setspawn") {
|
||||
coordinates("point") {
|
||||
executes {
|
||||
val player = sender as? Player ?: return@executes
|
||||
val position = argument<Position>("point")
|
||||
val location = position.toLocation(player.world)
|
||||
player.world.setSpawnLocation(location)
|
||||
sender.sendMessage("Spawn set to ${location.x}, ${location.y}, ${location.z}")
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**変更点**:
|
||||
- `Coordinates3` → `Position`
|
||||
- `coords.resolve(base)` → `position.toLocation(world)`
|
||||
- より明確な変数名
|
||||
|
||||
---
|
||||
|
||||
### 例 2: テレポートコマンド
|
||||
|
||||
#### ❌ 旧バージョン
|
||||
```kotlin
|
||||
literal("tp") {
|
||||
coordinates("destination") {
|
||||
executes {
|
||||
val player = sender as? Player ?: return@executes
|
||||
val coords = argument<Coordinates3>("destination")
|
||||
val target = coords.resolve(player.location)
|
||||
player.teleport(target)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### ✅ 新バージョン
|
||||
```kotlin
|
||||
literal("tp") {
|
||||
coordinates("destination") {
|
||||
executes {
|
||||
val player = sender as? Player ?: return@executes
|
||||
val position = argument<Position>("destination")
|
||||
val location = position.toLocation(player.world)
|
||||
player.teleport(location)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 例 3: 範囲指定コマンド
|
||||
|
||||
#### ❌ 旧バージョン
|
||||
```kotlin
|
||||
literal("fill") {
|
||||
coordinates("pos1") {
|
||||
coordinates("pos2") {
|
||||
executes {
|
||||
val player = sender as? Player ?: return@executes
|
||||
val base = player.location
|
||||
val pos1 = argument<Coordinates3>("pos1").resolve(base)
|
||||
val pos2 = argument<Coordinates3>("pos2").resolve(base)
|
||||
// 処理...
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### ✅ 新バージョン
|
||||
```kotlin
|
||||
literal("fill") {
|
||||
coordinates("pos1") {
|
||||
coordinates("pos2") {
|
||||
executes {
|
||||
val player = sender as? Player ?: return@executes
|
||||
val world = player.world
|
||||
val pos1 = argument<Position>("pos1").toLocation(world)
|
||||
val pos2 = argument<Position>("pos2").toLocation(world)
|
||||
// 処理...
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Position API リファレンス
|
||||
|
||||
### Position のメソッド
|
||||
|
||||
```kotlin
|
||||
interface Position {
|
||||
fun x(): Double
|
||||
fun y(): Double
|
||||
fun z(): Double
|
||||
|
||||
fun blockX(): Int
|
||||
fun blockY(): Int
|
||||
fun blockZ(): Int
|
||||
|
||||
fun toLocation(world: World): Location
|
||||
}
|
||||
```
|
||||
|
||||
### 使用例
|
||||
## Position API
|
||||
|
||||
```kotlin
|
||||
val position = argument<Position>("pos")
|
||||
|
||||
// 座標の取得
|
||||
// 座標取得
|
||||
val x = position.x()
|
||||
val y = position.y()
|
||||
val z = position.z()
|
||||
|
||||
// ブロック座標の取得
|
||||
val blockX = position.blockX()
|
||||
val blockY = position.blockY()
|
||||
val blockZ = position.blockZ()
|
||||
|
||||
// Location への変換
|
||||
val location = position.toLocation(player.world)
|
||||
// Location 変換
|
||||
val location = position.toLocation(world)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## トラブルシューティング
|
||||
|
||||
### 問題 1: `Coordinates3` が見つからない
|
||||
### `Coordinates3` が見つからない
|
||||
|
||||
**エラー**:
|
||||
```
|
||||
Unresolved reference: Coordinates3
|
||||
```
|
||||
|
||||
**解決方法**:
|
||||
`Coordinates3` は存在しません。`io.papermc.paper.math.Position` を使用してください。
|
||||
`Coordinates3` は存在しません。`Position` を使用してください。
|
||||
|
||||
```kotlin
|
||||
// ❌ 間違い
|
||||
|
|
@ -316,136 +92,27 @@ argument<Coordinates3>("pos")
|
|||
argument<Position>("pos")
|
||||
```
|
||||
|
||||
---
|
||||
### `resolve()` メソッドが見つからない
|
||||
|
||||
### 問題 2: `resolve()` メソッドが見つからない
|
||||
|
||||
**エラー**:
|
||||
```
|
||||
Unresolved reference: resolve
|
||||
```
|
||||
|
||||
**解決方法**:
|
||||
`Position` には `resolve()` メソッドはありません。`toLocation(world)` を使用してください。
|
||||
`Position` には `resolve()` はありません。`toLocation(world)` を使用してください。
|
||||
|
||||
```kotlin
|
||||
// ❌ 間違い
|
||||
val location = position.resolve(baseLocation)
|
||||
position.resolve(baseLocation)
|
||||
|
||||
// ✅ 正しい
|
||||
val location = position.toLocation(world)
|
||||
position.toLocation(world)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 問題 3: Player セレクターが動作しない
|
||||
## FAQ
|
||||
|
||||
**症状**: Player 引数を使用するとエラーが発生する
|
||||
**Q: 相対座標 (`~`) は使えますか？**
|
||||
A: はい、`Position` は相対座標を完全にサポートしています。
|
||||
|
||||
**解決方法**:
|
||||
最新バージョンに更新してください。内部的に `ArgumentResolver` が自動的に処理します。
|
||||
**Q: 旧バージョンとの互換性は？**
|
||||
A: `coordinates()` の型が変更されているため互換性はありません。他の引数（`player()`, `players()` など）は互換性があります。
|
||||
|
||||
```kotlin
|
||||
// これは自動的に動作します
|
||||
val player = argument<Player>("target")
|
||||
val players = argument<List<Player>>("targets")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 問題 4: コマンドが登録されない
|
||||
|
||||
**症状**: `/help` にコマンドが表示されない
|
||||
|
||||
**解決方法**:
|
||||
最新バージョンでは `kommand()` 関数の呼び出しで自動的に登録されます。
|
||||
|
||||
```kotlin
|
||||
class MyPlugin : JavaPlugin() {
|
||||
private lateinit var commands: KommandLib
|
||||
|
||||
override fun onEnable() {
|
||||
// これだけで自動的に登録されます
|
||||
commands = kommand(this) {
|
||||
command("mycommand") {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## よくある質問 (FAQ)
|
||||
|
||||
### Q1: 相対座標 (`~`) は引き続き使えますか？
|
||||
|
||||
**A**: はい、引き続き使えます。`Position` は相対座標を完全にサポートしています。
|
||||
|
||||
```kotlin
|
||||
// "~ ~1 ~-2" のような入力が可能
|
||||
val position = argument<Position>("pos")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Q2: 旧バージョンとの互換性はありますか？
|
||||
|
||||
**A**: `coordinates()` 引数の型が変更されているため、**互換性はありません**。マイグレーションが必要です。
|
||||
|
||||
ただし、`player()`, `players()`, `selector()` などの他の引数は互換性があります。
|
||||
|
||||
---
|
||||
|
||||
### Q3: マイグレーションにどのくらい時間がかかりますか？
|
||||
|
||||
**A**: プロジェクトの規模によりますが、通常は以下の通りです：
|
||||
|
||||
- **小規模** (1-5 コマンド): 5-10 分
|
||||
- **中規模** (5-20 コマンド): 15-30 分
|
||||
- **大規模** (20+ コマンド): 30-60 分
|
||||
|
||||
主な作業は検索と置換なので、比較的短時間で完了します。
|
||||
|
||||
---
|
||||
|
||||
### Q4: 段階的な移行は可能ですか？
|
||||
|
||||
**A**: いいえ、`coordinates()` を使用している場合は一度にすべて移行する必要があります。
|
||||
|
||||
ただし、`coordinates()` を使用していないコマンドは変更不要です。
|
||||
|
||||
---
|
||||
|
||||
## サポート
|
||||
|
||||
問題が発生した場合は、以下のドキュメントを参照してください：
|
||||
|
||||
- [README.md](./README.md) - 基本的な使い方
|
||||
- [BRIGADIER_REVIEW.md](./BRIGADIER_REVIEW.md) - 詳細なレビュー
|
||||
- [Paper API Documentation](https://docs.papermc.io/paper/dev/command-api/arguments/location) - Position API の詳細
|
||||
|
||||
---
|
||||
|
||||
## まとめ
|
||||
|
||||
### ✅ マイグレーションチェックリスト
|
||||
|
||||
- [ ] Paper API 1.21 以降を使用していることを確認
|
||||
- [ ] `Coordinates3` を `Position` に置換
|
||||
- [ ] `coords.resolve()` を `position.toLocation()` に置換
|
||||
- [ ] 必要な import を追加
|
||||
- [ ] ビルドが成功することを確認
|
||||
- [ ] サーバーでテストして動作を確認
|
||||
|
||||
### 🎉 完了！
|
||||
|
||||
マイグレーションが完了すると、以下のメリットが得られます：
|
||||
|
||||
- ✅ クライアント側での構文ヒント
|
||||
- ✅ より正確な型チェック
|
||||
- ✅ Paper の公式 API に準拠
|
||||
- ✅ より安定した動作
|
||||
|
||||
ご不明な点がございましたら、お気軽にお問い合わせください。
|
||||
**Q: 段階的な移行は可能？**
|
||||
A: `coordinates()` を使用している場合は一度にすべて移行する必要があります。
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user