SLIP INTO RUBY: UNDER THE HOOD PART 6: BATTLERS!

Hello Sports Fans! I was feeling generous and I've just started sharing these with RMRK and rpgmakerweb, so you get a bonus early edition of



It's finally the time all (most (some (a few (none (because nobody reads these))))) of you have been waiting for: battlers! We're going to delve in and get all nitty-gritty with some of the most complicated code you're going to see in the default scripts, so buckle your seatbelts, put on some fresh pants and pack a lunch!

Game_BattlerBase
This is the base class for battlers. It mainly handles stuff like parameter calculations, and is the superclass of Game_Battler.

First, we have a bunch of constants. Constants are, as the name suggests, variable values which will never change. We set them here so we can refer to them later by name, and if we ever DO decide to change a constant's value we only have to change it in the constant declaration rather than hunting down every instance of a number in the code. By convention, constants are always named in block capitals.



These constants determine the code numbers of the various features you can set for things in the database. We'll look at this in more detail shortly.



These constants determine flag values for the Special Flag settings in features.



These constants determine the starting icon indexes for in-battle stat buffs/debuffs.

And now, public instance variables:



We've got three, all attr_readers (so they can be read but not written to directly): one each for HP, MP and TP.



Abbreviated methods for accessing the various parameters, as denoted by their comments. Every parameter you could ever need condensed to a handy three-letter acronym. As you'll see soon, param, xparam and sparam are all methods themselves.



Okay, so the constructor sets HP, MP and TP to 0, the @hidden flag to false (we don't want invisible battlers by default, do we?) and calls a bunch of flag/value-clearing methods to give us a fresh, blank battler ready for action!



@param_plus is an instance variable which tracks bonuses for the 8 main stats; clearing it is a simple matter of setting the variable to an array of eight zeroes.



Clearing states involves setting @states to an empty array, and @state_turns/@state_steps to empty hashes.

A hash is pretty similar to an array, but refers to its members with a unique key-value pair instead of an indexed value. The reason it's done like this is that although @states is only ever going to contain a finite array of each state from the database in sequence, @state_turns and @state_steps are constantly going to be filled with a mishmash of references to the different states the battler currently has, which can't be indexed with a standard array.



This method is for erasing one particular state, and involves deleting the state_idth element of @states, and the key state_id from both @state_turns and @state_steps.



Clearing buffs involves declaring a new array with 8 elements, each of which is 0, and setting @buff_turns to a blank hash. Note that as far as I'm aware "Array.new(8) { 0 }" is completely functionally identical to "= [0] * 8", so I'm not sure why they used two different ways of doing the same thing.



This method checks whether a battler has the given state; it returns true if the @states array includes the parameter state_id in its values.



This method checks whether a battler is dead by calling state? and supplying death_state_id as the parameter. This is itself a method which returns...



...1! This is of course changeable and you could even if you wanted have multiple death states with different effects.



This method gets the states as an object array by returning each ID's associated data. You've seen .collect before, nothing new to see here.



This method gets the list of current states as an array of icon indexes and deletes any zeroes (since a 0 would mean there's no icon there).



This method gets the current battle buffs/debuffs as an array of their icon numbers. It starts with a blank array. each_with_index is similar to each but also provides an index as a block variable: the block variables in this case are lv, which is the value of the current element (which in this case is the level of buff/debuff the battler has) and i, the index. The block pushes to the icons array the result of calling buff_icon_index with lv and i as parameters:



Okay, so this might need an example. Let's say the battler has a level 2 defence buff. The buff_level is greater than 0, so we run the first return statement. It returns ICON_BUFF_START (which from the constants above is 64) + (2 - 1) * 8 + 3 (the ID for def), which simplifies to 64 + 1 * 8 + 3, which results in 75. If you look up 75 in the icon sheet (bearing in mind it's zero-indexed) you'll see the def buff icon with two arrows.

If we have, say, a level 2 defence debuff on the other hand, the buff_level is less than 0 so we go with the second return statement:

ICON_DEBUFF_START + (-buff_level - 1) * 8 + param_id
80 + (-2 - 1) * 8 + 3
80 + -3 * 8 + 3
80 - 24 + 3
59

And again, looking up icon 59 shows the defence debuff icon with two arrows.



This method simply returns states, which itself returns the data for each state the battler has.



This method uses the inject method, which we've seen before. In this case, the initial value of the returned array is a blank array, the memo variable is r, and the object in the current iteration is obj. The features property of obj is added to r for each element in the array.

features is a built-in property of RPG::BaseItem, which is the superclass of RPG::State, which is the class of the states in the database. Features is itself an array of RPG::BaseItem::Feature, instances of which consist of a feature code, a data_id, and a value.

That seems like a lot to take in, so let's break it down. Take a state like Ironbody. Its only feature is Sp-Parameter: PDR * 10%, which means the battler with this state takes 10% of normal physical damage. Looking again at the constants, the feature code for Sp-Parameters is 23. PDR is the 7th parameter in the list, so the data_id is 6 (remember arrays are 0-indexed) and the value is 0.1, as that's the decimal representation of 10%. So the feature list for $data_states[17] (Ironbody) will be a 1-element array with an instance of RPG::BaseItem::Feature which has @code 23, @data_id 6, and @value 0.1.



This is a slightly more discerning method for getting a list of state features; select is a method which iterates through the calling array and returns a new array of all elements for which the supplied block returned true. In this case, the block is that ft (block variable containing the currently-iterating element) has the same code as the supplied parameter. For instance, calling features(FEATURE_ATK_TIMES) would return all features which affect number of additional attacks.



This is an even stricter getter for features, and requires additionally that the element's ID is also equal to the supplied ID. For instance, calling features_with_id(FEATURE_PARAM, 3) would return any features which affect defence.



This method calculates the complement of feature values, and takes two parameters, a code and an ID. Starting with an initial r value of 1.0, it loops through each feature matching that code/ID and multiplies r by its value. For example, features_pi(FEATURE_PARAM, 0) when the battler has two states reducing max HP to 25%:

In the first iteration of .inject, r is 1.0 and ft is the first state. r is multiplied by ft's value, 0.25, and becomes 0.25. In the second iteration, r is 0.25 and ft is the second state. r is again multiplied by ft's value, 0.25, and becomes 0.0625, which is the complement of the two states. As we'll see soon, this creates a curve for the bonus/penalty on stacked features.



Similar to the above, this method instead calculates the sum of the feature values. In our example, this will result in r being 0.5.



Similar to the above again, but this method calculates the sum of all features for a particular code, without worrying about the ID. So it would return the value of all features affecting x-parameters, for instance.



This method takes code as a parameter and then calls inject, with r initially being an empty array, on features(code), which we know returns a list of all features matching that code. It adds the array element ft.data_id but only if it isn't already part of r. |= is a useful operator for uniquely adding elements to arrays; it's essentially a shorthand way of writing "r = r | " (look up bitwise OR assignment for more details)



Method for getting the base value of parameters; it always returns 0. This method is overridden by param_base of the Game_Actor and Game_Enemy classes to get the actual values.



This method returns the param_idth element of the @param_plus array, which will correspond to the param_id supplied as a parameter to the method. For example param_plus(3) will return @param_plus which is the bonus value to defence.



This method returns the minimum possible value for a parameter. It returns 0 if the ID is 1 (max MP) but 1 otherwise. You can change this if you want minimum max MP to be 1, or have stats that can go down to 0.



This method returns the maximum possible value for a parameter. Returns 999,999 if the ID is 0 (max HP), 9,999 if the ID is 1 (max MP) or 999 otherwise.



This is a shortcut method that calls features_pi on the given param_id. In the case of my example from that method, param_rate(0) would return 0.0625 for the battler with two +25% max HP states.



This method returns the multiplier from buffs and debuffs for the given parameter. For example, a level 3 atk buff would result in param_buff_rate(2) returning 3 * 0.25 + 1.0, or 1.75. Note that it adds 1.0 and not 1 because that automatically makes the return value a float instead of an integer; if it had just been 1, the return value would have been 1 or 2 depending on which way it was rounded, which would be useless for a multiplier.



Okay, so here is where we return the actual values for parameters.

value is set to the param_base of the given param_id plus param_plus for that ID.
It's then multiplied by param_rate * param_buff_rate
Finally, the return value is the maximum of an array consisting of the minimum between value and param_max, and param_min.

Examples ahoy!

Okay, so let's say we've called param(2) to get attack power on a level 1 Eric. Level 1 Soldier has 20 ATK. He currently has no stat bonuses but a level 2 atk buff.

value = 20 + 0
value *= 1.0 * 1.5 (it's now 30 at this point)
[.min, 1].max.to_i

The minimum value between 30 and 999 is obviously 30, and the maximum between 30 and 1 is 30, so the return value is 30.



Getting the value of an x-parameter involves calling features_sum with FEATURE_XPARAM and the given ID. For example xparam(2) would return the sum of all modifiers to critical hit rate.



Special parameters use the complement of the values rather than the sum. So for example sparam(0) would return the complement of all modifiers to target rate.

Let's say we have two effects: one that decreases physical damage to 10% and one that reduces it to 20%.

r will initially be 1.0. In the first iteration, it's multiplied by 0.1 and becomes 0.1. On the second iteration, 0.1 is multiplied by 0.2 to become 0.02, so damage is reduced to 2% instead of 10%.



This method follows a similar principle for elemental damage multipliers. Let's say Eric currently has two states which reduce fire damage to 10%. First iteration becomes 0.1, second becomes 0.01, so it's reduced to 1%.



Exactly the same method, but for debuff rates instead of elements.



The same, but for state resistances.



Returns an array of all states the battler resists (those which they can't have added to them)



This method checks whether a particular state was resisting by seeing if it's included in the array returned by state_resist_set.



Gets the elements of an attack by returning all of the attack element features. As we'll see later, if the user has multiple attack elements, the engine will use whichever one the enemy is weakest to (for example, if an enemy takes 0% damage from fire and 200% from ice, and the user has both fire and ice attack elements, it will be treated as if the user's element were ice).



Same as elements, but for states which attacks inflict.



Calculates attack state infliction rate as the sum of all features which inflict it. For example, if you have two states that give a 50% chance to poison on attack, you'll poison on attack 100% of the time.



Determines attack speed modifier as the sum of all features which affect attack speed.



Determines the number of additional attacks as the sum of all features which add or remove attacks (picking the maximum value between that one and 0, so you can't have negative attacks in a turn)



Determines the skill types which are added as an array of the skill type IDs added by features.



Determines whether a skill type is sealed by checking whether the supplied skill type ID is included in features which seal skills.



Determines which individual skills are added by features.



Determines whether a supplied skill ID is sealed by checking whether its ID is included in features which seal skills.



Determines whether a particular weapon type can be equipped by checking whether its type ID is included in features which enable equipping weapon types.



Same thing, but for armour.



Determines whether the supplied equipment type is fixed (can't be unequipped) by checking whether its type ID is included in features which fix equipment.



Same thing, but checks for the type being sealed rather than fixed.



This method determines slot type (for which there is only one option: Dual Wield). Returns the maximum value from features which affect slot type, or 0 if there are none.



Returns true if the slot type is 1 (there is a feature somewhere for which "Dual Wield" has been chosen)



This one gets an array of the probabilities for which an additional action will be granted to the battler. For example, having two effects with the Action Times+ 25% feature will result in an array consisting of .



any? returns true if the supplied block ever returns true on any element passed to it. In this case, each feature which affects special flags (Auto Battle, Guard, Substitute and Preserve TP) is compared to the supplied flag_id, and returns true if they match.

In short, this method returns true if any special flag is set for the battler.



Returns the maximum value of the features which affect collapse type (Boss, Instant, and Not Disappear) or 0 if none are set.



Checks whether any party ability is set (Encounter Half, Encounter None, Cancel Surprise, Raise Preemptive, Gold Double or Drop Item Double).



Determines whether the battler is set to battle automatically by calling special_flag with the ID of the autobattle flag (0).



Determines whether the battler is set to guard by checking whether the guard flag (1) is set, and also that the battler is able to act.



Same thing, but for the substitute flag.



Same thing, but for the preserve TP flag.



This method allows a battler's bonus parameters to be increased given a param_id and value (for example, add_param(0, 25) will add 25 to max HP bonus). Refresh updates stats, as we'll see shortly.



This is a setter method for HP.



Setter method for MP.



HP change method for actors; allows HP to be modified by an amount rather than set to a specific one. Takes two parameters: value, and a flag for whether the actor can die as a result of the change.

If the enable_death flag is false AND adding the value to HP would result in it being less than 0, set it to 1. Otherwise, add value to HP.



Setter method for TP. Sets @tp to the maximum value between [minimum of TP and max TP] and 0. This prevents TP going below 0 or above max.



And here we see that max_tp returns 100. You could change this if you wanted more or less max TP in your game.



Okay, refresh does a few things. First, it goes through each state the battler resists and calls a block on it, supplying state_id as the block variable. It then calls erase_state on that ID (the logic being that if the battler resists a state we don't want them to have it)

HP is set to the maximum value between [minimum of HP and max HP] and 0. As with TP, this prevents HP going below 0 or above max. Same thing happens with MP.
Finally, if HP is 0 we add the death state; if it isn't, we remove the death state.



Method for full recovery. Clears states and sets HP/MP to maximum values.



Returns the percentage of HP the battler has, by, funnily enough, dividing HP by max HP. Note that it's cast to a float so that the return value is a float and not an integer. You could actually achieve the same effect by doing @hp / mhp * 1.0, but it doesn't really make a difference.



Returns the percentage of MP if it's greater than 0, or 0 otherwise.



Returns the percentage of TP. Oddly enough, I would have expected them to do @tp.to_f / max_tp in case you decide to change the max value. Not sure why they used 100 as a literal here. Be aware that if you do change the max, you'll need to change it here too.



Method for hiding the battler; simply sets @hidden to true.



Method for showing the battler; simply sets @hidden to false.



Returns the value of @hidden.



Returns true if the battler is not hidden, false otherwise (the logic being that battlers which aren't visible don't "exist" at that moment in time)



Returns true if the battler exists AND has the death state.



Returns true if the battler exists AND does not have the death state.



Returns true if the battler exists AND has no action restrictions.



Returns true if normal is true AND the battler isn't set to auto battle.



Returns true if the battler exists AND restriction is less than 4 (Cannot move, as seen in the database. The other possibilities are None, Attack an enemy, Attack anyone, or Attack an ally)



Sure enough, this one returns true if the battlers exists AND the restriction is between 1 and 3.



You may remember confusion_level from looking at Game_Action; here we see that its return value is the value of retriction if the battler is confused, or 0 otherwise. This means a confused battler will have a confusion level of 1, 2 or 3, which we saw in the part of Game_Action that deals with confusion.



This method always returns false. I guess this is a good point to tell you that quite a few of these methods (this one, the ones dealing with features, etc.) will be overloaded by the child classes for actors and enemies. We'll see this in practice soon.



Same thing for determining whether the battler is an enemy.



This method sorts the states, putting the ones with higher priority first. It uses an array to sort by both priority and ID, so when two states have the same priority the one higher in the list (lower ID) will be first.



This method takes the array of states, runs through it creating a new array of the restrictions for those states, adds 0 to the array, and takes the maximum value. In other words, it gets the highest restriction value of all states the battler has (the logic being that "cannot move" is higher priority than "attack an ally" which is higher priority than "attack anyone" which is higher priority than "attack an enemy")



This method goes through each state and if that state has a message3 set (the message for the state continuing to be active) it returns that message. If all are empty, it returns a blank string. As the states are sorted every time a new state is added, this will prioritise the highest-priority state that has a continuation message.



Determines whether a weapon type required for a skill is equipped. The superclass method always returns true; this will be overloaded by the child classes.



Determines the MP cost for a particular skill. Returns the supplied skill's MP cost * mcr as an integer. (MCR being MP Cost Rate)



Determines the TP cost for a skill. Returns the supplied skill's TP cost.



Determines whether the cost of a skill is payable. Returns true if the battler's TP is greater than or equal to the skill's TP cost AND their MP is greater than or equal to its MP cost.



This method processes payment of skill costs. It reduces the battler's MP and TP by the associated costs calculated.



This method checks whether the current situation is an appropriate one in which to use a particular item or skill. If the party is in battle, called the battle_ok? method of the item. Otherwise calls the menu_ok? method of the item. These are built-in methods of RPG::UseableItem which check whether the item/skill is set to Always/Only in Battle or Always/Only from the Menu respectively.



This method checks whether the conditions are met to use a particular item or skill. Returns true if the battler is capable of acting and it's the appropriate situation.



Determines whether conditions are met to use a particular skill. Returns true if its conditions are met AND the user has the appropriate weapon type required for the skill AND the user can pay the skill's cost AND the user doesn't have that skill sealed AND the user doesn't have the skill's type sealed. Phew!



Item conditions are a bit more forgiving: is it the appropriate situation? Does the party have one? Have at it!



Determines whether an item or skill is useable. Checks whether it's of type RPG::Skill or RPG::Item and calls the appropriate conditions_met? method. Returns false if the item is neither of those things.



Determines whether a given item is equippable. Returns false unless it's of type RPG::EquipItem (you can't equip something that isn't equipment after all). Return false if the battler has that equipment type sealed. Return the result of checking whether the battler can equip the item's weapon type if it's a weapon, or its armour type if it's armour. Otherwise, return false.



Determines the skill ID for a normal physical attack, which in the default battle system is 1.



Determines the skill ID for the Guard command, which by default is 2.



Determines whether a normal attack can be used by calling usable? on the skill corresponding to attack_skill_id from the database.



Same thing, but for Guard.

Okay, so that's finally it for Game_BattlerBase! I don't know about you but I'm exhausted after all that. Take a breather. Go have a cup of tea. I'll be here waiting.

All refreshed? Great, let's continue.

Game_Battler
Child class of Game_BattlerBase, this one handles stuff like sprite manipulation and processing actions. It's the superclass for Game_Actor and Game_Enemy. It's almost like we're evolving Pokémon here!

First, constants.



The constants for various effects should be fairly self-explanatory by this point.



There's also one for the special effect escape.

Public instance variables!



Again these should all be pretty self-explanatory.



Okay, so on construction we're setting @battler_name to a blank string, @battler_hue to 0, @actions to an empty array, @speed to 0, @result to a new instance of Game_ActionResult (pointing to the battler it belongs to, as we discussed before), @last_target_index to 0, @guarding to false, calling clear_sprite_effects, and calling super (which calls the Initialize method of the superclass, in this case Game_BattlerBase).



Clearing sprite effects involves setting @animation_id to 0, @animation_mirror to false, and @sprite_effect_type to nil.



Method for clearing actions; clear is a method which removes all elements and results in the array being empty.



Clearing states involves calling the same method of the superclass and also calling clear_status_effects in @result, a method we've already seen.



Method for adding a new state to the battler, given a state_id as parameter. Checks to see whether the state is addable: if it is, call add_new_state with that ID unless the battler has it already. Reset the state counts for that state, and uniquely push that ID to the added_states property of @result. (uniq! in this case meaning to add the element in place to the @result array rather than returning a new one, and only adding the element if it isn't already there)



This is the method which determines whether the state can be added. Okay, so it'll return true if the battler is alive AND there is a database entry for the given state ID AND the battler doesn't resist the given state AND the battler hasn't had the same state removed during the same action AND the given state isn't removed by the action restrictions the battler currently has in place.



Determines whether the given state was already removed during the same action by checking whether the removed_states property of @result includes the state_id supplied.



Determines whether the given state would be removed by the battler's current restrictions (if it is, there's no point in adding it). Checks whether the state is set to "remove by restriction" AND the battler's restriction level is greater than 0.



Adds a new state. If the supplied ID is the death state ID, call die. Push the ID to the @states variable, call on_restrict if the battler's restriction is now greater than 0, sort the states, and refresh.



This method clears any actions the battler currently has queued, and then for each state they have, remove it from their states if that state is removed by restrictions.



This method resets the turn and step counts for a given state. state is set to the database entry for the state_idth state. Variance is set to 1 + the maximum value between (the maximum turns the state lasts - the minimum turns the state lasts) and 0.

Example: Blind in the default database is set to expire between 3 to 5 turns. In this case, variance will be 1 + [5 - 3, 0].max = 1 + 2 = 3.
@state_turns for the supplied ID is then set to the minimum turns (in this case 3) + a random number between 0 and the variance (0-2) so Blind will last between 3 and 5 turns.
Finally, @state_steps for the supplied ID is set to the number of steps set for removing the state (which will only be relevant if "remove by walking" has been set for the state)



Removes a state from the battler. First checks to see if they actually have the state in question: if they do and the state is death, call revive. Erase the state from the battler's list of states, refresh their stats, and uniquely push the state ID to @result's removed_states property.



Method for killing a battler. Sets their HP to 0 and clears their states/buffs. (interesting change you could make to this: have status ailments that persist through death)



Method for reviving a battler. Sets their HP to 1 if it's 0.



Method for the battler escaping from battle. Hide them if the party is in battle, clear their actions and states, and finally play the escape sound effect.



Method for adding a buff to the battler. Return unless the battler is alive (you can't buff a dead character). Add 1 to the param_idth element of @buffs unless that parameter is already buffed to its maximum level. Reset the buff state if that parameter was debuffed. Overwrite the duration in turns, uniquely push the param_id to @result's added_buffs property, and refresh.



Method for adding a debuff. Works almost identically to add_buff but subtracts one from @buffs instead of adding and erases if the character was already buffed. And obviously it pushes to added_debuffs instead of added_buffs.

Interesting note about the way buffs/debuffs work by default: if you have, say, a level 2 buff to atk, any atk debuff at all will reset it to 0. Likewise if you have a level 2 debuff, any buff will reset it. You could change this if you wanted so that buffing a debuff or debuffing a buff only adds/removes one level.



Method for removing a buff to a given param_id. Return unless alive again, obviously. Return if the level of buff for that param_id is 0 (which means no buff). erase the buff, delete the turns entry for it from @buff_turns, uniquely push the ID to @result's removed-buffs, and refresh.



Method for erasing a buff. Simply sets the param_idth element of @buffs to 0, and also sets the param_id key for @buff_turns to 0.



Determines whether a given param_id is buffed. Returns true if its buff level is greater than 0, false otherwise.



Same thing, but for debuff.



Determines whether the buff for a given param_id is at maximum level. Returns true if the level is 2, false otherwise.



Same thing but for debuffs.



Sets the param_id key of @buff_turns to the supplied turns value but only if the current number of turns is less than the new value. (doesn't overwrite if calling the method would result in a shorter buff)



Updates the turns left on states. Runs through each state and subtracts 1 from its turn count if the turn count is greater than 0.



Same thing, but for the buff turn counts.



Runs through each state and removes it if it's able to be removed at the end of battle (this method is only called when battle ends).



Ah, we haven't seen the times method for a while. This one basically loops through however many elements @buffs has at the time and removes each one.



This method removes states set to expire automatically. The supplied timing value will either be 1 (end of action) or 2 (end of turn).

Runs through each state and if the number of turns on it is 0 and that state's auto-removal timing is equal to the timing value supplied, remove it.



Automatically removes buffs that have expired. Runs through each buff present; goes to the next element if there's no buff OR the number of turns left on it is greater than 0. If it passes that check, removes the buff in question.



Removes states that expire on damage. Runs through each state, and if it's set to remove by damage AND a random number from 0-99 is less than the percentage chance set for the state being removed, remove it.



Wow, this one looks a bit more complicated than we're used to. Okay. We already know from Game_BattlerBase that action_plus_set is an array of the percentage chances for getting an extra action. Let's say we've got two effects, one for 25% and one for 15%. We're calling inject, with an initial value of 1, a memo variable r, and obj variable p.

If a random number between 0 and 1 is less than p, return r + 1, otherwise return r.

Let's say that the random number for the first iteration is 0.593848blah. It's not less than 0.25, so we return r, which is 1. The second iteration gives 0.0483983, which is less than 0.15 so we return r + 1, 2. The battler will get 2 actions this turn.



This method creates an array of actions for the battler. First, actions are cleared. We return unless the battler is movable, as there's no point in setting up actions for a battler that can't act. Then @actions is set to a new array with make_action_times elements, and the block sets each element to a new instance of Game_Action with the battler as the subject. In our example where the battler gets 2 actions, this will result in @actions being a 2-element array containing two instance of Game_Action.



This method sets @speed to the minimum value of an array consisting of the speeds of all actions being taken, or 0 if there are no actions to collect.



Returns the first element of the @actions array, which is naturally the current action being performed.



Removes the current action, which removes the first element of @actions and returns it.



This method forces an action on the battler and takes two parameters: a skill ID and a target index.
First the battler's actions are cleared, then action is set to a new instance of Game_Action and its set_skill method is called with skill_id as the argument. If the target index is -2, the target index of the action is set to last_target_index (as -2 denotes the most recent target of an action). If target index is -1, decide on a random target. Otherwise, set the action's target index to the argument given. Either way, push action to the @actions array.



Okay, so this is the method which determines how much damage a given skill or item does and takes two parameters: the user and the item in question.

item.damage is a built-in instance of RPG::UsableItem::Damage and its eval method is as follows: eval(a, b, v) (a is the user, b is the target, and v is the in-game variable array)

Looking at the source for the eval method, we see that it processes thusly:

[Kernel.eval(@formula), 0].max * sign rescue 0

Kernel is a module defining methods which can be referred to by any class. Its eval method takes the string (expr) as an argument and evaluates it as a Ruby program, returning the result. What we're basically saying here is "evaluate the damage formula as a program and return the maximum value between its return value and 0, multiplied by the damage sign (-1 if recovery, 1 otherwise) with 0 as a rescue return value (in other words, if evaluating the formula results in an error).

Take as an example the formula for a standard attack: a.atk * 4 - b.def * 2

We already know that in eval a is the user and b is the target. In this case the target is self, as the battler is finding out how much damage is being done to itself by an external source. $game_variables is passed I believe so that you can use v[n] in the formulae. So Kernel.eval will calculate the user's attack * 4 - the target's defence * 2 and return the result, which will be stored in value.

After this, the value is multiplied by the result of item_element_rate with the user and item as arguments (which will give an elemental multiplier based on the elements used in the attack, as we'll see shortly).

Then the value is multiplied by PDR if it's a physical attack or MDR if it's a magical attack (it can't be both), then multiplied by REC if it's set to recover HP.

Value is then set to the result of apply_critical with value as the argument if @result.critical is true. It is then set to the result of apply_variance with value and the damage variance as arguments. It is then set to the result of apply_guard with value as the argument. Finally, make_damage is called for @result, with the integer representation of value and item as arguments.



This is the method that determines an item's elemental multiplier. If the element ID of the item itself is less than 0, we check whether the user's attack elements list is empty. If it is, we return 1.0, otherwise we return the result of elements_max_rate on the user's attack elements. If the item's element ID is NOT 0, we return the result of element_rate on the item's element ID (this shows us that having a specific element for an item or skill overrides any intrinsic elements the user has)



This is the method that determines the maximum elemental multiplier, given an array of element IDs. We've seen inject several times now so what this is doing should be obvious, but the bottom line is that it's starting with 0.0, looping through each element passed to it and adding it to an array, then taking the maximum value from the array as the return value.



Criticals are pretty simple: the damage is just multiplied by 3.



Applying variance is fun! I've had to examine this one before, so let's see if I remember the mistake I made last time. First of all we're supplying two parameters, damage and variance. Variance is pulled from the database setting.

amp is set to the integer form of the maximum value between (the absolute form of damage * variance / 100) and 0. So say we've got 500 damage and variance is 20. This results in amp = .max.to_i = .max_to_i. The result of which is obviously 100. The .max part is just there to make sure variance isn't negative (though I don't see how it can be as variance can't be set below 0 and .abs ensures we're never dealing with negative damage values)

var is then set to a random number between 0 and amp+1 + another random number in the same range - amp

Let's say we get 34 and 95, var will be 29.

If damage is greater than or equal to 0, var is added to it. Otherwise, var is subtracted from it. In the example case, damage is now 529.



If damage is greater than 0 AND the battler has the guard special flag, return damage / (2 * GRD (GuaRD effect rate)); otherwise return damage / 1. In our example, if the battler had the guard flag and their GRD was 125%, the damage would be reduced to 423.



This is the method that actually does the damage, taking user as a parameter. Calls on_damage with @result.hp_damage as the argument if the damage was greater than 0, subtracts the HP damage from the battler's HP, the MP damage from the battler's MP, and adds to the user's HP/MP if any was drained.



Method for using a skill or item. First pays the skill cost if it's a skill, or consumes the item if it's an item. Then for each effect in the item's effects, it calls item_global_effect_apply, with effect as the argument.



This is the method called above for consuming an item, and calls the method of the same name from $game_party.



If the effect's code is EFFECT_COMMON_EVENT (44), call $game_temp.reserve_common_event supplying the effect's data ID as the argument (which will be the ID of the common event set in the database)



This method tests various scenarios to see if it actually makes sense to use an item or skill. Returns false if the item/skill is for a dead ally and the battler isn't dead. Returns true if in battle. Returns true if the item/skill is for an enemy. Returns true if the item/skill has recovery AND affects HP AND the battler's HP is less than their max HP. Returns true if the item/skill has recovery AND affects MP AND the battle's MP is less than their max MP. Returns true if the result of calling item_has_any_valid_effects? with user and item as arguments returns true. Otherwise, return false.



This method determines whether a given item has any valid effects. Runs through each effect and returns true if any of them return true for the block calling item_effect_test with user, item and effect as arguments.



Determines a skill/item's counterattack chance. Returns 0 unless it's a physical attack. Returns 0 unless opposite?(user) returns true, which checks that the effect came from an enemy. Otherwise, returns CNT.



Determines reflection rate of a skill/item. Returns MRF if it's magical, 0 otherwise.



Determines hit rate of a skill/item. rate is set to the success rate of the item * 0.01 (so 100% becomes 1) and multiplied by the user's hit rate if it's physical (which by default in most cases is 95%, so 1 would become 0.95) and the calculated rate is returned.



Determines the evasion chance for a skill/item. Returns EVA if it's physical, MEV if it's magical, 0 otherwise.



Calculates critical chance for a skill/item. If the item is set to allow critical hits, return the user's CRI * (1 - CEV), otherwise 0.

For example, most characters by default have a crit rate of 4% and no critical evasion. This would result in a critical rate of 0.04 * (1 - 0) = 0.04.



Applies the effects of a normal attack; calls item_apply with attacker and the attack skill details as arguments.



Okay, first we clear @result, then set its used flag to the result of item_test with user and item as arguments. We then set its missed flag to the result of checking whether used is true AND a random number between 0 and 1 is greater than or equal to the user's hit chance. We then set its evaded flag to the result of checking whether it did NOT miss AND a random number between 0 and 1 is less than the evasion chance.

If it hit, unless the item/skill does no damage, we set @result's critical flag to the result of checking whether a random number between 0 and 1 is less than the critical hit chance. We then call make_damage_value with user and item as arguments, and execute_damage with user as the argument.

After that's done, we call item_effect_apply for each item effect with user, item and effect as arguments, and finally call item_user_effect with user and item as arguments.



This method tests the result of using an item or skill, with a given user/item/effect.
First we check what the effect's code is:
If it involves recovering HP, the return value is the result of checking whether HP is less than max HP OR the effect's value is less than 0 OR the effect's second value is less than 0.
If it involves recovering MP, the return value is the result of checking whether MP is less than max MP OR the effect's value is less than 0 OR the effect's second value is less than 0.
If it involves adding a state, the return value is whether the battler does NOT have the state in question.
If it involves removing a state, the return value is whether the battler has the state in question.
If it involves adding a buff, the return value is whether the battler already has the max level buff for the given stat.
If it involves adding a debuff, the return value is whether the battler already has the max level debuff for the given stat.
If it involves removing a buff, the return value is whether the battler has that buff.
If it involves removing a debuff, the return value is whether the battler has that debuff.
If it involves learning a skill, the return value is whether the battler is an actor AND their skills don't already include the one in question.
Otherwise, return true.



This method determines what effect is happening and calls the appropriate method for processing it. method_table is set to a hash table where the keys are constants and the values are symbols pointing to the methods corresponding to that effect. For example, EFFECT_RECOVER_HP equates to 11 (which is the key) and the value is the symbol :item_effect_recover_hp.

method_name is set to the key in method_table corresponding to the supplied effect's code.
Then, if method_name is not nil, we call send with the arguments method_name, user, item and effect.

send allows you to invoke another method by name (in this case whichever symbol matches) and what follows determines the parameters the method receives.



This method recovers some amount of HP. The value is set to (max HP * the percentage HP recovery + the static HP recovery) * REC (RECovery effect rate). Let's say we have a potion that recovers 10% + 20 HP, and use it on a character with 200 max HP and 150% REC:

value = (200 * 0.1 + 20) * 1.5 = (20 + 20) * 1.5 = 60

value is then multiplied by the user's PHA (PHArmacology) if the item is an actual item and not a skill. It's finally converted to an integer.

@result's HP damage has value subtracted from it; the success flag is set to true, and the battler's HP is increased by value.



This is pretty much identical to the HP recovery effect but for MP instead.



Similar method for gaining TP. Only works in absolute values and not percentages, so the calculation is easier.



This method adds states set in the item's effects. If the ID is 0 (normal attack) the item will try to inflict any states that the user's normal attack is capable of. Otherwise, it will add the state specified.



For each of the user's potential attack states (states it can add with physical attacks), set chance to the effect's value1. Multiply it by the battler's state rate for that state. Multiply it by the user's attack state rate for that state. Multiply it by the user's luck effect rate. If a random number between 0 and 1 is less than chance, inflict the state and set @result's success flag to true.



This method adds a specified state. Follows a similar chance calculation to the previous one, but obviously without the user's state rates coming into play, and state_rate/luck effect are only taken into account if the state is added by an enemy.



No modifiers for removing states, just a straight percentage chance.



This method simply adds the given buff.



This method adds the given debuff. chance is determined as the battler's debuff rate for the specific stat, multiplied by the user's luck effect rate.



Removes the given buff if the battler has it, and sets @result's success flag to true.



Removes the given debuff if the battler has it, and sets @result's success flag to true.



The only special effect is "escape" as you can see from the code. The way they've set this and some other fields up makes me wonder if they intend on adding more in a patch or something.



This method gives a bonus to the specified stat and sets @result's success flag to true.



This method teaches the specified skill if the battler is an actor, and sets @result's success flag to true.



This doesn't actually do anything as common event handling was done by earlier code. I think it's just here to catch the effect code for common event.



This method adds TP to the user equal to the item's TP gain * the TCR (TP Charge Rate) of the user.



This method determines the user's luck effect rate. Let's say the user has 15 luck and the target has 1:

[1.0 + (15 - 1) * 0.001, 0.0].max =
[1.0 + (14) * 0.001, 0.0].max =
[1.0 + 0.014, 0.0].max =
[1.014, 0.0].max =
1.014

So the luck modifier will give an additional 1.4% to the calculation.



Determines if the relation is hostile: returns true if the result of checking whether the current battler is an actor is not the same as checking whether the supplied battler is (so either we'll get an actor and a not-actor, or a not-actor and an actor) OR if the battler is currently reflecting magic.



This method doesn't actually do anything, but is overloaded by the method of the same name in Game_Actor.



Initialises TP; it'll end up being a value anywhere from 0 to 25.



Clears TP, which is to say sets it to 0.



Charges TP by damage taken; damage_rate, as we'll see shortly, is the percentage of HP that was taken off by the attack.

Let's say for example we have a battler with 500 HP that's just taken 20 damage. damage_rate will be 0.04. With a TCR of 0, they will gain 50 * 0.04 = 2 TP.



This method regenerates HP.

damage is set to the integer form of the negative of (mhp * hrg (HP ReGeneration rate)

Let's say a battler has an HP regeneration rate of +10% and max HP of 500; damage will be -50.

We call perform_map_damage_effect if the party is in battle and damage is greater than 0.
@result's HP damage is set to the minimum value between damage and max_slip_damage.
The battler's HP is then reduced by @result's HP damage.



If "KO by slip damage" is checked in the database, we return HP, otherwise we return the maximum value between (HP - 1) and 0. In the case of our regen example above, @result's HP damage is set to -50, and we remove -50 HP from the battler, so they regain 50 HP.



Almost the same principle as regenerating HP, but for MP and using MRG.



Regenerating TP adds 100 * TP Regen Rate to the battler.



This method calls all regeneration methods if the battler is alive.



This method initialises TP when battle starts unless the battler has the "preserve TP" flag set.



At the end of an action, clears @result, removes states set to automatically expire after actions, and removes auto-expiring buffs.



At the end of a turn, clears @result, regenerates HP/MP/TP, updates the state/buff turns, and removes any states set to expire at the end of a turn.



At the end of a battle, clear @result, remove battle states, remove buffs, clear actions, clear TP (unless the flag is checked) and call appear, which unhides the battler if they were hidden.



Method called when taking damage; removes states that fall off when damaged and charges TP.

Phew! We've covered a LOT of material in just two classes. I was going to do Game_Actor, Game_Enemy, Game_Actors, Game_Unit, Game_Party and Game_Troop as well but I think we've gotten into ludicrous length territory as-is so I'll leave those for next week.

As always, all comments and criticisms welcome.

Until next time.