查看“Magic/Custom Spells”的源代码

== 插件自定义法术 ==

Magic的法术可以非常复杂，从零开始可能很困难,所以如果默认的内部法术里面有类似于你心中理想的法术，可以试试在此基础上修改修改

Magic的法术类似于脚本事件，可以包含十分复杂的规则、行为和逻辑，借此制作高度自由化的视觉以及游戏体验

== 工具和参考 ==

在阅读了以下教程后，有些网页工具就显得非常有用了:
* [http://reference.elmakers.com/ 参考指南] 深入所有细节，列出了所有参数、行为、效果以及其他本指南中提到的 [http://mine.elmakers.com/legacy/reference/ Legacy version] 1.13-版本专用
* [http://mine.elmakers.com/#spells 默认生存服法术列表] 查看更高级的内置生存服技能的相关信息，并且把游戏中的关键词转化为相应内容以查到正确的配置

== 教学 ==

本教程将由魔法导弹技能开始学习，逐步拨云见日地了解它的组成

== 分析法术 ==

多数法术有五个主要部分，我们每次讨论一个：

* '''Base Properties''': 基础的法术设置，比如图标、SP消耗和SP获取量，以及一些法杖升级或使用/cast parameters无法更改的内容
* '''Actions''': 完善的法术使用Modern spells use the [[Magic/Actions|行为系统]], 可以让你灵活地自定义法术的行为，实现你所想的效果
* '''Effects''': 有多种施法时产生的视觉效果，一般由施法多个过程触发
* '''Parameters''': 行为需要参数来改变它们的视觉效果。参数可以作为进阶法术、法杖或使用/cast parameters时的必备部分，更加直接和方便地测试法术的效果。译者注：参数包含如技能伤害、范围、时效等内容
* '''Costs''': 法术需要一些消耗才能释放，大多数情况消耗法力，当然物品、金钱和生命值也是可以作为消耗的

== 基础配置 ==

拿Magic Missile【魔法导弹】技能举例, [https://github.com/elBukkit/MagicPlugin/blob/master/Magic/src/main/resources/defaults/spells/missile.yml 它的配置文件在这].

<pre class="">missile:</pre>
这是技能的 &quot关键&quot; 名。当使用/cast命令或/wand命令时，显示的技能名就是这个，支持非英文

<pre class="">    icon: diamond_axe:160
    icon_disabled: diamond_hoe:160
    icon_url: http://textures.minecraft.net/texture/2ba95570c7b712713632d4c0d2fc66906613d3850a596a0267c6d763fe741ac</pre>
上述三个分别是：图标、不可用图标（如缺少法力、冷却未到）、图标URL。技能的图标，表现为在游戏中它显示成什么，通常在法杖、商店中作为物品时显示为这里设置的图标

Magic可以使用资源包里的图标(默认技能使用的图标就是),当然原版物品、玩家头颅也可以。如果config.yml的 &quoturl_icons_enabled&quot;设置为true，技能将会使用'''icon_url''' 以通过自定义材质创建玩家头颅作为图标。

如果不这样设置,那么技能将会采用'''icon'''属性中的内容作为图标。当一个技能暂不可用时 (法力不足、处于冷却、没有权限) ，则会采用 '''icon_disabled''' 属性中的内容作为图标 (头颅图标不支持icon_disabled)。 

在官方提供的资源包中，每一个技能的不可用图标会和正常图标相同，但是会多一个红色的 &quot;no&quot; 标志覆盖在上面

<pre class="">    upgrade_required_path: beginner
    upgrade_required_casts: 40</pre>
法术是可以进阶的，进阶法术可通过间隔符号&quot;|&quot;定义,这样的话 &quot;missile|2&quot;就代表着第二级别的 Magic Missile【魔法导弹】 Level 2。

法术的继承是根据上一级来的，这意味着未覆盖的设置将继承上一级的设置（比如二级技能只是参数里面的伤害和一级不一样，只写了damage的参数，其余继承一级技能的所有设置）

举例说明，请查阅[https://github.com/elBukkit/MagicPlugin/blob/master/Magic/src/main/resources/examples/survival/spells/missile.yml#L108 Magic Missile【魔法导弹】] ，二级的魔法导弹会提高射程和伤害

这些设置决定了进阶这一功能如何运作，恰如魔法导弹的进阶，你必须处于&quot;Beginner&quot;【初学者】 熟练度并且成功释放法术40次

<pre class="">    category: combat</pre>
技能可以设置类别，主要用于技能书的管理，或用于/spells 命令

<pre class="">    worth: 150
    earns_sp: 8
    earns_cooldown: 10000</pre>
这些设置项决定了 [[Magic/Spell Points|技能点]] 在此技能的运作方式。
'''worth''' 属性指此法术技能点 is the cost of the spell in spell points. (或金钱数, 需要有技能商店的设置)

'''earns_sp''' 属性决定了释放这一法术可获得的技能点 ''最大值'' 。当一个技能被释放时，玩家获得技能点，技能则会进入一段时间的冷却，在这段时间内，法术成功释放时额外获得的技能点数量将会有所削减。这个机制可以防止玩家反复释放技能刷技能点。

'''earns_cooldown''' 属性决定了技能点的获取冷却持续多久。注意，这并不是严格的冷却时间，在冷却时间内仍然可以获得技能点，但是会根据上次获得技能点的时间成比例减少。 

例如，首次使用Magic Missile【魔法导弹】,将可以获得8技能点，如果在五秒后使用 (假定这个技能自身的冷却是10秒) ，就只会获得4技能点

Magic Missile 【魔法导弹】也是玩家的默认法杖上自带的第一个法术,作为一个默认的教学类技能，它的技能点获取冷却其实是相当短的，其他的法术默认设置都是15分钟

当Magic Missile【魔法导弹】升级时,它的技能点冷却就和其他法术相同了（其实说的还是插件默认给的配置，可以忽略）

=== 游戏内文本 ===

如需本地化游戏文本, 可通过messages.yml修改全部的游戏内文本。每一个技能的名字和描述都可以在[https://github.com/elBukkit/MagicPlugin/blob/master/Magic/src/main/resources/examples/survival/messages/spells.yml#L1 &quot;spells&quot; 部分]被找到

不管怎样,处于方便起见你也可以在技能的基础配置里设置 '''name'''【名字】 和 '''description'''【描述】

=== class【法术类】 ===

一些老的法术,如[https://github.com/elBukkit/MagicPlugin/blob/master/Magic/src/main/resources/examples/survival/spells/superblob.yml#L10 SuperBlob【超级气泡】],这一技能就使用了如此一个技能类属性:

<pre class="">superblob:
    class: ConstructSpell</pre>
这些法术早于action【行为】系统，所以这类技能不能使用'''actions'''【行为】部分 

这些发射的表现形式完全硬代码写死。每一个技能都拥有它独立的类，请查阅[https://github.com/elBukkit/MagicPlugin/tree/master/Magic/src/main/java/com/elmakers/mine/bukkit/spell/builtin 此处提供的源代码]

如果可以避免，则不建议使用这类法术，最好还是使用基于'''actions'''【行为】编写的技能(即现在通行的常用技能)。无论如何，一些技能（如工程魔法）还尚未换用新模式。

== Actions【行为】 ==

大多数的技能现在都在使用[[Magic/Actions|Actions]]【行为】系统。'''actions''' 部分用于决定一个技能释放时的各种表现形式，是技能的核心部分

再来回顾一下 Magic Missile【魔法导弹】:

<pre class="">    actions:
        cast:
        - class: CustomProjectile
          actions:
          - class: Damage
          - class: BreakBlock
            ignore_result: true</pre>
行为可以有多个组成部分，但大部分技能只会有一个 '''cast'''部分,这些行为将在法术释放时得以执行

行为通常是一个层次化的结构，这意味着一个行为可能有&quot;child&quot;【子行为】，这就可以在特定条件下运行这一层次下的子行为

每一个行为都至少需要有一个'''class''' 【类】属性,类决定了行为会如何运作。类可以在 [[Magic/Actions|行为]] 页面找到,或者你也可以查阅[https://github.com/elBukkit/MagicPlugin/tree/master/Magic/src/main/java/com/elmakers/mine/bukkit/action/builtin 此处提供的源代码]

请注意：当引用源代码时，使用技能配置，&quot;Action&quot;【行为】部分的类名可能被遗漏

许多技能的内部配置都是以 &quot;CustomProjectile&quot;【自定义投掷物】开端（就和Mythicmobs的Projectile类似）。这个行为会创建一个虚拟的投掷物而非原版的雪球、箭矢等，通过自定义这个虚拟的投掷物以实现一些灵活的自定义效果。

注：如果说MM的投掷物技能必须要有一个载体如雪球，Magic则不需要，这个投掷物可以通过效果赋予它视觉上的感官而无需依托一个原版投掷物载体。

当此投掷物击中一个目标时（既可以是方块也可以是实体），将会运行行为列表上的行为

在这种情况下，当魔法导弹命中时会执行伤害行为和方块破坏行为。无论目标是什么，这两个行为都会被执行。但如果击中了方块，那么伤害行为就无效，如果击中了实体，那么方块破坏的行为就无效

=== 行为参数 ===

每个行为都有一些参数可供修改其表现形式。这些参数可以放到两个地方：直接作为行为列表中的一种属性；或者和其他共享性的参数一样，写在parameters【参数】部分即可（详情见下文）

在此情况下,BreakBlock【方块破坏】行为如有'''ignore_result'''，则会被设置为true

每个行为都会转向一个结果，通常结果分为：成功、失败或无目标。若要将一个法术算作成功释放，则至少需要有一个最终转向成功的行为。这是唯一能够获得技能点的方法，否则就需要有法术进阶将施法次数计入其中

拿Magic Missile【魔法导弹】举例,破坏方块更多的是一种次要的装饰效果，且不会计入获得技能点。必须通过魔法导弹击中且对实体造成伤害才算做成功计数。

因此,如果法术有 BreakBlock 行为，&quot;ignore_result: true&quot; 则表示着忽略此行为的结果，这意味着造成伤害是唯一影响法术整体效果的行为

== Effects【效果】 ==

'''effects''' 【效果】部分决定了一个法术将会使用什么样的虚拟效果（譬如说闪电没有实质性伤害和点燃）。通常来说，法术至少要有一个 '''cast'''的效果部分作为技能释放时的效果。给法术添加一些粒子效果和音效通常会让法术变得更加有趣。

来再回顾一下Magic Missile【魔法导弹】:

<pre class="">        cast:
        -  class: EffectSingle
           sound: magic.zap_crack
           location: origin
           color_override: color
           effectlib:
             class: ConeEffect
             iterations: 10
             particle: redstone
             lengthGrow: 0.1
             radiusGrow: 0.003
             updateLocations: false
             updateDirections: false</pre>
这里的'''cast'''部分将会在法术释放时运行。每个部分都是一个列表，藉此可以运行多个不同的效果。每一个部分都有一些设置项:

* '''class''': 效果所属的类。可能略微有些过时，可以忽略（译者注：我不认为这个东西可以随便忽略）。'''EffectSingle'''表示只运行一个简单的效果，但如今Magic大部分的效果都依赖于Effeclib。其他的设置为：EffectRing, EffectTrail 以及EffectTransform，但它们很少见也不常用。
* '''sound''': 播放的音效，这个音效可以是资源包中的自定义音效(譬如 &quot;magic.zap_crack&quot;)或原版内置的音效,这里有[https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Sound.html 原版音效枚举]
**sound_pitch** 和 '''sound_volume''' 分别指音调和音量,译者注：似乎原版音效的音调只能在0.0-2.0之间
* '''location''': 效果在什么地方播放。这里可以填写 '''origin''' (施法者), '''target'''(目标)或'''both'''(两者)
* '''color_override''': 通过技能可使法杖拥有个性化颜色。'''color_override'''属性会指示Effectlib使用和参数相同的颜色 (通常来说''color''【颜色】是大部分Effectlib的效果被控制的方式)。此项仅对redstone【红石】和mob_spell【气泡】粒子有效（这两个粒子可采用多种颜色）
* '''effectlib''': Magic和 [https://dev.bukkit.org/projects/effectlib EffectLib]密切相关，大多数法术都在使用Effectlib效果。详见[https://github.com/elBukkit/MagicPlugin/wiki/EffectLibParameters 此处查看]更多有关Effectlib的配置效果

Magic Missile also has a &quot;tick&quot; effect list:

<pre class="">        tick:
        - particle: redstone
          location: target </pre>
In this case you can see that '''class''' has been omitted, EffectSingle will be used as the default class.

The '''tick''' effect list is a special set of effects used by the CustomProjectile action. These effects will be shown on every server tick while the projectile is running. They may be shown multiple times per tick, depending on the projectile velocity and configuration, so it's best not to put anything too complex in here.

In this case, we are showing a single '''particle''', whose names come from [https://github.com/Slikey/EffectLib/blob/master/src/main/java/de/slikey/effectlib/util/ParticleEffect.java the EffectLib particle enum].

Magic Missile has several other effect blocks, too many to list here. It has special effects for headshots, hitting blocks, etc. If you're curious, take a look at [the configs].(https://github.com/elBukkit/MagicPlugin/blob/master/Magic/src/main/resources/examples/survival/spells/missile.yml#L18).

== Parameters ==

Spells have several base parameters that can be seen here: [[SpellParameters]]

Each action also has its own parameters, which can be seen on the [[Actions|Actions]] page, though it is not completely up to date. Action parameters can also be found [https://github.com/elBukkit/MagicPlugin/blob/master/Magic/src/main/java/com/elmakers/mine/bukkit/action/builtin/CustomProjectileAction.java#L226 in the source code] of each action, by searching for the &quot;prepare&quot; method and looking at what it reads out of its configuration.

Parameters in the '''parameters''' section affect all actions in the spell.

Let's look at Magic Missile (TODO: Flesh this out)

<pre class="">    parameters:
        allow_max_range: true
        velocity: 200
        range: 24
        hitbox: true
        target_type: Damageable
        player_damage: 2
        entity_damage: 4
        target_breakables: 1
        cooldown: 1000
        reorient: false
        destructible: solid
        destructible_durability: 50
        break_durability: 2
        undo: 10000</pre>
=== Headshots ===

The CustomProjectile action can detect when you hit an entity in the head. In this case, it may run a separate set of '''headshot''' actions, or in some cases (like Magic Missile) just use some extra parameters:

<pre class="">    headshot_parameters:
      damage_multiplier: 1.5</pre>
So a headshot with Magic Missile multiplies the damage done by 150%.

== Costs ==

Costs are lists of costs required to cast the spell. It is most often just mana, like this:

<pre class="">    costs:
        mana: 15</pre>
== Requirements ==

Spells can have requirements assigned to them, which much be met in order for the player to purchase and use them. This can be used to create reasearch or teching paths, requiring players to have a certain class, skill, spell, etc, before they can purchase the spell.

Right now the current requirements are supported:

* Type: skillapi
** skill - Requires the player to have the specified SkillAPI skill
** class - Requires the player to have the specified SkillAPI class

Here is an example requirement block, which might appear in a spell, Selector or other config. It requires the player to have the skillapi skill '''enchanting'''

<syntaxhighlight lang="yaml">    requirements:
        -  type: skillapi
        -  skill: enchanting</syntaxhighlight>
'''type''' specifies the type of requirement<br />
'''skill''' further specifies that a skill from skillAPI is required, and what that skill is