Feat/some new nice to have things

gradle.properties

@@ -7,6 +7,6 @@ org.jetbrains.dokka.experimental.gradle.pluginMode=V2Enabled
 javaVersion=25
 mcVersion=1.21.11
 group=dev.slne.surf
-version=1.21.11-2.67.0
+version=1.21.11-2.68.0
 relocationPrefix=dev.slne.surf.surfapi.libs
 snapshot=false

surf-api-bukkit/surf-api-bukkit-api/api/surf-api-bukkit-api.api

@@ -776,6 +776,7 @@ public final class dev/slne/surf/surfapi/bukkit/api/inventory/dsl/StaticPaneScop
 }
 
 public final class dev/slne/surf/surfapi/bukkit/api/inventory/framework/InventoryFrameworkExtensions {
+	public static final fun getOutlineItem (Lme/devnatan/inventoryframework/View;)Lorg/bukkit/inventory/ItemStack;
 	public static final fun modifyConfig (Lme/devnatan/inventoryframework/context/OpenContext;Lkotlin/jvm/functions/Function1;)Lme/devnatan/inventoryframework/ViewConfigBuilder;
 	public static final fun open (Lme/devnatan/inventoryframework/View;Ljava/util/Collection;)V
 	public static final fun open (Lme/devnatan/inventoryframework/View;Ljava/util/Collection;Ljava/lang/Object;)V
@@ -2431,6 +2432,7 @@ public final class dev/slne/surf/surfapi/bukkit/api/util/UtilBukkit {
 	public static final fun isChunkVisible (Lorg/bukkit/entity/Player;Lorg/bukkit/Location;)Z
 	public static final fun isChunkVisible (Lorg/bukkit/entity/Player;Lorg/bukkit/World;II)Z
 	public static final fun key (Ljava/lang/String;)Lorg/bukkit/NamespacedKey;
+	public static final fun readableString (Lorg/bukkit/Location;Z)Ljava/lang/String;
 	public static final fun toOfflinePlayers (Ljava/lang/Iterable;)Ljava/util/List;
 	public static final fun toOfflinePlayers (Lkotlin/sequences/Sequence;)Lkotlin/sequences/Sequence;
 	public static final fun toPlayers (Ljava/lang/Iterable;)Ljava/util/List;

surf-api-bukkit/surf-api-bukkit-api/src/main/kotlin/dev/slne/surf/surfapi/bukkit/api/inventory/framework/extensions.kt

@@ -2,11 +2,15 @@
 
 package dev.slne.surf.surfapi.bukkit.api.inventory.framework
 
+import dev.slne.surf.surfapi.bukkit.api.builder.buildItem
+import dev.slne.surf.surfapi.bukkit.api.builder.displayName
 import dev.slne.surf.surfapi.bukkit.api.inventory.framework.view.InventoryFrameworkDSL
 import dev.slne.surf.surfapi.core.api.messages.builder.SurfComponentBuilder
 import me.devnatan.inventoryframework.View
 import me.devnatan.inventoryframework.ViewConfigBuilder
 import me.devnatan.inventoryframework.context.OpenContext
+import net.kyori.adventure.text.Component
+import org.bukkit.Material
 import org.bukkit.entity.Player
 
 /**
@@ -142,4 +146,15 @@ inline fun ViewConfigBuilder.titleBuilder(title: @InventoryFrameworkDSL SurfComp
  * @param modifier DSL block applied to the [ViewConfigBuilder]
  */
 inline fun OpenContext.modifyConfig(modifier: @InventoryFrameworkDSL ViewConfigBuilder.() -> Unit) =
-    this.modifyConfig().apply(modifier)
+    this.modifyConfig().apply(modifier)
+
+/**
+ * Builds a neutral outline item for this [View], typically used as a UI border or filler slot.
+ *
+ * The returned item is a gray stained glass pane with an empty display name so it does not
+ * distract from interactive elements in the inventory.
+ */
+val View.outlineItem
+    get() = buildItem(Material.GRAY_STAINED_GLASS_PANE) {
+        displayName(Component.empty())
+    }

surf-api-bukkit/surf-api-bukkit-api/src/main/kotlin/dev/slne/surf/surfapi/bukkit/api/util/bukkit-util.kt

@@ -281,3 +281,30 @@ suspend fun World.getBlockAtAsync(pos: BlockPosition): Block {
         )
     }
 }
+
+/**
+ * Constructs a human-readable string representing the location, including coordinates and optionally
+ * rotation data.
+ *
+ * @param showRotation Determines whether to include rotation values (yaw and pitch) in the output string.
+ */
+fun Location.readableString(showRotation: Boolean) = buildString {
+    append(world?.name ?: "null")
+    append(":(")
+    append("%.2f".format(x))
+    append(", ")
+    append("%.2f".format(y))
+    append(", ")
+    append("%.2f".format(z))
+    if (showRotation) {
+        append(") [")
+        append("%.2f".format(yaw))
+        append(", ")
+        append("%.2f".format(pitch))
+        append("]")
+    } else {
+        append(")")
+    }
+}
+
+typealias BukkitSound = Sound

surf-api-core/surf-api-core-api/api/surf-api-core-api.api

@@ -285,6 +285,8 @@ public final class dev/slne/surf/surfapi/core/api/config/serializer/SpongeConfig
 
 public final class dev/slne/surf/surfapi/core/api/extensions/Packet_eventsKt {
 	public static final fun getPacketEvents ()Lcom/github/retrooper/packetevents/PacketEventsAPI;
+	public static final fun sendPacket (Lcom/github/retrooper/packetevents/wrapper/PacketWrapper;Ljava/lang/Object;)V
+	public static final fun sendPacket (Lcom/github/retrooper/packetevents/wrapper/PacketWrapper;Ljava/util/UUID;)V
 }
 
 public final class dev/slne/surf/surfapi/core/api/font/Small_capsKt {
@@ -6677,6 +6679,7 @@ public final class dev/slne/surf/surfapi/core/api/messages/adventure/Audience_ex
 	public static final fun openBook (Lnet/kyori/adventure/audience/Audience;Lkotlin/jvm/functions/Function1;)V
 	public static final fun playSound (Lnet/kyori/adventure/audience/Audience;Lkotlin/jvm/functions/Function1;)V
 	public static final fun playSound (Lnet/kyori/adventure/audience/Audience;ZLkotlin/jvm/functions/Function1;)V
+	public static final fun sendActionBar (Lnet/kyori/adventure/audience/Audience;Lkotlin/jvm/functions/Function1;)V
 	public static final fun sendText (Lnet/kyori/adventure/audience/Audience;Lkotlin/jvm/functions/Function1;)V
 	public static final fun showBossBar (Lnet/kyori/adventure/audience/Audience;Lkotlin/jvm/functions/Function1;)V
 	public static final fun showTitle (Lnet/kyori/adventure/audience/Audience;Lkotlin/jvm/functions/Function1;)V
@@ -7073,6 +7076,8 @@ public abstract interface class dev/slne/surf/surfapi/core/api/messages/builder/
 	public static synthetic fun text$default (Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;Ljava/lang/Number;Lnet/kyori/adventure/text/format/TextColor;[Lnet/kyori/adventure/text/format/TextDecoration;ILjava/lang/Object;)Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;
 	public static synthetic fun text$default (Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;Ljava/lang/String;Lnet/kyori/adventure/text/format/TextColor;[Lnet/kyori/adventure/text/format/TextDecoration;ILjava/lang/Object;)Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;
 	public static synthetic fun text$default (Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;ZLnet/kyori/adventure/text/format/TextColor;[Lnet/kyori/adventure/text/format/TextDecoration;ILjava/lang/Object;)Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;
+	public fun translatable (Ljava/lang/String;Lnet/kyori/adventure/text/format/TextColor;[Lnet/kyori/adventure/text/format/TextDecoration;)Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;
+	public static synthetic fun translatable$default (Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;Ljava/lang/String;Lnet/kyori/adventure/text/format/TextColor;[Lnet/kyori/adventure/text/format/TextDecoration;ILjava/lang/Object;)Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;
 }
 
 public final class dev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder$Companion {
@@ -7215,6 +7220,8 @@ public final class dev/slne/surf/surfapi/core/api/messages/builder/SurfComponent
 	public static synthetic fun text$default (Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;Ljava/lang/Number;Lnet/kyori/adventure/text/format/TextColor;[Lnet/kyori/adventure/text/format/TextDecoration;ILjava/lang/Object;)Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;
 	public static synthetic fun text$default (Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;Ljava/lang/String;Lnet/kyori/adventure/text/format/TextColor;[Lnet/kyori/adventure/text/format/TextDecoration;ILjava/lang/Object;)Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;
 	public static synthetic fun text$default (Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;ZLnet/kyori/adventure/text/format/TextColor;[Lnet/kyori/adventure/text/format/TextDecoration;ILjava/lang/Object;)Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;
+	public static fun translatable (Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;Ljava/lang/String;Lnet/kyori/adventure/text/format/TextColor;[Lnet/kyori/adventure/text/format/TextDecoration;)Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;
+	public static synthetic fun translatable$default (Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;Ljava/lang/String;Lnet/kyori/adventure/text/format/TextColor;[Lnet/kyori/adventure/text/format/TextDecoration;ILjava/lang/Object;)Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;
 	public static fun variableKey (Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;C[Lnet/kyori/adventure/text/format/TextDecoration;)Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;
 	public static fun variableKey (Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;Ljava/lang/Number;[Lnet/kyori/adventure/text/format/TextDecoration;)Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;
 	public static fun variableKey (Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;Ljava/lang/String;[Lnet/kyori/adventure/text/format/TextDecoration;)Ldev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder;

surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/extensions/packet-events.kt

@@ -1,5 +1,28 @@
 package dev.slne.surf.surfapi.core.api.extensions
 
 import com.github.retrooper.packetevents.PacketEvents
+import com.github.retrooper.packetevents.wrapper.PacketWrapper
+import dev.slne.surf.surfapi.core.api.surfCoreApi
+import java.util.*
 
-val packetEvents get() = PacketEvents.getAPI() ?: error("PacketEvents API is not yet initialized")
+val packetEvents get() = PacketEvents.getAPI() ?: error("PacketEvents API is not yet initialized")
+
+/**
+ * Sends the current packet to the player associated with the provided UUID.
+ * If no player is found for the specified UUID, the method returns without performing any action.
+ *
+ * @param uuid the UUID of the player to whom the packet will be sent
+ */
+fun PacketWrapper<*>.sendPacket(uuid: UUID) {
+    val player = surfCoreApi.getPlayer(uuid) ?: return
+    sendPacket(player)
+}
+
+/**
+ * Sends the current packet to the specified player.
+ *
+ * @param player the platform-specific player object to whom the packet will be sent
+ */
+fun PacketWrapper<*>.sendPacket(player: Any) {
+    packetEvents.playerManager.sendPacket(player, this)
+}

surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/adventure/audience-extension.kt

@@ -15,6 +15,10 @@ inline fun Audience.sendText(block: SurfComponentBuilder.() -> Unit) {
     sendMessage(SurfComponentBuilder(block))
 }
 
+inline fun Audience.sendActionBar(block: SurfComponentBuilder.() -> Unit) {
+    sendActionBar(SurfComponentBuilder(block))
+}
+
 inline fun Audience.openBook(block: @BookDsl Book.Builder.() -> Unit) {
     openBook(Book(block))
 }
@@ -45,8 +49,11 @@ inline fun Audience.uuid() = uuidOrNull() ?: error("Audience does not have a UUI
 inline fun Audience.nameOrNull() = getPointer(Identity.NAME)
 inline fun Audience.name() = nameOrNull() ?: error("Audience does not have a name pointer")
 inline fun Audience.displayNameOrNull() = getPointer(Identity.DISPLAY_NAME)
-inline fun Audience.displayName() = displayNameOrNull() ?: error("Audience does not have a display name pointer")
+inline fun Audience.displayName() =
+    displayNameOrNull() ?: error("Audience does not have a display name pointer")
+
 inline fun Audience.testPermission(permission: String) =
     getPointer(PermissionChecker.POINTER)?.value(permission) ?: TriState.NOT_SET
 
-inline fun Audience.hasPermission(permission: String) = getPointer(PermissionChecker.POINTER)?.test(permission) ?: false
+inline fun Audience.hasPermission(permission: String) =
+    getPointer(PermissionChecker.POINTER)?.test(permission) ?: false

surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/adventure/sound-extensions.kt

@@ -35,4 +35,6 @@ inline fun sound(block: @SoundDsl Sound.Builder.() -> Unit): Sound {
  * @param block The configuration block for building the sound.
  * @return A configured [Sound] instance.
  */
-inline fun Sound(block: @SoundDsl Sound.Builder.() -> Unit) = sound(block)
+inline fun Sound(block: @SoundDsl Sound.Builder.() -> Unit) = sound(block)
+
+typealias AdventureSound = Sound

surf-api-core/surf-api-core-api/src/main/kotlin/dev/slne/surf/surfapi/core/api/messages/builder/SurfComponentBuilder.kt

@@ -1,16 +1,13 @@
 package dev.slne.surf.surfapi.core.api.messages.builder
 
+import dev.slne.surf.surfapi.core.api.messages.*
 import dev.slne.surf.surfapi.core.api.messages.Colors.Companion.NOTE
 import dev.slne.surf.surfapi.core.api.messages.Colors.Companion.PREFIX
 import dev.slne.surf.surfapi.core.api.messages.Colors.Companion.SPACER
 import dev.slne.surf.surfapi.core.api.messages.Colors.Companion.VARIABLE_VALUE
-import dev.slne.surf.surfapi.core.api.messages.CommonComponents
 import dev.slne.surf.surfapi.core.api.messages.CommonComponents.DISCONNECT_HEADER
 import dev.slne.surf.surfapi.core.api.messages.CommonComponents.DISCORD_LINK
 import dev.slne.surf.surfapi.core.api.messages.CommonComponents.TIME_SEPARATOR
-import dev.slne.surf.surfapi.core.api.messages.NoLowercase
-import dev.slne.surf.surfapi.core.api.messages.joinToComponent
-import dev.slne.surf.surfapi.core.api.messages.joinToComponentNewLine
 import net.kyori.adventure.key.Key
 import net.kyori.adventure.text.*
 import net.kyori.adventure.text.event.ClickEvent
@@ -83,6 +80,11 @@ interface SurfComponentBuilder : TextComponent.Builder, ComponentBuilderColors {
     fun note(any: Any, vararg decoration: TextDecoration) = text(any.toString(), NOTE, *decoration)
 
     fun ellipsis(color: TextColor? = SPACER) = append(CommonComponents.ELLIPSIS.color(color))
+    fun translatable(
+        key: String,
+        color: TextColor? = Colors.WHITE,
+        vararg decoration: TextDecoration
+    ) = append(Component.translatable(key, color, *decoration))
 
     fun appendDiscordLink() = append(DISCORD_LINK)
     fun appendDisconnectHeader() = append(DISCONNECT_HEADER)