com.elmakers.mine.bukkit.api.magic

Interface MagicAPI

public interface MagicAPI

This is the primary entry point into the Magic API.

A Plugin should generally check for the "Magic" plugin, and then cast that Plugin to MagicAPI to interact with it.

Method Summary

Modifier and Type	Method and Description
boolean	cast(String spellName, org.bukkit.configuration.ConfigurationSection parameters, org.bukkit.command.CommandSender sender, org.bukkit.entity.Entity entity)
boolean	cast(String spellName, String[] parameters) Cast a specific Spell, with optional parameters.
boolean	cast(String spellName, String[] parameters, org.bukkit.command.CommandSender sender, org.bukkit.entity.Entity entity) Cast a specific Spell, with optional parameters, using a specific CommandSender and/or Player.
void	clearCache() Clear all image and schematic caches
boolean	commit() Commit and clear all loaded undo queues
org.bukkit.inventory.ItemStack	createBrushItem(String brushKey) Create an ItemStack that represents a Material Brush.
org.bukkit.inventory.ItemStack	createGenericItem(String magicItemKey) Create a generic version of an item with no extra data.
org.bukkit.inventory.ItemStack	createItem(String magicItemKey) Create a new Magic item.
org.bukkit.inventory.ItemStack	createItem(String magicItemKey, Mage mage)
org.bukkit.inventory.ItemStack	createSpellItem(String spellKey) Create an ItemStack that represents a Spell.
Wand	createUpgrade(String wandKey) Create an upgrade Wand item from a template.
Wand	createWand(org.bukkit.inventory.ItemStack item) Turn the given ItemStack into a wand
Wand	createWand(org.bukkit.Material iconMaterial, short iconData) Create a new Wand instance out of a given Material type.
Wand	createWand(String wandKey) Create a new Wand from a template.
String	describeItem(org.bukkit.inventory.ItemStack item) Return a string description of an item.
Collection<Mage>	getAutomata() Get a list of all known Automaton records.
String	getBrush(org.bukkit.inventory.ItemStack item) Get the key of the material brush represented by an item.
Collection<String>	getBrushes() Get a list of all valid Material Brush names.
MageController	getController() Get the MageController.
String	getItemKey(org.bukkit.inventory.ItemStack item) Return the key name of an item, so it can be re-created with createItem.
Logger	getLogger() Retrieve the Logger for this API instance.
Collection<LostWand>	getLostWands() Return a list of all known LostWand records.
Mage	getMage(org.bukkit.command.CommandSender sender) Deprecated.
Mage	getMage(org.bukkit.entity.Entity entity, org.bukkit.command.CommandSender sender) Deprecated.
Collection<Mage>	getMages() Deprecated.
Collection<Mage>	getMagesWithPendingBatches() Get all currently loaded Mage instances that have pending construction batches.
Messages	getMessages() Return the Messages controller, which manages Magic's localization store.
Collection<UndoList>	getPendingUndo()
Collection<String>	getPlayerNames() A utility method to get the names of all currently logged-in Players.
org.bukkit.plugin.Plugin	getPlugin() Retrieve the Bukkit Plugin for Magic
Collection<String>	getSchematicNames() Get a list of all known schematics.
String	getSpell(org.bukkit.inventory.ItemStack item) Get the key of the Spell or SpellTemplate represented by an item.
org.bukkit.inventory.ItemStack	getSpellBook(SpellCategory category, int count) Returns a written book item describing all of the spells in a given category.
SpellTemplate	getSpellTemplate(String key) Retrieve a specific SpellTemplate.
Collection<SpellTemplate>	getSpellTemplates() Get a list of all currently loaded SpellTemplate records, as defined in spells.defaults.yml and spells.yml
Collection<SpellTemplate>	getSpellTemplates(boolean showHidden)
Wand	getWand(org.bukkit.inventory.ItemStack item) Load a Wand instance of an ItemStack.
Collection<String>	getWandKeys() Retrieve the keys for all wand templates.
void	giveExperienceToPlayer(org.bukkit.entity.Player player, int xp) Give experience to a player, in a way that is safe for wands.
void	giveItemToPlayer(org.bukkit.entity.Player player, org.bukkit.inventory.ItemStack itemStack) A utility method for giving an item to a player.
boolean	hasItem(org.bukkit.entity.Player player, org.bukkit.inventory.ItemStack item) Check to see if a player has a specific item.
boolean	hasPermission(org.bukkit.command.CommandSender sender, String pNode) Check to see if a CommandSender has permission.
boolean	hasPermission(org.bukkit.command.CommandSender sender, String pNode, boolean defaultPermission) Deprecated.
boolean	isBrush(org.bukkit.inventory.ItemStack item) Check to see if an existing item is a material brush item.
boolean	isSpell(org.bukkit.inventory.ItemStack item) Check to see if an existing item is a spell item.
boolean	isUpgrade(org.bukkit.inventory.ItemStack item) Check to see if an existing item is a wand upgrade.
boolean	isWand(org.bukkit.inventory.ItemStack item) Check to see if an existing item is a Wand.
void	reload() Reload all Magic configurations.
void	reload(org.bukkit.command.CommandSender sender) Reload all Magic configurations, report success/fail to sender
void	removeLostWand(String id) Forget a specific LostWand.
void	save() Save all Magic data.
boolean	takeItem(org.bukkit.entity.Player player, org.bukkit.inventory.ItemStack item) Check to see if a player has a specific item, and remove it from the player's inventory.

Method Detail

getPlugin

org.bukkit.plugin.Plugin getPlugin()

Retrieve the Bukkit Plugin for Magic

Returns:

The Magic Plugin instance, likely "this"

getLogger

Logger getLogger()

Retrieve the Logger for this API instance.

Returns:

The logger being used by the API provider (usually MagicPlugin).

hasPermission

boolean hasPermission(org.bukkit.command.CommandSender sender,
                      String pNode)

Check to see if a CommandSender has permission.

This extends Bukkit's permission checks to account for special Magic bypass flags and Automata behavior.

Parameters:

sender - The CommandSender, may also be a Player or null.

pNode - The permission node to check

Returns:

True if the CommandSender has the requested permission

hasPermission

@Deprecated
boolean hasPermission(org.bukkit.command.CommandSender sender,
                                  String pNode,
                                  boolean defaultPermission)

Deprecated.

Check for permission, but include a default permission. This is generally used to do permission checks against something you can't specify in the defaults (such as a dynamically generated list), but would like permission to be enabled by default.

This is used, for instance, in Magic's list of wands and spells- players have access to all spells by default, unless a -Magic.cast.spellname pnode is added.

Parameters:

sender - The CommandSender, may also be a Player or null.

pNode - The permission node to check

defaultPermission - set to true to enable permission by default

Returns:

True if the sender has permission

save

void save()

Save all Magic data.

reload

void reload()

Reload all Magic configurations.

reload

void reload(org.bukkit.command.CommandSender sender)

Reload all Magic configurations, report success/fail to sender

clearCache

void clearCache()

Clear all image and schematic caches

commit

boolean commit()

Commit and clear all loaded undo queues

Returns:

True if anything was committed

getMages

@Deprecated
Collection<Mage> getMages()

Deprecated.

Get all currently loaded Mage instances.

These may be players or Automata (command blocks)

Returns:

The list of all currently active mages.

getMagesWithPendingBatches

Collection<Mage> getMagesWithPendingBatches()

Get all currently loaded Mage instances that have pending construction batches.

These may be players or Automata (command blocks)

Returns:

The list of Mages that have pending constructions in progress.

getPendingUndo

Collection<UndoList> getPendingUndo()

getMage

@Deprecated
Mage getMage(org.bukkit.command.CommandSender sender)

Deprecated.

Retrieve or create a Mage for a particular CommandSender.

There is one Mage for the Console sender, one Mage for each Player, and one Mage for each named Command Block.

Each Mage is persistent and singular- two command blocks with the same name, if loaded at the same time, will use the same Mage. This may cause conflicts with cooldowns or other persistent Spell data.

Parameters:

sender - the CommandSender (Player, Command block, etc) to turn into a Mage

Returns:

Mage instance, new, created or loaded.

getMage

@Deprecated
Mage getMage(org.bukkit.entity.Entity entity,
                         org.bukkit.command.CommandSender sender)

Deprecated.

Retrieve or create a Mage for a particular Entity.

Every Entity should use its own Mage for casting spells. Entity Mages are tracked by UUID, and their data is saved and restored as normal.

Parameters:

entity - the Entity to turn into a Mage

sender - the CommandSender to use, optional

Returns:

Mage instance, new, created or loaded.

giveItemToPlayer

void giveItemToPlayer(org.bukkit.entity.Player player,
                      org.bukkit.inventory.ItemStack itemStack)

A utility method for giving an item to a player. This will place the item in the player's hand if it is empty, else in the player's inventory. If there is no room, the item will drop on the ground.

If the item is a Wand, and it goes into the player's hand, it will be activated. Make sure to use this method, or else make sure to deal with activating wands as the player gets them.

Parameters:

player - The Player to give an item to

itemStack - The ItemStack to giev the player, may be a Wand.

giveExperienceToPlayer

void giveExperienceToPlayer(org.bukkit.entity.Player player,
                            int xp)

Give experience to a player, in a way that is safe for wands.

This method may get removed in the future if Wands can be smarter about XP being added externally.

Parameters:

player - The Player to give XP

xp - The amount of XP to give

getPlayerNames

Collection<String> getPlayerNames()

A utility method to get the names of all currently logged-in Players.

Useful for tab-completion.

Returns:

The names of all logged-in players.

getWandKeys

Collection<String> getWandKeys()

Retrieve the keys for all wand templates. These can be used with createWand to create a new Wand from a template.

Returns:

A list of all known wand template keys.

createItem

@Nullable
org.bukkit.inventory.ItemStack createItem(String magicItemKey)

Create a new Magic item. This could be a wand, spell, upgrade or brush.

Parameters:

magicItemKey - The template key, may be a wand, spell, etc.

Returns:

An ItemStack representing the magic item.

createItem

@Nullable
org.bukkit.inventory.ItemStack createItem(String magicItemKey,
                                                    Mage mage)

createGenericItem

@Nullable
org.bukkit.inventory.ItemStack createGenericItem(String magicItemKey)

Create a generic version of an item with no extra data.

Parameters:

magicItemKey - The template key, may be a wand, spell, etc.

Returns:

The specified item.

getItemKey

String getItemKey(org.bukkit.inventory.ItemStack item)

Return the key name of an item, so it can be re-created with createItem.

describeItem

@Nonnull
String describeItem(org.bukkit.inventory.ItemStack item)

Return a string description of an item.

This will use the display name if set, then Vault if present, then falling back to the Material name.

Parameters:

item - The item stack.

Returns:

A description of this item

hasItem

boolean hasItem(org.bukkit.entity.Player player,
                org.bukkit.inventory.ItemStack item)

Check to see if a player has a specific item.

takeItem

boolean takeItem(org.bukkit.entity.Player player,
                 org.bukkit.inventory.ItemStack item)

Check to see if a player has a specific item, and remove it from the player's inventory.

createWand

Wand createWand(String wandKey)

Create a new Wand from a template.

Once created, a Wand is a unique item. It "remembers" which template it was created from, but this is currently not used for anything.

Parameters:

wandKey - The template key, or blank for a default wand.

Returns:

A new Wand instance, with a useable ItemStack.

createWand

@Nullable
Wand createWand(org.bukkit.inventory.ItemStack item)

Turn the given ItemStack into a wand

Parameters:

item - The item to use as the wand's icon.

Returns:

The wand instance, or null on error.

createWand

Wand createWand(org.bukkit.Material iconMaterial,
                short iconData)

Create a new Wand instance out of a given Material type.

This will create a new ItemStack to represent the Wand.

Parameters:

iconMaterial - The type of Material to use as the Wand icon.

iconData - Data used for durability or icon variants.

Returns:

A newly-created Wand.

createUpgrade

Wand createUpgrade(String wandKey)

Create an upgrade Wand item from a template.

This can be used to create upgrade items from wand templates that are not originally meant to be upgrades.

Parameters:

wandKey - The template key

Returns:

A new Wand instance, converted to an upgrade if necessary.

getWand

Wand getWand(org.bukkit.inventory.ItemStack item)

Load a Wand instance of an ItemStack. Will return null if the given ItemStack does not have Wand NMS data.

Parameters:

item - The item to load Wand data from.

Returns:

The wand instance, or null on error.

isWand

boolean isWand(org.bukkit.inventory.ItemStack item)

Check to see if an existing item is a Wand. This will inspect the item's NBT data.

Parameters:

item - The ItemStack to inspect.

Returns:

true if the item is a Wand, in which case getWand can be used.

isUpgrade

boolean isUpgrade(org.bukkit.inventory.ItemStack item)

Check to see if an existing item is a wand upgrade. This will inspect the item's NBT data.

Parameters:

item - The ItemStack to inspect.

Returns:

true if the item is a wand upgrade, in which case getWand can be used.

isSpell

boolean isSpell(org.bukkit.inventory.ItemStack item)

Check to see if an existing item is a spell item. This will inspect the item's NBT data.

Parameters:

item - The ItemStack to inspect.

Returns:

true if the item is a spell, in which case getSpell can be used.

isBrush

boolean isBrush(org.bukkit.inventory.ItemStack item)

Check to see if an existing item is a material brush item. This will inspect the item's NBT data.

Parameters:

item - The ItemStack to inspect.

Returns:

true if the item is a wand upgrade, in which case getBrush can be used.

getSpell

@Nullable
String getSpell(org.bukkit.inventory.ItemStack item)

Get the key of the Spell or SpellTemplate represented by an item.

Parameters:

item - The item to inspect

Returns:

The key of the Spell represented by this item.

getBrush

@Nullable
String getBrush(org.bukkit.inventory.ItemStack item)

Get the key of the material brush represented by an item.

Parameters:

item - The item to inspect

Returns:

The key of the material brush represented by this item.

createSpellItem

org.bukkit.inventory.ItemStack createSpellItem(String spellKey)

Create an ItemStack that represents a Spell.

This item will be absorbed by a Wand on activate, adding that Spell to the Wand, if the Wand finds this item in a Player's inventory.

Parameters:

spellKey - The Spell to create an item for.

Returns:

A new ItemStack, or null on error.

createBrushItem

@Nullable
org.bukkit.inventory.ItemStack createBrushItem(String brushKey)

Create an ItemStack that represents a Material Brush.

This item will be absorbed by a Wand on activate, adding that brush to the Wand, if the Wand finds this item in a Player's inventory.

Parameters:

brushKey - The Material brush to create an item for.

Returns:

A new ItemStack, or null on error.

getLostWands

Collection<LostWand> getLostWands()

Return a list of all known LostWand records.

Returns:

A list of all known LostWand data.

removeLostWand

void removeLostWand(String id)

Forget a specific LostWand.

The ItemStack will not be removed if it still exists, and a new LostWand record may get created if the ItemStack is found again by the Chunk scanner.

Parameters:

id - The id of the LostWand to forget.

getAutomata

Collection<Mage> getAutomata()

Get a list of all known Automaton records.

Returns:

The list of currently known Automaton blocks.

cast

boolean cast(String spellName,
             String[] parameters)

Cast a specific Spell, with optional parameters.

The parameters are generally in alternating key/value format, such as {"radius", "32", "range", "64"}

This Spell will be cast using the COMMAND Mage.

Parameters:

spellName - The key name of the Spell to cast

parameters - A list of parameters, as if cast from the command-line.

Returns:

true if the spell succeeds, else false

cast

boolean cast(String spellName,
             String[] parameters,
             org.bukkit.command.CommandSender sender,
             org.bukkit.entity.Entity entity)

Cast a specific Spell, with optional parameters, using a specific CommandSender and/or Player.

The parameters are generally in alternating key/value format, such as {"radius", "32", "range", "64"}

The CommandSender and Player may differ, in which case both will be notified of Spell results.

Parameters:

spellName - The key name of the Spell to cast

parameters - A list of parameters, as if cast from the command-line.

sender - The CommandSender that originated this Spell

entity - The Entity this Spell is cast on behalf of, may be Player or differ from sender

Returns:

true if the spell succeeds, else false

cast

boolean cast(String spellName,
             org.bukkit.configuration.ConfigurationSection parameters,
             org.bukkit.command.CommandSender sender,
             org.bukkit.entity.Entity entity)

getSpellTemplates

Collection<SpellTemplate> getSpellTemplates()

Get a list of all currently loaded SpellTemplate records, as defined in spells.defaults.yml and spells.yml

A Spell is created for a Mage from a SpellTemplate.

Returns:

A list of all known SpellTemplate definitions.

getSpellTemplates

Collection<SpellTemplate> getSpellTemplates(boolean showHidden)

getSpellTemplate

@Nullable
SpellTemplate getSpellTemplate(String key)

Retrieve a specific SpellTemplate.

Parameters:

key - The key of the SpellTemplate to look up.

Returns:

The requested SpellTemplate, or null on failure.

getBrushes

Collection<String> getBrushes()

Get a list of all valid Material Brush names.

This will include all Block Materials, as well as special brushes (copy, clone, erase, replicate, map) and any known schematic brushes.

Returns:

A list of all valid brush keys.

getSchematicNames

Collection<String> getSchematicNames()

Get a list of all known schematics.

These will be loaded from Magic's built-in schematic collection, or from an external source (e.g. WorldEdit).

The list may be empty if schematics are disabled.

These are the raw schematic names, and do not have the "schematic:" prefix or ".schematic" extension.

Returns:

The list of known schematic names.

getController

MageController getController()

Get the MageController.

The controller is used for more advanced plugin interaction, and is used heavily by Spells themselves to interact with the Magic plugin's internal functionality.

Returns:

The current MageController, there is only one.

getSpellBook

org.bukkit.inventory.ItemStack getSpellBook(SpellCategory category,
                                            int count)

Returns a written book item describing all of the spells in a given category.

Parameters:

category - The category to look up

count - How many to give (max 1 stack)

Returns:

An ItemStack spell book

getMessages

Messages getMessages()

Return the Messages controller, which manages Magic's localization store.