spellbook_tutorial.md

Spellbook: Full Breakdown and Usage Guide

Spellbook is a utility library (developed by Darkhax) designed to simplify common Hytale modding tasks. It provides helper methods for world manipulation, entity state checking, flexible item generation, and a lightweight testing framework.

Below is a breakdown of the core components with examples of how to use them in your plugin.

---

1. Entity Utilities (EntityHelper)

EntityHelper provides shortcuts for checking complex entity states that usually require multiple ECS (Entity Component System) lookups.

Example: Checking if a Player is Crouching

import net.darkhax.spellbook.api.util.EntityHelper;
import com.hypixel.hytale.component.Ref;
import com.hypixel.hytale.server.core.universe.world.storage.EntityStore;

public void handlePlayerAction(EntityStore store, Ref<EntityStore> playerRef) {
    if (EntityHelper.isCrouching(store, playerRef)) {
        // Perform special action if the player is crouching
    }
}

---

2. World Utilities (WorldHelper)

WorldHelper simplifies interactions with the game world, particularly dropping items and handling coordinate rotations.

Example: Dropping Items at a Position

import net.darkhax.spellbook.api.util.WorldHelper;
import com.hypixel.hytale.math.vector.Vector3d;
import com.hypixel.hytale.server.core.inventory.ItemStack;
import java.util.List;

public void dropReward(World world, Vector3d position, List<ItemStack> items) {
    // Spawns items in the world at the specified location
    WorldHelper.dropItems(world, items, position);
}

Example: Rotating Block Sides

Useful for logic involving block orientation (like pipes or directional blocks).

import net.darkhax.spellbook.api.util.WorldHelper;
import com.hypixel.hytale.server.core.universe.world.connectedblocks.ConnectedBlockPatternRule.AdjacentSide;

// Rotates the 'NORTH' side 90 degrees clockwise (returns EAST)
AdjacentSide rotatedSide = WorldHelper.rotate(AdjacentSide.NORTH, 1);

---

3. Flexible Item Generation (ItemOutput)

ItemOutput is a codec-based system that allows you to define how items are generated (either by ID, weighted lists, or specific stacks) in a way that can be easily loaded from config files.

Example: Working with Item IDs and Random Amounts

import net.darkhax.spellbook.api.codec.output.IdOutput;
import com.hypixel.hytale.server.core.inventory.ItemStack;
import java.util.ArrayList;
import java.util.List;

public List<ItemStack> generateLoot() {
    // This is often loaded from a JSON/BSON config using Spellbook's CODECs
    IdOutput output = new IdOutput();
    // (In a real scenario, itemId and amount range would be set via reflection/config)
    
    // Convert the definition into actual ItemStacks
    return output.outputList(); 
}

---

4. Lightweight Testing Framework (@Test)

Spellbook includes a simple framework to run unit tests within the Hytale environment.

Example: Creating and Running Tests

import net.darkhax.spellbook.api.test.Test;
import net.darkhax.spellbook.api.test.Assert;
import net.darkhax.spellbook.api.test.TestHelper;

public class MyModTests {

    @Test
    public void testMathLogic() {
        int result = 2 + 2;
        Assert.assertEquals(4, result);
    }

    public void runPluginTests() {
        // Runs all methods annotated with @Test in this object
        TestHelper.runTests(this);
    }
}

---

5. Serialization Utilities (Codecs and BsonHelper)

Spellbook provides pre-configured Codec instances for Hytale-specific classes like AdjacentSide and Rotation, making it easier to save and load your mod's data.

Example: Using Built-in Codecs

import net.darkhax.spellbook.api.codec.Codecs;
import com.hypixel.hytale.codec.Codec;
import com.hypixel.hytale.server.core.universe.world.connectedblocks.ConnectedBlockPatternRule.AdjacentSide;

// Use this codec to serialize/deserialize Hytale's AdjacentSide type to/from BSON
Codec<AdjacentSide> sideCodec = Codecs.SIDE;

Summary of Key Packages

Package	Purpose
net.darkhax.spellbook.api.util	Generic helpers for World, Entity, and Math.
net.darkhax.spellbook.api.codec	Serialization tools and Item/Drop output logic.
net.darkhax.spellbook.api.test	Internal testing and assertion framework.
net.darkhax.spellbook.api.interaction	Base classes for block/world interactions.