JSpp

Warning

This scripting feature is a work-in-progress (WIP) and subject to change in future updates. Always check the latest documentation for updates and compatibility.

.jspp

Remember to update the vscode extension to get autocompletion and common errors checking of the new preview .jspp format.

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.