Spell chaining

Basics:

A spell system is multiple spells chained together. There's always one or multiple entry-point main spells that casts sub-spells, which might cast its own sub-spells and such.

Main spells:

• Main spells are the entry point of a spell chain like: Passive spells, spells with cast-item-<type>, spells casted by commands, etc.
• They are casted with the full cast mode - full processing.
• If spells are configured as helper spells (with helper-spell: true), then you only need to grant (teach or give grant permissions) for the main spell, not its sub-spells.

Sub-spells:

• Usually, all spells generate 5 different permissions per spell (grant, learn, cast, teach, and tempgrant), which takes a toll on plugin load time. For that reason, it is recommended that all sub-spells (non-entry-point spells) should be configured as helper spells.
• If you rely on the permission granting system, the main spells should have a permission-name. But also, if you don't want to use helper spells for whatever reason, you can make sub spells have the same permission-name instead.
• All sub-spells are casted with the partial cast mode. As per that page, they are casted without setting cooldown, removing reagents (cost), adding experience, displaying cast time, or sending str-<type> messages. Spells casted with the cast mode full do process these, and they are usually main spells, but you can force a sub-spell to be casted in that mode by configuring it like so: subSpell(mode=full). If you're interested, the linked page covers other cast arguments.

Helper spells:

• They are spells that are configured with helper-spell: true
• They will not generate any permissions at all. It's possible for any spell to cast helper spells as a sub-spell. For that reason, it's only important for the main spells to be granted to the player (taught or granted with permissions).
• They cannot be: listed in list spells, bound, taught (with Teach spell), or granted with permissions.

Example:

main_spell:
    spell-class: ".MultiSpell"
    # granted to everyone
    always-granted: true
    # or we remove the above and set
    permission-name: pyro
    spells:
      # default "partial" cast mode, no msg
      - sub_spell_dummy
      # full mode
      - sub_spell_msg(mode=full)

sub_spell_dummy:
    spell-class: ".instant.DummySpell"
    helper-spell: true
    str-cast-self: "<red>this won't be sent</red>"

sub_spell_msg:
    spell-class: ".instant.DummySpell"
    helper-spell: true
    str-cast-self: "<lime>this will be sent</lime>"