More documentation for script hooks, reworks stat changes to only be changeable through a function that allows for script hooks, and events.

src/dynamic_data/script_handling/script.rs

@@ -165,11 +165,19 @@ pub trait Script: Send + Sync {
         _modifier: &mut f32,
     ) {
     }
+    /// This function allows a script to apply a raw multiplier to the damage done by a move.
     fn change_damage_modifier(&self, _move: &ExecutingMove, _target: &Arc<Pokemon>, _hit: u8, _modifier: &mut f32) {}
+    /// This function allows a script to modify the outgoing damage done by a move.
     fn change_damage(&self, _move: &ExecutingMove, _target: &Arc<Pokemon>, _hit: u8, _damage: &mut u32) {}
+    /// This function allows a script to modify the incoming damage done by a move.
     fn change_incoming_damage(&self, _move: &ExecutingMove, _target: &Arc<Pokemon>, _hit: u8, _damage: &mut u32) {}
+    /// This function triggers when an incoming hit happens. This triggers after the damage is done,
+    /// but before the secondary effect of the move happens.
     fn on_incoming_hit(&self, _move: &ExecutingMove, _target: &Arc<Pokemon>, _hit: u8) {}
+    /// This function triggers when an opponent on the field faints.
     fn on_opponent_faints(&self, _move: &ExecutingMove, _target: &Arc<Pokemon>, _hit: u8) {}
+    /// This function allows a script attached to a Pokemon or its parents to prevent stat boost
+    /// changes on that Pokemon.
     fn prevent_stat_boost_change(
         &self,
         _target: &Pokemon,
@@ -179,9 +187,23 @@ pub trait Script: Send + Sync {
         _prevent: &mut bool,
     ) {
     }
-    fn change_stat_boost_change(&self, _target: &Pokemon, _stat: Statistic, _self_inflicted: bool, _amount: *mut i8) {}
+    /// This function allows a script attached to a Pokemon or its parents to modify the amount by
+    /// which the stat boost will change. If the stat boost is done by the user itself, self
+    /// inflicted will be true, otherwise it will be false.
+    fn change_stat_boost_change(&self, _target: &Pokemon, _stat: Statistic, _self_inflicted: bool, _amount: &mut i8) {}
+    /// This function allows a script attached to a Pokemon or its parents to prevent an incoming
+    /// secondary effect. This means the move will still hit and do damage, but not trigger its
+    /// secondary effect. Note that this function is not called for status moves.
     fn prevent_secondary_effect(&self, _move: &ExecutingMove, _target: &Arc<Pokemon>, _hit: u8, _prevent: &mut bool) {}
+    /// This function allows a script attached to a move or its parents to change the chance the
+    /// secondary effect of a move will trigger. The chance is depicted in percentage here, so
+    /// changing this to above or equal to 100 will make it always hit, while setting it to equal or
+    /// below 0 will make it never hit.
     fn change_effect_chance(&self, _move: &ExecutingMove, _target: &Arc<Pokemon>, _hit: u8, _chance: &mut f32) {}
+    /// This function allows a script attached to a Pokemon or its parents to change the chance the
+    /// secondary effect of an incoming move will trigger. The chance is depicted in percentage here,
+    /// so changing this to above or equal to 100 will make it always hit, while setting it to equal
+    /// or below 0 will make it never hit.
     fn change_incoming_effect_chance(
         &self,
         _move: &ExecutingMove,
@@ -190,25 +212,55 @@ pub trait Script: Send + Sync {
         _chance: &mut f32,
     ) {
     }
+    /// This function triggers when the move uses its secondary effect. Moves should implement their
+    /// secondary effects here. Status moves should implement their actual functionality in this
+    /// function as well, as status moves effects are defined as secondary effects for simplicity.
     fn on_secondary_effect(&self, _move: &ExecutingMove, _target: &Arc<Pokemon>, _hit: u8) {}
+    /// This function triggers on a move or its parents when all hits on a target are finished.
     fn on_after_hits(&self, _move: &ExecutingMove, _target: &Arc<Pokemon>) {}
+    /// This function prevents the pokemon it is attached to from being able to switch out.
     fn prevent_self_switch(&self, _choice: &TurnChoice, _prevent: &mut bool) {}
+    /// This function allows the prevention of switching for any opponent.
     fn prevent_opponent_switch(&self, _choice: &TurnChoice, _prevent: &mut bool) {}
+    /// This function is called on a move and its parents when the move fails.
     fn on_fail(&self, _target: &Pokemon) {}
+    /// This function is called on a script when an opponent fails.
     fn on_opponent_fail(&self, _target: &Pokemon) {}
+    /// This function allows preventing the running away of the Pokemon its attached to
     fn prevent_self_run_away(&self, _choice: &TurnChoice, _prevent: &mut bool) {}
+    /// This function prevents a Pokemon on another side than where its attached to from running away.
     fn prevent_opponent_run_away(&self, _choice: &TurnChoice, _prevent: &mut bool) {}
+    /// This function id triggered on all scripts active in the battle after all choices have finished
+    /// running. Note that choices are not active anymore here, so their scripts do not call this
+    /// function.
     fn on_end_turn(&self) {}
+    /// This function is triggered on a Pokemon and its parents when the given Pokemon takes damage.
     fn on_damage(&self, _pokemon: &Pokemon, _source: DamageSource, _old_health: u32, _new_health: u32) {}
+    /// This function is triggered on a Pokemon and its parents when the given Pokemon faints.
     fn on_faint(&self, _pokemon: &Pokemon, _source: DamageSource) {}
+    /// This function is triggered on a Pokemon and its parents when the given Pokemon is switched into
+    /// the battlefield.
     fn on_switch_in(&self, _pokemon: &Pokemon) {}
+    /// This function is triggered on a Pokemon and its parents when the given Pokemon consumes the
+    /// held item it had.
     fn on_after_held_item_consume(&self, _pokemon: &Pokemon, _item: &Item) {}
+    /// This function is triggered on a Pokemon and its parents when the given Pokemon gains experience,
+    /// and allows for changing this amount of experience.
     fn change_experience_gained(&self, _fainted_mon: &Pokemon, _winning_mon: &Pokemon, _amount: &mut u32) {}
+    /// This function is triggered on a Pokemon and its parents when the given Pokemon gains experience,
+    /// and allows for making the experience be shared across multiple Pokemon.
     fn share_experience(&self, _fainted_mon: &Pokemon, _winning_mon: &Pokemon, _shares: &mut bool) {}
+    /// This function is triggered on a battle and its parents when something attempts to change the
+    /// weather, and allows for blocking the weather change.
     fn block_weather(&self, _battle: &Battle, _blocked: &mut bool) {}
+    /// This function is called when a pokeball is thrown at a Pokemon, and allows modifying the catch
+    /// rate of this attempt. Pokeball modifier effects should be implemented here, as well as for
+    /// example status effects that change capture rates.
     fn change_capture_rate_bonus(&self, _target: &Pokemon, _pokeball: &Item, _modifier: &mut u8) {}
 
+    /// Helper function to turn the self into an Any for downcasting.
     fn as_any(&self) -> &dyn Any;
+    /// Helper function to turn the self into an Any for downcasting.
     fn as_any_mut(&mut self) -> &mut dyn Any;
 }