Spellbook

Spellbook is a library for Hytale, designed to provide helpful utility code,
new components, and a variety of features to empower pack makers!

⚠️ Warning: Early Access
The game Hytale is in early access, and so is this project! Features may be
incomplete, unstable, or change frequently. Please be patient and understanding as development
continues.

Features

• Block States
  • ItemGenerator
• Codecs
  • Item Output
  • Side
• Helpers
  • BsonHelper - Tools for working with JSON data.
  • MathsHelper - Tools related to maths.
  • WorldHelper - Tools related to the world and world data.
• Game Tests

Projects Using Spellbook

• Hopefully someone

Maven

This project is in early access and is not available on maven yet! For now please use
CurseMaven.

build.gradle

repositories {
    exclusiveContent {
        forRepository {
            maven {
                url "https://cursemaven.com"
            }
        }
        filter {
            includeGroup "curse.maven"
        }
    }
}

dependencies {
    implementation "curse.maven:spellbook-238222:2724420"
}

Block States

In Hytale, blocks are usually made with components, interactions, and other properties. While this works for most
blocks, some features require advanced logic that are not currently covered. These blocks rely on the legacy BlockState
system instead. Some examples of state blocks include chests, the furnace, and workbenches. Spellbook provides some
additional states to help you make custom blocks.

The state type can be defined in the BlockType section of your block JSON, using the State property.

{
  "BlockType": {
    "State": {
      "Id": "ExampleStateID",
      "Example": "An example property for the state."
    }
  }
}

ItemGenerator

The ItemGenerator state creates a block that will passively generate items over time and try to insert them into
adjacent inventories. You can configure which faces of the block to export through, how often items are generated, and
how multiple faces are handled. The generator also supports blocks that can be rotated NESW, automatically accounting
for how the block is rotated.

• Id - Always DarkhaxSpellbookItemGenerator
• Output - Determines what items should be generated by the generator.
• ExportFaces - The faces of the block that export items. The export order is determined by the order you wrote them.
• Cooldown - How many ticks does it take to generate the items?
• ExportOnce - By default, the generator will only export once, to the first valid side that accepts an item. If you
  set this to false, the generator will always try to export to all valid faces, regardless of if an item was already
  exported.

The following example creates a block that generates one dirt every 90 ticks (3 seconds). The generator will attempt to
export items into adjacent inventories on its north and south faces.

Because ExportOnce is set to false, the generator will try to export one dirt to each face every cycle. If
ExportOnce were set to true and both faces had a chest, the generator would export only to the north face until that
chest becomes full. Once the north chest is full, it would then begin exporting to the south face.

{
  "State": {
    "Id": "DarkhaxSpellbookItemGenerator",
    "Output": {
      "Type": "Item",
      "ItemId": "Soil_Dirt",
      "Amount": {
        "Min": 1,
        "Max": 1
      }
    },
    "ExportFaces": [
      "North",
      "South"
    ],
    "Cooldown": {
      "Min": 90,
      "Max": 90
    },
    "ExportOnce": false
  }
}

Codecs

Item Output

An ItemOutput defines a source for generating items.

Item

Generates an item by ID and amount.

• Type - Always Item.
• ItemId - The ID of the item.
• Amount - The amount to generate.
• Metadata - Additional data for the item.

The following example produces 1-5 dirt.

{
  "Output": {
    "Type": "Item",
    "ItemId": "Soil_Dirt",
    "Amount": {
      "Min": 1,
      "Max": 5
    }
  }
}

Drop List

Drop lists are predefined lists of items that are dropped when a certain action happens. For example, mobs use a drop
list to specify which items drop when they are defeated. Crops also use them to determine the items that drop when
harvested.

• Type - Always DropList.
• DropList - The ID of the drop list to use.
• Rolls - Determines how many times to generate items from the list.

{
  "Output": {
    "Type": "DropList",
    "DropList": "Drops_Plant_Crop_Wheat_StageFinal_Harvest",
    "Rolls": {
      "Min": 1,
      "Max": 3
    }
  }
}

Side

Represents one of the six sides of a block.

• Up
• Down
• North
• East
• South
• West

Game Tests

Spellbook has a very primitive system for writing and running tests in-game. Writing tests can help ensure your code is
working as expected, and detect when your code is broken. I recommend writing tests for codecs, and any logic that can
be easily tested. You can find an example of this system
here.

1. Create a new class for your tests.
2. Annotate methods with
   @Test
3. Run your tests by calling TestHelper#runTests from the start hook of your plugin.

Example

@Override
protected void start() {
    TestHelper.runTests(new ExampleTests());
}