mirror of
https://github.com/bitburner-official/bitburner-src.git
synced 2024-11-14 19:53:48 +01:00
563 lines
17 KiB
ReStructuredText
563 lines
17 KiB
ReStructuredText
Netscript Bladeburner API
|
|
=========================
|
|
Netscript provides the following API for interacting with the game's Bladeburner mechanic.
|
|
|
|
The Bladeburner API is **not** immediately available to the player and must be unlocked
|
|
later in the game
|
|
|
|
**WARNING: This page contains spoilers for the game**
|
|
|
|
The Bladeburner API is unlocked in BitNode-7. If you are in BitNode-7, you will
|
|
automatically gain access to this API. Otherwise, you must have Source-File 7 in
|
|
order to use this API in other BitNodes
|
|
|
|
**Bladeburner API functions must be accessed through the 'bladeburner' namespace**
|
|
|
|
In :ref:`netscript1`::
|
|
|
|
bladeburner.getContractNames();
|
|
bladeburner.startAction("general", "Training");
|
|
|
|
In :ref:`netscriptjs`::
|
|
|
|
ns.bladeburner.getContractNames();
|
|
ns.bladeburner.startAction("general", "Training");
|
|
|
|
.. _bladeburner_action_types:
|
|
|
|
Bladeburner Action Types
|
|
------------------------
|
|
|
|
Several functions in the Bladeburner API require you to specify an action using
|
|
its type and name. The following are valid values when specifying the action's type:
|
|
|
|
**Contracts**
|
|
* contract
|
|
* contracts
|
|
* contr
|
|
|
|
**Operations**
|
|
* operation
|
|
* operations
|
|
* op
|
|
* ops
|
|
|
|
**Black Ops**
|
|
* blackoperation
|
|
* black operation
|
|
* black operations
|
|
* black op
|
|
* black ops
|
|
* blackop
|
|
* blackops
|
|
|
|
**General Actions (Training, Field Analysis, Recruitment)**
|
|
* general
|
|
* general action
|
|
* gen
|
|
|
|
getContractNames
|
|
----------------
|
|
|
|
.. js:function:: getContractNames()
|
|
|
|
Returns an array of strings containing the names of all Bladeburner contracts
|
|
|
|
getOperationNames
|
|
-----------------
|
|
|
|
.. js:function:: getOperationNames()
|
|
|
|
Returns an array of strings containing the names of all Bladeburner operations
|
|
|
|
getBlackOpNames
|
|
---------------
|
|
|
|
.. js:function:: getBlackOpNames()
|
|
|
|
Returns an array of strings containing the names of all Bladeburner Black Ops
|
|
|
|
getGeneralActionNames
|
|
---------------------
|
|
|
|
.. js:function:: getGeneralActionNames()
|
|
|
|
Returns an array of strings containing the names of all general Bladeburner actions
|
|
|
|
getSkillNames
|
|
-------------
|
|
|
|
.. js:function:: getSkillNames()
|
|
|
|
Returns an array of strings containing the names of all Bladeburner skills
|
|
|
|
startAction
|
|
-----------
|
|
|
|
.. js:function:: startAction(type, name)
|
|
|
|
:param string type: Type of action. See :ref:`bladeburner_action_types`
|
|
:param string name: Name of action. Must be an exact match
|
|
|
|
Attempts to start the specified Bladeburner action. Returns true if the action
|
|
was started successfully, and false otherwise.
|
|
|
|
stopBladeburnerAction
|
|
---------------------
|
|
|
|
.. js:function:: stopBladeburnerAction()
|
|
|
|
Stops the current Bladeburner action
|
|
|
|
getCurrentAction
|
|
----------------
|
|
|
|
.. js:function:: getCurrentAction()
|
|
|
|
Returns an object that represents the player's current Bladeburner action::
|
|
|
|
{
|
|
type: Type of Action
|
|
name: Name of Action
|
|
}
|
|
|
|
If the player is not performing an action, the function will return an object
|
|
with the 'type' property set to "Idle".
|
|
|
|
getActionTime
|
|
-------------
|
|
|
|
.. js:function:: getActionTime(type, name)
|
|
|
|
:param string type: Type of action. See :ref:`bladeburner_action_types`
|
|
:param string name: Name of action. Must be an exact match
|
|
|
|
Returns the number of seconds it takes to complete the specified action
|
|
|
|
getActionEstimatedSuccessChance
|
|
-------------------------------
|
|
|
|
.. js:function:: getActionEstimatedSuccessChance(type, name)
|
|
|
|
:param string type: Type of action. See :ref:`bladeburner_action_types`
|
|
:param string name: Name of action. Must be an exact match
|
|
|
|
Returns the estimated success chance for the specified action. This chance
|
|
is returned as a decimal value, NOT a percentage (e.g. if you have an estimated
|
|
success chance of 80%, then this function will return 0.80, NOT 80).
|
|
|
|
getActionRepGain
|
|
----------------
|
|
|
|
.. js:function:: getActionRepGain(type, name[, level=current level])
|
|
|
|
:param string type: Type of action. See :ref:`bladeburner_action_types`
|
|
:param string name: Name of action. Must be an exact match
|
|
:param number level: Optional action level at which to calculate the gain
|
|
|
|
Returns the average Bladeburner reputation gain for successfully completing
|
|
the specified action. Note that this value is an 'average' and the real
|
|
reputation gain may vary slightly from this value.
|
|
|
|
getActionCountRemaining
|
|
-----------------------
|
|
|
|
.. js:function:: getActionCountRemaining(type, name)
|
|
|
|
:param string type: Type of action. See :ref:`bladeburner_action_types`
|
|
:param string name: Name of action. Must be an exact match
|
|
|
|
Returns the remaining count of the specified action.
|
|
|
|
Note that this is meant to be used for Contracts and Operations.
|
|
This function will return 'Infinity' for actions such as Training and Field Analysis.
|
|
|
|
getActionMaxLevel
|
|
-----------------
|
|
|
|
.. js:function:: getActionMaxLevel(type, name)
|
|
|
|
:param string type: Type of action. See :ref:`bladeburner_action_types`
|
|
:param string name: Name of action. Must be an exact match
|
|
|
|
Returns the maximum level for this action.
|
|
|
|
Returns -1 if an invalid action is specified.
|
|
|
|
getActionCurrentLevel
|
|
---------------------
|
|
|
|
.. js:function:: getActionCurrentLevel(type, name)
|
|
|
|
:param string type: Type of action. See :ref:`bladeburner_action_types`
|
|
:param string name: Name of action. Must be an exact match
|
|
|
|
Returns the current level of this action.
|
|
|
|
Returns -1 if an invalid action is specified.
|
|
|
|
getActionAutolevel
|
|
------------------
|
|
|
|
.. js:function:: getActionAutolevel(type, name)
|
|
|
|
:param string type: Type of action. See :ref:`bladeburner_action_types`
|
|
:param string name: Name of action. Must be an exact match
|
|
|
|
Return a boolean indicating whether or not this action is currently set to autolevel.
|
|
|
|
Returns false if an invalid action is specified.
|
|
|
|
setActionAutolevel
|
|
------------------
|
|
|
|
.. js:function:: setActionAutolevel(type, name, autoLevel)
|
|
|
|
:param string type: Type of action. See :ref:`bladeburner_action_types`
|
|
:param string name: Name of action. Must be an exact match
|
|
:param boolean autoLevel: Whether or not to autolevel this action
|
|
|
|
Enable/disable autoleveling for the specified action.
|
|
|
|
setActionLevel
|
|
--------------
|
|
|
|
.. js:function:: setActionLevel(type, name, level)
|
|
|
|
:param string type: Type of action. See :ref:`bladeburner_action_types`
|
|
:param string name: Name of action. Must be an exact match
|
|
:param level int: Level to set this action to
|
|
|
|
Set the level for the specified action.
|
|
|
|
getRank
|
|
-------
|
|
|
|
.. js:function:: getRank()
|
|
|
|
Returns the player's Bladeburner Rank
|
|
|
|
getSkillPoints
|
|
--------------
|
|
|
|
.. js:function:: getSkillPoints()
|
|
|
|
Returns the number of Bladeburner skill points you have
|
|
|
|
getSkillLevel
|
|
-------------
|
|
|
|
.. js:function:: getSkillLevel(skillName="")
|
|
|
|
:param string skillName: Name of skill. Case-sensitive and must be an exact match
|
|
|
|
This function returns your level in the specified skill.
|
|
|
|
The function returns -1 if an invalid skill name is passed in
|
|
|
|
getSkillUpgradeCost
|
|
-------------------
|
|
|
|
.. js:function:: getSkillUpgradeCost(skillName="")
|
|
|
|
:param string skillName: Name of skill. Case-sensitive and must be an exact match
|
|
|
|
This function returns the number of skill points needed to upgrade the
|
|
specified skill.
|
|
|
|
The function returns -1 if an invalid skill name is passed in.
|
|
|
|
upgradeSkill
|
|
------------
|
|
|
|
.. js:function:: upgradeSkill(skillName)
|
|
|
|
:param string skillName: Name of Skill to be upgraded. Case-sensitive and must be an exact match
|
|
|
|
Attempts to upgrade the specified Bladeburner skill. Returns true if the
|
|
skill is successfully upgraded, and false otherwise
|
|
|
|
getTeamSize
|
|
-----------
|
|
|
|
.. js:function:: getTeamSize(type, name)
|
|
|
|
:param string type: Type of action. See :ref:`bladeburner_action_types`
|
|
:param string name: Name of action. Must be an exact match
|
|
|
|
Returns the number of Bladeburner team members you have assigned to the
|
|
specified action.
|
|
|
|
Setting a team is only applicable for Operations and BlackOps. This function
|
|
will return 0 for other action types.
|
|
|
|
setTeamSize
|
|
-----------
|
|
|
|
.. js:function:: setTeamSize(type, name, size)
|
|
|
|
:param string type: Type of action. See :ref:`bladeburner_action_types`
|
|
:param string name: Name of action. Must be an exact match
|
|
:param int size: Number of team members to set. Will be converted using Math.round()
|
|
|
|
Set the team size for the specified Bladeburner action.
|
|
|
|
Returns the team size that was set, or -1 if the function failed.
|
|
|
|
getCityEstimatedPopulation
|
|
--------------------------
|
|
|
|
.. js:function:: getCityEstimatedPopulation(cityName)
|
|
|
|
:param string cityName: Name of city. Case-sensitive
|
|
|
|
Returns the estimated number of Synthoids in the specified city, or -1
|
|
if an invalid city was specified.
|
|
|
|
getCityEstimatedCommunities
|
|
---------------------------
|
|
|
|
.. js:function:: getCityEstimatedCommunities(cityName)
|
|
|
|
:param string cityName: Name of city. Case-sensitive
|
|
|
|
Returns the estimated number of Synthoid communities in the specified city,
|
|
or -1 if an invalid city was specified.
|
|
|
|
getCityChaos
|
|
------------
|
|
|
|
.. js:function:: getCityChaos(cityName)
|
|
|
|
:param string cityName: Name of city. Case-sensitive
|
|
|
|
Returns the chaos in the specified city, or -1 if an invalid city was specified
|
|
|
|
switchCity
|
|
----------
|
|
|
|
.. js:function:: switchCity(cityName)
|
|
|
|
:param string cityName: Name of city
|
|
|
|
Attempts to switch to the specified city (for Bladeburner only).
|
|
|
|
Returns true if successful, and false otherwise
|
|
|
|
getStamina
|
|
----------
|
|
|
|
.. js:function:: getStamina()
|
|
|
|
Returns an array with two elements:
|
|
|
|
[Current stamina, Max stamina]
|
|
|
|
Example usage::
|
|
|
|
function getStaminaPercentage() {
|
|
let res = bladeburner.getStamina();
|
|
return res[0] / res[1];
|
|
}
|
|
|
|
joinBladeburnerFaction
|
|
----------------------
|
|
|
|
.. js:function:: joinBladeburnerFaction()
|
|
|
|
Attempts to join the Bladeburner faction.
|
|
|
|
Returns true if you successfully join the Bladeburner faction, or if
|
|
you are already a member.
|
|
|
|
Returns false otherwise.
|
|
|
|
joinBladeburnerDivision
|
|
-----------------------
|
|
|
|
.. js:function:: joinBladeburnerDivision()
|
|
|
|
Attempts to join the Bladeburner division.
|
|
|
|
Returns true if you successfully join the Bladeburner division, or if you
|
|
are already a member.
|
|
|
|
Returns false otherwise
|
|
|
|
getBonusTime
|
|
------------
|
|
|
|
.. js:function:: getBonusTime()
|
|
|
|
Returns the amount of accumulated "bonus time" (seconds) for the Bladeburner mechanic.
|
|
|
|
"Bonus time" is accumulated when the game is offline or if the game is
|
|
inactive in the browser.
|
|
|
|
"Bonus time" makes the game progress faster, up to 5x the normal speed.
|
|
For example, if an action takes 30 seconds to complete but you've accumulated
|
|
over 30 seconds in bonus time, then the action will only take 6 seconds
|
|
in real life to complete.
|
|
|
|
Examples
|
|
--------
|
|
|
|
**Basic example usage**::
|
|
|
|
tprint(bladeburner.getContractNames());
|
|
tprint(bladeburner.getOperationNames());
|
|
tprint(bladeburner.getBlackOpNames());
|
|
tprint(bladeburner.getGeneralActionNames());
|
|
tprint(bladeburner.getSkillNames());
|
|
tprint(bladeburner.getActionTime("contract", "Tracking"));
|
|
tprint("Rank: " + bladeburner.getRank());
|
|
tprint("Skill Points: " + bladeburner.getSkillPoints());
|
|
tprint("Cloak Skill Level: " + bladeburner.getSkillLevel("Cloak"));
|
|
tprint("Trying to upgradeSkill: " + bladeburner.upgradeSkill("Cloak"));
|
|
tprint("Skill Points remaining: " + bladeburner.getSkillPoints());
|
|
|
|
tprint("Trying to switch to a nonexistent city: " + bladeburner.switchCity("lskgns"));
|
|
|
|
var chongqing = "Chongqing";
|
|
tprint("Trying to switch to Chongqing: " + bladeburner.switchCity(chongqing));
|
|
tprint("Chongqing chaos: " + bladeburner.getCityChaos(chongqing));
|
|
tprint("Chongqing estimated pop: " + bladeburner.getCityEstimatedPopulation(chongqing));
|
|
tprint("Chonqging estimated communities: " + bladeburner.getCityEstimatedCommunities(chongqing));
|
|
|
|
**Bladeburner handler example**. Note that this avoids the need of using the *bladeburner* namespace
|
|
identifier by attaching the Bladeburner API functions to an object::
|
|
|
|
const FIELD_ANALYSIS_INTERVAL = 10; //Number of minutes between field analysis states
|
|
const FIELD_ANALYSIS_DURATION = 5; //Duration in minutes
|
|
|
|
function BladeburnerHandler(ns, params) {
|
|
//Netscript environment becomes part of the instance
|
|
this.ns = ns;
|
|
|
|
//Netscript bladeburner API becomes part of this instance
|
|
for (var bladeburnerFn in ns.bladeburner) {
|
|
this[bladeburnerFn] = ns.bladeburner[bladeburnerFn];
|
|
}
|
|
|
|
this.fieldAnalysis = {
|
|
inProgress: params.startFieldAnalysis ? true : false,
|
|
cyclesRemaining: params.startFieldAnalysis ? FIELD_ANALYSIS_DURATION : 0,
|
|
cyclesSince: params.startFieldAnalysis ? FIELD_ANALYSIS_INTERVAL : 0,
|
|
}
|
|
}
|
|
|
|
|
|
|
|
BladeburnerHandler.prototype.getStaminaPercentage = function() {
|
|
var res = this.getStamina();
|
|
return 100 * (res[0] / res[1]);
|
|
}
|
|
|
|
BladeburnerHandler.prototype.hasSimulacrum = function() {
|
|
var augs = this.ns.getOwnedAugmentations();
|
|
return augs.includes("The Blade's Simulacrum");
|
|
}
|
|
|
|
BladeburnerHandler.prototype.handle = function() {
|
|
//If we're doing something else manually (without Simlacrum),
|
|
//it overrides Bladeburner stuff
|
|
if (!this.hasSimulacrum() && this.ns.isBusy()) {
|
|
this.ns.print("Idling bc player is busy with some other action");
|
|
return;
|
|
}
|
|
|
|
if (this.fieldAnalysis.inProgress) {
|
|
--(this.fieldAnalysis.cyclesRemaining);
|
|
if (this.fieldAnalysis.cyclesRemaining < 0) {
|
|
this.fieldAnalysis.inProgress = false;
|
|
this.fieldAnalysis.cyclesSince = 0;
|
|
return this.handle();
|
|
} else {
|
|
this.startAction("general", "Field Analysis");
|
|
this.ns.print("handler is doing field analyis for " +
|
|
(this.fieldAnalysis.cyclesRemaining+1) + " more mins");
|
|
return 31; //Field Analysis Time + 1
|
|
}
|
|
} else {
|
|
++(this.fieldAnalysis.cyclesSince);
|
|
if (this.fieldAnalysis.cyclesSince > FIELD_ANALYSIS_INTERVAL) {
|
|
this.fieldAnalysis.inProgress = true;
|
|
this.fieldAnalysis.cyclesRemaining = FIELD_ANALYSIS_DURATION;
|
|
return this.handle();
|
|
}
|
|
}
|
|
|
|
this.stopBladeburnerAction();
|
|
|
|
var staminaPerc = this.getStaminaPercentage();
|
|
if (staminaPerc < 55) {
|
|
this.ns.print("handler is starting training due to low stamina percentage");
|
|
this.startAction("general", "Training");
|
|
return 31; //Training time + 1
|
|
} else {
|
|
var action = this.chooseAction();
|
|
this.ns.print("handler chose " + action.name + " " + action.type + " through chooseAction()");
|
|
this.startAction(action.type, action.name);
|
|
return (this.getActionTime(action.type, action.name) + 1);
|
|
}
|
|
}
|
|
|
|
BladeburnerHandler.prototype.chooseAction = function() {
|
|
//Array of all Operations
|
|
var ops = this.getOperationNames();
|
|
|
|
//Sort Operations in order of increasing success chance
|
|
ops.sort((a, b)=>{
|
|
return this.getActionEstimatedSuccessChance("operation", a) -
|
|
this.getActionEstimatedSuccessChance("operation", b);
|
|
});
|
|
|
|
//Loop through until you find one with 99+% success chance
|
|
for (let i = 0; i < ops.length; ++i) {
|
|
let successChance = this.getActionEstimatedSuccessChance("operation", ops[i]);
|
|
let count = this.getActionCountRemaining("operation", ops[i]);
|
|
if (successChance >= 0.99 && count > 10) {
|
|
return {type: "operation", name: ops[i]};
|
|
}
|
|
}
|
|
|
|
//Repeat for Contracts
|
|
var contracts = this.getContractNames();
|
|
contracts.sort((a, b)=>{
|
|
return this.getActionEstimatedSuccessChance("contract", a) -
|
|
this.getActionEstimatedSuccessChance("contract", b);
|
|
});
|
|
|
|
for (let i = 0; i < contracts.length; ++i) {
|
|
let successChance = this.getActionEstimatedSuccessChance("contract", contracts[i]);
|
|
let count = this.getActionCountRemaining("contract", contracts[i]);
|
|
if (successChance >= 0.80 && count > 10) {
|
|
return {type: "contract", name: contracts[i]};
|
|
}
|
|
}
|
|
|
|
return {type:"general", name:"Training"};
|
|
}
|
|
|
|
|
|
BladeburnerHandler.prototype.process = async function() {
|
|
await this.ns.sleep(this.handle() * 1000);
|
|
}
|
|
|
|
export async function main(ns) {
|
|
//Check if Bladeburner is available. This'll throw a runtime error if it's not
|
|
ns.bladeburner.getContractNames();
|
|
|
|
var startFieldAnalysis = true;
|
|
if (ns.args.length >= 1 && ns.args[0] == "false") {
|
|
startFieldAnalysis = false;
|
|
}
|
|
|
|
var handler = new BladeburnerHandler(ns, {
|
|
startFieldAnalysis: startFieldAnalysis
|
|
});
|
|
while(true) {
|
|
await handler.process();
|
|
}
|
|
}
|