# Z-Power: Mid-Battle Scripting

This plugin adds various new keys to be used by the Deluxe Battle Kit's mid-battle scripting functionality.

***

<mark style="background-color:orange;">**Trigger Keys**</mark>

These are keys which trigger upon a battler utilizing Z-Power or its various mechanics.

* <mark style="background-color:purple;">**"BeforeZMove"**</mark>\
  Triggers right before a battler's selected generic or exclusive Z-Move is about to be executed.<br>
* <mark style="background-color:purple;">**"BeforeZStatus"**</mark>\
  Triggers right before a battler's selected Z-Powered status move is about to be executed.

{% hint style="info" %}
Trigger Extensions: You may extend these keys with a species ID or type ID to specify that they should only trigger when a specific species is about to use a Z-Powered move, or when a Z-Powered move of a specific type is about to be used. For example, <mark style="background-color:purple;">"BeforeZMove\_RAICHU"</mark> would trigger only when a Raichu is about to use a Z-Move, where <mark style="background-color:purple;">"BeforeZStatus\_PSYCHIC"</mark> would trigger only when a Psychic-type status move is about to be used with a Z-Powered effect.

Both triggers also accept an ID of a specific move as well, for example <mark style="background-color:purple;">"BeforeZMove\_CATASTROPIKA"</mark> would only trigger when the Z-Move Catastropika is about to be used, while <mark style="background-color:purple;">"BeforeZStatus\_MEMENTO"</mark> would only trigger when the move Memento is about to be used with a Z-Powered effect.&#x20;
{% endhint %}

* <mark style="background-color:purple;">**"BeforeUltraBurst"**</mark>\
  Triggers when a battler is going to use Ultra Burst this turn, but before that Pokemon actually Ultra Bursts.<br>
* <mark style="background-color:purple;">**"AfterUltraBurst"**</mark>\
  Triggers after a battler successfully uses Ultra Burst.

{% hint style="info" %}
Trigger Extensions: You may extend these keys with a species ID or a type ID to specify that they should only trigger when a specific species or species of a specific type triggers Ultra Burst. For example, <mark style="background-color:purple;">"BeforeUltraBurst\_NECROZMA"</mark> would trigger only when a Necrozma is about to Ultra Burst, where <mark style="background-color:purple;">"AfterUltraBurst\_DRAGON"</mark> would trigger only after a Pokemon has become a Dragon-type after using Ultra Burst.
{% endhint %}

***

<mark style="background-color:orange;">**Command Keys**</mark>

These are keys which trigger certain actions related to Z-Powered mechanics to take place during battle, such as forcing a trainer to use a Z-Move, or disabling Ultra Burst.

<details>

<summary><mark style="background-color:blue;">"useZMove"</mark> => <mark style="background-color:yellow;">Boolean or String</mark></summary>

Forces the battler to use a Z-Move when set to `true`, as long as they are able to. If set to a string instead, you can customize a message that will display upon this Z-Move triggering. Note that this can even be used to force a wild Pokemon to use a Z-Move, as long as they are capable of it.\
\
Like with using Z-Moves naturally, you can only use this to force a Pokemon to use a Z-Move prior to them using their move that turn. So setting this to happen at the end of a round for example would do nothing, since the Pokemon's move has already been executed by that point. Because of this, you can only really use this key during the actual battle phase prior to the Pokemon executing its move, such as with the <mark style="background-color:purple;">"RoundStartAttack"</mark> or <mark style="background-color:purple;">"TurnStart"</mark> Trigger Keys. This also won't do anything if a different action with this battler has been chosen, such as switching it out or using an item.

Also note that you cannot use this to control which Z-Move the selected Pokemon will use, just that it will use the Z-Powered version of whatever normal move it has selected if it's possible to do so. You can combine this with the <mark style="background-color:blue;">"useMove"</mark> Command Key however to first select the specific base move the Pokemon should use, and then use <mark style="background-color:blue;">"useZMove"</mark> to convert that base move into its Z-Move equivalent.

</details>

<details>

<summary><mark style="background-color:blue;"><strong>"disableZMoves"</strong></mark> => <mark style="background-color:yellow;">Boolean</mark></summary>

Toggles the availability of Z-Moves for the owner of the battler. If set to `true`, Z-Moves will be disabled for this trainer. If set to `false`, Z-Moves will no longer be disabled, allowing this trainer to use it again even if they've already used a Z-Move prior in this battle.

</details>

<details>

<summary><mark style="background-color:blue;">"ultraBurst"</mark> => <mark style="background-color:yellow;">Boolean or String</mark></summary>

Forces the battler to Ultra Burst their Pokemon when set to `true`, as long as they are able to. If set to a string instead, you can customize a message that will display upon this Ultra Burst triggering. Note that this can even be used to force a wild Pokemon to Ultra Burst, as long as they are capable of it.\
\
Unlike using Ultra Burst naturally, you can use this to force it to happen at any point in battle, even at the end of the turn or after the battler has already attacked. This cannot happen if a different action with this battler has been chosen however, such as switching it out or using an item.

</details>

<details>

<summary><mark style="background-color:blue;"><strong>"disableUltra"</strong></mark> => <mark style="background-color:yellow;">Boolean</mark></summary>

Toggles the availability of Ultra Burst for the owner of the battler. If set to `true`, Ultra Burst will be disabled for this trainer. If set to `false`, Ultra Burst will no longer be disabled, allowing this trainer to use it again even if they've already used Ultra Burst prior in this battle.

</details>

***

<mark style="background-color:orange;">**Hardcoding**</mark>

Here's a list of methods and/or properties that you might want to reference when hardcoding a midbattle script, since this plugin adds a lot of new custom content which you may need to call on to make certain things happen:

<details>

<summary>Battle Class</summary>

* `pbHasZRing?(idxBattler)`\
  Returns true if the trainer who owns the battler at index `idxBattler` has an item in their inventory flagged as a Z-Ring.<br>
* `pbGetZRingName(idxBattler)`\
  Returns the name of the specific item in a trainer's inventory flagged as a Z-Ring. The specific trainer's inventory checked for is the one who owns the battler at index `idxBattler`.
* `pbCanZMove?(idxBattler)`\
  Returns true if the battler at index `idxBattler` is capable of using a Z-Move.<br>
* `pbCanUltraBurst?(idxBattler)`\
  Returns true if the battler at index `idxBattler` is capable of using Ultra Burst.<br>
* `pbUltraBurst(idxBattler)`\
  Begins the Ultra Burst process for the battler at index `idxBattler`.

</details>

<details>

<summary>Battle::Battler Class</summary>

* `hasZMove?`\
  Returns true if this battler has a compatible Z-Move and is capable of using it.<br>
* `hasCompatibleZMove?(baseMove)`\
  Returns true if this battler has a compatible Z-Move. If `baseMove` is set to a specific battle move, this returns true only if the battler is capable of converting it into a compatible Z-Move. If `baseMove` is omitted or set as nil, this returns true if any move in the battler's moveset can be successfully converted into a compatible Z-Move.<br>
* `display_zmoves`\
  This converts all of the battler's moves into their compatible Z-Move equivalents. This can also be used to display Z-Moves in the player's Fight menu.<br>
* `ultra?`\
  Returns true if this battler is in Ultra Burst form.
* `hasUltra?`\
  Returns true if this battler is capable of using Ultra Burst.<br>
* `unUltra`\
  Forces a battler's Ultra Burst state to end, and reverts them back to their original form.

</details>