Actions

Action System

Magic has a flexible "action" system that lets you build your own spells, using the individual behaviors that the default spells employ.

Most spells in Magic are made up of "actions", rather than having a custom class for each spell.

Magic's action system intelligently load-balances given the number of mages actively casting spells. Magic will try to ensure that spells don't lag the server by modifying too many blocks or entities in a single tick.

This means that any spell has the potential to get "batched" for delayed processing. This is not strictly speaking "asynchronous", but it is the same general idea. If a spell requires too much "work" to complete in a single tick, it will spread out over multiple ticks.

Create your own spells

The action system lets you build your own spells for some really cool custom behavior! Take a look through the default spells file to get a feel for what's possible. In particular, there are a few spells (laser, singularity, magichat) that are documented pretty well, I'm hoping to do better with that in the future.

Built in Actions

I will attempt to maintain a list here of all the built in actions and how to use them. All builtin spell actions can be found in the source code, in case I miss any here. Note that "Action" part at the end of the class name can be omitted.

I will also try to add available parameters here, for now you can get a feeling for what's possible by looking in the defaults, or by using /cast with the in-game tab completion.

Common Spell Properties and Parameters All action-based spells share some common behavior and parameters, check here first.

Absorb Absorb a material onto a player's wand as a brush.

AddSpell Add a specific spell to a player's wand. Meant for use in NPC traits.

AllEntities Target all entities in a world.

AreaOfEffect Target all (or some) entities within a specific radius.

Ascend Teleport upward to the first safe location.

BlockSearch Find a Block in a specific direction from the current Block.

Brush Change the active brush.

BrushSelect Bring up the brush selection GUI, for engineering spell brushes.

Burn Light the target block on fire.

ChangeContext Modify the current spell context. This can be used to move the target location or direction, or to target the source, or a few other things.

ChangeWorld Move the target Entity to another World, preserving its location.

Command Run a command. May be run as the player, as the console, or as the player temp-op'd.

ConeOfEffect Target all (or some) entities within a specific Field of View in the target direction.

Count Count the number of entities targeted. Useful for debugging, or in the Entity Counter utility spell.

Cover Find the first solid block underneath the target. Often used with Disc to cover a surface (Frost, Fire)

Cure Remove all negative potion effects from an Entity.

CustomProjectile A highly customizable targeting action that behaves like a projectile.

Damage Apply damage to an Entity.

Deactivate Deactivate the target Mage, turning off any active spells (such as Levitate).

Delay Delay a specific amount of time before performing the following actions.

Descend Teleport downward to the first safe location.

DisablePhysics Temporarily disable vanilla physics. This can be used to prevent water and lava from flowing. This is currently a pretty hacky action, as physics is globally disabled while it is active- so use this sparingly!

Disc Create a circular disc, run a set of actions at each block.

EnchantWand Apply a number of XP levels to a player's wand, as if they had enchanted it. Generally for use in an NPC trait with a long (multiple hours) cooldown.

Explosion Create a vanilla explosion.

FallProtection Protect a player from fall damage for a period of time.

Feed Fill a Player's food level.

FillWand Fills a player's wand with all the spells they have permission to use. Generally for use on a rank/permission-based server with an NPC trait

Firework Launch a firework, or detonate a firework at a specific location.

Flower Grow flowers.

Freeze Create snow on the ground, pile up snow, freeze lava and water.

Hat Cause an Entity to wear a Block on its head.

Heal Heal the target Entity.

Ignite Light the target Entity on fire.

ItemShop Used by item shops, generally for NPC traits.

Kill Kill an Entity (applies 100x max health damage, bypassing PVP checks)

Lightning Spawn lightning.

Line Create a line along a certain direction, run a set of actions at each block.

Message Send the player a chat message.

ModifyBlock Modify a block- change its type, or turn it into a FallingBlock.

ModifyBreakable Set a Block to be breakable (spells will destroy it). This state is meant to be temporary and will not survive a server restart.

ModifyReflective Set a Block to be reflective (spells reflect off of it). This state is meant to be temporary and will not survive a server restart.

Mount Cause one Entity to mount another.

MoveBlock Moves a Block from one location to another.

Orient Change an Entity's facing direction.

Parallel Run the given set of actions in parallel- available work will be divided up amongst actions. This is useful for having multiple overlapping continuous effects (like Earthquake)

Plane Create a rectangular plane, run a set of actions at each block.

PlayEffects Play a set of effects using the builtin Effect system.

PlayRecord Play some music at a location.

PlayerSelect Show an online Player selection GUI, run a set of actions on selected Player.

PotionEffect Apply or remove potion effects on a target Entity.

Probability Randomly choose whether or not to perform a set of actions.

Projectile Throw a projectile. Actions can be run on projectile hit.

Random Randomly select one from a set of actions.

Recall Show the Recall GUI.

Repeat Repeat a set of actions a certain number of times.

Retarget Re-run targeting. Spells target at the beginning of the cast, but if you have a repeating effect that needs to re-target, you can use this action.

Serial Perform a set of actions serially (in order). This isn't needed much, excepting with the Random action or other cases where you need to make one action that simply performs several other actions.

Skip Skip a set of actions a certain number of times. Can be used with a Delay to provide an intermittent delay.

SpawnEntity Spawn an Entity.

SpellProgress Used to check on spell upgrade progress, generally for NPC traits.

SpellShop Used to create spell shops, generally for NPC traits.

Sphere Creates a spherical volume, running a set of actions for each Block.

Spread Spread out locations or directions randomly.

TNT Throw a PrimedTNT entity. Can run actions on explode.

Teleport Teleport to a specific location.

ThrowBlock Throw a FallingBlock as a projectile. Can run actions when the Block lands.

ThrowItem Throw an Item as a projectile. Can run actions when the item despawns.

Time Change the world time.

Torch Place a torch at the target location.

Tree Create a tree using the vanilla worldgen code (not undoable!)

Undo Undo the target block modification or spell.

Velocity Apply velocity to an Entity.

Volume Creates a rectangular volume, running a set of actions for each Block.

Weather Changes the weather.

Create your own actions

If you can't seem to get the effect you want, and have a bit of Java/Bukkit experience, it's pretty each to code up some new SpellAction classes. This is now the preferred method to extend Magic, rather than creating a new Spell class.

This will let you mix your custom actions in with the builtin actions!

All you need to do is to implement the SpellAction interface found in MagicAPI. Alternately, you can extend BaseSpellAction in MagicLib, which takes care of some of the boilerplate cod for you.

Action anatomy

Actions have a few important methods that get called at certain times. It is important, especially for performance, to know what to do and when.

initialize

This method is called whenever a spell is loaded for the first time. It is only called once per player per server session, and is given the action's parameters. Spells rarely use this, though in cases where you have a big list of things in your parameters or spell config it may be more efficient to pre-parse it here.

Any parameters read inside of initialize() cannot be overridden by /cast or /wand override.

prepare

This is called at the beginning of a spell cast, giving the action the current CastContext and parameters. This is generally when you'll want to read your parameters into class variables.

reset

This is called at the beginning of one "iteration" of a spell cast. This is generally only used by CompoundAction classes, to reset their counter to the beginning of their action list. It is rare you'll need to override this.

perform

This is the main body of your action, where you will do your work. This may be called many, many times during a spell cast, so try and keep things efficient.

finish

This is called for each action after the entire spell cast is complete, and is a good place to perform and cleanup or final actions.

Cast Context and Parameters

Most spells only need to override "prepare" and "perform". The "prepare" method is passed a ConfigurationSection, which can be used to read in the action's parameters.

Both "prepare" and "perform" are passed a CastContext object. This object is how you interact with all of the core Magic functionality- such as the undo system. Methods are constantly added to CastContext as needed by the builtin actions, so there is quite a bit there you can make use of.