|
| 1 | +--- |
| 2 | +icon: gear |
| 3 | +order: 99 |
| 4 | +--- |
| 5 | +# Getting Started |
| 6 | +This page contains a basic introduction to writing **Lua** scripts with **LuaLink**. |
| 7 | + |
| 8 | +It is important to know the basics of **Java** programming and **Bukkit API** because this is how you will interact with the Minecraft server. |
| 9 | + |
| 10 | +Basic **Lua** knowledge is an obvious prerequisite, but it should be relatively easy to pick up assuming you have some experience with programming. |
| 11 | + |
| 12 | +{.list-icon} |
| 13 | +- [**:icon-paperclip: Lua** (devdocs.io)](https://devdocs.io/lua/) |
| 14 | +- [**:icon-paperclip: Java 21** (devdocs.io)](https://devdocs.io/openjdk~21/) |
| 15 | +- [**:icon-paperclip: Paper Docs** (docs.papermc.io)](https://docs.papermc.io/paper/dev/api) |
| 16 | +- [**:icon-paperclip: Paper Javadocs** (jd.papermc.io)](https://jd.papermc.io/paper/1.21.4/) |
| 17 | + |
| 18 | +<br /> |
| 19 | + |
| 20 | +| Navigation {.compact} | |
| 21 | +| ------------------------------------------------------------ | |
| 22 | +| [1. Creating Scripts](#creating-scripts) | |
| 23 | +| [2. Script Life-cycle](#script-life-cycle) | |
| 24 | +| [3. Importing](#importing) | |
| 25 | +| [4. Constructors and Instances](#constructors-and-instances) | |
| 26 | +| [5. Commands](#commands) | |
| 27 | +| [6. Events](#events) | |
| 28 | +| [7. Scheduler](#scheduler) | |
| 29 | + |
| 30 | +<br /> |
| 31 | + |
| 32 | +### Creating Scripts |
| 33 | +There are a couple of things to keep in mind when using LuaLink. |
| 34 | +- Each script is stored in a separate folder inside the `plugins/LuaLink/scripts` directory, and libraries are stored in the `plugins/LuaLink/libs` directory. |
| 35 | + <sup>More about libraries can be found on the **[Libraries](libraries.md)** page.</sup> |
| 36 | +- Entry point of the script (or library) is a file named `main.lua` or `init.lua`. |
| 37 | + <sup>It doesn't matter which file you choose as the entry point, but you should be consistent with your naming convention.</sup> |
| 38 | +- Script life-cycle can be managed using `/lualink load`, `/lualink unload` and `/lualink reload` commands. |
| 39 | + <sup>More on this can be found on the **[Commands](commands.md)** page.</sup> |
| 40 | + |
| 41 | +<br /> |
| 42 | + |
| 43 | +### Script Life-cycle |
| 44 | +Scripts are automatically loaded after server has been fully started. They can also be loaded, unloaded or reloaded manually using commands. |
| 45 | +```lua |
| 46 | +-- Called after the script has been successfully loaded. |
| 47 | +script:onLoad(function() |
| 48 | + script:logger:info("Script has been loaded.") |
| 49 | +end) |
| 50 | + |
| 51 | +-- Called before the script is attempted to be unloaded. |
| 52 | +script:onUnload(function() |
| 53 | + script:logger:info("Script is about to be unloaded.") |
| 54 | +end) |
| 55 | +``` |
| 56 | + |
| 57 | +<br /> |
| 58 | + |
| 59 | +### Importing and Requiring |
| 60 | +Each referenced **Java** class must be imported using the `import` keyword. |
| 61 | +```lua |
| 62 | +local Bukkit = import("org.bukkit.Bukkit") |
| 63 | +local MiniMessage = import("net.kyori.adventure.text.minimessage.MiniMessage") |
| 64 | + |
| 65 | +script:onLoad(function(event) |
| 66 | + -- Creating Component using MiniMessage serializer. https://docs.advntr.dev/minimessage/index.html |
| 67 | + local component = MiniMessage:miniMessage():deserialize("<rainbow>Did you know you can make rainbow text?!") |
| 68 | + -- Sending component to everyone, including console. |
| 69 | + Bukkit:getServer():sendMessage(component) |
| 70 | +end) |
| 71 | +``` |
| 72 | +Each referenced **Lua** class or library, must be required using the `require` keyword. |
| 73 | +```lua |
| 74 | +local Counter = require("example_library") |
| 75 | + |
| 76 | +script:onLoad(function() |
| 77 | + -- Creating a new instance of the Counter class. |
| 78 | + local counter = Counter.new() |
| 79 | + -- Incrementing the counter three times. |
| 80 | + counter:increment() |
| 81 | + counter:increment() |
| 82 | + counter:increment() |
| 83 | + -- Printing current value of the counter to the console. |
| 84 | + script.logger.info(counter:get() .. |
| 85 | +``` |
| 86 | + |
| 87 | +<br /> |
| 88 | + |
| 89 | +### Constructors and Instances |
| 90 | +New instances of Java classes can be created as follows. |
| 91 | +```lua |
| 92 | +local Bukkit = import "org.bukkit.Bukkit" |
| 93 | +local Keyed = import "net.kyori.adventure.key.Keyed" |
| 94 | +local NamespacedKey = import "org.bukkit.NamespacedKey" |
| 95 | + |
| 96 | +script.onLoad(function() |
| 97 | + -- Creating new instance of NamespacedKey class. |
| 98 | + local key = NamespacedKey("minecraft", "overworld") |
| 99 | + -- Getting instance of the primary world. |
| 100 | + local world = Bukkit:getWorld(key) |
| 101 | + -- Checking if World is instance of Keyed. (SPOILER: IT IS) |
| 102 | + if (Keyed.class:isInstance(world) == true) then |
| 103 | + -- Sending loaded chunks count to the console. |
| 104 | + script.logger.info("World " .. world:key():asString() .. " has " .. world:getChunkCount() .. " chunks loaded.") |
| 105 | + end |
| 106 | +end) |
| 107 | +``` |
| 108 | + |
| 109 | +<br /> |
| 110 | + |
| 111 | +### Commands |
| 112 | +Non-complex commands can be created with little effort using built-in API. |
| 113 | +```lua |
| 114 | +local Bukkit = import "org.bukkit.Bukkit" |
| 115 | + |
| 116 | +-- Function to handle command tab-completion. |
| 117 | +function onTabComplete(sender, alias, args) |
| 118 | + -- No suggestions will be shown for this command. |
| 119 | + return {} |
| 120 | +end |
| 121 | + |
| 122 | +script:registerCommand(function(sender, args) |
| 123 | + -- Joining arguments to string using space as delimiter. |
| 124 | + local message = table.concat(args, " ") |
| 125 | + -- Sending message back to the sender. |
| 126 | + sender:sendRichMessage(message) |
| 127 | +end, { |
| 128 | + -- REQUIRED |
| 129 | + name = "echo", |
| 130 | + -- OPTIONAL |
| 131 | + aliases = {"e", "print"}, |
| 132 | + permission = "scripts.command.echo", |
| 133 | + description = "Prints specified message to the sender.", |
| 134 | + usage = "/echo [player]", |
| 135 | + tabComplete = onTabComplete |
| 136 | +}) |
| 137 | +``` |
| 138 | + |
| 139 | +<br /> |
| 140 | + |
| 141 | +### Events |
| 142 | +Bukkit events can be hooked into relatively easily. |
| 143 | +```lua |
| 144 | +-- Called when player joins the server. |
| 145 | +script:registerEvent("org.bukkit.event.player.PlayerJoinEvent", function(event) |
| 146 | + -- Getting player associated with the event. |
| 147 | + local player = event:getPlayer() |
| 148 | + -- Playing firework sound to the player. |
| 149 | + player:playSound(player:getLocation(), "entity.firework_rocket.launch", 1.0, 1.0) |
| 150 | + -- Sending welcome message to the player. |
| 151 | + player:sendRichMessage("<green>Welcome back to the server, " .. player:getName() .. "!") |
| 152 | +end) |
| 153 | +``` |
| 154 | + |
| 155 | +<br /> |
| 156 | + |
| 157 | +### Scheduler |
| 158 | +Scheduler can be used to register single-use, delayed or repeating tasks. |
| 159 | +```lua |
| 160 | +-- Schedules task to be run on the next tick. |
| 161 | +script.run(function() |
| 162 | + -- Whatever belongs to the task goes here. |
| 163 | +end) |
| 164 | + |
| 165 | +-- Schedules task to be run after 20 ticks has passed. Task function parameter can be omitted if not used. |
| 166 | +script.runDelayed(function(task) |
| 167 | + -- Whatever belongs to the task goes here. |
| 168 | +end, 20) |
| 169 | + |
| 170 | +-- Schedules task to be run after 20 ticks has passed, and repeated every 160 ticks. Task function parameter can be omitted if not used. |
| 171 | +script.runRepeating(function(task) |
| 172 | + -- Whatever belongs to the task goes here. |
| 173 | +end, 20, 160) |
| 174 | +``` |
| 175 | + |
| 176 | +Tasks can also be run asynchronously, but please note that neither the Bukkit API nor the LuaLink API is guaranteed to be thread-safe. |
| 177 | +```lua |
| 178 | +-- Schedules asynchronous task to be run on the next tick. |
| 179 | +script.runAsync(callback: () -> void): void |
| 180 | +-- Schedules asynchronous task to be run after {delay} ticks has passed. Task function parameter can be omitted if not used. |
| 181 | +script.runDelayedAsync(callback: (task: BukkitTask) -> void, delay: number): BukkitTask |
| 182 | +-- Schedules task to be run after {delay} ticks has passed, and repeated every {period} ticks. Task function parameter can be omitted if not used. |
| 183 | +script.runRepeatingAsync(callback: (task: BukkitTask) -> void, delay: number, period: number): BukkitTask |
| 184 | +``` |
0 commit comments