KubeJS 7 (1.21.1) 全局事件与核心函数速查手册

在 KubeJS 7 (适用于 Minecraft 1.21.1) 中，原版的 NBT 机制被极大地重构为了数据组件 (Data Components)，并且核心事件系统进行了全面的规范化。本手册为你梳理了各个脚本目录下的核心用法，并在底部附录中列出了全部暴露给 JS 使用的基础对象与方法。

目录 1 启动脚本 (Startup Scripts)

存放路径：kubejs/startup_scripts/

加载时机：游戏启动时加载一次。

主要用途：注册新物品、方块、流体，定制工具/护甲等级，以及通过硬编码修改原版对象行为。

1.1 物品与方块注册 (Registry Events)

通过 StartupEvents.registry 事件，使用特定的 Builder 来注册。

StartupEvents.registry('item', event => {
    // 基础物品
    event.create('magic_ingot').displayName('魔法锭').glow(true).maxStackSize(16);
    
    // 食物 (1.21+ 专有 FoodBuilder)
    event.create('magic_apple').food(food => {
        food.nutrition(4).saturation(0.3).alwaysEdible().fastToEat();
        // 添加药水效果 (ID, 持续Tick, 等级, 概率)
        food.effect('minecraft:regeneration', 200, 1, 1.0);
    });

    // 剑类武器
    event.create('magic_sword', 'sword').tier('diamond').attackDamageBaseline(7.0);
});

StartupEvents.registry('block', event => {
    // 基础方块
    event.create('magic_block')
         .displayName('魔法方块')
         .soundType('amethyst') // 设置声音类型
         .hardness(3.0)         // 设置硬度
         .resistance(3.0)       // 设置爆炸抗性
         .requiresTool(true)    // 需要工具挖掘
         .tagBlock('mineable/pickaxe'); // 绑定挖掘工具标签
});

1.2 属性修改 (Modification Events)

修改已有对象的硬编码属性。

ItemEvents.modification(event => {
    event.modify('minecraft:ender_pearl', item => {
        item.maxStackSize = 16;
        item.fireResistant = true; // 使其不怕火烧
    });
});

BlockEvents.modification(event => {
    event.modify('minecraft:obsidian', block => {
        block.destroySpeed = 5.0; // 加快黑曜石挖掘速度
        block.hasCollision = true;
    });
});

1.3 工具与护甲等级注册 (Tier Registry)

通过 toolTierRegistry 和 armorTierRegistry 添加自定义强度。

ItemEvents.toolTierRegistry(event => {
    event.add('magic_tier', tier => {
        tier.uses = 2500;
        tier.speed = 9.0;
        tier.attackDamageBonus = 3.0;
        tier.level = 4; // 挖掘等级 (4=下界合金)
        tier.enchantmentValue = 25;
        tier.repairIngredient = '#forge:ingots/magic';
    });
});

ItemEvents.armorTierRegistry(event => {
    event.add('magic_armor', tier => {
        tier.durabilityMultiplier = 40; // 耐久倍率
        tier.slotProtections = [3, 6, 8, 3]; // 鞋子, 裤子, 胸甲, 头盔
        tier.enchantmentValue = 20;
        tier.equipSound = 'minecraft:item.armor.equip_diamond';
        tier.repairIngredient = '#forge:ingots/magic';
        tier.toughness = 2.0; // 护甲韧性
        tier.knockbackResistance = 0.1; // 击退抗性
    });
});

1.4 创造模式物品栏 (Creative Tabs)

1.21.1 新增标准接口用于给原版或自定义物品栏追加物品。

StartupEvents.modifyCreativeTab('minecraft:ingredients', event => {
    event.add('kubejs:magic_ingot');
});

// 或者自己创建一个全新的物品栏
StartupEvents.registry('creative_tab', event => {
    event.create('magic_tab')
         .title('魔法物品')
         .icon(() => 'kubejs:magic_sword')
         .content(() => [
             'kubejs:magic_ingot',
             'kubejs:magic_apple',
             'kubejs:magic_sword',
             'kubejs:magic_block'
         ]);
});

目录 2 服务端脚本 (Server Scripts)

存放路径：kubejs/server_scripts/

加载时机：每次进入存档/服务器启动，或使用 /reload 重新加载数据包时。

主要用途：配方管理、标签操作、游戏逻辑事件监听（右键交互、掉落物、死亡生成等）。

2.1 配方修改 (Recipe Events)

使用 ServerEvents.recipes 事件。

ServerEvents.recipes(event => {
    // 删除配方
    event.remove({ output: 'minecraft:stick' }); 
    event.remove({ type: 'minecraft:smelting', mod: 'create' }); 

    // 添加有序配方
    event.shaped(
        'minecraft:diamond_sword',
        [
            ' A ',
            ' A ',
            ' B '
        ],
        { A: 'minecraft:diamond', B: 'minecraft:stick' }
    );

    // 添加无序配方
    event.shapeless('4x minecraft:planks', ['#minecraft:logs']);

    // 添加熔炉配方
    event.smelting('minecraft:glass', 'minecraft:sand');
    
    // 替换输入/输出
    event.replaceInput({ mod: 'minecraft' }, 'minecraft:stick', '#forge:rods/wooden');
});

2.2 标签修改 (Tag Events)

ServerEvents.tags('item', event => {
    event.add('forge:fruits', 'minecraft:apple');
    event.remove('minecraft:logs', 'minecraft:oak_log');
    event.removeAll('minecraft:wool');
});

2.3 实体与方块交互 (Interaction Events)

// 方块右键事件
BlockEvents.rightClicked('minecraft:stone', event => {
    if (event.item.id === 'minecraft:stick') {
        event.player.tell('你用木棍敲击了石头！');
        event.block.set('minecraft:cobblestone');
        event.cancel(); // 阻止原版逻辑
    }
});

// 实体死亡事件
EntityEvents.death('minecraft:zombie', event => {
    // 僵尸死亡时在原地生成苹果
    event.level.spawn('minecraft:item', event.entity.x, event.entity.y, event.entity.z)
               .mergeNbt({Item:{id:"minecraft:apple",Count:1}});
});

2.4 掉落物与战利品 (Drops Events)

1.21.1 提供了更便捷的掉落物事件 BlockEvents.drops 和 EntityEvents.drops：

BlockEvents.drops('minecraft:gravel', event => {
    // 移除原有掉落物
    event.removeDrop('minecraft:gravel'); 
    
    // 添加自定义掉落物，并带有 50% 几率
    event.addDrop('minecraft:flint').withChance(0.5);
    
    // 甚至可以获取挖掘它的玩家对象
    if (event.player && event.player.mainHandItem.id === 'minecraft:stick') {
        event.addDrop('minecraft:diamond');
    }
});

EntityEvents.drops('minecraft:zombie', event => {
    // 给僵尸添加自定义掉落
    event.addDrop('minecraft:iron_ingot');
});

目录 3 客户端脚本 (Client Scripts)

存放路径：kubejs/client_scripts/

加载时机：客户端资源包刷新时（F3+T）。

主要用途：界面展示、提示栏信息、配方查看器屏蔽、本地化翻译处理。

ItemEvents.modifyTooltips(event => {
    // 为特定物品或标签添加 tooltip (文本组件)
    event.add(Ingredient.of(/.*sword.*/), [
        Text.red('这把武器非常危险！'),
        Text.gray('按 Shift 查看详情')
    ]);
});

3.2 配方查看器统一接口 (Recipe Viewer Events)

在 KubeJS 7 中，RecipeViewerEvents 自动适配并整合了 JEI、REI 和 EMI 三大配方查看器。

RecipeViewerEvents.removeEntries('item', event => {
    // 隐藏特定物品不让玩家看到
    event.remove('minecraft:barrier');
    event.remove('minecraft:bedrock');
});

RecipeViewerEvents.addInformation('item', event => {
    // 给配方查看器中的该物品增加一页信息面板
    event.add('minecraft:clay', '你可以在河流和沼泽的底部找到它。');
});

3.3 语言本地化 (Lang Events)

ClientEvents.lang('zh_cn', event => {
    event.add('item.kubejs.magic_ingot', '魔法锭');
    event.add('item.minecraft.apple', '红彤彤的苹果'); // 可覆盖原版
});

3.4 网络通信 (Network Payloads)

// 客户端接收服务端的自定义数据包
NetworkEvents.dataReceived('custom_particle', event => {
    const data = event.data;
    event.level.spawnParticles('minecraft:heart', false, data.x, data.y, data.z, 0, 0.5, 0, 10, 0.1);
});

附录：核心对象与 API 方法全解

以下列出了你在事件（event.*）中获取到的主要 KubeJS 对象及其封装的全部常用方法。

PlayerKJS (玩家对象)

继承自 EntityKJS，拥有所有实体的功能，同时追加玩家特有的逻辑。

.tell(message) / .setStatusMessage(msg) - 发送聊天框信息 / 发送快捷栏上方(ActionBar)信息。
.runCommandSilent(command) - 以外挂权限在后台静默执行指令。
.give(item) - 强制给予玩家指定物品，如果背包满了会掉在地上。
.health / .maxHealth - 读写当前生命值 / 玩家的最大生命值。
.foodLevel / .addExhaustion(float) - 读写饱食度 / 增加疲劳值（加速饥饿）。
.mainHandItem / .offHandItem - 获取主手和副手的物品（返回 ItemStackKJS）。
.headArmorItem / .chestArmorItem / .legsArmorItem / .feetArmorItem - 获取对应盔甲槽位的物品。
.addItemCooldown(item, ticks) - 给某种物品强制增加冷却时间（类似末影珍珠扔出后的转圈）。
.paint(object) - 在该玩家屏幕上绘制自定义 UI 元素 (需配合 KubeJS UI/Painter 接口)。
.stages - 访问玩家的 GameStages 状态：
包含 .has('stage'), .add('stage'), .remove('stage')。
.persistentData - 获取一个持久化的键值对数据表 (KubeJS Data)，用于永久保存你分配给玩家的变量。

EntityKJS (实体对象)

.uuid / .type - 获取实体的唯一标识符 (UUID) / 注册 ID 字符串（如 'minecraft:zombie'）。
.alive - 返回实体是否存活（布尔值）。
.x / .y / .z - 读写实体在世界中的精确坐标。
.yaw / .pitch - 读写实体的偏航角（左右看）和俯仰角（上下看）。
.teleportTo(dimension, x, y, z, yaw, pitch) - 将实体瞬间传送到指定维度的坐标。
.spawn() / .kill() - 在世界中生成该实体 / 强行杀死实体。
.setMotionX(v) / .addMotion(x, y, z) - 设置或增加实体的运动向量。
.setOnFire(ticks) / .extinguish() - 将实体点燃指定的 Tick 数 / 立即熄灭。
.addPotionEffect(id, ticks, level) - 给予药水效果。
.addTag(tag) / .removeTag(tag) / .hasTag(tag) - 操作原版的记分板 Tag，常用于判断特殊怪物。

LevelKJS (世界/维度对象)

.getBlock(x, y, z) - 解析并返回该位置的方块对象 (BlockContainerJS)。
.getEntitiesWithin(aabb) - 扫描并返回处于 AABB 碰撞箱包围盒内的所有实体列表。
.spawnLightning(x, y, z, effectOnly) - 召唤闪电，effectOnly 决定是否只有视觉效果而无真实伤害。
.createExplosion(x, y, z).strength(float).explode() - 构建并在指定位置引爆。
.spawnParticles(type, false, x, y, z, vx, vy, vz, count, speed) - 召唤原版粒子效果。
.time / .dayTime / .setTime(ticks) - 读取和修改世界的总时间/日内时间。
.runCommandSilent(command) - 强制以所在维度的层级执行一条指令。

BlockContainerJS (方块对象)

.id - 当前方块的注册 ID 文本。
.x, .y, .z - 该方块的整型坐标。
.set('id', {properties}) - 强行替换当前方块。你可以同时传入状态属性，例如 .set('minecraft:chest', {facing: 'north'})。
.properties - 字典型 Map，包含它当前所有的状态数据（如朝向、是否充能等）。
.hasTag(tagId) - 检测方块是否属于某个方块标签（例如 '#minecraft:logs'）。
.offset(x, y, z) - 以自身为基点获取偏移量处的另一个方块对象。
.up() / .down() / .north() 等 - 快速获取直接相邻的方块面上的方块。
.popItem(item) - 直接在该方块的坐标处向外弹射出一个物品实体。
.getEntity() - 如果它是有界面的方块（如箱子、熔炉），可获取底层的 BlockEntity 来操作它的 NBT 或库存。

ItemStackKJS (物品栈对象)

.id - 物品栈的标识 ID。
.count - 读写此堆物品的当前数量。
.maxStackSize / .maxDamage - 只读，获取它的最大可堆叠数/最大耐久值。
.damageValue / .setDamageValue(val) - 读写当前物品被损耗了多少点耐久。
.withCount(count) - 返回一个改变了数量的物品栈副本（不修改原物品栈）。
.shrink(count) / .grow(count) - 直接让当前的物品栈减少或增加一定的数量。
.nbt - 获取自定义数据。注意：在 1.21.1 中，Minecraft 全面转用 Data Components。 KubeJS 在 NBT 层做了一定的组件包装桥接，但对于原版附魔、属性等复杂数据，应优先使用组件相关的 API 接口。
.hoverName - 获取或覆盖设置玩家在悬浮提示时看到的物品名称。

IngredientKJS (配方/匹配材料对象)

通常在处理配方或事件过滤时使用。

Ingredient.of(str) - 将字符串解析为规范的匹配材料（可接受 ID、Tag 或正则表达式）。
Ingredient.all - 表示通配任何物品的特殊材料对象。
.test(itemStack) - 测试给定的 ItemStackKJS 是否符合该材料的规则要求，返回布尔值。
.getItemIds() - 将该材料所包含/囊括的所有具体物品 ID 解析并输出为一个列表。

KubeJS 7 v1.21.1 核心速查手册 & 全对象API参考