KubeJS World Tools

KubeJS WorldTools

KubeJS WorldTools adds server-side world scripting helpers for KubeJS pack developers. It provides script bindings for zones, multiblock checks, markers, hologram data, item metadata definitions, cutscene-style player actions, and ghost preview state.

Use it for adventure maps, custom progression, server events, scripted machines, area triggers, and pack-specific world logic.

Script Bindings

Cutscene
Hologram
Zone
ItemData
Multiblock
GhostPreview
Marker

Zone Methods

Zone.create(id)
Zone.remove(id)

Zone.create(id)
  .dimension(dimensionId)
  .from(x, y, z)
  .to(x, y, z)
  .interval(ticks)
  .onEnter(player => {})
  .onLeave(player => {})
  .onTick(player => {})

Example:

ServerEvents.loaded(event => {
  Zone.create("spawn")
    .dimension("minecraft:overworld")
    .from(-20, 60, -20)
    .to(20, 90, 20)
    .interval(20)
    .onEnter(player => {
      player.tell("Entered spawn")
    })
    .onLeave(player => {
      player.tell("Left spawn")
    })
    .onTick(player => {
      player.addItemCooldown("minecraft:ender_pearl", 20)
    })
})

Multiblock Methods

Multiblock.create(id)
  .pattern(listOfRows)
  .where(symbol, blockId)
  .onComplete(context => {})
  .onBreak(context => {})

Example:

ServerEvents.loaded(event => {
  Multiblock.create("copper_core")
    .pattern([
      "CCC",
      "CIC",
      "CCC"
    ])
    .where("C", "minecraft:copper_block")
    .where("I", "minecraft:iron_block")
    .onComplete(ctx => {
      ctx.player().tell("Copper core complete")
    })
    .onBreak(ctx => {
      ctx.player().tell("Copper core broken")
    })
})

Cutscene Methods

Cutscene.start(player)
  .lockMovement(boolean)
  .fadeIn(ticks)
  .fadeOut(ticks)
  .camera(x, y, z, seconds)
  .lookAt(x, y, z)
  .subtitle(text)
  .playSound(soundId)
  .wait(ticks)
  .cancel()

Example:

PlayerEvents.loggedIn(event => {
  Cutscene.start(event.player)
    .subtitle("Welcome back")
    .playSound("minecraft:block.note_block.pling")
    .wait(40)
})

Note: subtitle and playSound are usable server-side actions. Camera, fade, and movement lock currently require a future client packet/renderer module and may throw an unsupported-operation error.

Hologram Methods

Hologram.create(id, level)
Hologram.remove(id)
Hologram.clear()

Hologram.create(id, level)
  .pos(x, y, z)
  .text(text)
  .item(itemId)
  .visibleTo(player)
  .distance(distance)

Example:

ServerEvents.loaded(event => {
  Hologram.create("shop_label", event.server.overworld())
    .pos(10.5, 65, -4.5)
    .text("Village Shop")
    .item("minecraft:emerald")
    .distance(48)
})

Note: this currently stores hologram definitions for script/world state. Full client rendering depends on future client-side support.

Marker Methods

Marker.create(player, id)
Marker.remove(id)
Marker.clear()

Marker.create(player, id)
  .entity(entity)
  .block(x, y, z)
  .icon(icon)
  .color(color)
  .text(text)
  .distanceText(boolean)

Example:

PlayerEvents.loggedIn(event => {
  Marker.create(event.player, "starter_objective")
    .block(100, 64, -30)
    .icon("!")
    .color("yellow")
    .text("Find the old tower")
    .distanceText(true)
})

ItemData Methods

ItemData.register(id, options)

Example:

ServerEvents.loaded(event => {
  ItemData.register("starter_blade", {
    item: "minecraft:iron_sword",
    rarity: "quest",
    ownerBound: true,
    bonusDamage: 3
  })
})

GhostPreview Methods

GhostPreview.show(player, id)
GhostPreview.clear(id)

Example:

PlayerEvents.loggedIn(event => {
  GhostPreview.clear("starter_preview")
})

Note: GhostPreview.show(player, id) is registered but currently unavailable until the fake-block client packet module is implemented