Lộ trình học KiteHướng dẫn từ A → Z: cài đặt → script đầu tiên → event → lệnh → file → plugin ngoài → dự án hoàn chỉnh

1Kite là gì?

Kite là một công cụ cho phép bạn viết plugin Minecraft bằng Kotlin mà không cần biên dịch / đóng gói / restart server. Bạn đặt file .kite.kts vào thư mục script, Kite tự động nạp và biên dịch sang bytecode, rồi chạy ngay.

2Cài đặt

1. Máy chủ Paper 1.21.11 (Java 21).
2. Tải plugin Kite từ trang chính thức và bỏ vào plugins/.
3. Khởi động server — Kite tạo thư mục plugins/Kite/scripts/.
4. Đặt các file .kite.kts vào thư mục đó.

3Script đầu tiên

Tạo file hello.kite.kts trong plugins/Kite/scripts/:

onLoad {
    println("Hello, World!")
}

Lưu file → chạy /kite reload hello → xem console có dòng Hello, World!. 🎉

4Cấu trúc script

Kite tự import sẵn các gói phổ biến của Paper, nên bạn dùng ngay Player, Material, server, logger… mà không cần import. API của plugin khác thì phải import tường minh. Xem chi tiết: Cấu trúc script.

Script một file

onLoad {
    println("Xin chào từ script một file!")
}

Script đa file

Đặt trong thư mục con — thư mục đó bắt buộc có file entry point tên main.kite.kts. Các file khác import qua @file:Import.

// scripts/my_plugin/main.kite.kts
@file:Import("helpers.kite.kts")

onLoad {
    println("Đã nạp my_plugin!")
    printHelper() // hàm từ helpers.kite.kts
}

// scripts/my_plugin/helpers.kite.kts
fun printHelper() {
    println("Tôi là helper! 🧰")
}

5Vòng đời script

Hai khối chính: onLoad (sau khi nạp) và onUnload (trước khi gỡ). Dùng để khởi tạo và dọn dẹp.

onLoad {
    println("Hello!")
}
onUnload {
    println("Goodbye!")
}

6Gửi tin nhắn (Adventure)

Paper hiện đại dùng Adventure API. sendRichMessage hỗ trợ mã màu kiểu MiniMessage <gold>, <red>…

player.sendRichMessage("<gold>Chào <bold>bạn</bold>!")

7Bắt event

Dùng on<Event> để phản ứng khi sự kiện xảy ra. Event Bukkit chuẩn (PlayerJoinEvent…) tự có sẵn, không cần import.

on<PlayerJoinEvent> { event ->
    event.player.sendRichMessage("<green>Chào mừng đến server!")
}

8Chạy lệnh

• player.performCommand("...") — player tự chạy lệnh.
• server.dispatchCommand(server.consoleSender, "...") — console chạy lệnh (cấp quyền, trao item, lệnh admin).
• Chèn biến: "give ${player.name} diamond 1".

server.dispatchCommand(server.consoleSender, "lp user ${player.name} permission set vip true")
player.performCommand("spawn")

9Hẹn giờ (Scheduler)

Paper cung cấp scheduler Folia-ready. Ví dụ chạy lặp mỗi 60 giây:

server.asyncScheduler.runAtFixedRate(server, { task ->
    server.broadcast(Component.text("⏰ Đã 1 phút!"))
}, 60 * 20, 60 * 20)

10Đọc file YAML

Dùng YamlConfiguration (có sẵn trong Paper) để đọc file cấu hình đặt cạnh script:

import org.bukkit.configuration.file.YamlConfiguration
import java.io.File

val msg = YamlConfiguration.loadConfiguration(File(scriptFile, "message.yml"))

on<PlayerJoinEvent> { e ->
    e.player.sendRichMessage(msg.getString("join.welcome")!!.replace("{player}", e.player.name))
}

11Dùng API plugin khác

Plugin đã cài trên server (FancyNpcs, LuckPerms…) → import tường minh class của nó, không cần @file:Dependency.

import de.oliver.fancynpcs.api.events.NpcInteractEvent

on<NpcInteractEvent> { event ->
    event.player.sendRichMessage("<gold>Bạn click NPC ${event.npc.data.name}")
}

12Dự án hoàn chỉnh: Quest NPC

Áp dụng mọi bài đã học thành một hệ thống: NPC yêu cầu nộp item → hoàn thành thì gán quyền → lần sau vào thẳng. Dùng quyền làm flag lưu trạng thái, cấu hình trong npc.yml.

Vòng khép kín (giống ConditionalEvents):

1. Lần đầu click NPC → chưa có quyền → đọc message nhiệm vụ, yêu cầu nộp item.
2. Đủ item → thu item → lp user ... permission set ... true gán quyền.
3. Lần sau → có quyền → chạy cmd_gained, không làm lại.

// npc.yml — cấu hình mọi NPC
npcs:
  shop:
    perm: "vip.npc.shop"
    need: "GOLD_INGOT"
    amount: 10
    cmd_gained:
      - "shop"
      - "give {player} diamond 1"

13Script hoàn chỉnh (copy-paste)

Đây là toàn bộ script daily_reward.kite.kts — một ví dụ khác hẳn với các ví dụ trong wiki. Nó tổng hợp các kỹ năng đã học: bắt event, đăng ký lệnh, đọc/ghi file YAML, gửi tin Adventure, hẹn giờ. Chỉ cần 1 file duy nhất — file data.yml được tự tạo để ghi nhớ lần nhận quà, bạn không phải tạo file cấu hình nào.

Cách dùng:

1. Copy nguyên khối dưới đây → tạo file daily_reward.kite.kts.
2. Đặt vào plugins/Kite/scripts/.
3. Chạy /kite load daily_reward.
4. Vào game — được chào mừng + nhận quà 1 lần/ngày; gõ /reward để nhận.

// ============================================================
// daily_reward.kite.kts — Chào mừng + quà hằng ngày
// Khác hẳn wiki: event Bukkit, lệnh, file, scheduler
// Cách dùng:
//   1) Đặt file vào  plugins/Kite/scripts/
//   2) Nạp:  /kite load daily_reward
//   3) Player vào server → chào mừng + nhận quà 1 lần/ngày
//   4) Gõ  /reward  → nhận quà qua lệnh
//   File data.yml tự tạo để ghi nhớ lần nhận cuối.
// ============================================================

import net.kyori.adventure.text.minimessage.MiniMessage
import org.bukkit.configuration.file.YamlConfiguration
import java.io.File
import java.time.LocalDate
import java.util.logging.Level

// ---- 1. FILE DỮ LIỆU (tự tạo nếu chưa có) ----
val dataFile = File(scriptFile, "data.yml")
val data = YamlConfiguration()

if (dataFile.exists()) {
    data.load(dataFile)                       // đọc dữ liệu cũ
} else {
    dataFile.parentFile.mkdirs()              // tạo thư mục nếu thiếu
    data.set("meta.created", LocalDate.now().toString())
    data.save(dataFile)                       // ghi file lần đầu
    logger.info("[daily_reward] Đã tạo data.yml lần đầu.")
}

// ---- 2. BẮT EVENT: chào mừng + quà khi vào server ----
on<PlayerJoinEvent> { event ->
    val player = event.player
    val uuid = player.uniqueId.toString()

    // Chào mừng bằng Adventure (màu MiniMessage)
    player.sendRichMessage("<gold>👋 Chào mừng <yellow><bold>${player.name}</bold></yellow> đến server!")
    player.sendRichMessage("<gray>Gõ <green>/reward</green> để nhận quà hằng ngày.")

    // Kiểm tra hôm nay đã nhận chưa
    val last = data.getString("rewards.$uuid")
    val today = LocalDate.now().toString()

    if (last == today) {
        player.sendRichMessage("<red>Bạn đã nhận quà hôm nay rồi. Quay lại ngày mai nhé! ⏰")
    } else {
        // Chưa nhận → tặng quà + ghi nhớ
        player.inventory.addItem(ItemStack(Material.DIAMOND, 1))
        player.inventory.addItem(ItemStack(Material.GOLDEN_APPLE, 2))
        data.set("rewards.$uuid", today)
        saveData()
        player.sendRichMessage("<green>✅ Đã tặng quà hằng ngày cho bạn!")
    }
}

// ---- 3. ĐĂNG KÝ LỆNH /reward ----
command("reward") { player, args ->
    val uuid = player.uniqueId.toString()
    val last = data.getString("rewards.$uuid")
    val today = LocalDate.now().toString()

    if (last == today) {
        player.sendRichMessage("<red>Hôm nay bạn đã nhận quà rồi. Quay lại vào <yellow>ngày mai</yellow>! ⏰")
    } else {
        // Cho phép nhận ngay qua lệnh
        player.inventory.addItem(ItemStack(Material.DIAMOND, 1))
        player.inventory.addItem(ItemStack(Material.GOLDEN_APPLE, 2))
        data.set("rewards.$uuid", today)
        saveData()
        player.sendRichMessage("<green>🎁 Nhận quà thành công qua lệnh!")
    }
}

// ---- 4. HẸN GIỜ: nhắc mọi người nhận quà mỗi 30 phút ----
// Dùng MiniMessage.miniMessage() để parse tag màu <yellow> cho đúng Adventure.
server.asyncScheduler.runAtFixedRate(server, {
    server.broadcast(
        MiniMessage.miniMessage().deserialize("<yellow>⏰ Đừng quên nhận quà hằng ngày: gõ /reward!")
    )
}, 30 * 20L, 30 * 60 * 20L)

// ---- 5. HÀM TIỆN ÍCH ----

/** Lưu dữ liệu xuống file, bọc try/catch để an toàn. */
fun saveData() {
    try {
        data.save(dataFile)
    } catch (e: Exception) {
        logger.log(Level.SEVERE, "[daily_reward] Không lưu được data.yml!", e)
    }
}

// ---- 6. LOG KHI NẠP / GỠ ----
onLoad {
    logger.info("[daily_reward] Đã nạp. Số người đã từng nhận quà: " +
        (data.getConfigurationSection("rewards")?.getKeys(false)?.size ?: 0))
}

onUnload {
    saveData()
    logger.info("[daily_reward] Đã gỡ script.")
}

plugins/Kite/scripts/
└── my_project/          // TẠO THÊM folder con
    ├── main.kite.kts         // bắt buộc tên "main" (entry point)
    ├── message_loader.kite.kts  // loader — hàm dùng chung
    ├── welcome.kite.kts      // script khác dùng sendMsg
    └── message.yml           // thông điệp dùng chung

// main.kite.kts — entry point, import loader
@file:Import("message_loader.kite.kts")

on<PlayerJoinEvent> { event ->
    val player = event.player
    sendMsg(player, "join.welcome", "{player}" to player.name)  // hàm từ loader
    sendMsg(player, "join.tip")
}

// message_loader.kite.kts — hàm dùng chung
import org.bukkit.configuration.file.YamlConfiguration
import java.io.File

val msg = YamlConfiguration.loadConfiguration(File(scriptFile, "message.yml"))

fun sendMsg(player: Player, path: String, vararg repl: Pair<String, String>) {
    val lines: List<String> = when (val v = msg.get(path)) {
        is String -> listOf(v)
        is List<*> -> v.filterIsInstance<String>()
        else -> return
    }
    lines.forEach { line ->
        var out = line
        repl.forEach { (k, v) -> out = out.replace(k, v) }
        player.sendRichMessage(out)
    }
}

// welcome.kite.kts — script độc lập, tự load message.yml
import org.bukkit.configuration.file.YamlConfiguration
import java.io.File

val msg = YamlConfiguration.loadConfiguration(File(scriptFile, "message.yml"))

on<PlayerJoinEvent> { event ->
    sendMsg(event.player, "join.welcome", "{player}" to event.player.name)
}

fun sendMsg(player: Player, path: String, vararg repl: Pair<String, String>) {
    val lines: List<String> = when (val v = msg.get(path)) {
        is String -> listOf(v)
        is List<*> -> v.filterIsInstance<String>()
        else -> return
    }
    lines.forEach { line ->
        var out = line
        repl.forEach { (k, v) -> out = out.replace(k, v) }
        player.sendRichMessage(out)
    }
}