KSpigot

About

KSpigot is a kotlin extension for the popular spigot server software for minecraft. KSpigot adds functionality missing in spigot and partly makes it possible to do it the kotlin way. Most of KSpigot's extensions are stable.

IMPORTANT: Extensions marked with NMS annotations like @NMS_GENERAL or @NMS_"VERSIONSTRING" are unstable.

Extensions marked with the @UnsafeImplementaion annotation do not promise to always give the correct result, but are still useful and therefore included in the project. This readme DOES NOT contain any unsafe parts of KSpigot.

First of all

Create an instance of KSpigot (the constructor requires your plugin instance)
Do NOT create multiple instances!

val kSpigot = KSpigot(plugin)

Inside of your onDisable() method, call:

kSpigot.shutdown()

Examples

Simple runnables and schedulers:

bukkitAsync(kSpigot) { /* short form for async schedulers */ }

bukkitSync(kSpigot) { /* sync some code to bukkits main thread */ }

bukkitRunnable(
    kSpigot,
    sync = false,
    howoften = 5,
    delay = 25,
    period = 20
) { /* runnable code */ }

Powerful builders

For items

val wand = KSpigotItems.buildItem(Material.GOLD_BLOCK) {
    
    amount = 3

    addEnchantment(Enchantment.KNOCKBACK, 2)

    itemMeta {

        displayName = "${ChatColor.GOLD}Magic wand"
        unbreakable = true

        addLore {
            + "This wand is truly special."
            + "Try it!"
        }

        customModelData = 1001

        flag(ItemFlag.HIDE_UNBREAKABLE)

    }
    
}

For complex chat components

KSpigotChat.buildComponent {

    text {
        text = "You got a friend request! "
        color = ChatColor.of("#4FEA40")
        bold = true
    }
    
    text { 
        text = "[Accept]"
        color = ChatColor.WHITE
        clickEvent = ClickEvent(ClickEvent.Action.RUN_COMMAND, "friend accept Foo")
        hoverEventText { 
            text { text = "Click here to accept the friend request!"; color = ChatColor.RED }
        }
    }

}

You can also access the builder by calling

commandSender.sendMessage { /* same in here as above */ }

And more

A lot of additional things are also suitable for builders. Just like fireworks etc...

NBTData support

Typesafe and consistent

// load nbt
val nbt = entity.nbtData

// retrieve data via keys
val health = nbt["hearts", NBTDataType.INT]

// set data for a given key
nbt["custom", NBTDataType.DOUBLE] = 3.3

// save data to the entity
entity.nbtData = nbt

// serialization support
val serializedString = nbt.serialize()
val deserializeMethod1 = NBTData(serializedString)
val deserializeMethod2 = NBTData.deserialize(serializedString)

Simple extension methods / values (with kotlin getters)

entity.isGroundSolid
entity.isInWater

vector.isFinite

playerInteractEntityEvent.interactItem

Direction API

Handles the hassle of struggling with direction angles for you.

val cardinal = CardinalDirection.fromLocation(loc) // NORTH, EAST, SOUTH, WEST
val vertical = VerticalDirection.fromLocation(loc) // UP, DOWN, STRAIGHT

// convert to BlockFace
val blockFace = cardinal.facing

CustomItemIdentifiers

You want to mess with resourcepacks and extend your possibilities?
Spigot is lacking a representation of custom items (via custom model data). This is what the data class CustomItemIdentifier is for!

val identifier = CustomItemIdentifier(itemStack)
// or
val identifier = CustomItemIdentifier(1001, Material.IRON_NUGGET)

// get an itemstack with the custom model data applied
val stack = identifier.itemStack

Any questions? Feel free to contact me!

3.8 KiB Raw Blame History