@gulg/mcjs v1.0.0

MCJS is a JavaScript to Minecraft Datapack compiler. It takes your JavaScript code, turns it into AST, turns that AST into MC commands and then injects the MCJS internals. It outputs a datapack, that you can add to your world without any modifications.

Quick start

Install MCJS through NPM:

npm i -g mcjs

Then, create a simple configuration file:

module.exports = {
    datapack: {
        name: "Example DataPack",
        namespace: "example",
        description: "Written in JS!",
        format: 48
    },
    include: ["./src/index.js"],
    output: "./dist"
};

Great! Now you can create a simple script and build it using MCJS:

// src/index.js
console.log("Hello world!");

mcjs ./mcjs.config.js

This should create dist folder in your project directory, containing your datapack.

How does it work?

MCJS uses Acorn to parse your JS files. It then uses data storages to create virtual object system. Everything is made according to this spec, however some features may not be implemented or may be simplified due to Minecraft limitations. In addition to internal properties specified in ECMA, MCJS also provides [[ObjectKind]] property to determine the type of an object: UNDEFINED (-1), NULL (0), OBJECT (1), PROXY (2). It's used in mcjs:internal/accessors/... to make lookup faster. I also used V8 and Chakra source code in my development.

Internal structure

Functions

MCJS engine datapack consists of three parts: internal functions for built-in objects, internal functions for binding JS OOP model to Minecraft data storages and load function, which initializes the whole engine. Internal object functions folder (functions) contains subfolders for every built-in object (like Function) with the following structure: /prototype/... for instance methods, /... for static methods, /prototype/internal/... for internal instance methods and /internal/... for static internal methods. MCJS utilizes macros to access data dynamically.

Objects

Every object is stored in mcjs:storage memory.view. Each object has its unique id, which is later passed to different functions, allowing them to change the value by reference. Each object is defined as a compound tag containing these child tags: internal (to store internal methods & properties), descriptors (to store public methods & properties) and properties (duplicate of descriptors, needed to access object's keys dynamically). So, the following JavaScript object can be represented in MCJS like this:

{
    x: 1,
    y: { a: 1, b: 2, c: 3 }
}

data modify storage mcjs:storage memory.view.1 set value { a: memory.view.n1, b: memory.view.n2, c: memory.view.n3 }

Notice, that memory.view.1 is not { a: 1, b: 2, c: 3 }, but instead it contains references to those numbers.

Implemented features

• Modules (except for import * as ...)
• Objects (partially)
• Functions
• Binary operations
• • Addition
• Logic operations
• • And
• • Or
• • Not

Engine specifics

To learn more info about the engine itself, check out this file. Execution contexts are simplified to just contain variable bindings.