pokemon-showdown/old-simulator-doc.txt

Sim events:

Any event that fires on a pokemon also fires on that pokemon's side. So, for instance,
foeModifyMove can be captured by Reflect, a side condition on the foe's side.

Any event that fires on a side also fires on the global battle. So, for instance,
a move's basePower event can be captured by Rain Dance, a weather condition on
the global battle.

=== LIST OF EVENTS ===

beforeMove(user, target) [on move]
beforeMove(user, target, move) [on user]
foeBeforeMove(user, target, move) [on target]
	Fired before a pokemon uses a move it chose. Return true to prevent
	the move.

	Mostly effects that prevent a user from moving, such as paralysis.

	Moves not called directly (e.g. moves called by Metronome, Sleep Talk,
	or Pursuit) do not fire this event.

	examples: [volatile] Flinching, [status] fully paralyzed,
	          [move] Focus Punch

basePower(user, target) [on move]
basePower(user, target, basePower, move) [on user]
foeBasePower(user, target, basePower, move) [on target]
	Fired while calculating a move's base power. Return the modified
	base power.

	examples: [ability] Technician, [foe side condition] Reflect,
	          [move] Gyro Ball

beforeTurn(pokemon) [on pokemon]
beforeTurn(user) [on move]
	Fired before a turn starts on every active pokemon.

	Used for Focus Punch (for the "focusing" message) and Pursuit
	(to activate the side condition that listens for the foeSwitchOut
	event).

	examples: [move] Focus Punch, [move] Pursuit

damage(user, target) [on move]
	Fired while calculating a move's damage. Return a damage value in
	directly in HP. Bypasses weaknesses and resistances, but not immunities.

	examples: [move] Night Shade, [move] Endeavor

modifyMove(user, target, move) [on user]
foeModifyMove(user, target, move) [on target]
	Fired before a pokemon uses a move. Return true to prevent the move.

	The API is very similar to beforeMove, but the usage is different.

	Behavior differences:
	1. It is passed a copy of the move object that can be modified.
	2. It is fired for moves that bypass beforeMove (moves called by
	Metronome, Sleep Talk, or Pursuit switching).

	NOTE: Base Power modifications should be handled in basePower, not in
	modifyMove. This is because many moves have variable base power.

	NOTE: Priority modifications should be handled in movePriority. This is
	for performance reasons (there's no need to fire movePriority for
	moves that bypass priority, e.g. moves called by Sleep Talk).

	examples: [ability] Adaptability, [ability, foe ability] No Guard

modifyPokemon(pokemon) [on pokemon]
	Any effect that modifies a pokemon should be applied here.

	These are the properties of pokemon you can modify:
	- pokemon.stats
	- pokemon.weighthg
	- pokemon.type

	Whenever any effect is added or removed, the pokemon is reset and
	modifyPokemon is fired.

	examples: [ability] Light Metal, [volatile] Conversion 2, etc

stats(stats, pokemon) [on pokemon]
	A shortcut event for modifyPokemon(pokemon) : stats = pokemon.stats.

	Stats modifiers should be applied here.

	examples: [ability] Swift Swim, [status] Paralysis, etc


type(user, target) [on move]
	Fired when calculating a move's type. Returns the move's type, for
	the purposes of calculating damage. Not used for the move's type in
	any other situation.

	Only used for Struggle, which is Normal-type but does ???-type damage.

	examples: [move] Struggle

switchIn(pokemon) [on pokemon]
foeSwitchIn(pokemon) [on pokemon's foe's side]
	Fired after a pokemon switches in.

	If two pokemon switch in at once (first turn, or after two pokemon
	faint simultaneously), both switchIn events will fire after both pokemon
	have switched in, and the faster pokemon's switchIn event will fire
	first.

	examples: [ability] Drizzle, [ability] Intimidate, etc

switchOut(pokemon) [on pokemon]
foeSwitchOut(pokemon) [on pokemon's foe's side]
	Fired before a pokemon switches out. Return true to interrupt and
	prevent the pokemon from switching out.

	NOTE: This event fires for (and overrides) Baton Pass and U-Turn and
	Pokémon with Shed Shell. DO NOT use it to implement trapping: see the
	trapping flag.

	NOTE: NOTHING in BW or earlier prevents a pokemon from switching out
	at this stage, so you most likely DO NOT want to ever return true.

	examples: [foe side condition] Pursuit

immunity(type, target) [on target]
	Fired when determining whether or not a pokemon is immune to a move.
	Return true if it is immune. Or: 'noMessage' if it is immune - this
	suppresses the "It had no effect!" message, so you can replace it with
	your own, such as "Motor Drive raised its speed!"

	examples: [volatile] Magnet Rise, [ability] Volt Absorb, etc

immunity(effect, target) [on target]
	Fired when determining whether or not a pokemon is immune to a non-move
	effect, such as status infection or weather damage.

	examples: [type] Poison, [ability] Water Veil, [ability] Sand Rush, etc

getHit(target, source, move) [on target]
foeGetHit(target, source, move) [on source]
hit(target, source) [on move]
	Fired when a move hits (doesn't miss). Return true to prevent the move's
	effects.

	Also used for moves whose effects are too complicated to be represented
	in any other way.

	examples: [foe volatile] Protect, [move] Belly Drum, etc

movePriority(priority, user, target, move) [on user]
foeMovePriority(priority, user, target, move) [on target]
	Fired when determining a move's priority. Return the move's priority.

	examples: [ability] Prankster

start(pokemon, source) [on status, on volatile]
start(side, source) [on side condition]
start(placeholder, source) [on weather, on field effect]
	Fired when an effect starts.

	source is the pokemon that inflicted the effect, or null if no such
	pokemon did. For instance, if Pikachu uses Toxic, source is Pikachu,
	but if you are poisoned by Toxic Spikes, source is null.

	Useful for cancelling an effect that fails (e.g. Encore against a newly
	switched-in foe), for giving messages that an effect has started, and
	for initializing effect data (e.g. Substitute, Wish).

	NOTE: Not fired for abilities and items. For abilities and items, see
	the switchIn event.

	examples: [volatile] Encore, [side condition] Reflect,
	          [volatile] Substitute

restart(pokemon) [on status, on volatile]
restart(side) [on side condition]
restart() [on weather, on field effect]
	Fired when trying to induce an effect that's already active.

	Useful for effects that can have multiple "layers".

	examples: [side condition] Toxic Spikes, [side condition] Pursuit,
	          [volatile] Stockpile

end(pokemon) [on status, on volatile, on item, on ability]
end(side) [on side condition]
end() [on weather, on field effect]
	Fired when an effect ends naturally, usually because its duration ends.
	Return true to stop an effect from ending.

	Most ways an effect can end are "natural". The biggest exception is
	when a pokemon switches out. In general, if you would receive a message
	when the effect ends, the end event would be fired.

	NOTE: NOT fired when a pokemon switches out (see switchOut).

	NOTE: If you return true when an event expires from its duration counter
	      reaching 0, it will never expire unless you reset its duration. To
	      extend an effect by one turn, simply set its duration counter to 1
	      before returning true.

	Useful for giving messages that an effect has ended.

	examples: [volatile] Encore, [side condition] Reflect,
	          [volatile] Substitute

duration(pokemon, source) [on status, on volatile]
duration(side) [on side condition]
duration() [on weather, on field effect]
	Fired while calculating an effect's duration. Returns the duration in
	turns, including the current one.

	source is the pokemon that inflicted the effect, or null if no such
	pokemon did. For instance, if Pikachu uses Toxic, source is Pikachu,
	but if you are poisoned by Toxic Spikes, source is null.

	For instance, Protect has a duration of 1 turn, and Wish has a duration
	of 2 turns. Return 0 to have it never expire.

	The effect's residual event is not fired when it expires - instead, its
	end event is fired when its residual event would otherwise have fired.

	Do not use this for effects that don't expire during a residual. For
	instance, sleep expires through a sleep counter that decrements every
	beforeMove event, not every residual event.

	examples: [weather] Rain Dance, [side condition] Reflect

residual(pokemon) [on status, on volatile, on ability, on item]
residual(side) [on side condition]
residual() [on weather, on field effect]
	Fired at the end of each turn, but before fainted pokemon are switched in.

	Useful for whatever end-of-turn effects this may have.

	The duration counter of each effect is decremented automatically before
	this event is fired (see duration for details).

	examples: [volatile] Ghost-type Curse, [weather] Sandstorm


=== DETAILED USAGE NOTES ===

In aesoft's unnamed sim, as well as in Pokémon Lab and DougJustDoug's framework,
everything in Pokémon is an effect.

There are 8 types of effects
- move, associated with a pokemon (Grass Knot, Magnitude...)
- status, associated with a pokemon (Sleep, Poison...)
- volatile, associated with a pokemon (Protect, Substitute...)
- ability, associated with a pokemon (Intimidate, Technician...)
- item, associated with a pokemon (Leftovers, Choice Scarf...)
- side condition, associated with a side (Reflect, Tailwind...)
- weather, associated with a battle (Rain Dance, Sunny Day...)
- field effect, associated with a battle (Trick Room...)

Effects associated with a side are also associated with every pokemon on a side,
and effects associated with a battle are associated with every pokemon.

For convenience, every effect has the same ID as the move, ability, or item that
induces it. The only exceptions are effects with many moves associated with them,
such as statuses, and certain volatile statuses (flinch, confusion, locked moves,
and trapping).

Nearly every effect has some sort of event listener, and each action fires an
event.

For instance, here is the Technician ability:

"Technician": {
	desc: "When this Pokemon uses an attack that has 60 Base Power or less, the
		move's Base Power receives a 50% boost. For example, a move with 60 Base
		Power effectively becomes a move with 90 Base Power.",
	basePowerCallbackPriority: 10,
	basePowerCallback: function(pokemon, target, basePower, move) {
		if (basePower <= 60) {
			return basePower * 1.5;
		}
		return basePower;
	},
	id: "Technician",
	name: "Technician",
	num: "101"
}

Now, let's work through an example:

> In rain, A Technician Roserade uses Grass Knot against a Vaporen behind Light
> Screen.

This fires the basePower event:

basePower(user, target) [on move]
basePower(user, target, basePower, move) [on user]
foeBasePower(user, target, basePower, move) [on target]

First, the basePower callback on the move is fired.

Grass Knot's basePowerCallback function returns 60 as its Base Power against
Vaporeon.

Next, all basePower callbacks associated with Roserade are fired. This includes
the basePower callbacks of Roserade's effects (its Technician ability), the
basePower callbacks of Roserade's teams's effects (there are none), and the
basePower callbacks of the battle effects (rain).

These callbacks are sorted by their listed priority. The Technician callback
goes first, since it has a priority of 10, and so the attack's new base power is 90.

Then, the rain's callback is called. Since Grass Knot is neither a Water nor a Fire
move, its base power is unchanged.

Finally, all foeBasePower callbacks associated with Vaporeon are fired.

These are also sorted by their listed priority, and then run. With the foeBasePower
callback of Light Screen, we get a final base power of 45, which is then
passed on to the damage formula.