doc(util/uuid): util/uuid を追加

Author: sya-ri

README.md

@@ -25,6 +25,9 @@ event<PlayerJoinEvent> {
 }
 ```
 
+### その他
+- [Util / UUID](sample/README.md#util--uuid)
+
 ## 導入
 
 ### EasySpigotAPI をプラグインとして導入する

sample/README.md

@@ -28,4 +28,55 @@ object EventListener : EventRegister {
 }
 ```
 
+## [Util / UUID](util-uuid)
+UUID 関連の便利な関数・クラスを追加します。
+
+```kotlin
+/**
+ * [UUID.fromString] を実行する
+ */
+fun uuid(name: String): UUID
+
+/**
+ * [uuid] を実行するが、例外が発生した場合は null を返す
+ */
+fun uuidOrNull(name: String): UUID?
+
+/**
+ * [Entity] が持つ [UUID] を操作しやすくしたクラス
+ *
+ * 変数に保存する際には [Entity] ではなく [UUID] で保存することを推奨する
+ */
+data class UUIDEntity(val uniqueId: UUID)
+
+/**
+ * [Player] が持つ [UUID] を操作しやすくしたクラス
+ *
+ * 変数に保存する際には [Player] や [OfflinePlayer] ではなく [UUID] で保存することを推奨する
+ */
+data class UUIDPlayer(val uniqueId: UUID)
+```
+
+例として UUIDPlayer を使用した処理を紹介しています。
+
+```kotlin
+object PlayerJoinChecker : EventRegister {
+    /**
+     * [UUIDPlayer] を使うと再ログインしても同一プレイヤーとして認識される
+     *
+     * 2回目のログイン以降は true と出力される
+     */
+    private val useUuidPlayer = mutableSetOf<UUIDPlayer>()
+
+    /**
+     * [Player] を使うと再ログインすると別のインスタンスになる
+     *
+     * 2回目のログイン以降も false と出力される
+     */
+    private val usePlayer = mutableSetOf<Player>()
+    
+    // ... 省略
+}
+```
+
 [<< 戻る](../README.md)

sample/util-uuid/README.md

@@ -0,0 +1,42 @@
+# Util / UUID
+
+## [PlayerJoinChecker.kt](src/main/kotlin/com/github/syari/spigot/api/sample/util/uuid/PlayerJoinChecker.kt)
+
+`UUID`, `UUIDPlayer` を使わないと同じプレイヤーがログインしても、別のプレイヤーとして扱われてしまう。
+そのため、変数として格納する時は必ずそれらを使用する。
+以下の例では、`Player` を用いた時に正常に動作しないことを確認している。
+
+```kotlin
+object PlayerJoinChecker : EventRegister {
+    /**
+     * [UUIDPlayer] を使うと再ログインしても同一プレイヤーとして認識される
+     *
+     * 2回目のログイン以降は true と出力される
+     */
+    private val useUuidPlayer = mutableSetOf<UUIDPlayer>()
+
+    /**
+     * [Player] を使うと再ログインすると別のインスタンスになる
+     *
+     * 2回目のログイン以降も false と出力される
+     */
+    private val usePlayer = mutableSetOf<Player>()
+
+    override fun Events.register() {
+        event<PlayerJoinEvent> {
+            val player = it.player
+            val uuidPlayer = UUIDPlayer.from(player)
+            player.sendMessage(
+                """
+                UUIDPlayer を使用: ${useUuidPlayer.contains(uuidPlayer)} (${useUuidPlayer.size})
+                Player を使用: ${usePlayer.contains(player)} (${usePlayer.size})
+                """.trimIndent()
+            )
+            useUuidPlayer.add(uuidPlayer)
+            usePlayer.add(player)
+        }
+    }
+}
+```
+
+[<< 戻る](../README.md)