Making Tricks

Creating a trick

Most tricks are fairly straight-forward to implement. You create a class which extends Trick and override the activate method. Here is a simple example:

public class IsEvenTrick extends Trick {
    public IsEvenTrick() {
        super(Pattern.of(3, 4, 5));
    }

    @Override
    public Fragment activate(SpellContext ctx, List<Fragment> fragments) throws BlunderException {
        return new BooleanFragment(expectInput(fragments, FragmentType.NUMBER, 0).number() % 2 == 0);
    }
}

Let's break this down. We've made a new class, IsEvenTrick, which extends Trick. We've overridden activate and passed a Pattern to the super constructor. The Pattern we passed is the pattern in-game that maps to this trick. Using a pattern already used by another trick results in the last one registered replacing all others, so be careful which pattern you pick. The activate method is where the logic of IsEvenTrick lies. When this trick is executed, it receives the context of the current execution and the fragments that resulted from evaluating all the child circles. IsEvenTrick calls expectInput, a function available to all inheritors of Trick, which takes a list of fragments, (optionally) a FragmentType, and an index. It will return the fragment of the appropriate type at the index given, or throw a BlunderException if there is none, or if it encounters a type mismatch. The returned fragment is a NumberFragment in this case. IsEvenTrick returns a new BooleanFragment whose value is equivalent to the result of n % 2 == 0.

Registering a trick

So you've got a trick implemented. But you need to register your trick before it will be available in game. To do this, we simply call Registry.register(Tricks.REGISTRY, Identifier.of("mymod", "is_even"), new IsEvenTrick()); in the addon's main initializer. Be sure to replace mymod with your addon's ID!

Your new trick should now be available in-game, but there's something missing still...

Translations and documentation

If you tried to use IsEvenTrick in-game without passing it a number, you may have noticed that the blunder in chat doesn't display the trick's name, but rather its translation key. You can add the translation for that key in your language file as you would any other translation.

Now, the final step: adding an entry to the Tome of Tomfoolery. While this isn't necessary, it is highly recommended, as otherwise there will be no way for players to know how to draw your trick without looking at the code themselves.

In your mod's assets (resources/assets/mymod), create the file lavender/books/tome_of_tomfoolery.json. In it, add the following snippet:

{
  "extend": "trickster:tome_of_tomfoolery"
}

Then, create the directory lavender/entries/tome_of_tomfoolery. Within this directory, create a markdown file. You may name it anything, as long as it contains only underscores and lower-case letters. At the top of this file, include a JSON code block, like so:

```json
{
  "title": "Addon Trick",
  "icon": "minecraft:stone",
  "category": "trickster:tricks"
}
```

Make sure the title, icon, and book category are correct! For more info on the available properties an entry can have, please refer to the docs. Then, beneath this code block, you can put a short description of this entry.

Cool tricks to impress your friends!

;;;;;

The five semicolons at the end denote a page break. For more info on Lavender syntax, please refer to its documentation. Following this page break, we can add our first entry:

<|glyph@trickster:templates|trick-id=mymod:is_even,title=Even Distortion|>

number -> boolean

---

Returns whether the given number is even.

Be sure to replace mymod:is_even with the correct identifier, and to change the string after title= so it matches the translation. And finally, you have your first trick available in game, with an entry in the Tome of Tomfoolery, so it can be found!

Ploys

//TODO: tryWard, useMana, expectCanBuild, and mana usage Lavender element