A Pokemon may use a Z-Move in battle as long as it's holding a Z-Crystal and has a compatible move for that crystal. Below, I'll explain each variety of Z-Move in detail, as well as cover everything related to Z-Crystals.
PBS Data
Upon installing the plugin for the first time, you must recompile your game. This is not an optional step. This will update all of your relevant PBS files with the necessary data. If you're unaware of how to recompile your game, simply hold down the CTRL key while the game is loading in debug mode and the game window is in focus.
Installation Details
If done correctly, your game should recompile. However, you will also notice lines of yellow text above the recompiled files, like this:
This indicates that the appropriate data have been added to the following PBS files:
moves.txt
moves_Gen_9_Pack.txt (if the Gen 9 Pack is installed)
This will only occur the first time you install the plugin. If you for whatever reason ever need to re-apply the data this plugin adds to these PBS files, you can force this to happen again by holding the SHIFT key while loading your game in debug mode. This will recompile all your plugins, and the data will be re-added by this plugin as if it was your first time installing.
In addition to the changes made to existing files, this plugin adds two new PBS files.
moves_zpower.txt
This file contains all of the Z-Moves added by this plugin. If you design any new custom Z-Moves, it should be added to this file.
items_zpower.txt
This file contains all of the Z-Rings as well as Z-Crystals added by this plugin. If you design any new items of this type, they should be added to this file.
Z-Crystals
Z-Crystals are items used to unlock a Pokemon's Z-Moves when held. However, a Z-Crystal has two different forms in practice. A "bag" form which act as key items that cannot be tossed or sold, and a "hold-able" form, which are disposable and infinite in supply.
Z-Crystal Pocket
Z-Crystals are stored in their own exclusive pocket in the bag. This Z-Crystal pocket will automatically be added to your game. Essentials has 8 bag pockets by default, so the Z-Crystal pocket is assigned to the 9th bag slot to accommodate this, and all graphics provided by this plugin assume that this will be the case. If your bag has more or fewer than 8 pockets, you may have to edit the graphics in the following folders:
In Graphics/Icons...
bagPocket9
In Graphics/UI/Bag...
bag_9
bag_9_f
bg_9
However, if you wish to edit which pocket the Z-Crystal pocket is assigned to, you may do so by opening the plugin settings and setting ZCRYSTAL_BAG_POCKET to your desired bag slot number. For example, if you want Z-Crystals to replace the mail pocket, which is pocket number 6 normally, then you would set ZCRYSTAL_BAG_POCKET = 6. You don't have to change any of the pocket data for your Z-Crystals in the PBS data, the plugin will always ignore this data and simply assign Z-Crystals to whichever pocket is listed in this setting.
Note however that any time you change this setting, you must recompile your game for the changes to take effect. It's also advised that you clear the player's existing bag of all items with the debug tools afterwards, because it may be necessary to reset the position of all items. You will also have to manually edit your bag pocket sprites to display the correct Z-Crystal pocket icon if you assign the Z-Crystal pocket to anything besides pocket 9.
Another thing to note is that you can also use the ZCRYSTAL_BAG_POCKET_NAME setting to assign a different name to the Z-Crystal pocket, if you please. By default, the name of this pocket is simply set to "Z-Crystals."
If you have the Bag Screen with interactable Party plugin installed, the bag UI will automatically update to include the Z-Crystal pocket if this pocket is assigned to pocket number 9. If you want to assign this to a different pocket however, you'll have to manually edit your sprites to display the Z-Crystal bag icon for the right pocket.
Equipping Z-Crystals
Since Z-Crystals are considered key items, they cannot be removed from your bag. This means they cannot simply be given to a Pokemon to hold like a normal held item. Instead, you have to "use" a Z-Crystal like you would other key items, such as the Bicycle. When a Z-Crystal is used, it spawns a shard of itself which can be given to a Pokemon in your party.
If a particular Z-Crystal is compatible with a Pokemon, they will be given a piece of it to hold. Note that you may still have a Pokemon hold a Z-Crystal even if they are not compatible with it, but there will be a message which indicates its incompatibility.
Z-Crystal Displays
Z-Crystals have two different types of description text to account for the fact that there are slight differences between the "bag" form and "held" form of the items. To display the "bag" description, you may call this as you would with any item by using Item.description, where Item is the specific item object you want the description of. However, if you want to display the secondary "held" item description, you may do so with Item.held_description. Note that if the specific item does not have a held description, the normal description will be displayed instead. So there is no harm calling this with any item.
One last thing to note is that while a Pokemon is holding a Z-Crystal, a Z-Crystal icon will be displayed instead of the usual held item icon. This is similar to how Mega Stones work.
Z-Moves
A Z-Move is a general term for a move that is unlocked when powering up one of the user's base moves with Z-Power. However, there's actually three different varieties of Z-Move, and each one is set up and handled a bit differently.
Generic Z-Moves
Each of the 18 base types in the game have their own corresponding Z-Crystal which transforms any offensive move of that type into a generic Z-Move. For example, when the Z-Crystal Normalium Z is held by a Pokemon, all of its damaging-dealing Normal-type moves can be converted into the Z-Move Breakneck Blitz.
[BREAKNECKBLITZ]
Name = Breakneck Blitz
Type = NORMAL
Category = Physical
Power = 1
Accuracy = 0
TotalPP = 1
Target = NearOther
Flags = ZMove_NORMAL,CannotMetronome
Description = The user builds up its momentum using its Z-Power and crashes into the target at full speed.
Here's an example of how Breakneck Blitz is set up in the moves_zpower.txt PBS file. This is mostly set up like any other move, but there are a few key things to note:
The category you set for any Z-Move doesn't matter. By default, all of them are set to Physical. However, in practice, what you set doesn't make any difference since the category will always be inherited from the base move, unless it's a status move.
Generic Z-Moves must have a Power of 1. This is what allows the move's power to scale depending on what the base move was. For example, if converting a high base power move like Hyper Beam into this Z-Move, it'll have a much higher power than if the base move was Tackle.
All Z-Moves must have an Accuracy of 0. This allows it to ignore Accuracy checks.
All Z-Moves must have a TotalPP of 1.
All Z-Moves must have the CannotMetronome flag.
Generic Z-Moves must have the ZMove_TYPE flag, where TYPE is the ID of the specific type of move this Z-Move will replace. This type should always be the same type as the Z-Move's type.
Now that we have an example of a generic Z-Move, we need a specific Z-Crystal which unlocks it.
[NORMALIUMZ]
Name = Normalium Z
NamePlural = Normalium Z
Pocket = 9
Price = 0
FieldUse = OnPokemon
Flags = KeyItem,ZCrystal
Move = BREAKNECKBLITZ
Description = It converts Z-Power into crystals that upgrade Normal-type moves to Normal-type Z-Moves.
HeldDescription = This is a crystallized form of Z-Power. It upgrades Normal-type moves to Z-Moves.
Above is an example of how Normalium-Z is set up in the items_zpower.txt PBS file. This is mostly set up like any other item, but there are a few key things to note:
Every Z-Crystal must have FieldUse = OnPokemon, so that it may be used from the bag.
Every Z-Crystal must have the ID of the specific move it unlocks entered in the Move field. This move must be flagged as a Z-Move.
Every Z-Crystal must have the ZCrystal flag as well as the KeyItem flag.
Every Z-Crystal is stored in their own exclusive bag Pocket. This plugin uses pocket 9 for all Z-Crystals by default. However, whatever is set here in the PBS data actually doesn't matter, because Z-Crystals are hardcoded to automatically fill whatever the last pocket is in the player's bag, which will always be the Z-Crystal pocket.
Every Z-Crystal should have a description and a HeldDescription. The normal description is used to describe the "master" Z-Crystal when viewed in the bag. The held description is used to describe the individual shard that was spawned from the bag crystal that was given to a Pokemon to hold. This description isn't displayed anywhere by default, but you may use this if you have a custom Summary UI that can display held item descriptions.
Exclusive Z-Moves
Some Z-Moves are exclusive to certain species when using a particular move. For example, a Snorlax holding the Z-Crystal Snorlium Z may upgrade the move Giga Impact to the Z-Move Pulverizing Pancake.
[PULVERIZINGPANCAKE]
Name = Pulverizing Pancake
Type = NORMAL
Category = Physical
Power = 210
Accuracy = 0
TotalPP = 1
Target = NearOther
Flags = ZMove,Contact,CannotMetronome
Description = Snorlax moves its enormous body energetically and attacks the target with full force.
Here's an example of how Pulverizing Pancake is set up in the moves_zpower.txt PBS file. This is mostly set up like a generic Z-Move, but there are a few key things to note:
Unlike generic Z-Moves, exclusive Z-Moves can have a set Power. These moves are not meant to scale their power based on the original move, so you can set whatever power you wish for these moves. If you set it to 1 however, its power will scale like generic Z-Moves do.
Unlike generic Z-Moves, you can make an exclusive Z-Move a status move. For example, the Z-Move Extreme Evoboost is a status move even though its base move is Last Resort, which is a damage-dealing move. Make sure to set the Target of the Z-Move appropriately if you wish to do this.
Unlike generic Z-Moves, exclusive Z-Moves must have the ZMove flag without a type ID attached.
Now that we have an example of an exclusive Z-Move, we need a specific Z-Crystal which unlocks it.
[SNORLIUMZ]
Name = Snorlium Z
NamePlural = Snorlium Z
Pocket = 9
Price = 0
FieldUse = OnPokemon
Flags = KeyItem,ZCrystal
Move = PULVERIZINGPANCAKE
Description = It converts Z-Power into crystals that upgrade Snorlax's Giga Impact to an exclusive Z-Move.
HeldDescription = This is a crystallized form of Z-Power. It upgrades Snorlax's Giga Impact to a Z-Move.
ZCombo = GIGAIMPACT,SNORLAX
Above is an example of how Snorlium Z is set up in the items_zpower.txt PBS file. This is mostly set up like a generic Z-Crystal, but there are a few key things to note:
The ZCombo field is required on Z-Crystals that unlock exclusive Z-Moves. This field must contain at least two entries:
The ID of the specific move that acts as the base move for the exclusive Z-Move this Z-Crystal unlocks. This must always be the first entry on this line.
The ID of the specific species that this Z-Crystal is exclusive to. This is usually only one species or form ID, but you can add as many additional ones as you like if this Z-Move should be exclusive to multiple species or forms.
Exclusive Z-Crystals that should be usable by all forms of the entered species can be given the flag UsableByAllForms. This will allow all Pokemon of that species to be compatible with this Z-Crystal, regardless of form.
Z-Powered Status Moves
Status moves can enjoy benefits from Z-Power even though they aren't converted into a generic or exclusive Z-Move. Instead, status moves are simply powered up to grant additional effects on top of their natural one.
For example, if a Normal-type status move like Growl is given Z-Power through the use of Normalium Z, the user will be able to use Z-Growl. This will boost the user's Defense by 1 stage on top of Growl's normal effect.
There are a variety of different possible effects that a status move can be given through Z-Power. Each Z-Powered effect is given to a status move by giving that move a particular flag in its PBS data. Below, I'll list every possible type of Z-Power that may be given to a status move, and the flag that is used to grant that Z-Power.
Each of the below flags are entered as ZPower_FLAG, where FLAG can be any one of the following:
HealUser
When a status move with this flag is used with Z-Power, it will fully restore the HP of the user prior to using its natural effects. For example, using Z-Belly Drum will fully restore the user's HP before using its base effect.
HealSwitch
When a status move with this flag is used with Z-Power, it will fully restore the HP of an incoming party member. For example, using Z-Parting Shot will apply an effect on the user's position. Once the user switches out to a new Pokemon due to the effects of Parting Shot, the switched-in Pokemon will trigger the effect and become fully healed.
FollowMe
When a status move with this flag is used with Z-Power, it will make the user the center of attention and redirect all attacks to itself as if it used Follow Me. For example, Z-Destiny Bond will force the opponent to direct their attacks at the user upon setting up the Destiny Bond.
CriticalHit
When a status move with this flag is used with Z-Power, it will boost the user's critical hit ratio by two stages, as if it's under the Focus Energy effect. For example, using Z-Tailwind will grant the user +2 critical hit stages on top of its normal effects.
ResetStats
When a status move with this flag is used with Z-Power, it will neutralize any of the user's lowered stat stages. For example, using Z-Recover will return all of the user's lowered stats to normal on top of its normal healing effect.
Stat Boosting Flags
In addition to the above flags, you may also set up a Z-Power flag that boosts the user's stats by a number of stages. Each stat ID is a valid flag, which is then followed by the number of stages.
For example, the move Splash has the flag ZPower_ATTACK_3. This means when you use Z-Splash, the move will grant +3 Attack. You can do this for any stat which can be raised in battle, including ACCURACY and EVASION.
Finally, if you would like a Z-Powered status move to raise all of the user's main stats a number of stages, you may do so by using AllStats instead of a stat ID. For example, the move Celebrate has the flag ZPower_AllStats_1. This means using Z-Celebrate will raise all of the user's main stats by 1 stage each.
Every official status move in Essentials has been given one of the Z-Power flags described above to make them function as they did in Pokemon Sun & Moon. For any new moves introduced in later gens that don't have any official Z-Powered effects, they were given flags that makes the most sense for that move to have by looking at the Z-Powered effects that similar moves were given.
For example, the move Obstruct did not exist in Sun & Moon. However, it has been given the flag ZPower_ResetStats in this plugin because all Protect-like moves had this Z-Powered effect in Sun & Moon, so it's safe to assume Obstruct would have worked the same if it existed at that time.
However, there are a handful of rare status moves that are exempt from being given any Z-Powered effects. The following status moves were not given any Z-Power flags:
Healing Wish
Lunar Dance
Metronome
Nature Power
Assist
This is due to the specific ways in which these moves work. The moves Healing Wish and Lunar Dance do not grant any Z-Powered effects simply because any effects that these moves could be given would be entirely irrelevant. Boosting the user in some way is pointless, since the moves force the user to faint anyway. For the other listed moves, the reason they don't grant any effects is because these moves simply use the Z-Powered versions of the moves that they call. For example, if Nature Power calls the move Tri Attack, it will simply use the generic Normal-type Z-Move instead, Breakneck Blitz.
Coding custom Z-Move effects
If you decide you want to create your own custom Z-Moves that have some sort of effect, this is done the same way you would code the move function for any other regular move. However, there is one key difference. A typical battle move is defined in the class Battle::Move. Z-Moves however use a subclass of this called Battle::ZMove.
This means that when you are coding a move function, this is the class you need to use, rather than Battle::Move. For example, here's the move function for the Z-Move Genesis Supernova, which sets up Psychic Terrain after dealing damage:
You'll see that class Battle::ZMove is what's used here prior to the move's function code. This is required for Z-Moves. However, Z-Moves can access everything from the normal Battle::Move class, so you can still use this as a subclass as needed.
Because of this, it's possible to just inherit all of the attributes of a regular move's function code. For example, this is what the function for the Z-Move Searing Sunrise Smash looks like, which has the effect of ignoring the target's ability:
You'll notice that no actual code is required for this function code. That's because Battle::ZMove::IgnoreTargetAbility simply inherits all of the same functionality as the base Battle::Move version, so there's no reason to rewrite any of the code. You can simply set the function for the base move as the subclass for this Z-Move to inherit all of its features.
It's worth keeping the above in mind when coding your own Z-Moves, as this can save you a lot of extra redundant work.
How a held Z-Crystal differs from other held item icons.
