🛠️ Simplified Mojang API

[!WARNING] ⚠️ WORK IN PROGRESS! ⚠️ This repository is constantly evolving and undergoing active updates, so some features or simplified methods may be missing or not yet implemented. Please keep this in mind when using it!

A simple tool that makes it easier to use the Mojang scripting API for Minecraft Bedrock, by providing pre-built and simplified classes.

What is this?

It's an informal or professional repository designed to simplify the logic of the native @minecraft/server module by integrating various pre-built classes and methods to save time and reduce code, as well as tools I've customized myself for use in any add-on.

Install:

Just run this in your terminal:

npm install simplified-mojang-api@latest (In case of errors, use --force)

(Make sure you also have the base @minecraft/server stuff installed!)

Build Setup:

If you are new to TypeScript and Minecraft Add-on development, don't panic! Minecraft only reads .js files, so we need to "compile" or "bundle" our .ts files into a single JavaScript file. We use esbuild for this because it's incredibly fast.

Here is the step-by-step guide to setting up your compiler:

1. Install the Bundler

First, you need to install esbuild as a development dependency in your project. Run this in your terminal:

npm install --save-dev esbuild

2. Prepare your Folder Structure

Make sure your behavior pack looks something like this:

📦 behaviors/YOUR_ADDON/
 ┣ 📂 scripts/      (This will be auto-generated by the compiler)
 ┣ 📂 src/
 ┃ ┗ 📜 main.ts     (You write your TypeScript code here)
 ┗ 📜 manifest.json

3. Update your package.json

Open your package.json file and replace or add the "scripts" section with these commands. You will need to replace YOUR_ADDON with the actual folder name of your behavior pack:

  "scripts": {
    "copy:api-assets": "node -e \"const fs = require('fs'); const src = 'node_modules/simplified-mojang-api/structures'; if (fs.existsSync(src)) fs.cpSync(src, 'behaviors/YOUR_ADDON/structures', { recursive: true, force: false });\"",
    "compile": "npm run copy:api-assets && esbuild behaviors/YOUR_ADDON/src/main.ts --bundle --format=esm --outfile=behaviors/YOUR_ADDON/scripts/main.js --target=es2020 --external:@minecraft/server --external:@minecraft/server-ui --external:@minecraft/server-gametest --external:@minecraft/server-graphics --external:@minecraft/server-net --external:@minecraft/debug-utilities --external:@minecraft/gameplay-utilities --sourcemap",
    "watch": "npm run compile -- --watch"
  }

4. Run

Now you are ready to compile! Open your terminal and use one of these commands:

• To compile once: (Do this before publishing your add-on)

npm run compile

• To auto-compile (Recommended): (Run this while you are coding. It will stay open and automatically re-compile every time you save a file!)

npm run watch

Available Modules

The API is split up into several handy modules to fit whatever your development workflow needs. Here is what's currently available out of the box:

[!NOTE] The wrapped @minecraft/... modules might not have every single vanilla event fully mapped out just yet. I'll be adding the rest and keeping things updated to make your dev experience as smooth as possible.

import { 
    afterEventsSimplified, 
    beforeEventsSimplified, 
    customEventsManager, 
    debugToolsSimplified, 
    fakePlysSimplified, 
    worldToolsSimplified 
} from "simplified-mojang-api";

Each module comes packed with different methods for your daily coding routine. Here's a quick rundown of what they do:

• afterEventsSimplified: Wraps the main world.afterEvents methods. These fire off right after an action has already happened. Perfect for reading data or triggering logic after the fact.
• beforeEventsSimplified: Wraps the main world.beforeEvents methods. These trigger right before the actual event takes place in the game. Super handy if you need to cancel an event entirely or tweak things before they go through.
• customEventsManager: Packed with custom-built tools designed to streamline your workflow, cut down on boilerplate code, and give you robust tools to handle pretty much any scenario.
• debugToolsSimplified: Custom and simplified wrappers for the debug-utilities module to make visual debugging a lot easier for developers.
• fakePlysSimplified: Clever wrappers for the server-gametest module to make spawning and managing simulated entities/players a breeze. Mostly focused on helping you test multiplayer features solo with fake players.
• worldToolsSimplified: Your go-to toolbox for server.world and server.system. It brings cleaner shortcuts and universal tools for everyday tasks, making your coding loop way faster and straightforward.

API Examples:

Fast Offhand Items

Make items jump to the offhand with a single click.

import { customEventsManager } from "simplified-mojang-api";

// Any item with these words in its ID becomes a fast-equip item
customEventsManager.fastItemsSystem(["totem", "shield", "arrow"]);

Visual Debugging (Hitboxes)

Easily show visual hitboxes for all nearby entities using the debug module. Great for testing custom mob sizes or attack ranges!

import { debugToolsSimplified } from "simplified-mojang-api";

// Shows hitboxes to the specific player within a 50 block radius
debugToolsSimplified.showHitboxes(player, 50);

// Turn them off when you're done testing
// debugToolsSimplified.stopHitboxes();

Fake Player Spawner

Instantly spawn a simulated player into the world using the gametest API. Perfect for testing multiplayer mechanics solo.

import * as mc from "@minecraft/server";
import { fakePlysSimplified } from "simplified-mojang-api";

// Spawns a fake player named "Dummy" in Survival mode
fakePlysSimplified.createFakePly("Dummy", mc.GameMode.Survival);

Real-Time Timer

Creates a timer that's saved directly on the player and runs in real-time, no need to mess with scoreboard ticks! Set an initial value and you're good to go—super easy and fast to use.

import { customEventsManager } from "simplified-mojang-api";

const paramsTimer: CustomTimerParam = {
    sourcePly: player, // The player who gets the timer
    timerId: "ha:timer_unique", // Unique ID for the timer, just in case you run more than one
    initialMns: 2, // Starting minutes for the timer, or the minutes to display
    forceRestart: true, // (Optional) Need to update the time? E.g., new minutes or seconds? Set this to true to restart the timer.

    // (Optional) Events triggered every time a second goes by.
    onSecondPass: (ply, timer) => {
        console.log(`A second has passed! The timer now is ${timer}`);
    },
};

// Starts the timer for the player. HEADS UP: this is an under-the-hood timer so it's invisible by default. To show it on a UI, use events like onSecondPass.
customEventsManager.startTimerLocal(paramsTimer);

Contributing

Found a bug or want to wrap a new Mojang method? PRs are super welcome!

Author: HaJuegos License: MIT