⚡ Universe JS API 文档

📖 简介

Universe 模块内置了基于 Rhino 的 JavaScript 引擎，允许用户通过编写 JS 脚本来扩展功能。

你可以用JS脚本实现自定义功能、自动化操作、界面定制等。

🚀 快速开始

第一个脚本

// hello.js
function onEnable() {
    Log.info("脚本已启用！");
    KJ.print("Hello, KJ!");
}

function onDisable() {
    Log.info("脚本已禁用");
}

function onTick() {
    // 每帧调用（约60次/秒）
}

生命周期

📝 语法说明

Universe 脚本使用标准 JavaScript ES6 语法，基于 Mozilla Rhino 引擎。

支持的特性

• 变量声明：var, let, const
• 函数：普通函数、箭头函数
• 对象、数组、字符串方法
• 条件语句、循环
• 正则表达式
• JSON 解析/序列化
• setTimeout / setInterval

🎮 KJ 核心对象

全局对象 KJ 提供了所有游戏相关的API。

工具方法

👤 玩家 API

示例

// 自动打招呼脚本
var lastHello = 0;

function onTick() {
    var now = KJ.getCurrentTimeMs();
    if (now - lastHello > 60000) { // 每分钟
        var name = KJ.getPlayerName();
        KJ.sendChat("大家好！我是" + name);
        lastHello = now;
    }
}

🌍 世界 API

👾 实体 API

示例：列出附近玩家

function listNearbyPlayers() {
    var count = KJ.getEntityCount();
    var players = [];

    for (var i = 0; i < count; i++) {
        if (KJ.isEntityPlayer(i)) {
            var name = KJ.getEntityName(i);
            var dist = KJ.getDistanceToEntity(i).toFixed(1);
            players.push(name + " (" + dist + "m)");
        }
    }

    Log.info("附近玩家: " + players.join(", "));
    return players;
}

🎒 背包 API

🎨 渲染 API

颜色格式

颜色使用ARGB整数格式：0xAARRGGBB

// 红色半透明
var red = 0x80FF0000;

// 绿色不透明
var green = 0xFF00FF00;

// 蓝色半透明
var blue = 0x800088FF;

⚙️ 模块 API

可用模块名

📋 Log 日志

全局对象 Log 用于输出日志到脚本控制台。

⏱️ 定时器

支持标准的JS定时器函数。

示例

// 3秒后执行
setTimeout(function() {
    Log.info("3秒过去了");
}, 3000);

// 每秒执行
var count = 0;
var timer = setInterval(function() {
    count++;
    Log.info("已经过 " + count + " 秒");
    if (count >= 10) {
        clearInterval(timer);
    }
}, 1000);

📡 事件系统

通过定义特定函数名来监听游戏事件。

💡 脚本示例

示例1：自动跳

// 走到边缘自动跳
var lastJump = 0;

function onTick() {
    if (!KJ.isPlayerOnGround()) return;

    var now = KJ.getCurrentTimeMs();
    if (now - lastJump < 500) return;

    // 检查前方是否有掉落
    var px = KJ.getPlayerX();
    var py = KJ.getPlayerY();
    var pz = KJ.getPlayerZ();

    if (!KJ.isBlockSolid(px, py - 1, pz)) {
        // 脚下没方块，自动跳
        KJ.setPlayerMotion(0, 0.42, 0);
        lastJump = now;
    }
}

示例2：自动打招呼

// 检测到玩家自动打招呼
var greeted = {};

function onTick() {
    var count = KJ.getEntityCount();
    var now = KJ.getCurrentTimeMs();

    for (var i = 0; i < count; i++) {
        if (!KJ.isEntityPlayer(i)) continue;

        var name = KJ.getEntityName(i);
        var dist = KJ.getDistanceToEntity(i);

        if (dist < 8 && !greeted[name]) {
            KJ.sendChat("你好 " + name + " 👋");
            greeted[name] = now;
        }

        // 5分钟后可以再次打招呼
        if (greeted[name] && now - greeted[name] > 300000) {
            delete greeted[name];
        }
    }
}

function onDisable() {
    greeted = {};
}

示例3：坐标显示

// 在头顶显示自己的坐标
function onRender() {
    KJ.clearRenderObjects();

    var x = KJ.getPlayerX().toFixed(1);
    var y = KJ.getPlayerY().toFixed(1);
    var z = KJ.getPlayerZ().toFixed(1);

    var text = "XYZ: " + x + ", " + y + ", " + z;

    KJ.addFloatingText(
        text,
        KJ.getPlayerX(),
        KJ.getPlayerY() + 2.5,
        KJ.getPlayerZ(),
        0xFF00FF00  // 绿色
    );
}