KubeJS Tutorial

KubeJS tutorial

This example lets a player use an amethyst shard to convert 5 raw magic into 5,000 survey aether. The player can then use a spyglass to spend 1,000 aether on a minute of Crackle Ley Vision. Both actions use the nearest eligible nexus at the player’s position.

Use the NeoForge 1.21.1 stack. The scripting bridge was tested with KubeJS 2101.7.2-build.381 and Rhino 2101.2.7-build.85. Use the matching dependencies listed by the KubeJS file. Put the scripts on the dedicated server or in the local pack instance. KubeJS file and dependencies · Rhino build 85

1. Register a currency

Save this as kubejs/startup_scripts/ley_currency.js.

StartupEvents.init(() => {
  LeyLines.registerCurrency('kubejs:survey_aether', '1000')
})

Restart the Minecraft client for single-player or the entire dedicated server for multiplayer. Startup registration runs before the currency catalogue freezes. Run /skysleylines rates as an operator and look for kubejs:survey_aether with a saved rate of 1,000 per raw and installed=true.

2. Convert and spend

Save this as kubejs/server_scripts/ley_survey.js.

ItemEvents.rightClicked('minecraft:amethyst_shard', event => {
  if (event.hand.name() !== 'MAIN_HAND') return
  const player = event.player
  const pos = player.blockPosition()
  const result = LeyLines.convertAt(player.serverLevel(), pos.x, pos.y, pos.z,
    'kubejs:survey_aether', '5', 'kubejs:survey_converter', player)
  player.tell('Ley conversion: ' + result.get('status'))
})

ItemEvents.rightClicked('minecraft:spyglass', event => {
  if (event.hand.name() !== 'MAIN_HAND') return
  const player = event.player
  const pos = player.blockPosition()
  const result = LeyLines.spendAt(player.serverLevel(), pos.x, pos.y, pos.z,
    'kubejs:survey_aether', '1000', 'kubejs:survey_vision', player)
  if (result.get('succeeded')) {
    LeyLines.grantVision(player, 'kubejs:survey_vision', 20 * 60, 'skysleylines:crackle')
    event.cancel()
  } else {
    player.tell('Ley payment: ' + result.get('status'))
  }
})

Use /reload after editing this server script. The hand check keeps the example tied to the main-hand action. The example uses the items as reusable triggers, so every qualifying right-click can attempt another payment. A pack that needs a cooldown should check it before spending.

3. Try it in a world

1. In the Overworld, run /skysleylines locate nexus as an operator. Move to a crossing, then use /skysleylines account to check that you are within reach and the nexus has at least 5 raw magic. Use the same spot for both interactions.
2. With an empty survey balance, aim into the air and right-click with the spyglass. You should see INSUFFICIENT_CURRENCY.
3. Aim into the air and right-click once with the amethyst shard in your main hand. Expect SUCCESS and 5,000 survey aether in the account at the default rate.
4. Use the spyglass once. Expect Crackle vision and a 4,000 aether balance. The effect lasts 1,200 server ticks. At 20 ticks per second this is one minute.
5. Leave the nexus and repeat the attempt. Expect NO_NEXUS. If testing with an operator account, run /skysleylines vision off first so the operator toggle does not keep the overlay visible after the script grant expires.

For a machine interaction, pass the machine’s actual block coordinates instead of the player’s feet. Pass the player as the actor when a player initiated the action. A timer or automated machine can omit the actor. Check the result before granting an item, starting a machine, or casting a spell. KubeJS Reference

4. Change the pack safely

Keep kubejs:survey_aether stable across updates. Editing '1000' in the startup file and restarting changes the configured rate. Existing worlds keep their saved rate until an operator previews and applies a migration. Removing the startup definition retains the balance as inactive. Restoring the same ID reactivates it at its saved rate. Configuration and Save Data

To let players carry some of that aether away and spend it later, open a personal pool for the same currency. The player energy guide uses the currency registered above and shows how to spend it from the player’s own balance. If you use its spyglass example, replace the spyglass handler above so each click has one payment path. Player Energy Pools