There are many calculators out there for planetarion, many of them are used by alliances from their private web sites, often incorporating these calculators into the sites requires hours of sifting through html code to find the key variables required to set up the link and to populate the calculator from internal data. This page is intended to try and reduce the effort required to integrate the calculator into web sites. All of the variables and values are case sensitive so its important to check the case of any variables or values should you encounter difficulties.
Each race can be selected for both defence and attack, this is allows races to hidden or shown. The races are selected with either "att" or "def" followed by the first letter of the race to decide which side of the calc is going to be modified. So this gives the following variables :-
"attt", "attc", "attx", "attz" and "atte" for the attacking races and "deft", "defc", "defx", "defz" and "defe" for the defending races, with a value of "checked" to make that race visible just skip the variable to hide it.
For classes it is possible to define them using "u" followed by the 2 letter abbreviation for that class, "u" stands for use in case you are wondering. This gives the following variables "ufi", "uco", "ufr", "ude", "ucr" and "ubs", setting these to checked will allow these to selected in fleet suggestions, this is not really a very useful set of switches for interfacing, not suppying any of these variables is the same as checking them all.
The ship variables are made up from either "Att" or "Def" followed by the first 7 characters of the ship name capitolised, the following php code creates the abbreviated ship name from the full name an formats it appropriately..
$org_name = ucwords(strtolower($org_name)); // convert the ship names to uppercase on each word
$paramname = str_replace(" ", "", $org_name); // remove any spaces from the name
$paramname = substr($paramname, 0, 7); // get the first 7 characters of the name
return $paramname; // return the ship abbreviation
so all the ship names can be created with something like $HomeName = "Def".$ships["ABR_name"][$i]; these variables allow the numbers of each ship to be defined in the url. Missing out the ship variable make the calc assume a value of 0.
It is possible to hide ships on either side that have a count of 0 (zero), this allows the calculator to use less screen area for larger battles, the following options may be set, "AutoShipsD", "AutoShipsA" and "AutoShips", setting these values to checked activates the zero ship hiding feature, "AutoShipsD" hides ships on the defence side, "AutoShipsA" hides ships on the attack side and "AutoShips" hides ships on both sides.
There are variables to allow the value and roids of both sides to be entered and the number of structures for the defenders, this allowes the calculator to accurately calculate XP/Roid gains for the attacker and with the attackers roids it also allows the time to recover any lost ships. The roids and structures allow the change in values of both sides to be calculated. the following variables define these values :-
DefValue = the defenders value
AttValue = the attackers value
DefMetal = the number of defenders roids (this should have been changed to DefRoid but people were already interfacing to it)
AttRoid = the number of roids the attacker has
DefStruc = the number of structures the defender has (generally not very useful)
The calculator makes use of a little trick to make selection of buttons in the url easier, all of the buttons have the same name, which is ticks, the value of the buttons is used to decide what is actually being pressed, in case you are not familiar with the the button value, the value is the texted thats displayed on the button in the browser. So to use a button in the url simply set ticks to a the text from one of the buttons, i.e. ticks="Calculate Battle" or ticks="Needed"
The calculator also has a little support for bots, this allows the same options for configuration and control as the normal url but has a text only output, this option is very similar to the "Needed" button giving the ships needed for defence. To use this feature set the variable "saveme" to the required ETA and the calculator will output what ships would help cover an attacker. This feature assumes maximum travel research and alliance travel times. The major differences between this and the normal bots for getting info on ships is that it is possible to define multiple ships and also if the attacker ship targets the definding one and is lower init then the defending ships is increase to compensate for loses, so the number of ships needed will be correct(ish).
This link sets up the attack and defence fleets and tries to calculate whats needed by the defender, in this case only using terran ships in defence against a xan attacker Example1, this is the same calculation except the defender is allowing Cathaar defence also Example2 this should give the general idea of how to interface to the calculator. This last link is identical to Example2 but uses the Bot feature with ETA 10 Example3, this next link is the same again but with ETA 7 Example4. This final example is a typical link from a battle planner to help a player plan an attack Example5.
Notice that the links use index.php instead of a direct link to the current version of the calculator, this ensures that just because I change the round codes for the physical file does not mean that the links need to change, the same links will work for all versions of the calculator, obviously the ship names may change so the variable names used will change.
As of Round 19 I have added player profiles to the battle calculator, this allows a player to create a standard attack or defence fleet that can be loaded either with a button as described in the documentation or it can also be loaded with a URL parameter, if the bcalc is started with LDP=1 (i.e. http://bcalc.thrud.co.uk?LDP=1 will load your profile if you have one saved) then the users profile will be added to the current calc, any other URL parameters included in the URL will be added to this profile, this allows players to set a default attack fleet and for web driven attack planners to load there default attack options and set up the ships/roids and stats for the defender.