Personal_mirrors/bitburner-src
1
0
Fork 0
mirror of https://github.com/bitburner-official/bitburner-src.git synced 2024-12-18 12:15:44 +01:00
Code Issues Packages Projects Releases Wiki Activity

update ns2 doc

Browse Source
This commit is contained in:
Olivier Gagnon 2021-11-05 15:43:38 -04:00
parent d83650c3bc
commit ec76c2ecca
3 changed files with 66 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
doc/source/netscript/autocomplete.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 60 KiB

131
doc/source/netscript/netscriptjs.rst
View File

@ -1,37 +1,37 @@
.. _netscriptjs:
NetscriptJS (Netscript 2.0)
===========================
Netscript 2.0, or Netscript JS, is the improved version of Netscript that
NS2
===
The improved version of Netscript that
allows users to write full-fledged Javascript code in their scripts, while
still being able to access the Netscript functions.
NetscriptJS was developed primarily by `Github user jaguilar <https://github.com/jaguilar>`_
ns2 was developed primarily by `Github user jaguilar <https://github.com/jaguilar>`_
On top of having almost all of the features and capabilities of JavaScript, NetscriptJS is also
significantly faster than Netscript 1.0.
On top of having almost all of the features and capabilities of JavaScript, ns2 is also
significantly faster than ns1.
This documentation will not go over any of the additional features of NetscriptJS, since
This documentation will not go over any of the additional features of ns2, since
there is plenty of documentation on Javascript available on the web.
Browser compatibility
---------------------
As of the time of writing this, a few browsers do not support `dynamic import <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import>`_ functionality and therefore cannot run NetscriptJS scripts. These browsers will thus only be capable of using Netscript 1.0.
As of the time of writing this, a few browsers do not support `dynamic import <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import>`_ functionality and therefore cannot run ns2 scripts. These browsers will thus only be capable of using ns1.
How to use NetscriptJS
How to use ns2
----------------------
Working with NetscriptJS scripts is the same as Netscript 1.0 scripts. The only difference
is that NetscriptJS scripts use the ".ns" or ".js" extension rather than ".script". E.g.::
Working with ns2 scripts is the same as ns1 scripts. The only difference
is that ns2 scripts use the ".ns" or ".js" extension rather than ".script". E.g.::
$ nano foo.ns
$ run foo.ns -t 100 arg1 arg2 arg3
exec("foo.ns", "purchasedServer1", "100", "randomArg");
The caveat when using NetscriptJS to write scripts is that your code must be
The caveat when using ns2 to write scripts is that your code must be
asynchronous. Furthermore, instead of using the global scope and executing your code
sequentially, NetscriptJS uses a :code:`main()` function as an entry point.
sequentially, ns2 uses a :code:`main()` function as an entry point.
Furthermore, the "Netscript environment" must be passed into a NetscriptJS script through
Furthermore, the "Netscript environment" must be passed into a ns2 script through
the main function. This environment includes all of the pre-defined Netscript functions
(:code:`hack()`, :code:`exec`, etc.) as well as the arguments you pass to the script.
@ -65,7 +65,7 @@ Here is a summary of all rules you need to follow when writing Netscript JS code
* **Do not write any infinite loops without using a** :code:`sleep` **or one of the timed Netscript functions like** :code:`hack`. Doing so will freeze your game.
* Any global variable declared in a NetscriptJS script is shared between all instances of that
* Any global variable declared in a ns2 script is shared between all instances of that
script. For example, assume you write a script *foo.ns* and declared a global variable like so::
//foo.ns
@ -91,69 +91,68 @@ Here is a summary of all rules you need to follow when writing Netscript JS code
the script will repeatedly print the value 5).
These global variables can be thought of as `C++ static class members <https://www.tutorialspoint.com/cplusplus/cpp_static_members.htm>`_,
where a NetscriptJS script is a class and a global variable is a static member within that class.
where a ns2 script is a class and a global variable is a static member within that class.
Examples
--------
Example
-------
**Script Scheduler (scriptScheduler.ns)**
early-hack-template.script
This script shows some of the new functionality that is available in NetscriptJS,
including objects and object constructors, changing an object's prototype, and
importing other NetscriptJS scripts::
.. code-block:: javascript
import {tprintColored} from "tprintColored.ns"; //Importing from other NetscriptJS scripts works!
function ScriptJob(params) {
if (params.fn == null) {
throw new Error("No Filename (fn) passed into ScriptJob ctor");
var target = args[0];
var moneyThresh = getServerMaxMoney(target) * 0.75;
var securityThresh = getServerMinSecurityLevel(target) + 5;
if (fileExists("BruteSSH.exe", "home")) {
brutessh(target);
}
nuke(target);
while(true) {
if (getServerSecurityLevel(target) > securityThresh) {
weaken(target);
} else if (getServerMoneyAvailable(target) < moneyThresh) {
grow(target);
} else {
hack(target);
}
this.fn = params.fn;
this.threads = params.threads ? params.threads : 1;
this.args = params.args ? params.args : [];
}
ScriptJob.prototype.run = function(ns) {
let runArgs = [this.fn, this.threads].concat(this.args);
if (!ns.run.apply(this, runArgs)) {
throw new Error("Unable to run " + this.fn + " on " +ns.getHostname());
}
tprintColored("Running " + this.fn + " on " + ns.getHostname(), "blue");
}
early-hack-template.ns
ScriptJob.prototype.exec = function(ns, target) {
ns.scp(this.fn, target);
let execArgs = [this.fn, target, this.threads].concat(this.args);
if (!ns.exec.apply(this, execArgs)) {
throw new Error("Unable to execute " + this.fn + " on " + target);
}
tprintColored("Executing " + this.fn + " on " + target, "blue");
}
.. code-block:: javascript
export async function main(ns) {
tprintColored("Starting scriptScheduler.ns", "red");
try {
let job = new ScriptJob({
fn: "test.js",
threads: 1,
args: ["foodnstuff"]
});
job.run(ns);
job.exec(ns, "foodnstuff");
} catch (e) {
ns.tprint("Exception thrown in scriptScheduler.ns: " + e);
var target = ns.args[0];
var moneyThresh = ns.getServerMaxMoney(target) * 0.75;
var securityThresh = ns.getServerMinSecurityLevel(target) + 5;
if (ns.fileExists("BruteSSH.exe", "home")) {
ns.brutessh(target);
}
ns.nuke(target);
while(true) {
if (ns.getServerSecurityLevel(target) > securityThresh) {
await ns.weaken(target);
} else if (ns.getServerMoneyAvailable(target) < moneyThresh) {
await ns.grow(target);
} else {
await ns.hack(target);
}
}
}
Final Note
----------
NetscriptJS opens up a lot of possibilities when scripting. I look forward to seeing
the scripts that people come up with. Just remember that the power and capabilities of
NetscriptJS come with risks. Please backup your save if you're going to experiment with
NetscriptJS and report any serious exploits.
What's with the weird comment
-----------------------------
With great power comes great responsibility
You may have noticed that every new ns2 file will contains the following comment.
Happy hacking
.. code-block:: javascript
/**
* @param {NS} ns
**/
This command is used to help the text editor autocomplete functions in the Netscript API. You can enabling it by pressing ctrl+space after `ns.`
.. image:: autocomplete.png
The comment can be safely removed but it is recommended to keep it as it will help you.

3
doc/source/netscript/netscriptscriptarguments.rst
View File

@ -22,5 +22,4 @@ into a script using::
args.length
**WARNING: Do not try to modify the args array. This will break the game.
I will do my best to prevent players from doing this.**
**WARNING: Do not try to modify the args array. This will break the game.**