LuScript
LuScript 是一个高性能脚本引擎,旨在将 Lua 的轻量级灵活性引入 Spigot 和 Paper 服务器。作为 Skript 等传统脚本引擎的强大替代方案,它摒弃了复杂的语言解析,转而采用标准的编程范式。
LuScript 允许开发者使用简洁高效的 Lua 语法编写服务器逻辑,同时保持对强大服务端功能的直接访问权限,如原生权限管理、动态命令注册以及跨脚本通信。
工作原理
LuScript 将安全的 Lua VM(虚拟机)直接嵌入到您的 Minecraft 服务器中。它将 Bukkit 的内部系统——命令、事件和任务——映射为简单的 Lua 函数。当您保存脚本并运行 /luscript reload [script.lua] 时,引擎会立即卸载旧逻辑,清除已注册的监听器,移除动态创建的命令,并注入新代码,整个过程无需重启服务器、玩家重新登录或重置其他正在运行的脚本。
功能特性
1. 细粒度的单脚本重载
支持即时卸载和重载特定脚本。运行 /luscript reload <filename.lua> 可以有针对性地销毁并重建仅属于该特定脚本的事件监听器、自定义命令和全局信号,而不会影响所有其他活跃的服务器脚本。
2. 智能且美观的开发者诊断
当脚本出错时,不再需要解析杂乱无章、如同“文字墙”般的 Java 堆栈跟踪转储信息。LuScript 动态捕获加载时的语法错误和运行时执行异常:
- 高亮代码片段:在聊天或控制台中打印彩色的 3 行内联代码块,直接显示问题发生的确切行号。
- 可读的错误日志:自动剥离原始的内部 VM 跟踪信息,为开发者提供易于理解、以开发者为中心的反馈。
- 运行时错误捕获:捕获动态命令执行或事件监听器失败的情况,并将详细信息直接路由到游戏内授权开发者的聊天频道。
3. 面向对象的坐标包装器
LuScript 自动将 Bukkit 的坐标封装为智能的 Lua 表。这些表完全支持在 Lua 中直接使用流畅、可链式调用的方法语法:
loc.getDirection():返回一个包含 .getX()、.getY() 和 .getZ() 辅助获取器的方向向量表。
loc.clone():返回位置表的独立精确副本。
loc.add(dx, dy, dz):动态偏移坐标参数并返回修改后的位置表。
- 智能调用约定:完全支持点号 (
loc.add(x, y, z)) 和冒号 (loc:add(x, y, z)) 两种调用约定。
4. 世界检查与方块碰撞 API
使用 GetBlock(location) 在世界中的任何位置读取方块状态。轻松检查方块属性,例如判断方块是否为实体、是否为空气,或获取其材质类型。非常适合编写防碰撞传送机制、自定义破坏事件或交互限制。
代码示例
高级命令与 Tab 补全
注册具有动态 Tab 补全和原生权限的复杂命令,无需编辑任何 plugin.yml 文件。
RegisterCommand("heal", {
permission = "luscript.command.heal",
usage = "/heal [player]",
tabComplete = function(sender, args)
if #args == 1 then
return {"@a", "@p", sender.getName()}
end
end,
execute = function(sender, args)
local target = sender
if #args > 0 then
target = GetPlayer(args[1])
end
if target then
target.setHealth(20)
sender.sendMessage("&aHealed " .. target.getName())
else
sender.sendMessage("&cPlayer not found.")
end
end
})
模块化跨脚本信号
允许多个脚本通过全局信号总线进行通信。非常适合解耦的多文件系统。
-- Script A
RegisterCommand("alert", {
execute = function(sender, args)
EmitSignal("AdminAlert", { user = sender.getName(), msg = args[1] })
end
})
-- Script B
OnSignal("AdminAlert", function(data)
print("ALERT: " .. data.user .. " sent: " .. (data.msg or "nothing"))
end)
自定义物品与安全传送
结合自定义物品引擎和方块检查 API,创建一把剑,只有当玩家不会落入实心方块内部时,才能将其向前传送。
RegisterCommand("godsword", {
execute = function(sender, args)
local item = CreateItem("diamond_sword", 1)
item.setName("&6&lGod Sword")
item.setLore({
"&7A sword with ancient powers.",
"&eRight-click to teleport forward!"
})
item.addEnchant("sharpness", 10)
item.addEnchant("fire_aspect", 2)
sender.giveItem(item)
sender.sendMessage("&eYou received the &6&lGod Sword&e!")
end
})
RegisterEvent("player_interact", function(event)
local player = event.player
local item = event.item
local action = event.action
if item and item.getType() == "diamond_sword" then
if action == "right_click_air" or action == "right_click_block" then
player.sendMessage("&bSwoosh! Teleporting...")
local loc = player.getLocation()
local dir = loc.getDirection()
-- Calculate landing coordinates
local targetLocation = loc.clone().add(dir.getX() * 10, dir.getY() * 10, dir.getZ() * 10)
-- Check if path is clear (feet & head space)
local blockFeet = GetBlock(targetLocation)
local blockHead = GetBlock(targetLocation.clone().add(0, 1, 0))
if blockFeet.isSolid or blockHead.isSolid then
player.sendMessage("&cTeleport path is blocked by solid blocks!")
else
player.teleport(targetLocation)
end
end
end
end)
为什么选择 LuScript?
- 零重新加载延迟:通过
/luscript reload <filename.lua> 即时更新脚本,无需中断玩家或重置其他活动脚本。
- 易读的脚本诊断信息:在聊天窗口或控制台中直接显示带颜色编码的 3 行内联代码错误预览,隐藏丑陋的 Java 堆栈跟踪细节。
- 纯 Lua 语法:利用标准、简洁的编程范式——无需臃肿的自定义语言语法或类似英语的解析逻辑。
- 原生性能:运行于轻量级沙盒化 Lua VM 之上,提供直接的 Bukkit 映射,开销几乎为零。
- 安全沙箱:配置为限制危险的文件/系统调用(
io、os、luajava),确保生产环境的绝对安全性。
LuScript
LuScript is a high-performance scripting engine designed to bring the lightweight flexibility of Lua to Spigot and Paper servers. Built as a powerful alternative to traditional scripting engines like Skript, it removes complex language parsing in favor of standard coding paradigms.
LuScript allows developers to write server logic using the clean, efficient syntax of Lua while maintaining direct access to powerful server-side capabilities like native permissions, dynamic command registration, and inter-script communication.
How It Works
LuScript embeds a secure Lua VM directly into your Minecraft server. It maps Bukkit's internal systems—commands, events, and tasks—into simple Lua functions. When you save a script and run /luscript reload [script.lua], the engine instantly unloads the old logic, clears registered listeners, removes dynamically created commands, and injects the new code without requiring a server restart, player re-logins, or resetting other active scripts.
Features
1. Granular Single-Script Reloading
Unload and reload specific scripts on the fly. Running /luscript reload <filename.lua> selectively tears down and rebuilds only the event listeners, custom commands, and global signals belonging to that specific script, leaving all other active server scripts untouched.
2. Intelligent, Beautiful Developer Diagnostics
No more parsing messy, wall-of-text Java stacktrace dumps when a script fails. LuScript dynamically captures both load-time syntax errors and runtime execution exceptions:
- Highlighted Code Snippets: Prints a colored, 3-line inline code block directly in the chat or console showing the exact line number where the issue occurred.
- Readable Error Logs: Automatically strips raw internal VM traces, giving developers understandable, developer-centric feedback.
- Runtime Error Trapping: Traps dynamic command execution or event listener failures and routes details directly to authorized developer chat feeds in-game.
3. Object-Oriented Location Wrapper
LuScript automatically wraps Bukkit's coordinates into smart Lua tables. These tables fully support fluent, chainable method syntax directly in Lua:
loc.getDirection(): Returns a direction vector table with .getX(), .getY(), and .getZ() helper getters.
loc.clone(): Returns an isolated, exact clone of the location table.
loc.add(dx, dy, dz): Offsets the coordinate parameters dynamically and returns the modified location table.
- Smart Calling Convention: Fully supports both dot (
loc.add(x, y, z)) and colon (loc:add(x, y, z)) calling conventions.
4. World Inspection & Block Collision API
Read block states anywhere in the world using GetBlock(location). Easily inspect block properties such as whether a block is solid, is air, or get its material type. Perfect for writing collision-safe teleportation mechanics, custom break events, or interaction constraints.
Code Showcase
Advanced Commands & Tab-Completion
Register complex commands with dynamic tab-completion and native permissions without editing a single plugin.yml.
RegisterCommand("heal", {
permission = "luscript.command.heal",
usage = "/heal [player]",
tabComplete = function(sender, args)
if #args == 1 then
return {"@a", "@p", sender.getName()}
end
end,
execute = function(sender, args)
local target = sender
if #args > 0 then
target = GetPlayer(args[1])
end
if target then
target.setHealth(20)
sender.sendMessage("&aHealed " .. target.getName())
else
sender.sendMessage("&cPlayer not found.")
end
end
})
Modular Cross-Script Signals
Allow multiple scripts to communicate through a global signal bus. Perfect for decoupled, multi-file systems.
-- Script A
RegisterCommand("alert", {
execute = function(sender, args)
EmitSignal("AdminAlert", { user = sender.getName(), msg = args[1] })
end
})
-- Script B
OnSignal("AdminAlert", function(data)
print("ALERT: " .. data.user .. " sent: " .. (data.msg or "nothing"))
end)
Custom Items & Safety Teleportation
Combine the Custom Item Engine and the Block Inspection API to create a sword that teleports players forward only if they won't end up inside solid blocks.
RegisterCommand("godsword", {
execute = function(sender, args)
local item = CreateItem("diamond_sword", 1)
item.setName("&6&lGod Sword")
item.setLore({
"&7A sword with ancient powers.",
"&eRight-click to teleport forward!"
})
item.addEnchant("sharpness", 10)
item.addEnchant("fire_aspect", 2)
sender.giveItem(item)
sender.sendMessage("&eYou received the &6&lGod Sword&e!")
end
})
RegisterEvent("player_interact", function(event)
local player = event.player
local item = event.item
local action = event.action
if item and item.getType() == "diamond_sword" then
if action == "right_click_air" or action == "right_click_block" then
player.sendMessage("&bSwoosh! Teleporting...")
local loc = player.getLocation()
local dir = loc.getDirection()
-- Calculate landing coordinates
local targetLocation = loc.clone().add(dir.getX() * 10, dir.getY() * 10, dir.getZ() * 10)
-- Check if path is clear (feet & head space)
local blockFeet = GetBlock(targetLocation)
local blockHead = GetBlock(targetLocation.clone().add(0, 1, 0))
if blockFeet.isSolid or blockHead.isSolid then
player.sendMessage("&cTeleport path is blocked by solid blocks!")
else
player.teleport(targetLocation)
end
end
end
end)
Why LuScript?
- Zero Reload Latency: Update your script instantly using
/luscript reload <filename.lua> without interrupting players or resetting other active scripts.
- Readable Script Diagnostics: Displays color-coded, 3-line inline code previews of errors directly in the chat or console, hiding ugly Java stacktrace details.
- Pure Lua Syntax: Leverages standard, clean scripting paradigms—no bulky custom language grammar or English-like parsing required.
- Native Performance: Runs on a lightweight, sandboxed Lua VM, offering direct Bukkit mappings with near-zero overhead.
- Secure Sandbox: Configured to restrict dangerous file/system calls (
io, os, luajava), ensuring absolute safety for production environments.
评论 0
登录后参与评分
还没有评论,来抢沙发吧