KubeJS Script Profiler

KubeJS Script Profiler Description

KubeJS Script Profiler adds lightweight profiling helpers for KubeJS scripts. It helps pack developers measure custom script callbacks, track slow logic, inspect reload timing, and generate readable performance reports.

Use it when a pack has slow reloads, expensive tick handlers, laggy scripted events, or large KubeJS files that need optimization.

Script Binding

KJSProfiler

Profiler Methods

KJSProfiler.start()
KJSProfiler.stop()
KJSProfiler.enabled()
KJSProfiler.reset()
KJSProfiler.report()
KJSProfiler.profile(name, callback)

Start Profiling

ServerEvents.loaded(event => {
  KJSProfiler.start()
})

Stop Profiling

ServerEvents.loaded(event => {
  KJSProfiler.stop()
})

Check If Enabled

ServerEvents.tick(event => {
  if (!KJSProfiler.enabled()) {
    return
  }

  // profiler is active
})

Reset Stored Samples

ServerEvents.loaded(event => {
  KJSProfiler.reset()
  KJSProfiler.start()
})

Print A Report

ServerEvents.loaded(event => {
  console.log(KJSProfiler.report())
})

Profile A Callback

ServerEvents.tick(
  KJSProfiler.profile("server_tick_custom_logic", event => {
    // Expensive script logic here
  })
)

Profile A Command Or Custom Function

function rebuildCache(event) {
  // scan recipes, tags, player data, etc.
}

ServerEvents.loaded(
  KJSProfiler.profile("rebuild_cache", event => {
    rebuildCache(event)
  })
)

Profile Multiple Events

PlayerEvents.loggedIn(
  KJSProfiler.profile("player_login_setup", event => {
    event.player.tell("Loading player data...")
  })
)

BlockEvents.rightClicked(
  KJSProfiler.profile("block_right_click_logic", event => {
    if (event.block.id == "minecraft:crafting_table") {
      event.player.tell("Crafting table clicked")
    }
  })
)

Typical Optimization Flow

ServerEvents.loaded(event => {
  KJSProfiler.reset()
  KJSProfiler.start()
})

ServerEvents.tick(
  KJSProfiler.profile("main_tick_handler", event => {
    // test the code you suspect is slow
  })
)

ServerEvents.loaded(event => {
  console.log(KJSProfiler.report())
})

What The Report Includes

Status: running/stopped
Minecraft version
Loader version
KubeJS version
Duration
Reload profile
Event profile
Tick hotspots
Suggestions

Notes

• KJSProfiler.profile(name, callback) only records while the profiler is enabled.
• Tick-related names containing tick are treated as tick hotspot samples.
• Slow callbacks can print warnings based on the config thresholds.
• Reload timing is automatic on supported versions. Older builds may expose fewer reload details depending on KubeJS internals.