可调用对象速查（API 参考）¶

原文：原创速查（ぴよまる）

写 KubeJS 脚本时，最常问的就是：「event 里到底能拿到什么？这个对象能干什么？」这篇把所有能调用的对象和它们的常用属性/方法整理成速查表。配合「事件列表」篇使用：先查事件，再查本页拿对象。

⚠️ 注意：KubeJS 6.x（1.20.1）API 以官方文档为准，这里列的是最常用、最稳定的部分。

1. 事件对象（event）里能拿到什么¶

每个事件回调都会收到一个 event 参数，里面装着这次事件相关的所有对象：

ServerEvents.recipes(event => {
  // 不同事件能拿到的对象不一样，下面是最常见的
})

PlayerEvents.chat(event => {
  event.player        // 触发事件的玩家（Player 对象）
  event.message       // 玩家发的消息内容（字符串）
  event.cancel()      // 取消这次事件（比如拦截聊天）
})

BlockEvents.broken(event => {
  event.player        // 破坏方块的玩家
  event.block         // 被破坏的方块（Block 对象）
  event.cancel()      // 取消破坏
})

EntityEvents.death(event => {
  event.entity        // 死亡的实体（Entity 对象）
  event.source        // 死亡原因（可能是玩家/环境/其他实体）
  event.source.player // 如果是被玩家杀的，这里能拿到那个玩家
})

ItemEvents.rightClicked(event => {
  event.player        // 使用物品的玩家
  event.item          // 被使用的物品（Item 对象）
  event.hand          // 用的是哪只手（'main' 主手 / 'off' 副手）
  event.cancel()      // 取消右键行为
})

速查：常见事件里能拿到的对象

事件	常用对象
`PlayerEvents.*`	`event.player`、`event.message`（chat）
`BlockEvents.*`	`event.player`、`event.block`
`ItemEvents.*`	`event.player`、`event.item`
`EntityEvents.*`	`event.entity`、`event.source.player`
`ServerEvents.*`	`event.server`、`event.recipes`（recipes 事件）
`LevelEvents.*`	`event.level`、`event.block`（爆炸事件）
`ClientEvents.*`	`event.player`（客户端玩家）

2. 玩家对象（player）¶

常用属性（直接读）¶

event.player.username          // 玩家名（字符串）：'pyz'
event.player.x                 // X 坐标（数字）
event.player.y                 // Y 坐标
event.player.z                 // Z 坐标
event.player.health            // 当前血量（数字）
event.player.maxHealth         // 最大血量
event.player.foodLevel         // 饥饿值（0~20）
event.player.saturation        // 饱和度
event.player.experienceLevel   // 经验等级
event.player.mainHandItem      // 主手拿的物品（Item 对象）
event.player.offHandItem       // 副手物品
event.player.persistentData    // 永久存档数据（对象，重启不丢）
event.player.server            // 服务器对象
event.player.level             // 所在世界（Level 对象）
event.player.isCrouching       // 是否在潜行（布尔）

常用方法（调用做事）¶

event.player.tell('你好！')                    // 给玩家发消息
event.player.give('minecraft:diamond')         // 给玩家物品
event.player.give('5x minecraft:iron_ingot')   // 给 5 个铁锭
event.player.setHealth(20)                     // 设置血量（20 = 满血）
event.player.setFoodLevel(20)                  // 设置饥饿值（满）
event.player.setSaturation(20)                 // 设置饱和度
event.player.addExperience(100)                // 加 100 经验值
event.player.kill()                            // 杀死玩家
event.player.playSound('minecraft:entity.player.levelup', 1, 1)  // 播放音效
event.player.runCommand('gamemode creative')   // 玩家执行命令

使用示例¶

PlayerEvents.loggedIn(event => {
  let player = event.player          // 拿到玩家对象
  player.tell('§a欢迎回来，' + player.username + '！')
  player.give('1x minecraft:golden_apple')   // 每人送一个金苹果
  player.persistentData.joinCount = (player.persistentData.joinCount || 0) + 1
})

3. 方块对象（block）¶

常用属性¶

event.block.id              // 方块 ID（字符串）：'minecraft:stone'
event.block.x               // 方块 X 坐标
event.block.y               // 方块 Y 坐标
event.block.z               // 方块 Z 坐标
event.block.persistentData  // 方块持久数据（方块实体才有意义）
event.block.level           // 方块所在世界

常用方法¶

event.block.popItem('minecraft:diamond')   // 在方块位置掉落物品
event.block.set('minecraft:air')           // 把方块替换成空气（移除）
event.block.exists                         // 方块是否还存在（布尔）
event.block.getBlockEntity()               // 获取方块实体（如果有）

使用示例¶

BlockEvents.placed(event => {
  if (event.block.id === 'kubejs:magic_block') {
    event.block.popItem('minecraft:diamond')   // 放下去就掉钻石
    event.player.tell('你放置了魔法方块！')
  }
})

4. 物品对象（item）¶

常用属性¶

event.item.id            // 物品 ID（字符串）：'minecraft:diamond'
event.item.count         // 数量（数字）
event.item.empty         // 是否为空（布尔）
event.item.maxStackSize  // 最大堆叠数
event.item.nbt           // NBT 数据（对象，附魔/自定义标签等）
event.item.name          // 物品显示名

常用方法¶

event.item.count = 1                  // 直接改数量
event.item.nbt                       // 读写 NBT
event.item.withCount(3)              // 返回一个数量为 3 的新物品
event.item.shrink(1)                 // 数量减 1
event.item.grow(1)                   // 数量加 1

使用示例¶

ItemEvents.crafted(event => {
  if (event.item.id === 'minecraft:diamond') {
    event.player.tell('你合成了钻石！')
    event.item.count = 1   // 不管合出几个，只留 1 个
  }
})

5. 实体对象（entity）¶

常用属性¶

event.entity.type           // 实体类型 ID：'minecraft:zombie'
event.entity.x              // X 坐标
event.entity.y              // Y 坐标
event.entity.z              // Z 坐标
event.entity.health         // 当前血量
event.entity.maxHealth      // 最大血量
event.entity.persistentData // 实体持久数据
event.entity.name           // 实体名称
event.entity.customName     // 自定义名称
event.entity.isAlive        // 是否活着（布尔）

常用方法¶

event.entity.kill()                        // 杀死实体
event.entity.setCustomName('大Boss')       // 设置自定义名称
event.entity.setGlowing(true)              // 发光
event.entity.teleportTo(x, y, z)           // 传送
event.entity.setHealth(20)                 // 设置血量

使用示例¶

EntityEvents.spawned(event => {
  if (event.entity.type === 'minecraft:zombie') {
    event.entity.setCustomName('§c超级僵尸')   // 所有生成的僵尸改名
    event.entity.setGlowing(true)              // 发光，方便发现
  }
})

6. 服务器对象（server）¶

常用属性¶

event.server.players       // 所有在线玩家（数组，forEach 遍历）
event.server.overworld     // 主世界（Level 对象）
event.server.tick          // 当前 tick 数（20 tick = 1 秒）
event.server.allLevels     // 所有世界

常用方法¶

event.server.runCommandSilent('time set day')        // 执行命令（无输出）
event.server.runCommand('give @p diamond')           // 执行命令（有输出）
event.server.scheduleInTicks(100, () => { ... })     // 延时 100 tick（5秒）后执行
event.server.tell('全服广播！')                      // 给所有玩家发消息
event.server.runCommandSilent(`tp ${playerName} 0 100 0`)  // 带变量命令

使用示例¶

PlayerEvents.chat(event => {
  if (event.message === '!全体') {
    event.server.players.forEach(p => {
      p.tell('管理员发来问候！')
    })
  }
})

7. 世界对象（level）¶

常用属性¶

event.level.dayTime     // 游戏内时间（数字，24000 = 一天）
event.level.dimension   // 维度 ID：'minecraft:overworld'
event.level.players     // 世界里的玩家
event.level.difficulty  // 难度

常用方法¶

event.level.getBlock(x, y, z)        // 获取某个坐标的方块对象
event.level.getEntities()            // 获取所有实体（小心卡顿）
event.level.playSound(...)           // 播放音效

使用示例¶

LevelEvents.loaded(event => {
  if (event.level.dayTime > 12000) {
    console.log('这个世界的白天过半了')
  }
})

8. 最常用代码模式（直接抄）¶

8.1 拿到玩家并操作¶

PlayerEvents.loggedIn(event => {
  let player = event.player      // ← 最常见的写法：把玩家存进变量
  player.tell('你好！')
  player.give('minecraft:bread')
})

8.2 判断物品/方块 ID¶

ItemEvents.rightClicked(event => {
  if (event.item.id === 'kubejs:my_wand') {
    event.player.tell('你用了魔法棒！')
  }
})

BlockEvents.broken(event => {
  if (event.block.id === 'minecraft:bedrock') {
    event.cancel()
  }
})

8.3 给多个物品加标签 / 配方¶

ServerEvents.tags('item', event => {
  ['minecraft:stone', 'minecraft:cobblestone'].forEach(id => {
    event.add('forge:stone', id)
  })
})

8.4 数据存档（persistentData）¶

BlockEvents.broken(event => {
  let data = event.player.persistentData   // 玩家的永久存档
  data.mined = (data.mined || 0) + 1       // 挖方块计数 +1
})

9. 常见对象获取速查表¶

想拿什么	写法
触发事件的玩家	`event.player`
玩家名	`event.player.username`
玩家坐标	`event.player.x / .y / .z`
玩家血量	`event.player.health`
玩家持久数据	`event.player.persistentData`
涉及的方块	`event.block`
方块 ID	`event.block.id`
方块坐标	`event.block.x / .y / .z`
使用的物品	`event.item`
物品 ID	`event.item.id`
涉及的实体	`event.entity`
实体类型	`event.entity.type`
服务器对象	`event.server`（或 `player.server`）
世界对象	`event.level`（或 `player.level`）
所有在线玩家	`event.server.players`
给玩家发消息	`event.player.tell('...')`
给玩家物品	`event.player.give('id 数量')`
执行命令	`event.server.runCommandSilent('...')`
延时执行	`event.server.scheduleInTicks(20, () => {...})`
取消事件	`event.cancel()`

💡 记忆口诀：event 是事件入口 → .player 玩家、.block 方块、.item 物品、.entity 实体、.server 服务器 → 拿到对象后用 .属性 读数据、.方法() 做动作。