Welcome to MCExtensions

MCExtClass

The MCExtClass is the main entry point to the MCExtensions API. It is accessible globally via the MCExt constant in your scripts.

Its primary role is to register new extensions, which serve as containers for your custom commands, behaviors, and logic. Registering an extension returns a MCHandler, which you'll use to define commands, interact with players, and more.

Example

const ext = MCExt.registerExtension("myExtension", {
    description: "My custom extension"
});

In this example, we register a new extension called "myExtension" with an optional description. The returned ext (MCHandler) can now be used to define commands, schedule timers, log messages, and more.

MCHandler

The MCHandler object is returned when you register an extension using MCExt.registerExtension(). It serves as the main interface to define commands, access metadata, and interact with the extension runtime.

This handler allows you to:

• 🧩 Define multiple custom commands via command()
• 📋 Access and update extension metadata (name, description)
• 🪵 Write formatted log messages to the server console (not the in-game chat)
• 🕛 Schedule repeating or delayed callbacks with callOnTimer() and callAfterTime()
• 🌍 Read and write blocks in the world with setBlock() and getBlock()

Basic Command Example

ext.command({
    name: "hello",
    description: "Sends a friendly greeting",
    usage: "/hello",
    execute({ player }) {
        player.sendMessage("Hello!");
    }
});

Logging to the Server Console

ext.log("Hello from extension!");
ext.warn("Something may be wrong...");
ext.err("Something went wrong!", error);

These logging methods support multiple arguments and are printed to the server console, not the in-game chat. They are useful for debugging, tracking extension behavior, or warning about misusage.

Accessing and Modifying Extension Metadata

const meta = ext.getMetaData();
ext.log("Extension name:", meta.getName());

meta.setDescription("Updated description");
ext.setMetaData(meta);

Cleanup

MCPlayer

MCPlayer represents a player currently online on the server. This class provides a variety of methods to interact with the player — such as sending messages, modifying health, changing flight permissions, accessing their inventory, and teleporting them around the world.

Sending Messages

player.sendMessage("Welcome!");
player.sendMessage("You have", player.getXpLevel(), "XP levels.");

You can pass multiple arguments to sendMessage(), and each one will be sent as a separate message line in the chat.

Teleporting the Player

const pos = player.getPosition();
pos.y += 10;
player.setPosition(pos);

setPosition() moves the player to the specified location. It does not perform safety checks — it is your responsibility to ensure the destination is valid (e.g. not inside blocks or void).

Velocity and Push

player.push(0, 1, 0); // Applies an upward knockback-style effect

The push() method adds to the player's velocity, making it behave like knockback or launching.

Health Control

player.setHealth(10);
ext.log("Current health:", player.getHealth());

Health values are clamped automatically between 0 and 20, the default maximum for players.

Flight Control

player.setAllowedFlight(true);
ext.log("Flight enabled:", player.allowedFlight());

This enables or disables whether the player can fly — not whether they are currently flying.

Inventory Access

const inv = player.getInventory();
inv.clear();

The player's inventory can be accessed at any time via getInventory(). See MCInventory for details.

MCInventory

MCInventory represents any inventory such as from a Player. It provides methods to inspect, modify, and manage the contents of the inventory — including adding items, setting specific slots, and clearing everything.

Accessing the Inventory

const inv = player.getInventory();

You can safely access the inventory of any player using getInventory(). This always returns a valid MCInventory instance.

Clearing All Items

inv.clear();

Completely removes all items from the inventory.

Getting Items

const item = inv.getItem(0);

Returns an MCStack representing the item at the given slot.

Setting Items

inv.setItem(0, new MCStack(new MCResource("diamond"), 1));

Sets the item at the given slot to the specified stack.

Adding Items

const leftover = inv.addItem(new MCStack(new MCResource("stone"), 100));

Attempts to add an item stack to the inventory. It will fill existing partial stacks first, then empty slots. If the inventory is full, it returns a map of leftover items that couldn’t be added:

// Example output:
{
    36: MCStack { ... },
    37: MCStack { ... }
}

Checking Inventory Size

ext.log("Inventory has", inv.size(), "slots");

The number of slots depends on the inventory type. Always use size() to determine bounds before using getItem() or setItem().

MCPos

MCPos represents a location in the world. It holds three coordinates: x, y, and z, along with an optional world property.

Creating and Modifying Positions

const pos = new MCPos(10, 68, 143);
player.setPosition(pos);

const pos = player.getPosition();
pos.y += 5;
player.setPosition(pos);

Position values (x, y, z) are doubles and can be modified freely in JavaScript. You can directly update the properties to move or offset positions.

Working with Worlds

pos.world = MCWorld.NETHER;

You can assign a specific world to a position using pos.world. If no world is defined, MCExtensions will attempt to use a fallback — such as the world the player is currently in, or the OVERWORLD when relevant.

Format String

ext.log(pos.getFormatString());

Outputs a string representing the full coordinates and world, useful for logging or debugging.

Example Use for Block Placement

const blockPos = player.getPosition();
blockPos.y -= 1;
ext.setBlock(blockPos, new MCResource("stone"));

This example places a block one unit below the player using a valid MCPos.

MCWorld

MCWorld represents a specific world on the Minecraft server. It's commonly used when dealing with positions (MCPos), or for interacting with world-level data like time.

Predefined Worlds

pos.world = MCWorld.OVERWORLD;
pos.world = MCWorld.NETHER;
pos.world = MCWorld.END;

You can reference the default Minecraft worlds using the constants MCWorld.OVERWORLD, MCWorld.NETHER, and MCWorld.END.

Getting and Setting Time

const world = pos.world;
ext.log("Current world time:", world.getTime());

world.setTime(6000); // Noon

World time is represented as ticks, ranging from 0 (sunrise) to 24000 (full day). Calling setTime() updates the time immediately for all players in that world.

Retrieving the World Name

ext.log("World name:", world.getName());

This returns the internal name of the world, such as "world" or "world_nether". It corresponds to the name used in your server’s world folders.

MCStack

MCStack represents a stack of items — combining both the MCResource (item type) and the amount. It is commonly used when adding or modifying a player's inventory.

Creating an Item Stack

const stack = new MCStack(new MCResource("stone"), 64);

You must provide both the MCResource and a positive integer amount. Omitting the amount or passing a value less than 0 will throw an error.

Working with Stacks

stack.setAmount(10);
stack.setResource(new MCResource("diamond_sword"));

ext.log("Amount:", stack.getAmount());
ext.log("Item name:", stack.getResource().getName());

You can change both the item type and the quantity at any time. getAmount() returns a number, and getResource() returns a copy of the associated MCResource.

Checking for Item Validity

const res = new MCResource("stone");
if (res.isItem()) {
    const stack = new MCStack(res, 32);
}

Use the isItem() method to check if a resource is valid for Stack-related actions.

MCResource

MCResource represents a block or item type in Minecraft, such as stone or minecraft:diamond_sword. It is used whenever you want to refer to a resource in inventory operations or world interactions.

Creating a Resource

const res = new MCResource("stone");
const sword = new MCResource("minecraft:diamond_sword");

The constructor accepts either a simple name ("stone") or a full namespaced ID like "minecraft:stone". Internally, the string is uppercased and passed to Bukkit’s Material.matchMaterial() method.

Getting the Resource Name

ext.log("ID:", res.getName().toLowerCase()); // stone

getName() returns the internal enum name (e.g. "WHITE_WOOL"). Use .toLowerCase() in JS to convert it to lowercase formatting if needed.

Checking Type

if (res.isItem()) {
    ext.log("This is a valid item");
}
if (res.isBlock()) {
    ext.log("This is a valid block");
}

Use isItem() and isBlock() to verify if the resource is usable in inventories or block placement respectively.

ExtensionMetaData

ExtensionMetaData holds the name and description of your extension. You can use it to retrieve or change the visible identity of your script.

Accessing Metadata

const meta = ext.getMetaData();

ext.log("Extension name:", meta.getName());
ext.log("Description:", meta.getDescription());

Use getMetaData() on your extension handler to retrieve this object at any time.

Changing Metadata

meta.setName("coolerName");
meta.setDescription("This plugin just got renamed.");

You can modify the name and description dynamically while the server is running. The updated values are reflected immediately in output like /extensions and tab completion.

MCExt

MCExt is the global object available in every script. It's the entry point for registering new extensions and interacting with the MCExtensions system.

Registering an Extension

const ext = MCExt.registerExtension("myPlugin", {
    description: "An example plugin created using MCExtensions."
});

The registerExtension method creates a new extension instance and returns an MCHandler. The name must only contain letters, numbers, underscores, or dashes ([A-Za-z0-9_-]+).

toString()

console.log(MCExt.toString()); // MCExt<>

include()

include() is a global function used to access native Java-backed classes such as MCPlayer, MCStack, and others. It must be called in every script that wants to use these types.

const { MCPlayer, MCStack, MCPos } = include();

The function returns the same reference every time and exposes:

• MCPlayer — Represents a player
• MCPos — A 3D position (with optional world)
• MCWorld — A world reference
• MCResource — An item/block type
• MCStack — A stack of items