Character Stat Code Documentation

The stat calculation javascript (Swtor.Calc.Standalone.js) serves two purposes: it is a generic, public script for anyone to use on a Mr. Robot SWTOR character profile and retrieve updated stats. The second, more specific purpose is to drive the character stat panel on the Mr. Robot SWTOR Character Builder.

Modifications to the javascript should keep both of these scenarios in mind.

There are a lot of stats that get calculated -- a full list can be found in the Character Stat List.

Public API

The public API is documented here: Character Stat API. The public API should not be modified except to add functionality requested by the community. It basically consists of the getProfileStats method.

Generic/Supporting Code

The Swtor.Calc.Standalone.js file contains several supporting modules that do not need to be modified:
  • TeamRobot (Tr) module
  • TeamRobot.Swtor module
  • TeamRobot.Swtor.Calc.Armor module
  • TeamRobot.Swtor.Calc.Rating module
  • TeamRobot.Swtor.Calc.Shield module
  • TeamRobot.Swtor.Calc.Weapon module
The first 2 modules are "plumbing" for compatibility with the Team Robot code base, and provide some generic methods. The last 4 modules contain data extracted from the game, and are used to get the proper values of certain item stats.

TeamRobot.Swtor.Calc

This is the main module that needs to be kept up-to-date with game mechanics. The main method that does work is getAllStats. The rest of the methods are organized to break up the calculations done by this method into logical groups.

Code Structure

For those new to javascript, this section describes the code structure in a pragmatic fashion to get you comfortably editing stat formulas without worrying about the details of javascript programming. If you want more background, the general pattern used is described here: Module Pattern.

In general: a method that looks like the following is a "private" method, and you can make as many such functions as you like when writing your code:
function doSomething() {
}

There are also a few "public" methods that look like this:
calc.getStatGroups = function (profile, comp) {
};
The signatures of these functions (the name, number and order of parameters) should not be changed. The contents can be changed if necessary, though you will likely only need to change calc.getAllStats.

calc.getAllStats

This is the main method, the BIG ONE, the bad boy. For those unfamiliar with javascript, there are some more complex sections that you can safely ignore -- this documentation is designed to point you to the likely places you will need to edit.

Lookups

The following lookups should be reviewed and updated periodically:
  • healthLookup -- the amount of base health at each character level
  • companionToAdvancedClass -- maps each companion to an advanced class; there is one "special" advanced class called "MeleeAim" to deal with Aim-based melee companions like Torian.

Generic Calculations

There are two generic calculation methods that should be reviewed and updated periodically:
  • getDiminishedStat -- the main diminishing returns formula for SWTOR. At present (pre-2.0 code), this is a function of 3 variables: r, b, and N.
    • r -- roughly: rating / level
    • b -- one of the DR constants
    • N -- another DR constant
The lookups dr_b and dr_N are used to drive this method. Also, N_crit_primary is the N value for calculating DR on crit from primary stats like Strength.
  • getBaseStats -- gets base stats as a function of character level.

The Main Method

First, description of the parameters:
  • profile -- a Mr. Robot character profile object. See Character API Documentation for more details.
  • gearSet -- an array of the player's gear; technically the gear also exists on the profile object, but it is possible in some places for a profile to have multiple gear sets. Thus, getAllStats is explicitly given the gear set on which to calculate.
  • comp -- if calculating for a companion, this is the companion ID (or null or 'None' if calculating for a normal player)
  • buffs -- array of the active buffs (or an empty array if no buffs)
  • stance -- string, active stance ID (or null)
  • stimLevel -- 0 (None), 1 (Exotech), 2 (Rakata), 3 (Prototype Hyper-Battle)
  • stimType -- None, Will, Strength, Aim, Cunning, Endurance

Most of the code of this method should not need modification. The main work is done by separate functions. There are a few sections that may need review though:
  • calculation of presence stats for companions
  • calculation of the various DR stats (AccuracyBonus, CritStrengthBonus, etc.) -- assuming that a similar DR approach is being used in 2.0, this can probably be handled by just updating getDiminishedStat, but who knows what wacky things they might have done...

So enough background -- on to the main methods that do work:

applyDatacronsToStats

Very straightforward, adds stats from datacrons. Each datacron has an ID -- a poor-man's documentation of that is here: Datacron List

The new 2.0 datacrons have not been added as of authoring this. They are a good example of how to modify this code: looking at the datacron list, datacron 94 gives 10 presence. So all you would need to do is use the existing helper method:
addDatacronStat([94], 'Presence', 10);

applyBuffsToStats

Applies buffs, stims, and stances to stats. "buffs" is an array of buff IDs (as strings). All cases that would be provided via a character profile are already coded -- the values may need tweaking. (Feel free to let us know if a buff/stim/stance needs to be added/removed from character profiles).

This is a good example of using the incrementStat method. This is the main way to change the value of a stat, parameters described here:
  • stats -- the main stats object that has a property for each stat
  • stat -- the stat to increment (as a string)
  • inc -- the amount to increment stat by (this method is additive)

applySkillsToStats

Applies skill trees to the stats. This method itself doesn't need modifications, but warrants some explanation: based on the advanced class, it will call an advanced class specific method to apply the skill tree stat modifications. This obviously does nothing for companions, with one exception: the Sorcerer/Sage presence bonus skill needs to be applied to companions. Below this method, you will see functions specific to each advanced class, e.g. skillFuncs.Powertech. This is where the main work needs to be done.

Skill Function Parameters:
  • stats -- the main stats object that has a property for each stat
  • lvl -- the character's level
  • trees -- a 2-dimensional array of the player's skill points: the first index is the tree (0, 1, or 2 from left-to-right as they appear in-game); the second index is the position in that tree, starting bottom-left and going left-to-right, bottom-to-top (starts at 0, ignores blank spaces that do not have a skill in them)
  • stance -- the player's active stance ID (string)

The existing code should serve as an example of how to access the number of points in any skill, e.g. trees[1][3] for a Powertech is the number of points in the Prototype Cylinders skill of the Advanced Prototype tree.

applyLegacyBonusesToStats

Add legacy bonuses. There are two properties on the profile: LegacyCompanionCount, the number of completed companions; and LegacyCompanionBonuses, an array of the specific bonuses active by companion type.

addRangedStats, addMeleeStats, etc.

The other main methods add stats for each block as it appears on the character sheet: Ranged, Melee, Tech, Force, Defense, PvP. These methods should be relatively self-explanatory. There are a few lines of code that may seem extraneous, e.g.
stats['TechCritCunningBonus'] = stats['CritCunningBonus'];
This creates a new stat called "TechCritCunningBonus" that is exactly the same as "CritCunningBonus". Just roll with it -- they are used by the user interface on AMR to display tooltips correctly.


And that's about it -- the major work that needs to be done with game updates is updating the skill tree calculations, and with a major patch like 2.0, some of the DR formulas probably need fixing.

Testing

And of course... test your calculations! Read the Character Stat API for an easy example of how to test. We would recommend creating a character profile on Mr. Robot that matches your in-game character, then compare the calculated stats with your in-game character sheet stats.

Last edited Apr 24, 2013 at 5:45 PM by Yellowfive, version 8

Comments

No comments yet.