SuperLuckyBlock | The MOST CUSTOMIZABLE LuckyBlock Plugin | CUSTOM Surprises | Wands | 1.16 - 1.21.x -----
Create your own CUSTOM surprises, lucky blocks, wands, and more with SuperLuckyBlock!4.4.0 - Scripting Support for Custom Surprises
NOTE: Scripting is disabled by default! You will have to enable the feature in the settings.yml.
Please only run scripts from which you fully know what they are doing!
About
This update adds support for the use of Lua scripts as custom surprises. This allows you to make custom surprises without the limitations of the configuration file (which only allows you to drop items, spawn entities, etc.). Lua scripts can freely access Java and Spigot methods, giving you way more options than your normal custom surprise.
I intended to add JavaScript support, but support for this was removed in newer Java versions. Adding support for JavaScript became a lot more complicated. I will be looking into adding support for JavaScript or other scripting languages in the future.
Sandbox
By default, all Lua scripts are considered untrusted, which means it will run in a sandbox. In this sandbox, the script only has access to a select few methods that I consider safe to use. When a script is marked as trusted in settings.yml, the script gets access to all Java and Spigot methods. This allows you to create any surprise you want!
If there are any methods that are not available in the sandbox, please contact me and I will look into making them available.
Using the script in a surprise
After you have created a script, you will have to add it to a luckyblock. You can do that like this:
default.yml
CustomSurprises:
Example:
Name : Example
Chance : 100.0
Permission:
Enabled : false
Commands:
Enabled : false
Items:
Enabled : false
Entities:
Enabled : false
Building:
Enabled : false
Blocks:
Enabled : false
Messages:
Enabled : false
Script:
Enabled : true
Script : "example.lua"
Examples
When you enable scripting in the settings.yml file, and you restart the server, a new folder named "scripts" will be created. This folder contains 2 example scripts, showing you how everything works. They also contain a bunch of information at the top of the file. You can also find these examples below.
Untrusted Script Example(example.lua)
Trusted Script Example(example_trusted.lua)
About
This update adds support for the use of Lua scripts as custom surprises. This allows you to make custom surprises without the limitations of the configuration file (which only allows you to drop items, spawn entities, etc.). Lua scripts can freely access Java and Spigot methods, giving you way more options than your normal custom surprise.
I intended to add JavaScript support, but support for this was removed in newer Java versions. Adding support for JavaScript became a lot more complicated. I will be looking into adding support for JavaScript or other scripting languages in the future.
Sandbox
By default, all Lua scripts are considered untrusted, which means it will run in a sandbox. In this sandbox, the script only has access to a select few methods that I consider safe to use. When a script is marked as trusted in settings.yml, the script gets access to all Java and Spigot methods. This allows you to create any surprise you want!
If there are any methods that are not available in the sandbox, please contact me and I will look into making them available.
Using the script in a surprise
After you have created a script, you will have to add it to a luckyblock. You can do that like this:
default.yml
Code (YAML):
CustomSurprises:
Example:
Name : Example
Chance : 100.0
Permission:
Enabled : false
Commands:
Enabled : false
Items:
Enabled : false
Entities:
Enabled : false
Building:
Enabled : false
Blocks:
Enabled : false
Messages:
Enabled : false
Script:
Enabled : true
Script : "example.lua"
When you enable scripting in the settings.yml file, and you restart the server, a new folder named "scripts" will be created. This folder contains 2 example scripts, showing you how everything works. They also contain a bunch of information at the top of the file. You can also find these examples below.
Untrusted Script Example(example.lua)
Code (Text):
--[[
Example script that can run untrusted.
The following variables are available to lua scripts. All of these variables are exact copies of their Java classes from Spigot:
- player - The player that broke the luckyblock. Documentation: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/entity/Player.html
- loc - The location of the broken luckyblock. Documentation: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Location.html
- world - The world the luckyblock was broken in. Documentation: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/World.html
- scheduler - The bukkit scheduler which can be used to, for example, delay tasks: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/scheduler/BukkitRunnable.html
- All material enum values are available as global variables, prefixed with MATERIAL_. (For example, you can use MATERIAL_IRON_BOOTS to use the IRON_BOOTS Material). Materials: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html
- All effect enum values are available as global variables, prefixed with EFFECT_. Usage is the same as the material values. Effects: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Effect.html
- All sound enum values are available as global variables, prefixed with SOUND_. Usage is the same as the material values. Sounds: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html
- All enchantment values are available as global variables, prefixed with ENCHANTMENT_. Usage is the same as the material values. Enchantments: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/enchantments/Enchantment.html
SuperLuckyBlock also provides a utils class, which allows you to do the following things:
- utils:createItemStack(material, amount) - Allows you to create a new ItemStack. Docs: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/inventory/ItemStack.html
- utils:colorText(text) - Converts values like &3 to their respective colors.
- utils:createEnchantment(name) - Creates an Enchantment object with the specified enchantment. Enchantments: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/enchantments/Enchantment.html
Methods on these variables can be called in 2 ways:
- player:setFireTicks(100)
- player.setFireTicks(player, 100)
As you can see, calling a method with a dot requires you to pass the variable(in this case player) alongside the other arguments. You don't have to do that when using the semicolon.
If you are missing access to any classes/methods, feel free to contact me and I will look into adding support for it.
]]
local name = player:getName()
if string.find(name, "i") ~= nil then
local itemStack = utils:createItemStack(MATERIAL_DIAMOND_SWORD, 1)
local itemMeta = itemStack:getItemMeta()
itemMeta:setDisplayName(utils:colorText("&2&lSome &3&lRandom &4&lSword"))
itemMeta:addEnchant(utils:createEnchantment("KNOCKBACK"), math.random(1, 10), true)
itemStack:setItemMeta(itemMeta)
world:dropItemNaturally(loc, itemStack)
else
local fireTicks = math.random(100, 500)
player:setFireTicks(fireTicks)
player:chat("I'm on fire for " .. fireTicks .. " ticks!")
end
Example script that can run untrusted.
The following variables are available to lua scripts. All of these variables are exact copies of their Java classes from Spigot:
- player - The player that broke the luckyblock. Documentation: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/entity/Player.html
- loc - The location of the broken luckyblock. Documentation: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Location.html
- world - The world the luckyblock was broken in. Documentation: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/World.html
- scheduler - The bukkit scheduler which can be used to, for example, delay tasks: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/scheduler/BukkitRunnable.html
- All material enum values are available as global variables, prefixed with MATERIAL_. (For example, you can use MATERIAL_IRON_BOOTS to use the IRON_BOOTS Material). Materials: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html
- All effect enum values are available as global variables, prefixed with EFFECT_. Usage is the same as the material values. Effects: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Effect.html
- All sound enum values are available as global variables, prefixed with SOUND_. Usage is the same as the material values. Sounds: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html
- All enchantment values are available as global variables, prefixed with ENCHANTMENT_. Usage is the same as the material values. Enchantments: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/enchantments/Enchantment.html
SuperLuckyBlock also provides a utils class, which allows you to do the following things:
- utils:createItemStack(material, amount) - Allows you to create a new ItemStack. Docs: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/inventory/ItemStack.html
- utils:colorText(text) - Converts values like &3 to their respective colors.
- utils:createEnchantment(name) - Creates an Enchantment object with the specified enchantment. Enchantments: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/enchantments/Enchantment.html
Methods on these variables can be called in 2 ways:
- player:setFireTicks(100)
- player.setFireTicks(player, 100)
As you can see, calling a method with a dot requires you to pass the variable(in this case player) alongside the other arguments. You don't have to do that when using the semicolon.
If you are missing access to any classes/methods, feel free to contact me and I will look into adding support for it.
]]
local name = player:getName()
if string.find(name, "i") ~= nil then
local itemStack = utils:createItemStack(MATERIAL_DIAMOND_SWORD, 1)
local itemMeta = itemStack:getItemMeta()
itemMeta:setDisplayName(utils:colorText("&2&lSome &3&lRandom &4&lSword"))
itemMeta:addEnchant(utils:createEnchantment("KNOCKBACK"), math.random(1, 10), true)
itemStack:setItemMeta(itemMeta)
world:dropItemNaturally(loc, itemStack)
else
local fireTicks = math.random(100, 500)
player:setFireTicks(fireTicks)
player:chat("I'm on fire for " .. fireTicks .. " ticks!")
end
Code (Text):
--[[
Example script that can only be ran in trusted mode.
The same methods as specified in example.lua are available in trusted mode. In addition to that, scripts that run in trusted mode have access to the following features:
- All Java and Spigot classes (Luajava library)
- Any file reading or writing
- The IO library
- The OS library
- Loading other scripts
- Creating coroutines
Luajava provides two important functions that make trusted mode so powerful, but also dangerous:
- luajava.bindClass("fully.qualified.class.name") - Example: luajava.bindClass("org.bukkit.Bukkit"). Allows you to call static methods, access static fields and enum values
- luajava.newInstance("fully.qualified.class.name") - Example luajava.newInstance("org.bukkit.inventory.ItemStack"). Creates a new instance of the specified class. Allows the methods of that class to be used.
]]
local bukkit = luajava.bindClass("org.bukkit.Bukkit")
local server = bukkit:getServer()
local itemstack = luajava.newInstance("org.bukkit.inventory.ItemStack", MATERIAL_DIAMOND_BLOCK, 4)
player:chat("Hello! Welcome to " .. server:getName())
world:dropItemNaturally(player:getLocation(), itemstack)
Example script that can only be ran in trusted mode.
The same methods as specified in example.lua are available in trusted mode. In addition to that, scripts that run in trusted mode have access to the following features:
- All Java and Spigot classes (Luajava library)
- Any file reading or writing
- The IO library
- The OS library
- Loading other scripts
- Creating coroutines
Luajava provides two important functions that make trusted mode so powerful, but also dangerous:
- luajava.bindClass("fully.qualified.class.name") - Example: luajava.bindClass("org.bukkit.Bukkit"). Allows you to call static methods, access static fields and enum values
- luajava.newInstance("fully.qualified.class.name") - Example luajava.newInstance("org.bukkit.inventory.ItemStack"). Creates a new instance of the specified class. Allows the methods of that class to be used.
]]
local bukkit = luajava.bindClass("org.bukkit.Bukkit")
local server = bukkit:getServer()
local itemstack = luajava.newInstance("org.bukkit.inventory.ItemStack", MATERIAL_DIAMOND_BLOCK, 4)
player:chat("Hello! Welcome to " .. server:getName())
world:dropItemNaturally(player:getLocation(), itemstack)
Resource Information
Author:
----------
Total Downloads:
703
First Release:
Nov 5, 2017
Last Update:
Oct 5, 2024
Category:
---------------
All-Time Rating:
57 ratings
Version
-----
Released:
--------------------
Downloads:
------
Version Rating:
----------------------
-- ratings