Create a battle history

Principle

A history is composed of four elements:

1. A history class: stores the data of an entry (turn, contextual data, utility methods).
2. An attr_reader on PokemonBattler: exposes the array of entries.
3. An initialization in the PokemonBattler constructor: creates the empty array.
4. An add_X_to_history method on PokemonBattler: adds an entry to the array.

The feeding is done from the handler or procedure concerned, at the moment the action occurs.

Step 1: create the history class

Create a file in 5 Battle/03 PokemonBattler/ (e.g., 103 HealHistory.rb).

module PFM
  class PokemonBattler
    class HealHistory
      # @return [Integer] the turn when the heal occurred
      attr_reader :turn
      # @return [Integer] amount of HP healed
      attr_reader :amount
      # @return [PFM::PokemonBattler, nil] launcher of the heal
      attr_reader :launcher
      # @return [Battle::Move, nil] move that caused the heal
      attr_reader :move

      def initialize(amount, launcher, move)
        @turn = $game_temp.battle_turn
        @amount = amount
        @launcher = launcher
        @move = move
      end

      def current_turn?
        return @turn == $game_temp.battle_turn
      end

      def last_turn?
        return @turn == $game_temp.battle_turn - 1
      end
    end
  end
end

• The turn is always captured from $game_temp.battle_turn in the constructor.
• The current_turn? and last_turn? methods are the standard pattern across all histories.
• The attributes depend on what you want to track.

Step 2: declare the attribute on PokemonBattler

In 001 PokemonBattler.rb, add the attr_reader:

# Get the heal history
# @return [Array<HealHistory>]
attr_reader :heal_history

Step 3: initialize the array

In the initialize method of PokemonBattler, add the initialization:

@heal_history = []

Step 4: create the add method

In PokemonBattler, add the method that creates and appends an entry:

def add_heal_to_history(amount, launcher, move)
  @heal_history << HealHistory.new(amount, launcher, move)
end

Feeding the history

Call add_X_to_history from the handler or procedure that performs the action. Here is where existing histories are fed:

History	Fed from
move_history	proceed_internal (always, even on failure)
successful_move_history	proceed_internal (only on success)
damage_history	DamageHandler#damage_change
stat_history	StatChangeHandler#stat_change

For a custom history, the call goes in the same place as the action:

# In the relevant handler or procedure
target.add_heal_to_history(amount, launcher, skill)

Existing histories -- reference

MoveHistory

Attribute	Type	Description
turn	Integer	Turn of use
move	Battle::Move	Copy (dup) of the move
original_move	Battle::Move	Direct reference to the move object
targets	Array<PFM::PokemonBattler>	Affected targets
attack_order	Integer	Pokémon's attack order this turn

SuccessfulMoveHistory inherits from MoveHistory without additions.

DamageHistory

Attribute	Type	Description
turn	Integer	Turn of damage
damage	Integer	Amount of damage taken
launcher	PFM::PokemonBattler, nil	Launcher of the damage
move	Battle::Move, nil	Move that caused the damage
ko	Boolean	Whether the Pokémon was KO'd

StatHistory

Attribute	Type	Description
turn	Integer	Turn of the change
stat	Symbol	:atk, :dfe, :spd, :ats, :dfs, :acc, :eva
power	Integer	Power (positive = increase)
target	PFM::PokemonBattler	Target of the change
launcher	PFM::PokemonBattler, nil	Launcher of the change
move	Battle::Move, nil	Move that caused the change

Conclusion

• Create a history class with turn, current_turn?, last_turn?, and specific attributes.
• Declare an attr_reader on PokemonBattler and initialize the array in initialize.
• Add an add_X_to_history method that creates and appends the entry.
• Call this method from the handler or procedure at the moment of the action.