Admin Instructions

OUTDATED

This page is no longer maintained, none of the pages here are. Please go to:

https://github.com/elBukkit/MagicPlugin/wiki

Installation

Magic requires CraftBukkit, just place Magic.jar into the plugins folder. This is all you need to do to experiment with spells, by default only ops can get wands (though anyone can cast any spells if they get ahold of a wand with spells!)

See these files for updated documentation on specific configuration parameters:

https://github.com/elBukkit/MagicPlugin/blob/master/CONFIGURATION.md https://github.com/elBukkit/MagicPlugin/blob/master/SPELLS.md https://github.com/elBukkit/MagicPlugin/blob/master/WANDS.md

Commands

The default permissions give several new commands to admins:

Wand Commands

/wand : Create a new, empty wand.
/wand <name> : Create a new wand from one of the preset wands defined in wands.yml
/wand list : List available wand templates from wands.yml
/wand add <spell> : Add a new spell to the currently held wand.
/wand fill : Fill a wand with all known (permissible) spells.
/wand remove <spell> : Remove a spell from the currently held wand.
/wand configure <property> <value> : Configure wand properties (see below)
/wand upgrade <property> <value> : Configure wand properties, but never lower any values (see below)
/wand combine <wand> : Add a wand template to an existing wand (upgrade it)
/wand add material <material> : Add a new material to the currently held wand.
/wand remove material <material> : Remove a material from the currently held wand.
/wand name <name> : Name a wand (note that you can also rename a wand on an anvil)
/wand describe : List all of a wand's properties, advanced, use with "configure"
/wand unlock : Unlock a locked wand to make it editable. ("/wand configure locked "true to lock)
/wand enchant : Create a wand out of the item you are holding
/wand unenchant : Unenchant (destroy) the wand you are holding.
/wand enchant <xp levels> : Add a number of XP levels to a wand, as if via enchanting - does not actually cost XP.
/wand enchant <xp> : Add all of your XP levels (consuming the XP) to your wand. Can be used in command blocks for a leveling system.
/wandp <player> <etc...> : Use /wand commands on a specific player.

Wand configuration parameters for "configure" and "upgrade":

https://github.com/elBukkit/MagicPlugin/blob/master/WANDS.md

The mgive Command

The /mgive command works a lot like the vanilla and Esssentials /give commands. It can be used to give any item to any player, including Magic items like wands, spells and upgrades. It can also be used to give XP to players, which currently may be needed as a work-around to wands blocking XP given by the /xp command.

/mgive [player] <item> [amount] : The general, flexible format of the command. The "item" is the only required parameter.
/mgive NathanWolf elder : Give NathanWolf an Elder Wand
/mgive fling 32 : Give yourself 32 "fling" spells. Spells will stack, and can be placed in chests or given to players.
/mgive NathanWolf xp 200 : Give NathanWolf 200 XP, which will work event if he is holding a wand.
/mgive NathanWolf gold_nugget 32 : Give NathanWolf 32 gold nuggets. Item format must follow Bukkit's Material enum.
/mgive spell:wolf : Give yourself the "wolf" spell. The "spell:", "wand:", and "upgrade:" prefixes can be used to differentiate between items with the same name.
/mgive book:engineering : The "book:<category>" item will create a "Spell Book" containing all the spells in that category, with lore and costs descriptions.
/mgive book:all : Give a "master" spellbook that contains all spells, organized by category.

Utility Commands

/magic load : Reload config files, update spell configurations.
/magic save : Force saving of player data. Also saves other data, like lost wands and image maps.
/magic commit : Commit all changes (like casting "Commit" on all players)
/magic cancel : Cancel all in-progress construction batches.
/magic list [wands | automata | maps | tasks] <player> : List all lost wands, maps or automata. The "tasks" parameter can be used to check for runaway tasks in any plugin.
/magic clean <player> : Clear unowned lost wands, or a specific player's lost wands.
/magic clean ALL : Clear all wands from all worlds.

/spells : Lists all spells that a player knows about. A player may view detailed information about any spells they have permission to cast. This command is safe to give to players, though it removes some of the mystery. Players can see the same information in-game about spells they have on their wands (via the lore tooltips).

The Cast Command

The /cast in-game command is very powerful. It lets you cast any spell directly, but (more importantly) it lets you use "command line parameters" to play around with the configurable spell system. Many spells in Magic are based on the same "building block" spell, using parameters. And, by tweaking those parameters yourself, you can create some interesting and powerful spells. A server admin can then make them "official" spells by adding them to spells.yml, so players can use the new spell on their wands.

As an example, the "boom", "kamikazee", "kaboom" and "nuke" spells are all variants of "BoomSpell", tweaking the "size" parameter (mainly). A "nuke" for instance is "size 20" - want to see what a 10x nuke would look like? Try /cast boom size 200 ... but be forewarned, it's not pretty!

Parameters to the cast command follow the same name and format as in spells.yml, and are passed in pairs - e.g. /cast <spell> <param> <value> <param> <value>. Browsing through the default spells.yml is the best way to get a feel for what your options are.

Detailed parameter documentation: https://github.com/elBukkit/MagicPlugin/blob/master/SPELLS.md

Customizing Magic

Magic is completely customizable. Plugin behavior, available spells and wands, and all in-game text can be customized.

If you don't need to customize a specific aspect of Magic, it helps to leave that file alone, this way you will get the benefit of easy upgrades as I frequently make changes to the default configurations.

I am making an attempt to have the default configuration be a well-balanced, fun experience. I'd like your help to make that happen- I am always willing to make changes to the defaults if it fits in with my overall vision for the plugin. But if you want something really different, feel free to go off on your own!

The default Magic experience entails:

Players have access to no Magic commands by default
Players may craft wands (with a blaze rod and nether star)
(Currently disabled by default): Players may find wands in naturally-spawned chests
Wands start out low-level, but can be upgraded with XP on an enchanting table
Wands can be combined on an anvil, bought in Essentials shops, and included in Essentials kits.
Naming a wand on an anvil binds it to the player, and no other player may wield it.
Admins can set up quests or other rewards to upgrade or create wands
Wands are indestructible. They will show up on dynmap (if installed) so players can find lost wands.
Each wand has an inventory of spells and materials that the player can use and manipulate.
Wands use a "mana" system for slowly-regenerating magic power.
All players have access to all spells, if they can find or create a wand that has them.

Any of the above may be disabled or modified. Some different options:

There are 3 different wand inventory modes to choose from: A chest inventory (the default), click-to-cycle, and a powerful hotbar-enabled inventory mode.
Permission-based wands, spells and commands (ranking, VIPs, etc)
Players keep wands on death (all players, or per-wand)
Wands come pre-filled with all spells the player has permission to use
Reagents instead of mana
Other item types for wands (enchanted swords, etc - maybe Bows + enchanted arrows one day)

In addition, the default spell and wand templates can be completely modified.

If you only wish to localize Magic, you can modify messages.yml and leave the rest alone. I'd love to add your localization to my resources section, if you'd share it!

Customizing Spells

Magic is a configurable system, set up to let admins create their own experience on their servers. It will create a default configuration (spells.defaults.yml) with a variety of spells. If you want to add, remove or create your own spells, edit the "spells.yml" template file that Magic generates, or replace it with your own.

Take a look at the spells.defaults.yml file that Magic generates at first run. It contains a list of spells, that players can use in-game, configured from building-block spells.

The default configuration files have detailed instructions on use, as well as descriptions of all available options.

All spells have a few common properties that you might want to tweak:

enabled - Set to "false" to completely remove an existing (default) spell.
cooldown - spells can only be cast so often (in seconds)
range - How far a spell can target (in blocks)
target_through - What a spell can target through (e.g. glass, water)
costs - A list of casting costs (items and amounts) consumed when the spell is cast
name, description, wand icon, etc - All editable in spells.yml

Detailed documentation:

https://github.com/elBukkit/MagicPlugin/blob/master/SPELLS.md

Permissions

By default, all players have access to the wand and all spells. This can be limited using the following permission nodes:

Magic.wand.use : Player can use a wand
Magic.commands.spells : Player can use /spells
Magic.commands.wand : Player can use /wand
Magic.commands.wand.wand.<wandname> : Player can use /wand to get a specific wand. All wands are available by default.
Magic.commands.wand.add : Player can use /wand add
Magic.commands.wand.add.spell.<spellname> : Player may add a specific spell to a wand. All spells are allowed by default.
Magic.commands.wand.add.material : Player may add a material to a wand. True by default.
Magic.commands.wand.remove : Player can use /wand remove
Magic.commands.wand.name : Player can use /wand name
Magic.commands.wand.list : Player can use /wand list
Magic.commands.wand.fill : Player can use /wand fill
Magic.commands.wand.configure : Player can use /wand configure
Magic.commands.wandp : Player can use /wandp
Magic.commands.wandp.wand.<wandname> : Player can use /wandp to give a specific wand. All wands are available by default.
Magic.commands.wandp.add : Player can use /wandp add
Magic.commands.wandp.add.spell.<spellname> : Player may add a specific spell to a wand remotely. All spells are allowed by default.
Magic.commands.wandp.add.material : Player may add a material to a wand remotely. True by default.
Magic.commands.wandp.remove : Player can use /wand remove
Magic.commands.wandp.name : Player can use /wand name
Magic.commands.wandp.list : Player can use /wand list
Magic.commands.wandp.fill : Player can use /wand fill
Magic.commands.wandp.configure : Player can use /wand configure
Magic.commands.cast : Player can use /cast
Magic.cast.<spellname> : Player can cast a specific spell
Magic.protected : A player is always protected, as if by a Protection X wand
Magic.powered : A player is superpowered and may bypass certain restrictions (like anti-pvp areas)

And also the following admin-oriented commands:

Magic.commands.magic.load : Reload spells.yml, wands.yml, config.yml and messages.yml. (And the defaults)
Magic.commands.magic.[save|clean|search|list| .. etc] : All commands follow the same pnode format.

Localization

All in-game text can be overridden with a messages.yml file. The defaults will be loaded first, so any entries missing in messages.yml will use the fall back messages.defaults.yml (English).

MagicWorlds

If you'd like to have your naturally-generated chests populated with wands (or much more!), check out the MagicWorlds plugin for Magic:

http://dev.bukkit.org/plugins/MagicWorlds/

Essentials Integration

Magic will integrate with Essentials if present, and if the config option "enable_essentials_signs" is set to true. This will allow buying wands via Essentials signs. Selling and trading do not work.

Simply use an item name of the format "wand: <wandname>", e.g. "wand: avatar" in a [Buy] or [Free] sign and Magic should pick it up.

CommandBook Integration

Magic will integrate with CommandBook, for using its warps with the Recall spell.

Dynmap Integration

Magic will integrate with Dynmap if present. There are config options to control behavior, by default Magic will do two things:

Update map tiles whenever magic is used to modify the world
Add wands as markers to the map (they are indestructible by default!)

WorldGuard Integration

Magic will integrate with WorldGuard if present. All attempts will be made to respect building and PVP restrictions.

Factions Integration

Magic will respect Factions claims for build permissions. Magic does not currently respect Factions PVP flags.

dtlTraders Integration

Magic integrates with dtlTraders for selling wands and other magic items

Citizens Integration

Magic will respect Citizens NPCs, and generally make them untargetable (Except for certain spells, like Camera)

Other Configuration

The config.yml file also has a few other global tweakable parameters, such as turning on/off cast messages or changing the way all spells function at a basic level. Magic generates a config.defaults.yml file.

Playing with Magic

In order to use magic, you will need a wand. An admin can create one using the /wand commands, it will appear as an enchanted stick named "Wand", and its lore tooltips will tell you how many spells it knows.

To get started quickly, use the following command:

/wand demo

This will give you the preset "demo" wand. This wand has three spells on it, blink, fling and torch.

When you equip a wand, you can cast its active spell by left-clicking. This may consume XP or reagents depending on the spell, wand, and server configuration.

If a wand is imbued with more than one spell, you can right-click while holding it to open and close its inventory. While the wand inventory is active, you can switch the active spell using the hotbar buttons. Spells are represented with their icons as defined in spell.yml, so you can drag them around as you would other items.

If you open your inventory screen (‘E’ Button, normally) while the wand’s inventory is active, you can re-arrange spells and magic materials, putting the ones you need in your hot bar.

Try casting and switching the three spells on the demo wand (casting costs are ignored with this wand!).

Casting Costs

Magic has a casting cost system built in. It is fully configurable, but the default config is set up to have most spells cost XP. Spells can also be configured to cost "reagents" (set amounts of specific items), though I don't necessarily recommend this approach for Magic anymore, it's not a great fit.

The player will see a message on-screen if they don't have the resources to cast, unless Magic is configured to not show messages in config.yml.

Wand Properties

Wands can be given specific properties:

XP Reneneration - When used with XP-based casting costs, can give a player a renewable MP supply. While it is generally kept to a minimum (e.g. under 5 levels) you should still be aware of the potential for anvil and enchanting table abuse.
Health / Hunger Regeneration - Gives the player back health or hunger over time
Protection - Various forms of protection can be given to a wand
# of Uses - Wands can be made temporary, such that they break after a certain number of uses. Wands cannot be repaired.

These properties only affect a player while they are holding a wand.

Properties can be configured in wands.yml, or via the “/wand configure <property> <value>” command. In both cases the available properties are:

cost_reduction
damage_reduction
damage_reduction_physical
damage_reduction_projectiles
damage_reduction_falling
damage_reduction_fire
damage_reduction_explosions
xp_regeneration
xp_max
health_regeneration
hunger_regeneration

The “reduction” values range from 0-1 (where 1 is fully reduced, so prevent all damage, make spells free, etc).

The “regeneration” values are in units per second. So if you want to gain back one health per second, set health_regeneration to 1.

Detailed parameter descriptions:

https://github.com/elBukkit/MagicPlugin/blob/master/WANDS.md

Construction Spells

Magic has a lot of spells that focus on construction- a lot of things you might normally do with WorldEdit, for instance, you could do with "spells" - and there are also a lot of "fun" construction-oriented spells.

The "engineer" wand (/wand engineer) has a good selection of construction spells, and also comes with a few basic materials so you can try out the material system.

Materials

Spells can be configured to work with a specific material (e.g. create "midas touch" type spells), but by default they work with the targeted material. So if you cast pillar on dirt, it will create a pillar of dirt.

Wands can be also imbued with materials, and the player can then use the material selection system to construct with specific materials. Materials will appear in a wand’s inventory along with spell icons, and can be selected in the same way.

Spells that use a material will display the active material in the wand’s tooltip.

There are two special cases in the material system:

Copy (Melon Seeds) : Means use the targeted material. This is also the default behavior if no material is assigned to a wand.
Erase (Sulphur) : A sulphur icon actually represents "air" - it is a special material representation for turning any construction spell into a destruction (erase) spell.

These two special materials can only be given to a wand via admin commands (/wand add material {copy|erase}). Other materials may be added to a wand by a player if they have the absorb spell.

Undo

The undo spell is an undo for any construction spells. It does a pretty good job, but it is limited- keep in mind it will not undo chest or sign contents, that sort of thing- it's not meant to replace world backups or a good WorldProtect type of system. Magic is very dangerous so please take care when installing it on your server!

The commit spell can be used to prevent accidentally undoing some construction. Once cast, your undo queue is cleared and your actions are made permanent. (This does not include auto-undo spells like breach and peek)

Spell Parameters

This list is incomplete, and it's always easier to play around with "/cast" rather than edit spells.yml and reload.