I've been messing with the plugin configs for awhile now but I'm still having trouble with the actions system.

I'm not sure when which actions or parameters are appropriate in specific sections of the config.

For example, if I wanted to create an active spell that drained x amount of energy/mana per second but gave the caster a potion effect as long as the spell was active, how would I do it?

When do I define actions in spells.yml versus using "class: SomeSpell" for similar tasks? Do I define parameters on the action sections of spells.yml directly, or do I lump all of them into the "parameters" section?

Unfortunately for your specific question, action spells don't support being "active" yet- or at least not in an official sense. It's been on my list for a while.

In a more general sense, if you're making an action spell you just omit the "class" part. The specific spell classes were the old way of doing things, where each spell type had some custom code that drove it. The action system replaces that, so you build your own spells from little Lego pieces instead of having to write custom code.

The parameters can be in either place. Parameters in the main "parameters" section will apply to any appropriate actions. This can be nice, for instance if you have a spell that has a Sphere action to change blocks and an AreaOfEffect action to damage entities, you can use a single radius parameter in the "parameters" section to make them both the same size. This is especially useful if you want the spell to level up and have the radius grow.

Alternately, if you want the two radii to differ you can put a radius on a specific action. Parameters on specific actions will override anything in the main parameters block.

I know it if is very complex and not well documents, the default spells should be a good start to get a feel for what is possible, but I realize it's still a steep learning curve.

I hope this helps at least a little, let me know if I can be more descriptive!

That cleared up a lot, thank you.

In regards to parameters, I've seen some spells using variable placeholders (like $duration). Where does that data come from, and where is it actually applicable?

Those (I think) only work in effects blocks. The idea is to link the FX up to the actual spell behavior. So the visual effects will last as long as the spell does, or have the same radius as the spell.

In order to do this in a way that ties into EffectLib, you can use "$parameter" as a variable for anything in the main "parameters" blocks. So giving an effect something like "radius: $radius" means to use the radius defined in parameters.

It's a little more complex than it needs to be, but it made creating spell levels much easier in some cases- if you want a spell where the duration levels up, for instance, you don't need to re-create the effects for every level of the spell.

Do the variables only come from the main "parameters" block or will params defined directly with the action classes override them?

IIRC, only the main parameter block.

Otherwise how would it know which one to use- you could have several different "radius" parameters attached to different actions, for instance.

Fair enough. It's a little confusing because the action spells aren't defined in a linear manner (ie the variables are used before the parameters block is even defined in the config). A good wiki page that explains the process would be a big help to new users of the plugin.

Yeah I agree it's a little confusing, but I do keep the parameters in the main block on purpose. It's easier to tweak them that way, you can do "/cast blob radius 32" in-game to test changes to parameters, or use the "/wand override" command.

Parameters attached to actions become baked in and can't easily be changed in-game or by a spell upgrade.

When making your own spells, you are welcome to arrange things however you want. You can attach parameters to actions directly, or put the parameters block before actions or whatever works best for you.

Another question about spell definitions: If a spell is given a class (like LevitateSpell), does it ignore all actions and effects defined in the YAML config? Or does it just add them onto whatever functionality the spell class has? If both can be used together it can solve quite a few problems (in particular the problem of action spells not being able to be "active").

No, the legacy spell classes do not support actions.

LevitateSpell is one of the few remaining legacy spells I still use, it's a horrible mish-mosh of functionality for flying, levitating, broom-riding, air scootering, etc. It's very possible it could be replaced with actions at this point (spawn entity, mount, apply velocity on repeat, etc).