Customization - elBukkit/MagicPlugin Wiki

Customizing Magic

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

In-Game Editing

See In-Game Customization, you can make most types of edits in-game using commands or via a web editor.

Common Problems

My edits are not working!

Please read the files you're editing. There are comments at the top of the files that explain how things work.

Most importantly, don't edit the files in plugins/Magic/defaults.

Those are there for reference, and will be overwritten on restart. They represent the current set of configs, including defaults and your edits.

Your edits go in plugins/Magic, if that's confusing please keep reading.

Default Survival Configs

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:

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

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!

Plugin Folder Layout

There will be several files and folders created in plugins/Magic on first run.

The rest of the folders correspond to your configs. You can make customizations in any of the YML files in plugins/Magic, or in individual files placed in folders.

Simple Customizations

See the default configs file for some examples of things admins commonly want to change. The config defaults list all of the default settings, with explanations of each.

There is also an example spells.yml file were you can look at some of the common simple spell customizations you can make.

Customizing Crafting Recipes

You can edit crafting.yml to modify, remove or add crafting recipes. Do not edit crafting.defaults.yml, it is only there for reference and your changes will be overwritten.

To disable a builtin recipe, add some lines like this to the file:

battle:
  enabled: false

Reference survival crafting recipes to see all of the recipes that are included by default.

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.

Do not edit spells.defaults.yml, it is only there for reference and your changes will be overwritten.

Similar to spell customization, disabling a spell is simple. Add this to spells.yml to disable the blast spell:

blast:
  enabled: false

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

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:

Detailed documentation:

[[Custom Spells]]

Action System

New in 4.0, spells are now transitioning to use an action-based system. You can identify "action" spells because they have an "actions" list in their configs, and no "class". For example:

disintegrate:
    icon_url: http://i.imgur.com/zZKzDFS.png
    icon: bone
    category: combat
    pvp_restricted: true
    worth: 2500
    actions:
        cast:
        - class: Damage
        - class: ModifyBlock
    # ... effects and parameters omitted for brevity

Action spells don't necessarily have any custom code- they are constructed from basic "Lego" blocks of behavior that I call "actions".

You can see in Disintegrate, it will either do damage to entities or modify (erase) a block.

For more information, see the Action System documentation.

Adding Custom Wands

You can add new wands to wands.yml, or create a wand in-game and save it with the "/wand save" command.

See the default configs for examples of the builtin wands. It is recommended to inherit from the "base_wand" template if you want the item to function like a wand (has a spell inventory, casts on left-click, etc) but this is not necessary.

Here is an annotated example taken from the war configs:

# This is a base template, it is not an actual item you would use in-game, but rather a set
# of common properties that you might want to use for multiple items.
base_gun:
  # This template is hidden since we don't want to use it directly. It will not show up in tab-completion
  # or in any lists of wands
  hidden: true
  # In this case, for guns, we want to cast on right-click, not left-click
  right_click: cast
  # Left-click will alt-cast, which for guns is the reload spell
  left_click: alt_cast
  # If using custom icons, a wand must always be indestructible. This is because the damage value is
  # used to differentiate between icons.
  indestructible: true
  # This makes spell casts originate from a specific location relative to the player's eyes. In this case
  # we position them to come roughly out of the barrel of the weapon.
  cast_location: 0.5,-0.4,0.5
  # This prevents the vanilla mechanic that makes the items come up very slowly
  attributes:
    GENERIC_ATTACK_SPEED: 10

# This is an actual gun we will use in-game.
ak47:
  # Inherit from the base_gun template above, meaning we will use all of the properties that are set there.
  inherit: base_gun
  # This is the icon used. If adding your own items you will also need to add new items to the resource pack,
  # which is a bit complex and not covered here.
  icon: diamond_pickaxe:1
  # Each gun has only two spells- one that is cast on right-click
  active_spell: ak47
  # And one cast on left-click, to reload. There is no spell inventory
  alternate_spell: reload_ak47
  # Mana for guns represents ammo. It does not regenerate, the reload spell refills it.
  mana: 70
  mana_max: 70

The most important thing that differentiates a wand from a normal item is the ability to cast spells (run a set of actions, basically, doesn't have to be magical) and attach other mechanics to various clicks. In total wands can perform actions on any of the following:

The actions that can be bound to these keys

Detailed documentation:

[[Custom Wands]]

Customizing Progression

The default Magic configurations use a progression system that can be customized.

The basics of progression in Magic are:

  1. Players craft a wand, which starts at the "beginner" rank.
  2. Players earn Spell Points by casting spells.
  3. Players interact with an enchantment table to show the spell shop.
  4. The spell shop shows the player spells available to the beginner rank.
  5. Players purchase spells from the spell shop by spending Spell Points.
  6. For each spell purchased, a wand may gain mana, protection or other attributes.
  7. Once a player collects all of the beginner spells, they rank up to student.
  8. Ranking up may give the player a mana boost, change their wand icon, or have other effects.
  9. Now the player will see student spells in the spellshop.

Detailed documentation:

[[Custom Paths]]

Custom Icons

For information on how to set up your own custom spell and wand icons, see Custom Icons.