技术教程

package com.example.myplugin

import taboolib.common.platform.Plugin
import taboolib.platform.BukkitPlugin

object MyPlugin : BukkitPlugin() {

    override fun onEnable() {
        logger.info("插件已启动！")
    }

    override fun onDisable() {
        logger.info("插件已关闭！")
    }
}

name: MyPlugin
version: ${version}
main: com.example.myplugin.MyPlugin
api-version: "1.20"
author: YourName
description: 我的第一个 TabooLib 插件

taboolib:
  id: myplugin
  loader: kotlin

// 基础用法
@Config(file = "config.yml")
lateinit var config: SecuredFile
    private set

// 带完整参数
@Config(file = "config.yml", autoReload = true, migrate = "%plugin%/config.yml.old")
lateinit var fullConfig: SecuredFile
    private set

// 读取配置
val name = config.getString("plugin.name")
val version = config.getInt("plugin.version")
val enabled = config.getBoolean("plugin.enabled", true)

// 读取列表
val list = config.getStringList("rewards")

// 写入配置
config.set("plugin.name", "MyPlugin")
config.save()

import taboolib.common.platform.function.submit

// 延迟执行（1秒后）
submit(delay = 20) { player.sendMessage("Hello!") }

// 异步执行（不在主线程）
submit(async = true) {
    val result = database.query("SELECT * FROM players")
    submit { player.sendMessage("查询完成: $result") }
}

// 定时重复执行（每秒）
submit(period = 20) { world.players.forEach { it.health = it.maxHealth } }

// 取消任务
val task = submit(period = 20) { }
task.cancel()

import taboolib.common.platform.SubscribeEvent
import org.bukkit.event.EventPriority

// 基本用法
@SubscribeEvent
fun onJoin(event: PlayerJoinEvent) {
    val player = event.player
    player.sendMessage("欢迎来到服务器!")
}

// 指定优先级
@SubscribeEvent(priority = EventPriority.HIGHEST)
fun onHighJoin(event: PlayerJoinEvent) { }

// 忽略已取消的事件
@SubscribeEvent(ignoreCancelled = true)
fun onMove(event: PlayerMoveEvent) { }

// 组合使用
@SubscribeEvent(priority = EventPriority.HIGH, ignoreCancelled = true)
fun onPlayerCommand(event: PlayerCommandPreprocessEvent) { }

import taboolib.common.platform.command.*

command("heal", permission = "myplugin.heal") {
    execute<Player> { player, _, _ ->
        player.health = player.maxHealth
        player.sendMessage("§a已恢复生命值!")
    }
}

command("teleport", permission = "myplugin.teleport") {
    literal("random") {
        execute<Player> { player, _, _ ->
            val randomPlayer = player.world.players.randomOrNull()
            if (randomPlayer != null) {
                player.teleport(randomPlayer.location)
            }
        }
    }
    
    dynamic("target", optional = true) {
        suggestion<Player> { _, _ -> server.onlinePlayers().map { it.name } }
        execute<Player> { player, _, args ->
            val target = server.getPlayer(args["target"]!!)
            if (target != null) player.teleport(target.location)
        }
    }
}

import taboolib.platform.util.*
import taboolib.platform.util.ItemBuilder
import org.bukkit.Material
import org.bukkit.enchantments.Enchantment

// 创建物品
val item = ItemBuilder(Material.DIAMOND_SWORD)
    .name("§b钻石剑")
    .lore("§7一把锋利的钻石剑", "§7攻击力: 10")
    .shiny()
    .nbt("custom", "value")
    .enchant(Enchantment.DAMAGE_ALL, 5)
    .build()

// 玩家头颅
val skull = ItemBuilder(Material.PLAYER_HEAD)
    .name("§e${player.name}")
    .skullOwner(player)
    .build()

// 玩家扩展函数
player.hasItem(Material.DIAMOND, 10)  // 检查物品
player.giveItem(ItemStack(Material.DIAMOND))  // 给予物品

import taboolib.module.chat.Component
import taboolib.module.chat.HoverEvent
import taboolib.module.chat.ClickEvent
import taboolib.module.chat.hoverAction
import taboolib.module.chat.clickAction

// 悬停显示文本
val component = Component.create("§6[点我打开链接]")
    .hover(hoverAction { showText("§e点击打开 GitHub") })
    .click(clickAction { openUrl("https://github.com") })

// 点击执行命令
val cmdComponent = Component.text("§e[传送]")
    .hover(hoverAction { showText("§7传送到主城") })
    .click(clickAction { runCommand("/spawn") })

// 建议补全
val suggestComponent = Component.text("§a[私聊]")
    .click(clickAction { suggestCommand("/msg ${player.name} ") })

import taboolib.library.nms.NMSRegistry

// 获取完整版本字符串
val version = NMSRegistry.getServerVersion()  // 如 "v1_20_R3"

// 获取主版本号
val majorVersion = NMSRegistry.getMajorVersion()  // 如 20

// 版本范围判断
when {
    majorVersion <= 8 -> { /* 1.8.x */ }
    majorVersion in 9..12 -> { /* 1.9 - 1.12 */ }
    majorVersion in 13..16 -> { /* 1.13 - 1.16 */ }
    majorVersion in 17..20 -> { /* 1.17 - 1.20 */ }
    majorVersion >= 21 -> { /* 1.21+ */ }
}

// 动态加载 NMS 类
val nmsClass = NMSRegistry.getNMSClass("PacketPlayOutChat")

import taboolib.module.nms.ItemTag
import taboolib.module.nms.ItemTagData
import taboolib.module.nms.toNBT
import taboolib.module.nms.toItemTag

// 创建 NBT
val tag = ItemTag()
tag["customKey"] = ItemTagData.ofString("value")
tag["number"] = ItemTagData.ofInt(123)
tag["enabled"] = ItemTagData.ofBoolean(true)

// 应用到物品
val itemWithNBT = tag.toItemTag(itemStack)

// 读取物品的 NBT
val readTag = itemWithNBT.toNBT()
val customValue = readTag["customKey"]?.asString()
val intValue = readTag["number"]?.asInt()

// 变量
set{ "name" to "苏屿" }
set{ "level" to 100 }

// 发送消息
tell "Hello World!"
tell color "&a绿色消息"
tell color inline "&bHello {{ player }}"

// 执行命令
cmd "/spawn" as console
cmd "/eco give {{ player }} 1000" as player

// 条件判断
if{ "%player_level%" >= 50 } then {
    tell "你达到了50级!"
} else {
    tell "继续加油!"
}

// 循环
foreach [1, 2, 3, 4, 5] {
    tell "%loop_value%"
}

// 延迟
delay 20 {
    tell "延迟后的消息"
}

import taboolib.module.kether.*
import taboolib.common.platform.ProxyPlayer

// 注册自定义动作
@KetherProperty("myplugin")
object MyActions {
    
    @KetherShell(shared = true)
    val heal = KetherAction.ofScript { script ->
        script.frame.newFrame {
            script.executor().thenAccept { value ->
                val amount = (value as? Number)?.toDouble() ?: 20.0
                val player = script.sender?.castSafely<ProxyPlayer>()
                player?.health = amount
            }
        }
    }
}

// 代码中调用 Kether
fun executeKetherScript(player: ProxyPlayer, script: String) {
    KetherShell.eval(script, sender = player).thenAccept { result ->
        println("Script result: $result")
    }
}