bitburner-src/markdown/bitburner.ns.md

Home > bitburner > NS

NS interface

Signature:

export interface NS extends Singularity 

Extends: Singularity

Properties

Property	Type	Description
args	any[]	Arguments passed into a script can be accessed using a normal array using the [] operator (args[0], args[1], etc…).It is also possible to get the number of arguments that was passed into a script using:

args.length

WARNING: Do not try to modify the args array. This will break the game. | | bladeburner | Bladeburner | | | codingcontract | CodingContract | | | gang | Gang | | | hacknet | HackNet | Not all functions in the Hacknet Node API are immediately available.Note that none of these functions will write to the script’s logs.If you want to see what your script is doing you will have to print to the logs yourself. | | sleeve | Sleeve | | | stock | TIX | |

Methods

Method	Description
brutessh(host)	Runs the BruteSSH.exe program on the target server. BruteSSH.exe must exist on your home computer.
clear(handle)	This function is used to clear data in a Netscript Ports or a text file.If the port/fn argument is a number between 1 and 20, then it specifies a port and will clear it (deleting all data from the underlying queue).If the port/fn argument is a string, then it specifies the name of a text file (.txt) and will delete all data from that text file.
clearLog()	Clears the script’s logs.
deleteServer(host)	Deletes one of your purchased servers, which is specified by its hostname.The hostname argument can be any data type, but it will be converted to a string. Whitespace is automatically removed from the string. This function will not delete a server that still has scripts running on it.
disableLog(fn)	Disables logging for the given function. Logging can be disabled for all functions by passing `ALL` as the argument.Note that this does not completely remove all logging functionality. This only stops a function from logging when the function is successful. If the function fails, it will still log the reason for failure.Notable functions that cannot have their logs disabled: run, exec, exit.
enableLog(fn)	Re-enables logging for the given function. If `ALL` is passed into this function as an argument, then it will revert the effects of disableLog(`ALL`).
exec(script, host, numThreads, args)	Run a script as a separate process on a specified server. This is similar to the run function except that it can be used to run a script on any server, instead of just the current server.If the script was successfully started, then this functions returns the PID of that script. Otherwise, it returns 0.PID stands for Process ID. The PID is a unique identifier for each script. The PID will always be a positive integer.Running this function with a numThreads argument of 0 will return 0 without running the script. However, running this function with a negative numThreads argument will cause a runtime error.
exit()	Terminates the current script immediately.
fileExists(filename, host)	Returns a boolean indicating whether the specified file exists on the target server. The filename for scripts is case-sensitive, but for other types of files it is not. For example, fileExists(“brutessh.exe”) will work fine, even though the actual program is named 'BruteSSH.exe'.If the hostname/ip argument is omitted, then the function will search through the current server (the server running the script that calls this function) for the file.
ftpcrack(host)	Runs the FTPCrack.exe program on the target server. FTPCrack.exe must exist on your home computer.
getBitNodeMultipliers(url, target, host)	Returns an object containing the current BitNode multipliers. This function requires Source-File 5 in order to run. The multipliers are returned in decimal forms (e.g. 1.5 instead of 150%). The multipliers represent the difference between the current BitNode and the original BitNode (BitNode-1).For example, if the CrimeMoney multiplier has a value of 0.1, then that means that committing crimes in the current BitNode will only give 10% of the money you would have received in BitNode-1.
getFavorToDonate()	Returns the amount of Faction favor required to be able to donate to a faction.
getGrowTime(host, hackLvl, intLvl)	Returns the amount of time in seconds it takes to execute the grow Netscript function on the target server. The function takes in an optional hackLvl parameter that can be specified to see what the grow time would be at different hacking levels.
getHackingLevel()	Returns the player’s current hacking level.
getHackingMultipliers()	Returns an object containing the Player’s hacking related multipliers. These multipliers are returned in fractional forms, not percentages (e.g. 1.5 instead of 150%).
getHacknetMultipliers()	Returns an object containing the Player’s hacknet related multipliers. These multipliers are returned in fractional forms, not percentages (e.g. 1.5 instead of 150%).
getHackTime(host, hackLvl, intLvl)	Returns the amount of time in seconds it takes to execute the hack Netscript function on the target server. The function takes in an optional hackLvl parameter that can be specified to see what the hack time would be at different hacking levels.
getHostname()	Returns a string with the hostname of the server that the script is running on.
getPortHandle(port)	Get a handle to a Netscript Port.WARNING: Port Handles only work in NetscriptJS (Netscript 2.0). They will not work in Netscript 1.0.
getPurchasedServerCost(ram)	Returns the cost to purchase a server with the specified amount of ram.
getPurchasedServerLimit()	Returns the maximum number of servers you can purchase.
getPurchasedServerMaxRam()	Returns the maximum RAM that a purchased server can have.
getPurchasedServers(hostnameMode)	Returns an array with either the hostnames or IPs of all of the servers you have purchased.
getScriptExpGain(script, host, args)	Returns the amount of hacking experience the specified script generates while online (when the game is open, does not apply for offline experience gains). Remember that a script is uniquely identified by both its name and its arguments.This function can also return the total experience gain rate of all of your active scripts by running the function with no arguments.
getScriptIncome(script, host, args)	Returns the amount of income the specified script generates while online (when the game is open, does not apply for offline income). Remember that a script is uniquely identified by both its name and its arguments. So for example if you ran a script with the arguments “foodnstuff” and “5” then in order to use this function to get that script’s income you must specify those same arguments in the same order in this function call.This function can also be called with no arguments. If called with no arguments, then this function will return an array of two values. The first value is the total income ( / second) of all of your active scripts (scripts that are currently running on any server). The second value is the total income ( / second) that you’ve earned from scripts since you last installed Augmentations.
getScriptLogs(fn, host, args)	Returns a script’s logs. The logs are returned as an array, where each line is an element in the array. The most recently logged line is at the end of the array. Note that there is a maximum number of lines that a script stores in its logs. This is configurable in the game’s options. If the function is called with no arguments, it will return the current script’s logs.Otherwise, the fn, hostname/ip, and args… arguments can be used to get the logs from another script. Remember that scripts are uniquely identified by both their names and arguments.
getScriptName()	Returns the current script name.
getScriptRam(script, host)	Returns the amount of RAM required to run the specified script on the target server. Returns 0 if the script does not exist.
getServer(host)	Returns a server object for the given server. Defaults to the running script's server if host is not specified.
getServerBaseSecurityLevel(host)	Returns the base security level of the target server. This is the security level that the server starts out with. This is different than getServerSecurityLevel because getServerSecurityLevel returns the current security level of a server, which can constantly change due to hack, grow, and weaken, calls on that server. The base security level will stay the same until you reset by installing an Augmentation(s).
getServerGrowth(host)	Returns the server’s instrinsic “growth parameter”. This growth parameter is a number between 1 and 100 that represents how quickly the server’s money grows. This parameter affects the percentage by which the server’s money is increased when using the grow function. A higher growth parameter will result in a higher percentage increase from grow.
getServerMaxMoney(host)	Returns the maximum amount of money that can be available on a server.
getServerMinSecurityLevel(host)	Returns the minimum security level of the target server.
getServerMoneyAvailable(host)	Returns the amount of money available on a server. Running this function on the home computer will return the player’s money.
getServerNumPortsRequired(host)	Returns the number of open ports required to successfully run NUKE.exe on the specified server.
getServerRam(host)	Returns an array with two elements that gives information about a server’s memory (RAM). The first element in the array is the amount of RAM that the server has total (in GB). The second element in the array is the amount of RAM that is currently being used on the server (in GB).
getServerRequiredHackingLevel(host)	Returns the required hacking level of the target server.
getServerSecurityLevel(host)	Returns the security level of the target server. A server’s security level is denoted by a number, typically between 1 and 100 (but it can go above 100).
getTimeSinceLastAug()	Returns the amount of time in milliseconds that have passed since you last installed Augmentations.
getWeakenTime(host, hackLvl, intLvl)	Returns the amount of time in seconds it takes to execute the weaken() Netscript function on the target server. The function takes in an optional hackLvl parameter that can be specified to see what the weaken time would be at different hacking levels.
grow(host, opts)	Use your hacking skills to increase the amount of money available on a server. The runtime for this command depends on your hacking level and the target server’s security level. When `grow` completes, the money available on a target server will be increased by a certain, fixed percentage. This percentage is determined by the target server’s growth rate (which varies between servers) and security level. Generally, higher-level servers have higher growth rates. The getServerGrowth() function can be used to obtain a server’s growth rate.Like hack, `grow` can be called on any server, regardless of where the script is running. The grow() command requires root access to the target server, but there is no required hacking level to run the command. It also raises the security level of the target server by 0.004.
growthAnalyze(host, growthAmount)	This function returns the number of “growths” needed in order to increase the amount of money available on the specified server by the specified amount. The specified amount is multiplicative and is in decimal form, not percentage.Warning: The value returned by this function isn’t necessarily a whole number.
growthAnalyzeSecurity(threads)	Returns the security increase that would occur if a grow with this many threads happened.
hack(host, opts)	Function that is used to try and hack servers to steal money and gain hacking experience. The runtime for this command depends on your hacking level and the target server’s security level. In order to hack a server you must first gain root access to that server and also have the required hacking level.A script can hack a server from anywhere. It does not need to be running on the same server to hack that server. For example, you can create a script that hacks the `foodnstuff` server and run that script on any server in the game.A successful `hack()` on a server will raise that server’s security level by 0.002.
hackAnalyzePercent(host)	Returns the percentage of the specified server’s money you will steal with a single hack. This value is returned in percentage form, not decimal (Netscript functions typically return in decimal form, but not this one).
hackAnalyzeSecurity(threads)	Returns the security increase that would occur if a hack with this many threads happened.
hackAnalyzeThreads(host, hackAmount)	This function returns the number of script threads you need when running the hack command to steal the specified amount of money from the target server. If hackAmount is less than zero or greater than the amount of money available on the server, then this function returns -1.Warning: The value returned by this function isn’t necessarily a whole number.
hackChance(host)	Returns the chance you have of successfully hacking the specified server.This returned value is in decimal form, not percentage.
hasRootAccess(host)	Returns a boolean indicating whether or not the player has root access to the specified target server.
httpworm(host)	Runs the HTTPWorm.exe program on the target server. HTTPWorm.exe must exist on your home computer.
isLogEnabled(fn)	Checks the status of the logging for the given function.
isRunning(script, host, args)	Returns a boolean indicating whether the specified script is running on the target server. Remember that a script is uniquely identified by both its name and its arguments.
kill(script, host, args)	Kills the script on the target server specified by the script’s name and arguments. Remember that scripts are uniquely identified by both their name and arguments. For example, if `foo.script` is run with the argument 1, then this is not the same as `foo.script` run with the argument 2, even though they have the same code.
kill(scriptPid)	Kills the script with the specified PID. Killing a script by its PID will typically have better performance, especially if you have many scripts running. If this function successfully kills the specified script, then it will return true. Otherwise, it will return false.
killall(host)	Kills all running scripts on the specified server. This function returns true if any scripts were killed, and false otherwise. In other words, it will return true if there are any scripts running on the target server.
ls(host, grep)	Returns an array with the filenames of all files on the specified server (as strings). The returned array is sorted in alphabetic order.
nFormat(n, format)	Converts a number into a string with the specified formatter. This uses the numeraljs library, so the formatters must be compatible with that. This is the same function that the game itself uses to display numbers.
nuke(host)	Runs the NUKE.exe program on the target server. NUKE.exe must exist on your home computer.
peek(port)	This function is used to peek at the data from a port. It returns the first element in the specified port without removing that element. If the port is empty, the string “NULL PORT DATA” will be returned.
print(msg)	Prints a value or a variable to the script’s logs.
prompt(txt)	Prompts the player with a dialog box with two options: “Yes” and “No”. This function will return true if the player click “Yes” and false if the player clicks “No”. The script’s execution is halted until the player selects one of the options.
ps(host)	Returns an array with general information about all scripts running on the specified target server.
purchaseServer(hostname, ram)	Purchased a server with the specified hostname and amount of RAM.The hostname argument can be any data type, but it will be converted to a string and have whitespace removed. Anything that resolves to an empty string will cause the function to fail. If there is already a server with the specified hostname, then the function will automatically append a number at the end of the hostname argument value until it finds a unique hostname. For example, if the script calls `purchaseServer(“foo”, 4)` but a server named “foo” already exists, the it will automatically change the hostname to `foo-0`. If there is already a server with the hostname `foo-0`, then it will change the hostname to `foo-1`, and so on.Note that there is a maximum limit to the amount of servers you can purchase.Returns the hostname of the newly purchased server as a string. If the function fails to purchase a server, then it will return an empty string. The function will fail if the arguments passed in are invalid, if the player does not have enough money to purchase the specified server, or if the player has exceeded the maximum amount of servers.
read(handle)	This function is used to read data from a port or from a text file (.txt).If the argument port/fn is a number between 1 and 20, then it specifies a port and it will read data from that port. A port is a serialized queue. This function will remove the first element from that queue and return it. If the queue is empty, then the string “NULL PORT DATA” will be returned.If the argument port/fn is a string, then it specifies the name of a text file (.txt) and this function will return the data in the specified text file. If the text file does not exist, an empty string will be returned.
relaysmtp(host)	Runs the relaySMTP.exe program on the target server. relaySMTP.exe must exist on your home computer.
rm(name, host)	Removes the specified file from the current server. This function works for every file type except message (.msg) files.
run(script, numThreads, args)	Run a script as a separate process. This function can only be used to run scripts located on the current server (the server running the script that calls this function). Requires a significant amount of RAM to run this command.If the script was successfully started, then this functions returns the PID of that script. Otherwise, it returns 0.PID stands for Process ID. The PID is a unique identifier for each script. The PID will always be a positive integer.Running this function with a numThreads argument of 0 will return 0 without running the script. However, running this function with a negative numThreads argument will cause a runtime error.
scan(host, hostnames)	Returns an array containing the hostnames or IPs of all servers that are one node way from the specified target server. The hostnames/IPs in the returned array are strings.
scp(files, destination)	Copies a script or literature (.lit) file(s) to another server. The files argument can be either a string specifying a single file to copy, or an array of strings specifying multiple files to copy.
scp(files, source, destination)	Copies a script or literature (.lit) file(s) to another server. The files argument can be either a string specifying a single file to copy, or an array of strings specifying multiple files to copy.
scriptKill(script, host)	Kills all scripts with the specified filename on the target server specified by hostname/ip, regardless of arguments.
scriptRunning(script, host)	Returns a boolean indicating whether any instance of the specified script is running on the target server, regardless of its arguments.This is different than the isRunning function because it does not try to identify a specific instance of a running script by its arguments.
serverExists(host)	Returns a boolean denoting whether or not the specified server exists.
sleep(millis)	Suspends the script for n milliseconds.
spawn(script, numThreads, args)	Terminates the current script, and then after a delay of about 10 seconds it will execute the newly-specified script. The purpose of this function is to execute a new script without being constrained by the RAM usage of the current one. This function can only be used to run scripts on the local server.Because this function immediately terminates the script, it does not have a return value.
sprintf(format, args)	Complete open source JavaScript sprintf implementation
sqlinject(host)	Runs the SQLInject.exe program on the target server. SQLInject.exe must exist on your home computer.
tail(fn, host, args)	Opens a script’s logs. This is functionally the same as the tail Terminal command.If the function is called with no arguments, it will open the current script’s logs.Otherwise, the fn, hostname/ip, and args… arguments can be used to get the logs from another script. Remember that scripts are uniquely identified by both their names and arguments.
tprint(msg)	Prints a value or a variable to the Terminal.
tryWrite(port, data)	Attempts to write data to the specified Netscript Port. If the port is full, the data will not be written. Otherwise, the data will be written normally.
vsprintf(format, args)	Complete open source JavaScript sprintf implementation
weaken(host, opts)	Use your hacking skills to attack a server’s security, lowering the server’s security level. The runtime for this command depends on your hacking level and the target server’s security level. This function lowers the security level of the target server by 0.05.Like hack and grow, `weaken` can be called on any server, regardless of where the script is running. This command requires root access to the target server, but there is no required hacking level to run the command.
weakenAnalyze(threads, cores)	Returns the security decrease that would occur if a weaken with this many threads happened.
wget(url, target, host)	Retrieves data from a URL and downloads it to a file on the specified server. The data can only be downloaded to a script (.script, .ns, .js) or a text file (.txt). If the file already exists, it will be overwritten by this command. Note that it will not be possible to download data from many websites because they do not allow cross-origin resource sharing (CORS).IMPORTANT: This is an asynchronous function that returns a Promise. The Promise’s resolved value will be a boolean indicating whether or not the data was successfully retrieved from the URL. Because the function is async and returns a Promise, it is recommended you use wget in NetscriptJS (Netscript 2.0).In NetscriptJS, you must preface any call to wget with the await keyword (like you would hack or sleep). wget will still work in Netscript 1.0, but the functions execution will not be synchronous (i.e. it may not execute when you expect/want it to). Furthermore, since Promises are not supported in ES5, you will not be able to process the returned value of wget in Netscript 1.0.
write(handle, data, mode)	This function can be used to either write data to a port or to a text file (.txt).If the first argument is a number between 1 and 20, then it specifies a port and this function will write data to that port. The third argument, mode, is not used when writing to a port.If the first argument is a string, then it specifies the name of a text file (.txt) and this function will write data to that text file. If the specified text file does not exist, then it will be created. The third argument mode, defines how the data will be written to the text file. If *mode is set to “w”, then the data is written in “write” mode which means that it will overwrite all existing data on the text file. If mode is set to any other value then the data will be written in “append” mode which means that the data will be added at the end of the text file.