JStom

JStom is a lightweight Minecraft server implementation built on top of Minestom, featuring a powerful JavaScript scripting engine powered by GraalVM. It allows you to write server logic, handle events, and interact with the Minestom API directly using JavaScript, with support for runtime hot-reloading.

Features

• JavaScript Scripting: Write your server logic in standard JavaScript (ES6+ support via GraalJS).
• Hot Reloading: modifying scripts does not require a server restart. Use the reload command to apply changes instantly.
• Isolated Contexts: Each script file runs in its own isolated context, preventing global variable collisions while still sharing the server API.
• Full API Access: Scripts have access to the full Java classpath, allowing usage of any Minestom class.

Prerequisites

• Java 25 (Required by the latest Minestom version).

Getting Started

Windows

1. Double-click run.bat to build and start the server.
2. The server will start on port 25565.

Linux / Mac

1. Grant execution permissions: chmod +x gradlew
2. Build and run:

   ./gradlew installDist
   ./build/install/jstom/bin/jstom
   

Usage

Managing Scripts

Scripts are located in the scripts/ directory. You can add as many .js files as you like. They are loaded automatically on startup.

Commands:

• reload: Unloads and reloads all scripts.
• reload <filename.js>: Reloads a specific script file (e.g., reload index.js).
• stop: Stops the server.

Scripting API

The global server object is your gateway to the Minestom API.

Logging:

server.log("Hello from JavaScript!");

Event Handling: You can listen to any Minestom event by its fully qualified class name.

// Listen for a player joining
server.on('net.minestom.server.event.player.PlayerSpawnEvent', (event) => {
    const player = event.getPlayer();
    player.sendMessage("Welcome to JStom!");
    server.log(`${player.getUsername()} joined the game.`);
});

Accessing Java Classes: Since allowHostClassLookup is enabled, you can import and use Java classes directly.

const Pos = Java.type('net.minestom.server.coordinate.Pos');
const ItemStack = Java.type('net.minestom.server.item.ItemStack');
const Material = Java.type('net.minestom.server.item.Material');

// Example: Give an item
server.on('net.minestom.server.event.player.PlayerSpawnEvent', (event) => {
    const player = event.getPlayer();
    player.getInventory().addItemStack(ItemStack.of(Material.DIAMOND));
});

Project Structure

• src/main/java/net/jstom/: Java source code (Server initialization, ScriptManager).
• scripts/: Directory for user JavaScript files.
• build.gradle.kts: Project dependencies and build configuration.