Welcome to MCExtensions!

Welcome to the API Documentation

This is the official reference for the MCExtensions JavaScript API — your toolkit for building real-time Minecraft server features using plain JavaScript.

Everything here is script-accessible. You'll find methods and classes to create commands, modify the world, talk to players, and much more — all without ever touching Java or restarting your server.

The sidebar on the left lists everything that's available. Click on any item to jump to its usage details and code examples.

💡 Tip: The built-in editor has autocomplete for all documented functions — no need to memorize anything.

MCExt

MCExt is the global object available in every script. It's your starting point for using MCExtensions.

You call MCExt.registerExtension() to define a new extension — think of it as a "module" where your custom commands and logic live. It returns an MCHandler, which you'll use to build your actual features.

Registering an Extension

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

This sets up a new extension named myExtension. The ext you get back lets you define commands, log messages, schedule timers, and more — all from that one object.

toString()

console.log(MCExt.toString());

MCHandler

MCHandler is what you get back from MCExt.registerExtension(). It's your main handle for working with your extension — you'll use it to register commands, log info, access metadata, schedule tasks, and interact with the world.

Here's what it gives you:

• 🧩 Define custom commands using command()
• 📋 Read or update your extension's metadata (name, description, etc.)
• 🪵 Log messages to the server console with log(), warn(), and err()
• 🕛 Schedule timers using callOnTimer() (repeat) or callAfterTime() (delay)
• 🌍 Read and write blocks using getBlock() and setBlock()

Define a Command

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

Console Logging

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

Logging goes to the server console, not in-game chat. Pass multiple args like console.log.

Working with Metadata

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

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

Automatic Cleanup

MCPlayer

MCPlayer represents a currently connected player. It gives you full control over player-related logic — messaging, health, inventory, teleportation, flight, and more.

Sending Messages

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

You can pass multiple values to sendMessage() — each one shows up as a separate message in the player's chat.

Teleporting

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

setPosition() moves the player instantly. It does not check for safety — it's on you to avoid suffocation or void deaths.

Push / Velocity

player.push(0, 1, 0); // Launches the player upward

push() adds velocity to the player, similar to knockback or a jump boost.

Health

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

Health is clamped between 0 and 20 (Minecraft's default max). Setting it to 0 kills the player.

Flight Permissions

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

setAllowedFlight(true) enables flight for the player. It doesn't toggle whether they're flying, just whether they can.

Inventory

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

Use getInventory() to access the player's inventory. See MCInventory for full control options.

MCInventory

MCInventory represents any inventory — typically from a MCPlayer. It lets you inspect, modify, and manage item contents: add stacks, set individual slots, or clear the whole thing.

Accessing Inventory

const inv = player.getInventory();

Call getInventory() on a player to get a valid MCInventory instance.

Clearing All Items

inv.clear();

Removes everything in the inventory.

Getting Items

const item = inv.getItem(0);

Gets the MCStack in the specified slot.

Setting Items

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

Places a stack into the given slot.
use include() to be able to use MCStack and MCResource.

const { MCStack, MCResource } = include();

Adding Items

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

Tries to insert a stack. Fills existing partials first, then empty slots. If there's not enough space, returns leftover items:

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

Inventory Size

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

Use size() to get the number of available slots.

MCPos

MCPos is a simple coordinate object that represents a location in the world. It includes x, y, and z values, plus an optional world field.

Creating and Modifying Positions

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

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

Coordinates are doubles and editable. You can directly update the fields to move or shift a position.

Working with Worlds — MCWorld

pos.world = MCWorld.NETHER;

Set the world property to target a specific dimension. If not set, MCExtensions will infer a default (usually the player's current world or OVERWORLD).

Formatted Output

ext.log(pos.getFormatString());

Returns a readable string with coordinates and world — useful for debugging or logs.

Example: Place a Block Below the Player

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

This places a block directly under the player using a MCPos.

MCWorld

MCWorld represents a specific dimension or world on the server. It's used alongside MCPos for positioning, or when you need to control world-level properties like time.

Predefined Worlds

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

You can access the three default Minecraft dimensions using these 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

Time is measured in ticks — from 0 (sunrise) to 24000 (full day/night cycle). Use setTime() to instantly update time for everyone in that world.

Retrieving the World Name

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

Returns the internal world name (e.g. "world", "world_nether"), matching your server folder structure.

MCStack

MCStack represents a stack of items. It combines a MCResource (the item type) with an amount. Use it to add, remove, or manipulate items in inventories.

Creating an Item Stack

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

You must provide both the MCResource and a positive integer for the amount. Passing a negative or missing amount 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 update the item and quantity at any time. getAmount() returns the current amount, while getResource() gives you the resource object representing the item.

Checking for Item Validity

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

Use isItem() to confirm that a resource is valid before creating a stack from it.

MCResource

MCResource is how you reference any block or item in Minecraft — like "stone" or "minecraft:diamond_sword". It's used for anything involving inventory actions, block placement, or stack creation.

Creating a Resource

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

You can pass just the name ("stone") or the full namespaced ID ("minecraft:stone"). Either works.

Getting the Resource Name

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

getName() returns the resource name in uppercase by default. Call toLowerCase() on it if you want it lowercased.

Checking Type

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

Use isItem() to check if it's usable in inventories, or isBlock() for block placement. Useful for validating input before running commands.

ExtensionMetaData

ExtensionMetaData stores your extension's display name and description. You can read or modify it at runtime to update how your script shows up in /extensions and other UIs.

Accessing Metadata

const meta = ext.getMetaData();

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

Call getMetaData() on your MCHandler instance to retrieve the current metadata.

Changing Metadata

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

You can change both values dynamically. Once updated, the new name and description take effect immediately — even in things like /extensions and tab suggestions.

include()

include() is a global function that gives your script access to all the native MCExtensions types. It must be called at the top of any file that uses these classes.

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

This gives you constructors for all the core building blocks used in commands, events, and gameplay logic.

• MCPlayer — Represents a player
• MCPos — A 3D position in the world
• MCWorld — A reference to a specific world
• MCResource — An item or block type
• MCStack — A stack of items (item + count)