JSpp

.jspp#

This scripting mode uses Java under the hood but allows some JavaScript-inspired syntax for convenience.

Advantages:

• Requires less code: common imports are automatically resolved.
• Faster to write.

Disadvantages:

• No debugger.
• Autocomplete is not precise and mostly missing.
• The intellisense is not always reliable on errors.
• Hard to identify and fix bugs in your code.

✅ Syntax Basics#

• Semicolons (;) are mandatory at the end of each statement, like in Java.
• You can use const, let, or var to declare variables.
• Supports lambda expressions and Java class imports.

🌟 Script Variables#

Scripts inherit several predefined variables from the event that triggered the script. These variables are automatically available in your script and are prefixed with a $ to avoid name conflicts:

• $plugin: The plugin instance.
• $event: The event that triggered the script.
• $player: The player involved in the event (if applicable).
• $customStack: The custom item stack involved (if applicable).
• $itemStack: The standard item stack involved (if applicable).
• $customEntity: The standard custom entity involved (if applicable).

The generated Java class for the script includes a main function with the following signature:

public static void main(Plugin $plugin, Event $event, Player $player, CustomStack $customStack, ItemStack $itemStack)

Or the following signature if a custom entity script:

public static void main(Plugin $plugin, Event $event, Player $player, CustomEntity $customEntity)

📝 Note: This structure is currently fixed and cannot be modified. Ensure your scripts are designed to work within this framework.

⏳ Delays#

Use the delay(ticks, () -> { ... }) function to delay execution.

• 1 second = 20 ticks

delay(40, () => {
  msg($player, "This message appears after a 2 seconds delay.");
});

📦 Importing Java Classes#

You can import external classes using the import keyword with quotes:

import "org.bukkit.Bukkit";
import "org.bukkit.entity.LivingEntity";
import "net.kyori.adventure.text.Component";
import "com.comphenix.protocol.ProtocolLibrary";

❌ Cancelling The Event#

You can cancel the current event using:

cancelEvent();

🔧 Utility Functions#

🧱 ItemStack Utilities#

isCustom(ItemStack itemStack);
newCustomStack(String namespacedId);
newCustomStack(String namespacedId, int amount);
newStack(Material material);

🧍 Player Held Item#

isHeld(Player player, String namespacedId);
isHeld(Player player, CustomStack customStack);
isHeld(Player player, Material material);
setHeld(Player player, String namespacedId);

🧱 Block Utilities#

isCustom(Block block);
customBlock(Block block);
customBlock(Location location);

block(String worldName, int x, int y, int z);
block(World world, int x, int y, int z);
block(Location location);

location(String worldName, int x, int y, int z);

removeBlock(Block block);
placeBlock(Block block, Material material);
placeBlock(Block block, CustomBlock customBlock);
placeBlock(Block block, String identifier);

💬 Messaging and Logging#

msg(Player player, String message);
msg(Player player, String message, boolean minimessage);
msg(Player player, Component message);
log(String message);

↺ Casting#

Exactly how it works in Java.

Type1 item = (Type2) item2;

📌 Best Practices#

• Use delay() for animations or delayed feedback.
• Always check isCustom() before modifying custom items or blocks.
• Log actions with log() during debugging.
• Use cancelEvent() to prevent default behavior when handling interactions.