KubeJS Spellcraft

KubeJS Spellcraft lets modpack developers script spell systems through KubeJS, including custom spells, spell schools, mana costs, cooldowns, damage, scroll loot, casting events, upgrades and player-specific bonuses.

About

KubeJS Spellcraft is a KubeJS addon designed for spell-focused modpacks.

It exposes spell casting and spell configuration to scripts, allowing pack developers to rebalance magic systems, create progression paths and react to spell casts without writing a full custom mod.

Features

Create custom spells
Modify existing spells
Create and configure spell schools
Change mana costs, cooldowns, damage, range and duration
Add spell scrolls to loot tables
Create spell recipes and upgrade paths
Give and remove spells from players
Add player-specific spell bonuses
Cancel or replace spell effects through events

Script Bindings

Spellcraft
SpellEvents

Events

Before a Spell is Cast

Runs before a spell is cast and can cancel the cast.

SpellEvents.preCast(event => {
  if (
    event.spell === "irons_spellbooks:fireball" &&
    event.player.level.dimension === "minecraft:the_nether"
  ) {
    event.cancel()
  }
})

Spell Cast

Runs after a spell is successfully cast.

SpellEvents.cast(event => {
  if (event.spell === "irons_spellbooks:fireball") {
    event.player.tell("Fireball cast")
  }
})

Spell Effect

Runs when a spell effect is applied. Effects can be cancelled or replaced where supported.

SpellEvents.effect(event => {
  if (event.spell === "irons_spellbooks:fireball") {
    event.replace(ctx => {
      ctx.target.setSecondsOnFire(5)
    })
  }
})

Spell Cooldown

Runs when a spell cooldown is calculated or applied.

SpellEvents.cooldown(event => {
  if (event.player.headArmorItem.id === "minecraft:golden_helmet") {
    event.cooldown = Math.floor(event.cooldown * 0.8)
  }
})

Methods

Register a Custom Spell

Spellcraft.registerSpell("modpack:ember_bolt", spell => {
  spell.school("modpack:ember")
  spell.manaCost(20)
  spell.cooldown(60)
  spell.damage(6)
  spell.range(24)
  spell.duration(0)

  spell.effect(event => {
    event.target.setSecondsOnFire(4)
  })
})

Modify an Existing Spell

Spellcraft.modifySpell("irons_spellbooks:fireball", spell => {
  spell.manaCost(35)
  spell.cooldown(120)
  spell.damage(10)
  spell.range(32)
  spell.duration(80)
})

Create a Spell School

Spellcraft.school("modpack:ember", school => {
  school.name("Ember")
  school.color("#ff6633")
  school.icon("minecraft:blaze_powder")
})

Add Spell Scroll Loot

Spellcraft.addScrollLoot(
  "minecraft:chests/ancient_city",
  "modpack:ember_bolt",
  8
)

Create a Spell Recipe

Spellcraft.recipe("modpack:ember_bolt_recipe", recipe => {
  recipe.input("minecraft:paper")
  recipe.input("minecraft:blaze_powder")
  recipe.resultSpell("modpack:ember_bolt")
})

Create an Upgrade Path

Spellcraft.upgrade("modpack:ember_bolt_2", upgrade => {
  upgrade.from("modpack:ember_bolt")
  upgrade.to("modpack:ember_bolt_greater")
  upgrade.cost("minecraft:blaze_rod", 2)
})

Check Whether a Player Knows a Spell

if (Spellcraft.hasSpell(player, "modpack:ember_bolt")) {
  player.tell("You know Ember Bolt")
}

Give a Spell

Spellcraft.giveSpell(player, "modpack:ember_bolt")

Remove a Spell

Spellcraft.removeSpell(player, "modpack:ember_bolt")

Set a Player-Specific Cooldown

Spellcraft.setCooldown(
  player,
  "irons_spellbooks:fireball",
  200
)

Read a Player-Specific Cooldown

let cooldown = Spellcraft.getCooldown(
  player,
  "irons_spellbooks:fireball"
)

Override a Mana Cost

Spellcraft.setManaCost(
  player,
  "irons_spellbooks:fireball",
  15
)

Add a Temporary Spell Bonus

Spellcraft.addBonus(player, "nether_star_focus", {
  school: "irons_spellbooks:fire",
  damageMultiplier: 1.25,
  manaCostMultiplier: 0.85
})

Remove a Spell Bonus

Spellcraft.removeBonus(player, "nether_star_focus")

Requirements

KubeJS
A supported spell mod for your Minecraft version and loader

Compatibility

Builds are only provided for versions and loaders where KubeJS and the required spell dependencies are available.

Unsupported combinations are skipped instead of being presented as working.