mirror of
https://github.com/bitburner-official/bitburner-src.git
synced 2024-12-19 04:35:46 +01:00
197 lines
7.1 KiB
ReStructuredText
197 lines
7.1 KiB
ReStructuredText
.. _gameplay_scripts:
|
|
|
|
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 the :ref:`netscript` language.
|
|
|
|
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
|
|
:ref:`netscriptlearntoprogram`.
|
|
|
|
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. For more details, see
|
|
:ref:`netscript_script_arguments`.
|
|
|
|
For information on how to run scripts with arguments, see
|
|
:ref:`gameplay_working_with_scripts_in_terminal` and
|
|
:ref:`gameplay_working_with_scripts_in_netscript` below.
|
|
|
|
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 :js:func:`run`, :js:func:`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 :js:func:`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.
|
|
|
|
.. _gameplay_scripts_multithreadingscripts:
|
|
|
|
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
|
|
:js:func:`hack`, :js:func:`grow`, and :js:func:`weaken` Netscript 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
|
|
:ref:`mem_terminal_command` Terminal command to see how much RAM a script
|
|
requires with `n` threads::
|
|
|
|
$ mem [scriptname] -t n
|
|
|
|
.. _gameplay_working_with_scripts_in_terminal:
|
|
|
|
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 :ref:`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 a valid
|
|
extension: .script, or .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
|
|
|
|
.. _gameplay_working_with_scripts_in_netscript:
|
|
|
|
Working with Scripts in Netscript
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
TODO/Coming Soon...
|
|
|
|
Notes about how Scripts Work Offline
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
The scripts that you write and execute are interpreted 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 Netscript commands 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 Netscript interpreter is
|
|
implemented, 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.
|