SorceryCraft/API.md

# API

## Getting Started
1. Add Dependency to Gradle
    ```gradle
    repositories {
        maven { url 'https://maven.thebrokenrail.com' }
    }
    dependencies {
        modImplementation 'com.thebrokenrail:sorcerycraft:VERSION'
        // VERSION = "<Mod Version>+<MC Version>", for example "1.2.4+20w12a"
    }
    ```
2. Add Dependency to ```fabric.mod.json```
    ```json
    {
        "depends": {
            "sorcerycraft": "1.2.x"
        }
    }
    ```
3. Create a class extending ```com.thebrokenrail.sorcerycraft.spell.api.Spell```
    ```java
    public class ExampleSpell extends Spell {
       public ExampleSpell(Identifier id, int level) {
           super(id, level);
       }

       @Override
       public void execute(Entity target, Entity source, Entity attacker) {
           // OPTIONAL
           // Called when ExampleSpell hits an entity
           // Override this if you want the spell to affect entities
       }

       @Override
       public void execute(World world, BlockHitResult hitResult) {
           // OPTIONAL
           // Called when ExampleSpell hits a block
           // Override this if you want the spell to affect blocks
       }

       @Override
       public int getXPCost() {
           // REQUIRED
           // Return the amount of levels required to make ExampleSpell in a Casting Table
           switch (getLevel()) {
               case 0: {
                   return 4;
               }
               case 1: {
                   return 8;
               }
           }
           return -1;
       }

       @Override
       public ItemStack getItemCost() {
           // REQUIRED
           // Return the item(s) required to make ExampleSpell in a Casting Table
           // Return ItemStack.EMPTY if an item is not required
           switch (getLevel()) {
               case 0: {
                   return new ItemStack(Items.SUGAR_CANE);
               }
               case 1: {
                   return new ItemStack(Items.BOOK);
               }
           }
           return ItemStack.EMPTY;
       }

       @Override
       public int getMaxLevel() {
           // REQUIRED
           // Return ExampleSpell's maximum level
           return 2;
       }

       @Override
       public Text getTranslation() {
           // OPTIONAL
           // Return a custom display name for ExampleSpell
           // Override this only if you want a custom display name
           return new LiteralText("Example " + (getLevel() + 1));
       }
    }
    ```
4. Register the spell in your ModInitializer
    ```java
    public class ExampleMod implements ModInitializer {
        public static final Identifier EXAMPLE_SPELL = SpellRegistry.register(new Identifier("modid", "example_spell"), ExampleSpell.class);
    }
    ```
5. Add Spell Translation (skip this if you have overridden ```Spell.getTranslation()``)
    ```json
    {
        "spell.modid.example_spell": "Example"
    }
    ```

## Useful Methods
- ```(non-static) Spell.getLevel()```
- ```(non-static) Spell.getID()```
- ```(static) SpellRegistry.register()```

## API Stability
APIs are only guaranteed to be stable in the ```com.thebrokenrail.sorcerycraft.api``` package, it is unrecommended to rely on any SorceryCraft classes outside of this package.

## Spell Levels
Spell levels are 0-indexed, if you have a level 1 Example Spell, ```Spell.getLevel()``` wil return 0, and if it is level 2 ```Spell.getLevel()``` wil return 1, ```Spell.getMaxSpell()``` should be the maximum-acceptable value of ```Spell.getLevel() + 1```, so if Example Spell has levels 1-2, ```Spell.getMaxLevel()``` should return 2.

## JavaDoc
[View JavaDoc](https://jenkins.thebrokenrail.com/job/SorceryCraft/job/master/JavaDoc/)