mirror of
https://github.com/bitburner-official/bitburner-src.git
synced 2026-04-18 07:18:38 +02:00
Added documentation for Bladeburner API. Fixed typo in BN-7 description.
This commit is contained in:
danielyxie
446
doc/build/html/_sources/netscriptbladeburnerapi.rst.txt
vendored
Normal file
446
doc/build/html/_sources/netscriptbladeburnerapi.rst.txt
vendored
Normal file
@@ -0,0 +1,446 @@
|
||||
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 palyer 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 Netscript 1.0::
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
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: Optional name of Skill. Empty string by default
|
||||
|
||||
If no argument or an empty string is passed in, this function returns
|
||||
an object with your level for all Bladeburner Skills (only for skills that
|
||||
have at least one level). In the object, the name of the Bladeburner Skills
|
||||
are the keys and your skill levels are the values. For example::
|
||||
|
||||
{
|
||||
"Blade's Intuition": 10,
|
||||
"Cloak": 5,
|
||||
"Evasive System": 6
|
||||
}
|
||||
|
||||
If the name of a skill is passed in as an argument, then this function
|
||||
returns your level in 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. 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.
|
||||
|
||||
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: FIELD_ANALYSIS_DURATION,
|
||||
cyclesSince: FIELD_ANALYSIS_INTERVAL
|
||||
}
|
||||
}
|
||||
|
||||
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;
|
||||
}
|
||||
} 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");
|
||||
} else {
|
||||
var action = this.chooseAction();
|
||||
this.ns.print("handler chose " + action.name + " " + action.type + " through chooseAction()");
|
||||
this.startAction(action.type, action.name);
|
||||
}
|
||||
}
|
||||
|
||||
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() {
|
||||
this.handle();
|
||||
await this.ns.sleep(60000);
|
||||
}
|
||||
|
||||
export async function main(ns) {
|
||||
ns.disableLog("sleep");
|
||||
//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();
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user