This plugin adds various new keys to be used by the Deluxe Battle Kit's mid-battle scripting functionality.
Trigger Keys
These are keys which trigger at various points of a wild Pokemon calling for help.
"BeforeSOS"
Triggers before a wild Pokemon makes its call for help.
"AfterSOS"
Triggers after a wild Pokemon successfully called an ally Pokemon.
"FailedSOS"
Triggers after a wild Pokemon called for help, but its help failed to appear.
Trigger Extensions: You may extend these keys with a species ID or a type ID to specify that they should only trigger when an SOS call is made by a specific species, or species of a specific type. For example, "BeforeSOS_PIKACHU" would trigger only when a wild Pikachu is about to call for help, where "FailedSOS_ELECTRIC" would trigger only when a wild Electric-type attempted to call for help, but no help appeared.
Command Keys
These are keys which trigger certain actions related to SOS calls, or adding new battlers or trainers to the battle.
"sosCall" => Boolean
Forces a wild Pokemon to call for help when set to true. This will be ignored if the Pokemon isn't a wild Pokemon, is fainted, in the middle of a two-turn attack, or if their side of the battlefield is already at max capacity.
Unlike a normal SOS call, forcing a wild Pokemon to call for help in this way cannot fail, so the call will always be answered by a new Pokemon. This can even be used to force SOS calls for species who typically have a call rate of zero, and would normally be unable to use SOS calls.
Additionally, this can be used to force a wild Pokemon to call for an ally even if they already have one ally on the field, allowing you to use this to add a third wild Pokemon to the opponent's side. This is the only way to have a third Pokemon enter the field via SOS call, as the mechanic normally will only trigger if there is only a single wild Pokemon on the field.
"disableSOS" => Boolean
Toggles the ability of wild Pokemon to call for help during this battle. If set to true, wild Pokemon will be flagged as unable to call for help via SOS. When set to false, this flag is removed, allowing wild Pokemon to make SOS calls again, if they are able to.
"addWild" => Symbol, Boolean, or Array
Adds a new wild Pokemon to the opponent's side of the field during a wild battle, as long as their is room for a new battler. This happens independently of any SOS mechanics.
When entered as a symbol, you can simply set this to a species ID to generate a Pokemon of that species to join the battle. If set to true, the species that is spawned is determined by whatever species the existing wild Pokemon on the field would normally call if the SOS mechanic was being used. If set as an array, you can include an integer as the second element of this array to indicate the level that this wild Pokemon should be. If no level is specified, the wild Pokemon will generate with whatever level a normal SOS spawn would typically have.
Note that the species added to battle in this way inherits the same traits as the ones set for that species with the "setSOSPokemon" and "addSOSPokemon" Battle Rules.
For example if you use the "setSOSPokemon" rule to set the SOS call for this battle to be a shiny Magikarp, then if you use this Command Key to add a wild Magikarp to the battle, it will also be shiny even though it wasn't properly SOS called. You can use this as a way of editing the attributes of specific species you intend to add to the battle with this key, even if you don't intend to use the actual SOS mechanic for this battle.
"addTrainer" => Array
Adds a new trainer to join the opponent's side during a trainer battle, as long as there is room for a new battler.
This must be set as an array which contains a trainer type ID of the trainer you want to add, followed by the name of that specific trainer. Optionally, you may include a version number as a third entry in this array if you want to add a trainer which has multiple versions. Otherwise, the version number is always assumed to be zero.
Hardcoding
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:
Battle class
Variables
@sosBattle
When set equal to true, wild Pokemon may call for help. When set to false, this is disabled.
@totemBattle
This battle is considered a Totem Battle when the value of this variable is anything but false or nil.
@primarySOS
Stores the species ID or hash of data that will be used to replace the SOS species that would normally be called by the wild Pokemon. For Totem Battles, this refers to the first Pokemon that the Totem Pokemon will summon.
@secondarySOS
Stores the species ID or hash of data that will be used to add an additional SOS species that the wild Pokemon may call. For Totem Battles, this refers to the second Pokemon that the Totem Pokemon will summon.
@sos_chain
Stores the current SOS chain count.
@adrenalineOrb
When set to true, this will flag the battle as if an Adrenaline Orb has been used to boost the SOS call rate.
@originalCaller
Stores the Pokemon object of the initial caller that started the SOS chain. If the chain is broken, the new caller will be saved as the original caller.
Methods
pbCallForHelp(caller)
Makes a wild battler attempt to call for help. The caller argument is the battler object who should be making the call.
pbCallForHelpSimple(caller)
Identical to the method above, except this simplifies the calling process and makes it so that the user's call is guaranteed to be answered by a wild Pokemon.
pbAddNewBattler(species, level)
Forces a new wild Pokemon to join the opponent's side, independent of any SOS mechanics. The species argument must be a species ID, and level should be the level of this new wild Pokemon. If either or both of these arguments are set to nil, the species and level of the called Pokemon will be determined based on the SOS data of the first available battler on the opponent's side.
pbAddNewTrainer(tr_type, tr_name, version)
Forces a new trainer to join the opponent's side in a trainer battle. The tr_type argument must be a valid trainer type ID, where tr_name should be the name of the specific trainer you want to add. For the version argument, you may enter the number of the specific version of this trainer that you want. If omitted, the version defaults to zero.
Battle::Battler class
Variables
@totemBattler
When set to true, this battler object is considered a Totem Pokemon.
@tookSuperEffectiveDamage
When set to true, this flags the battler as if they have taken Super Effective damage this round. This is used to boost call rate chances.
Methods
sos_call_rate
Returns the effective SOS call rate for this battler. This is based off of the base call rate of this battler's species. This always returns 100 if the battler is a Totem Pokemon. Defaults to a call rate of 9 if the battler's default call rate is zero but are being forced to make an SOS call anyway.
canSOSCall?
Returns true if the battler is capable of making an SOS call and passes all randomized checks based on their call rate.
canSOSCallSimple?
Returns true if the battler is capable of making an SOS call. This is a simplified version of the method above, and ignores call rate calculations. It simply returns true if nothing is preventing the battler from making an SOS call.
isRivalSpecies?(other)
Returns true if this battler is a rival species to the battler object entered as other.