API

Spellbook Plus provides a developer API for creating custom spells and integrations.

Service Registry

Access services globally via ServiceRegistry:

SpellbookConfig config = ServiceRegistry.get(SpellbookConfig.class);
CooldownManager cooldowns = ServiceRegistry.get(CooldownManager.class);
ManaManager mana = ServiceRegistry.get(ManaManager.class);
SpellHotbarManager hotbar = ServiceRegistry.get(SpellHotbarManager.class);
SpellCastHandler castHandler = ServiceRegistry.get(SpellCastHandler.class);
NodeRegistry nodes = ServiceRegistry.get(NodeRegistry.class);

Interfaces

IManaManager

Manage player mana resources.

public interface IManaManager {
    boolean hasMana(UUID playerId, int amount);
    boolean consumeMana(UUID playerId, int amount);
    void addMana(UUID playerId, int amount);
    void setMana(UUID playerId, int amount);
    void setMaxMana(UUID playerId, int maxMana);
    int getCurrentMana(UUID playerId);
    int getMaxMana(UUID playerId);
    int calculateManaCost(String spellId);
    void removePlayer(UUID playerId);
}

ICooldownManager

Manage spell cooldowns.

public interface ICooldownManager {
    boolean canCast(UUID playerId, String spellId);
    void applyCooldown(UUID playerId, SpellDefinition spell);
    void applyCooldown(UUID playerId, SpellDefinition spell, float multiplier);
    void applyCooldownMs(UUID playerId, String spellId, long cooldownMs);
    long getRemainingCooldown(UUID playerId, String spellId);
    void clearCooldown(UUID playerId, String spellId);
    void clearAllCooldowns(UUID playerId);
    long getGlobalCooldownMs();
}

ISpellExecutor

Execute spell graphs.

public interface ISpellExecutor {
    GraphExecutionResult execute(SpellDefinition spell, TriggerContext context);
    GraphExecutionResult execute(SpellDefinition spell, TriggerContext context,
                                  InstabilityOutcome instabilityOutcome);
}

ISpellValidator

Validate spell definitions.

public interface ISpellValidator {
    ValidationResult validate(SpellDefinition spell);
    boolean isValid(SpellDefinition spell);
    boolean isNodeTypeAllowed(String nodeType);
}

ISpellStorage

Store and retrieve player spells.

public interface ISpellStorage {
    SaveResult saveSpell(UUID playerId, SpellDefinition spell);
    LoadResult loadSpell(UUID playerId, String spellId);
    List<String> listSpells(UUID playerId);
    boolean deleteSpell(UUID playerId, String spellId);
    boolean hasSpell(UUID playerId, String spellId);
}

Spell Definition Schema

SpellDefinition

public class SpellDefinition {
    String id;
    String name;
    int version;
    String checksum;
    SpellGraph graph;
    SpellMetadata metadata;
}

SpellGraph

public class SpellGraph {
    List<SpellNode> nodes;
    List<NodeConnection> connections;
}

SpellNode

public class SpellNode {
    String id;
    String type;
    Map<String, Object> parameters;
    Position2D editorPosition;
}

NodeConnection

public class NodeConnection {
    String sourceNodeId;
    String sourceOutputSlot;
    String targetNodeId;
    String targetInputSlot;
}

Node Types

Trigger Nodes

Type	Description
on_cast	Spell initiation trigger
on_hit	Projectile hit trigger
on_expire	Spell end trigger

Action Nodes

Type	Description
damage	Apply damage to targets
heal	Heal target
spawn_projectile	Create projectiles
apply_effect	Apply status effects
push	Knockback effect
shield	Absorption shield
teleport	Movement/blink
conditional	If/then branching

Creating Custom Nodes

Extend SpellNodeHandler:

public class MyCustomNode extends SpellNodeHandler {

    @Override
    public ExecutionResult execute(NodeExecutionContext context) {
        // Get parameters
        int value = context.getParameter("value", Integer.class, 10);

        // Execute logic
        // ...

        return ExecutionResult.success();
    }

    @Override
    protected void validateParameters(SpellNode node,
                                       ValidationResult.Builder builder) {
        // Validate node parameters
        if (!node.getParameters().containsKey("value")) {
            builder.addError("Missing required parameter: value");
        }
    }
}

Register in NodeRegistry:

NodeRegistry registry = ServiceRegistry.get(NodeRegistry.class);
registry.register("my_custom_node", new MyCustomNode());

TriggerContext

Context passed during spell execution:

public class TriggerContext {
    UUID casterId;
    Ref<EntityStore> casterRef;
    float[] castPosition;
    float[] aimDirection;
    UUID targetId;
    CommandBuffer<EntityStore> commandBuffer;
    SpellDefinition spell;
    StaffQuality staffQuality;
}

Cast Results

CastResult

public class CastResult {
    boolean success;
    CastFailureReason failureReason;
    GraphExecutionResult executionResult;
    InstabilityOutcome instabilityOutcome;
    int manaConsumed;
    long cooldownApplied;
    String message;
}

CastFailureReason

public enum CastFailureReason {
    SUCCESS,
    INVALID_SPELL,
    INSUFFICIENT_MANA,
    ON_COOLDOWN,
    PERMISSION_DENIED,
    NODE_NOT_UNLOCKED,
    VALIDATION_FAILED,
    EXECUTION_ERROR,
    CHECKSUM_MISMATCH,
    FIZZLED,
    BACKFIRED,
    NO_SPELL_EQUIPPED
}

Validation

ValidationResult

public class ValidationResult {
    boolean valid;
    List<String> errors;
    List<String> warnings;

    // Static factory methods
    static ValidationResult valid();
    static ValidationResult invalid(String error);
    static ValidationResult invalid(List<String> errors);

    // Instance methods
    boolean isValid();
    List<String> getErrors();
    List<String> getWarnings();
    boolean hasWarnings();
}

Whitelists

Projectile Types

fireball, iceball, lightning, magic_orb

Effect Types

fire, poison, regeneration, slowness, weakness

Damage Types

magic, fire, ice, lightning, physical, poison, holy, dark

Events

Hytale Events

The mod listens to these Hytale events:

Event	Purpose
PlayerMouseButtonEvent	Spell staff interactions
AddPlayerToWorldEvent	Initialize player components
PlayerDisconnectEvent	Cleanup player data

Components

ECS-style components for entities:

Component	Purpose
ManaComponent	Player mana tracking
CooldownComponent	Per-spell cooldowns
SpellHotbarComponent	Selected spells
SpellLifetimeComponent	Projectile lifetime
ProjectileDataComponent	Projectile metadata

Network Packets

EffectPacket

Sends visual effects to clients:

public class EffectPacket {
    EffectType type;  // damage, heal, hit, cast, teleport, shield
    float[] position;
    // ...
}

Example: Custom Spell Handler

public class CustomSpellPlugin {

    public void onEnable() {
        // Get managers
        IManaManager mana = ServiceRegistry.get(ManaManager.class);
        ICooldownManager cooldown = ServiceRegistry.get(CooldownManager.class);

        // Check if player can cast
        UUID playerId = player.getUUID();
        String spellId = "fireball";

        if (!cooldown.canCast(playerId, spellId)) {
            long remaining = cooldown.getRemainingCooldown(playerId, spellId);
            player.sendMessage("On cooldown: " + remaining + "ms");
            return;
        }

        if (!mana.hasMana(playerId, 18)) {
            player.sendMessage("Not enough mana!");
            return;
        }

        // Consume mana and apply cooldown
        mana.consumeMana(playerId, 18);
        cooldown.applyCooldownMs(playerId, spellId, 2000);

        // Execute spell logic...
    }
}