Netscript Functions

This page contains the complete documentation for all functions that are available in Netscript. This includes information such as function signatures, what they do, and their return values.

Defining your own Functions
You can define your own functions in Netscript using the following syntax

function name(args...) { function code here... return some_value }

Functions should have some return value. Here is an example of defining and using a function:

function sum(values) { res = 0; for (i = 0; i < values.length; ++i) { res += values[i]; }    return res; } print(sum([1, 2, 3, 4, 5])); print(sum([1, 10]));

The example above prints the following in its log:

15 11

Note about variable scope in functions
Functions can access "global" variables declared outside of the function's scope. However, they cannot change the value of any "global" variables. Any changes to "global" variables will only be applied locally to the function. This also means that any variable that is first defined inside a function will NOT be accessible outside of the function.

For example, the following code:

function sum(values) { res = 0; for (i = 0; i < values.length; ++i) { res += values[i]; }    return res; } print(res);

results in the following runtime error:

Script runtime error: Server Ip: 75.7.4.1 Script name: test.script Args:[] variable res not defined

The following example shows that any change to "global" variable inside a function only applies in the function's local scope:

function foo { i = 5; return "foo"; } i = 0; print(i); foo; print(i);

Results in the following log:

0 0

Other Notes about creating your own functions
Defining a function does not create a Javascript function object in the underlying game code. This means that you cannot use any function you create in functions such as Array.sort (not yet at least, I'll try to make it work in the future).

hack(hostname/ip)
Core function that is used to try and hack servers to steal money and gain hacking experience. The argument passed in must be a string with either the IP or hostname of the server you want to hack. The runtime for this command depends on your hacking level and the target server's security 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. Returns true if the hack is successful and false otherwise.

Examples:

sleep(n, log=true)
Suspends the script for n milliseconds.

The second argument is an optional boolean that indicates whether or not the function should log the sleep action. If this argument is true, then calling this function will write 'Sleeping for N milliseconds' to the script's logs. If it's false, then this function will not log anything. If this argument is not specified then it will be true by default.

Example:

grow(hostname/ip)
Use your hacking skills to increase the amount of money available on a server. The argument passed in must be a string with either the IP or hostname of the target 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 server's growth rate and varies between servers. 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. Returns the number by which the money on the server was multiplied for the growth. Works offline at a slower rate.

Example:

weaken(hostname/ip)
Use your hacking skills to attack a server's security, lowering the server's security level. The argument passed in must be a string with either the IP or hostname of the target server. 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. Returns the total amount the server security's level was weakened by, which is equivalent to 0.05 multiplied by the number of threads the script is runnig with. Works offline at a slower rate

Example:

print(x)
Prints a value or a variable to the scripts logs (which can be viewed with the 'tail [script]' terminal command ).

tprint(x)
Prints a value or a variable to the Terminal

scan(hostname/ip, [hostnames=true])
Returns an array containing the hostnames or IPs of all servers that are one node away from the specified server. The first argument must be a string containing the IP or hostname of the target server. The second argument is a boolean that specifies whether the hostnames or IPs of the scanned servers should be output. If it is true then hostnames will be returned, and if false then IP addresses will. This second argument is optional and, if ommitted, the function will output the hostnames of the scanned servers. The hostnames/IPs in the returned array are strings.

nuke(hostname/ip)
Run NUKE.exe on the target server. NUKE.exe must exist on your home computer.

Example:

brutessh(hostname/ip)
Run BruteSSH.exe on the target server. BruteSSH.exe must exist on your home computer.

Example:

ftpcrack(hostname/ip)
Run FTPCrack.exe on the target server. FTPCrack.exe must exist on your home computer.

Example:

relaysmtp(hostname/ip)
Run relaySMTP.exe on the target server. relaySMTP.exe must exist on your home computer.

Example:

httpworm(hostname/ip)
Run HTTPWorm.exe on the target server. HTTPWorm.exe must exist on your home computer.

Example:

sqlinject(hostname/ip)
Run SQLInject.exe on the target server. SQLInject.exe must exist on your home computer.

Example:

run(script, [numThreads], [args...])
Run a script as a separate process. The first argument that is passed in is the name of the script as a string. This function can only be used to run scripts located on the current server (the server running the script that calls this function). The second argument is optional, and it specifies how many threads to run the script with. This argument must be a number greater than 0. If it is omitted, then the script will be run single-threaded. Any additional arguments will specify arguments to pass into the new script that is being run. If arguments are specified for the new script, then the second argument numThreads argument must be filled in with a value.

Returns true if the script is successfully started, and false otherwise. Requires a significant amount of RAM to run this command.

The simplest way to use the run command is to call it with just the script name. The following example will run 'foo.script' single-threaded with no arguments:

The following example will run 'foo.script' but with 5 threads instead of single-threaded:

The following example will run 'foo.script' single-threaded, and will pass the string 'foodnstuff' into the script as an argument:

exec(script, hostname/ip, [numThreads], [args...])
Run a script as a separate process on another server. The first argument is the name of the script as a string. The second argument is a string with the hostname or IP of the 'target server' on which to run the script. The specified script must exist on the target server. The third argument is optional, and it specifies how many threads to run the script with. If it is omitted, then the script will be run single-threaded. This argument must be a number that is greater than 0. Any additional arguments will specify arguments to pass into the new script that is being run. If arguments are specified for the new script, then the third argument numThreads must be filled in with a value.

Returns true if the script is successfully started, and false otherwise.

The simplest way to use the exec command is to call it with just the script name and the target server. The following example will try to run 'generic-hack.script' on the 'foodnstuff' server:

The following example will try to run the script 'generic-hack.script' on the 'joesguns' server with 10 threads:

The following example will try to run the script 'foo.script' on the 'foodnstuff' server with 5 threads. It will also pass the number 1 and the string 'test' in as arguments to the script.

kill(script, hostname/ip, [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.

The first argument must be a string with the name of the script. The name is case-sensitive. The second argument must be a string with the hostname or IP of the target server. Any additional arguments to the function will specify the arguments passed into the script that should be killed.

The function will try to kill the specified script on the target server. If the script is found on the specified server and is running, then it will be killed and this function will return true. Otherwise, this function will return false.

Examples: If you are trying to kill a script named 'foo.script' on the 'foodnstuff' server that was ran with no arguments, use this:

If you are trying to kill a script named 'foo.script' on the current server that was ran with no arguments, use this:

If you are trying to kill a script named 'foo.script' on the current server that was ran with the arguments 1 and 'foodnstuff', use this:

killall(hostname/ip)
Kills all running scripts on the specified server. This function takes a single argument which must be a string containing the hostname or IP of the target server. This function will always return true.

exit
Terminates the script immediately.

scp(script, [source], destination)
Copies a script or literature (.lit) file to another server. The first argument is either a string with the filename of the script or literature file to be copied, or an array with filename(s) to be copied. The next two arguments are strings containing the hostname/IPs of the source and target server. The source refers to the server from which the script/literature file will be copied, while the destination refers to the server to which it will be copied. The source server argument is optional, and if ommitted the source will be the current server (the server on which the script is running). Returns true if the script/literature file is successfully copied over and false otherwise. If the first argument passed in is an array, this function will return true if at least one of the files in the array is successfully copied.

Examples:

//Copies hack-template.script from the current server to foodnstuff scp('hack-template.script', 'foodnstuff'); //Copies foo.lit from the helios server to the home computer scp('foo.lit', 'helios', 'home');

//Tries to copy three files from rothman-uni to home computer files = ["foo1.lit", "foo2.script", "foo3.script"]; scp(files, "rothman-uni", "home");

ls(hostname/ip)
Returns an array with the filenames of all files on the specified server (as strings). The argument is a string with the hostname/ip of the target server.

The returned array is sorted in alphabetic order.

hasRootAccess(hostname/ip)
Returns a boolean (true or false) indicating whether or not the Player has root access to a server. The argument passed in must be a string with either the hostname or IP of the target server.

Example:

getHostname
Returns a string with the hostname of the server that the script is running on

getHackingLevel
Returns the Player's current hacking level.

getHackingMultipliers
Returns an object containing the Player's hacking related multipliers. These multipliers are returned in integer forms, not percentages (e.g. 1.5 instead of 150%). The object has the following structure:

{    chance: Player's hacking chance multiplier speed: Player's hacking speed multiplier money: Player's hacking money stolen multiplier growth: Player's hacking growth multiplier }

Example:

mults = getHackingMultipliers; print(mults.chance); print(mults.growth);

getBitNodeMultipliers
Returns an object containing the current BitNode multipliers. This function requires Source-File 5 in order to run. The multipliers are returned in integer forms, not percentages (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. The object has the following structure (subject to change in the future):

{    ServerMaxMoney: 1, ServerStartingMoney: 1, ServerGrowthRate: 1, ServerWeakenRate: 1, ServerStartingSecurity: 1, ManualHackMoney: 1, ScriptHackMoney: 1, CompanyWorkMoney: 1, CrimeMoney: 1, HacknetNodeMoney: 1, CompanyWorkExpGain: 1, ClassGymExpGain: 1, FactionWorkExpGain: 1, HackExpGain: 1, CrimeExpGain: 1, FactionWorkRepGain: 1, FactionPassiveRepGain: 1, AugmentationRepCost: 1, AugmentationMoneyCost: 1, }

Example:

mults = getBitNodeMultipliers; print(mults.ServerMaxMoney); print(mults.HackExpGain);

getServerMoneyAvailable(hostname/ip)
Returns the amount of money available on a server. The argument passed in must be a string with either the hostname or IP of the target server.

Running this function on the home computer will return the player's money

Example:

getServerMaxMoney(hostname/ip)
Returns the maximum amount of money that can be available on a server. The argument passed in must be a string with the hostname or IP of the target server.

Example:

getServerGrowth(hostname/ip)
Returns the server's intrinsic "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 this server's money is increased when using the grow function. A higher growth parameter will result in a higher percentage increase from grow.

The argument passed in must be a string with the hostname or IP of the target server.

getServerSecurityLevel(hostname/ip)
Returns the security level of a server. The argument passed in must be a string with either the hostname or IP of the target server. A server's security is denoted by a number typically between 1 and 100.

getServerBaseSecurityLevel(hostname/ip)
Returns the base security level of a 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.

The argument passed in must be a string with either the hostname or IP of the target server. A server's base security is denoted by a number typically between 1 and 100.

getServerMinSecurityLevel(hostname/ip)
Returns the minimum security level of a server. The argument passed in must be a string with either the hostname or IP of the target server.

getServerRequiredHackingLevel(hostname/ip)
Returns the required hacking level of a server. The argument passed in must be a string with either the hostname or IP or the target server.

getServerNumPortsRequired(hostname/ip)
Returns the number of open ports required to successfully run NUKE.exe on a server. The argument passed in must be a string with either the hostname or IP of the target server.

getServerRam(hostname/ip)
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 (in GB). The second element in the array is the amount of RAM that is currently being used on the server.

serverExists(hostname/ip)
Returns a boolean denoting whether or not the specified server exists. The argument must be a string with the hostname or IP of the target server.

fileExists(filename, [hostname/ip])
Returns a boolean (true or false) indicating whether the specified file exists on a server. The first argument must be a string with the name of the file. A file can either be a script, a program, or a literature file. A script name is case-sensitive, but a program/literature file is not. For example, fileExists('brutessh.exe') will work fine, even though the actual program is named BruteSSH.exe.

The second argument is a string with the hostname or IP of the server on which to search for the program. This second argument is optional. If it is omitted, then the function will search through the current server (the server running the script that calls this function) for the file.

Examples:

The first example above will return true if the script named 'foo.script' exists on the 'foodnstuff' server, and false otherwise. The second example above will return true if the current server (the server on which this function runs) contains the FTPCrack.exe program, and false otherwise.

isRunning(filename, hostname/ip, [args...])
Returns a boolean (true or false) indicating whether the specified script is running on a server. Remember that a script is uniquely identified by both its name and its arguments.

The first argument must be a string with the name of the script. The script name is case sensitive. The second argument is a string with the hostname or IP of the target server. Any additional arguments passed to the function will specify the arguments passed into the target script. The function will check whether the script is running on that target server.

Examples:

The first example above will return true if there is a script named 'foo.script' with no arguments running on the 'foodnstuff' server, and false otherwise. The second example above will return true if there is a script named 'foo.script' with no arguments running on the current server, and false otherwise. The third example above will return true if there is a script named 'foo.script' with the arguments 1, 5, and 'test' running on the 'joesguns' server, and false otherwise.

getNextHacknetNodeCost
Returns the cost of purchasing a new Hacknet Node.

purchaseHacknetNode
Purchases a new Hacknet Node. Returns a number with the index of the Hacknet Node. This index is equivalent to the number at the end of the Hacknet Node's name (e.g The Hacknet Node named 'hacknet-node-4' will have an index of 4). If the player cannot afford to purchase a new Hacknet Node then the function will return false. Does NOT work offline

purchaseServer(hostname, ram)
Purchases a server with the specified hostname and amount of RAM. The first argument can be any data type, but it will be converted to a string using Javascript's String function. Anything that resolves to an empty string will cause the function to fail. The second argument specified the amount of RAM (in GB) for the server. This argument must resolve to a numeric and it must be a power of 2 (2, 4, 8, etc...).

This function 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 or if the player does not have enough money to purchase the specified server.

Note that the player can have a maximum of 25 purchased servers.

Example:

deleteServer(hostname)
Deletes one of your purchased servers with the specified hostname. The first argument can be any type, but it will be converted to a string using Javascript's String function. Whitespace is automatically removed from the string. This function will not work on a server that still has scripts running.

Returns true if successful and false otherwise.

getPurchasedServers([hostname=true])
Returns an array with either the hostname or IPs of all of the servers you have purchased. It takes an optional parameter specifying whether the hostname or IP addresses will be returned. If this parameter is not specified, it is true by default and hostnames will be returned.

round(n)
Rounds the number n to the nearest integer. If the argument passed in is not a number, then the function will return 0.

write(port/fn, data="", mode="a")
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 10, then it specifies a port and this function will write data to a port. Read about how Netscript Ports work here. The second argument defines the data to write to the port. If the second argument is not specified then it will write an empty string to the port. The third argument,, is not used when writing data 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 a text file. The second argument defines the data to be written to the text file. If it is not specified then it is an empty string by default. This third argument,, defines how the data will be written to the text file. If  is set to "w", then the data is written in 'write' mode which means that it will overwrite the existing data on the file, or it will create a new file if it does not already exist. Otherwise, the data will written in 'append' mode which means that the data will be added at the end of the existing file, or it will create a new file if it does not already exist. If  isn't specified then it will be "a" for 'append' mode by default.

read(port/fn)
This function is used to read data from a port or from a text file (.txt).

This function takes a single argument. If this argument is a number between 1 and 10, then it specifies a port and it will read data from a port. Read about how Netscript Ports work here. A port is a serialized queue. This function will remove the first element from the queue and return it. If the queue is empty, then the string 'NULL PORT DATA' will be returned.

If the first argument 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.

clear(port/fn)
This function is used to clear a Netscript Port or a text file.

It takes a single argument. If this argument is a number between 1 and 10, then it specifies a port and will clear it (deleting all data from it).

If the argument is a string, then it specifies the name of a text file (.txt) and will clear the text file so that it is empty.

rm(fn)
This function is used to remove a file. It takes a string with the filename as the argument. Returns true if it successfully deletes the given file, and false otherwise. This function works for every file type except message files (.msg)

scriptRunning(scriptname, hostname/ip)
Returns a boolean (true or false) indicating whether any instance of the specified script is running on a server, regardless of its arguments.

This is different than isRunning because it does not try to identify a specific instance of a running script by its arguments.

The first argument must be a string with the name of the script. The script name is case sensitive. The second argument is a string with the hostname or IP of the target server. Both arguments are required.

Examples:

The first example above will return true if there is any script named 'foo.script' running on the 'foodnstuff' server, and false otherwise. The second example above will return true if there is any script named 'foo.script' running on the current server, and false otherwise.

scriptKill(scriptname, hostname/ip)
Kills all scripts with the filename scriptname that are running on the server specified by hostname/ip, regardless of arguments. Returns true if one or more scripts were successfully killed, and false if there were none (i.e it returns false if there are no scripts with the specified name running on the target server).

The first argument must be a string with the name of the script. The script name is case sensitive. The second argument is a string with the hostname or IP of the target server. Both arguments are required.

getScriptRam(scriptname, hostname/ip)
Returns the amount of RAM required to run the specified script on the target server.

The first argument must be a string with the name of the script. The script name is case sensitive. The second argument is a string with the hostname or IP of the server where that script is. Both arguments are required.

getHackTime(hostname/ip)
Returns the amount of time in seconds it takes to execute the hack Netscript function on the server specified by the hostname/ip. The argument must be a string with the hostname/ip of the target server.

getGrowTime(hostname/ip)
Returns the amount of time in seconds it takes to execute the grow Netscript function on the server specified by the hostname/ip. The argument must be a string with the hostname/ip of the target server.

getWeakenTime(hostname/ip)
Returns the amount of time in seconds it takes to execute the weaken Netscript function on the server specified by the hostname/ip. The argument must be a string with the hostname/ip of the target server.

getScriptIncome([scriptname], [hostname/ip], [args...])
Returns the amount of income the specified script generates while online (when the game is open, does not apply for offline income). 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 ($/sec) of all of your active scripts (currently running). The second value is the total income ($/sec) from scripts since you last installed Augmentations (or destroyed a BitNode).

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 arguments in this function call.

The first argument, if specified, must be a string with the name of the script (including the .script extension). The second argument must be a string with the hostname/IP of the target server. If the first argument is specified then the second argument must be specified as well. Any additional arguments passed to the function will specify the arguments passed into the target script.

getScriptExpGain([scriptname], [hostname/ip], [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). This function can also return the total experience gain rate of all of your active scripts by running the function with no arguments.

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 arguments in this function call.

The first argument, if specified, must be a string with the name of the script (including the .script extension). The second argument must be a string with the hostname/IP of the target server. If the first argument is specified then the second argument must be specified as well. Any additional arguments passed to the function will specify the arguments passed into the target script.

getTimeSinceLastAug
Returns the amount of time in milliseconds that have passed since you last installed Augmentations (or destroyed a BitNode).

sprintf and vsprintf
See this link for details

prompt
Prompts the player with a dialog box with two options: 'Yes' and 'No'. This function will returns true if the player clicks 'Yes' and false if the player click's 'No'. The script's execution is halted until the player selects 'Yes' or 'No'. The function takes a single string as an argument which specifies the text that appears on the dialog box.