bitburner-src/src/Documentation/ui/doc/basic/scripts.md

Scripts

Scripts are programs that can be used to automate the hacking process and almost every other part of the game. Scripts must be written in JavaScript.

It is highly recommended that you have a basic background in programming to start writing scripts. You by no means need to be an expert. All you need is some familiarity with basic programming constructs like for/while loops, conditionals (if/else), functions, variables, etc. If you'd like to learn a little bit about programming, see this page.

Script Arguments

When running a script, you can choose to pass arguments to that script. The script's logic can access and act on these arguments. This allows for flexibility in your scripts.

Identifying a Script

Many commands and functions act on an executing script (i.e. a script that is running). Therefore, there must be a way to specify which script you want those commands & functions to act on.

The best way to identify a script is by its PID (Process IDentifier). This unique number is returned from run, exec, etc., and also shows in the output of ps.

A secondary way to identify scripts is by name and arguments. However (by default) you can run a multiple copies of a script with the same arguments, so this does not necessarily uniquely identify a script. In case of multiple matches, most functions will return an arbitrary one (typically the first one to be started). An exception is kill, which will kill all the matching scripts.

The arguments must be an exact match. This means that both the order and type of the arguments matter.

Multithreading scripts

A script can be run with multiple threads. This is also called multithreading. The effect of multithreading is that every call to the hack, grow, and weaken functions will have their results multiplied by the number of threads. For example, if a normal single-threaded script is able to hack $10,000, then running the same script with 5 threads would yield $50,000.

(This is the only affect of running a script with multiple threads. Scripts will not actually become multithreaded in the real-world sense.)

When multithreading a script, the total RAM cost can be calculated by simply multiplying the base RAM cost of the script with the number of threads, where the base cost refers to the amount of RAM required to run the script single-threaded. In the terminal, you can run the mem Terminal command to see how much RAM a script requires with n threads::

$ mem [scriptname] -t n

Working with Scripts in Terminal

Running a script requires RAM. The more complex a script is, the more RAM it requires to run. Scripts can be run on any server you have root access to.

Here are some terminal commands that are useful when working with scripts:

check [script] [args...]

Prints the logs of the script specified by the name and arguments to Terminal. Arguments should be separated by a space. Remember that scripts are uniquely identified by their arguments as well as their name. For example, if you ran a script foo.js with the argument foodnstuff then in order to 'check' it you must also add the foodnstuff argument to the check command::

$ check foo.js foodnstuff

free

Shows the current server's RAM usage and availability

kill [pid] or kill [script] [args...]

Stops a script that is running with the specified PID, or script name and arguments. Arguments should be separated by a space. Remember that scripts are identified by their arguments as well as their name. For example, if you ran a script foo.js with the argument 1 and 2, then just typing kill foo.js will not work. You have to use:

$ kill foo.js 1 2

mem [script] [-t] [n]

Check how much RAM a script requires to run with n threads

nano [script]

Create/Edit a script. The name of the script must end with .js

ps

Displays all scripts that are actively running on the current server

rm [script]

Delete a script from the server. This is permanent

run [script] [-t] [n] [args...]

Run a script with n threads and the specified arguments. Each argument should be separated by a space. Both the arguments and thread specification are optional. If neither are specified, then the script will be run single-threaded with no arguments.

Examples:

Run foo.js single-threaded with no arguments::

$ run foo.js

Run foo.js with 10 threads and no arguments:

$ run foo.js -t 10

Run foo.js single-threaded with three arguments: [foodnstuff, sigma-cosmetics, 10]:

$ run foo.js foodnstuff sigma-cosmetics 10

Run foo.js with 50 threads and a single argument: [foodnstuff]:

$ run foo.js -t 50 foodnstuff

tail [pid] or tail [script] [args...]

Displays the logs of the script specified by the PID or name and arguments. Note that scripts are identified by their arguments as well as their name. For example, if you ran a script foo.js with the argument foodnstuff then in order to tail it you must also add the foodnstuff argument to the tail command as so: tail foo.js foodnstuff

top

Displays all active scripts and their RAM usage

Notes about how Scripts work offline

The scripts that you write and execute are in JavaScript. For this reason, it is not possible for these scripts to run while offline (when the game is closed). It is important to note that for this reason, conditionals such as if/else statements and certain commands such as purchaseHacknetNode() or nuke() will not work while the game is offline.

However, Scripts WILL continue to generate money and hacking exp for you while the game is offline. This offline production is based off of the scripts' production while the game is online.

grow() and weaken() are two functions that will also be applied when the game is offline, although at a slower rate compared to if the game was open. This is done by having each script keep track of the rate at which the grow() and weaken() commands are called when the game is online. These calculated rates are used to determine how many times these function calls would be made while the game is offline.

Also, note that because of the way the JavaScript engine works, whenever you reload or re-open the game all of the scripts that you are running will start running from the BEGINNING of the code. The game does not keep track of where exactly the execution of a script is when it saves/loads.