mirror of
https://github.com/bitburner-official/bitburner-src.git
synced 2024-11-13 03:03:54 +01:00
328 lines
21 KiB
HTML
328 lines
21 KiB
HTML
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="English">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<title>NetscriptJS (Netscript 2.0) — Bitburner 1.0 documentation</title>
|
|
<link rel="stylesheet" href="_static/agogo.css" type="text/css" />
|
|
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
|
<script type="text/javascript">
|
|
var DOCUMENTATION_OPTIONS = {
|
|
URL_ROOT: './',
|
|
VERSION: '1.0',
|
|
COLLAPSE_INDEX: false,
|
|
FILE_SUFFIX: '.html',
|
|
HAS_SOURCE: true,
|
|
SOURCELINK_SUFFIX: '.txt'
|
|
};
|
|
</script>
|
|
<script type="text/javascript" src="_static/jquery.js"></script>
|
|
<script type="text/javascript" src="_static/underscore.js"></script>
|
|
<script type="text/javascript" src="_static/doctools.js"></script>
|
|
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
|
|
<link rel="index" title="Index" href="genindex.html" />
|
|
<link rel="search" title="Search" href="search.html" />
|
|
<link rel="next" title="Netscript Data Types and Variables" href="netscriptdatatypes.html" />
|
|
<link rel="prev" title="Netscript Documentation" href="netscript.html" />
|
|
</head>
|
|
<body>
|
|
<div class="header-wrapper" role="banner">
|
|
<div class="header">
|
|
<div class="headertitle"><a
|
|
href="index.html">Bitburner 1.0 documentation</a></div>
|
|
<div class="rel" role="navigation" aria-label="related navigation">
|
|
<a href="netscript.html" title="Netscript Documentation"
|
|
accesskey="P">previous</a> |
|
|
<a href="netscriptdatatypes.html" title="Netscript Data Types and Variables"
|
|
accesskey="N">next</a> |
|
|
<a href="genindex.html" title="General Index"
|
|
accesskey="I">index</a>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="content-wrapper">
|
|
<div class="content">
|
|
<div class="document">
|
|
|
|
<div class="documentwrapper">
|
|
<div class="bodywrapper">
|
|
<div class="body" role="main">
|
|
|
|
<div class="section" id="netscriptjs-netscript-2-0">
|
|
<span id="netscriptjs"></span><h1>NetscriptJS (Netscript 2.0)<a class="headerlink" href="#netscriptjs-netscript-2-0" title="Permalink to this headline">¶</a></h1>
|
|
<p>Netscript 2.0, or Netscript JS, is the new and improved version of Netscript that
|
|
allows users to write (almost) full-fledged Javascript code in their scripts, while
|
|
still being able to access the Netscript functions.</p>
|
|
<p>NetscriptJS was developed primarily by <a class="reference external" href="https://github.com/jaguilar">Github user jaguilar</a></p>
|
|
<p>On top of having almost all of the features and capabilities of Javascript, NetscriptJS is also
|
|
significantly faster than Netscript 1.0.</p>
|
|
<p>This documentation will not go over any of the additional features of NetscriptJS, since
|
|
there is plenty of documentation on Javascript available on the web.</p>
|
|
<div class="section" id="netscriptjs-in-mozilla-firefox">
|
|
<h2>NetscriptJS in Mozilla Firefox<a class="headerlink" href="#netscriptjs-in-mozilla-firefox" title="Permalink to this headline">¶</a></h2>
|
|
<p>As of the time of writing this, the Mozilla Firefox browser does not support
|
|
dynamic import functionality and therefore cannot run NetscriptJS scripts.</p>
|
|
<p>(This may be some option/method for enabling this in Firefox, but I don't know
|
|
what is it)</p>
|
|
</div>
|
|
<div class="section" id="how-to-use-netscriptjs">
|
|
<h2>How to use NetscriptJS<a class="headerlink" href="#how-to-use-netscriptjs" title="Permalink to this headline">¶</a></h2>
|
|
<p>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.:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span>$ nano foo.ns
|
|
$ run foo.ns -t 100 arg1 arg2 arg3
|
|
exec("foo.ns", "purchasedServer1", "100", "randomArg");
|
|
</pre></div>
|
|
</div>
|
|
<p>The caveat when using NetscriptJS 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 class="code docutils literal"><span class="pre">main()</span></code> function as an entry point.</p>
|
|
<p>Furthermore, the "Netscript environment" must be passed into a NetscriptJS script through
|
|
the main function. This environment includes all of the pre-defined Netscript functions
|
|
(<code class="code docutils literal"><span class="pre">hack()</span></code>, <code class="code docutils literal"><span class="pre">exec</span></code>, etc.) as well as the arguments you pass to the script.</p>
|
|
<p>Therefore, the signature of the <code class="code docutils literal"><span class="pre">main()</span></code> function must be:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">export</span> <span class="k">async</span> <span class="n">function</span> <span class="n">main</span><span class="p">(</span><span class="n">ns</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="n">ns</span><span class="o">.</span><span class="n">print</span><span class="p">(</span><span class="s2">"Starting script here"</span><span class="p">);</span>
|
|
<span class="k">await</span> <span class="n">ns</span><span class="o">.</span><span class="n">hack</span><span class="p">(</span><span class="s2">"foodnstuff"</span><span class="p">);</span> <span class="o">//</span><span class="n">Use</span> <span class="n">Netscript</span> <span class="n">hack</span> <span class="n">function</span>
|
|
<span class="n">ns</span><span class="o">.</span><span class="n">print</span><span class="p">(</span><span class="n">ns</span><span class="o">.</span><span class="n">args</span><span class="p">);</span> <span class="o">//</span><span class="n">The</span> <span class="n">script</span> <span class="n">arguments</span> <span class="n">must</span> <span class="n">be</span> <span class="n">prefaced</span> <span class="k">with</span> <span class="n">ns</span> <span class="k">as</span> <span class="n">well</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Here is a summary of all rules you need to follow when writing Netscript JS code:</p>
|
|
<ul>
|
|
<li><p class="first">Write <code class="code docutils literal"><span class="pre">await</span></code> before any call to the following Netscript functions:</p>
|
|
<blockquote>
|
|
<div><ul class="simple">
|
|
<li>hack</li>
|
|
<li>grow</li>
|
|
<li>weaken</li>
|
|
<li>sleep</li>
|
|
<li>run</li>
|
|
<li>exec</li>
|
|
<li>prompt</li>
|
|
</ul>
|
|
</div></blockquote>
|
|
</li>
|
|
<li><p class="first">Any function that contains <code class="code docutils literal"><span class="pre">await</span></code> must be declared as <code class="code docutils literal"><span class="pre">async</span></code></p>
|
|
</li>
|
|
<li><p class="first">Always <code class="code docutils literal"><span class="pre">await</span></code> any function that is marked as <code class="code docutils literal"><span class="pre">async</span></code></p>
|
|
</li>
|
|
<li><p class="first">Any functions that you want to be visible from other scripts must be marked with <code class="code docutils literal"><span class="pre">export</span></code>.</p>
|
|
</li>
|
|
<li><p class="first"><strong>Do not write any infinite loops without using a</strong> <code class="code docutils literal"><span class="pre">sleep</span></code> <strong>or one of the timed Netscript functions like</strong> <code class="code docutils literal"><span class="pre">hack</span></code>. Doing so will crash your game.</p>
|
|
</li>
|
|
<li><p class="first">Any global variable declared in a NetscriptJS script is shared between all instances of that
|
|
script. For example, assume you write a script <em>foo.ns</em> and declared a global variable like so:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="o">//</span><span class="n">foo</span><span class="o">.</span><span class="n">ns</span>
|
|
<span class="n">let</span> <span class="n">globalVariable</span><span class="p">;</span>
|
|
|
|
<span class="n">export</span> <span class="k">async</span> <span class="n">function</span> <span class="n">main</span><span class="p">(</span><span class="n">ns</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="n">globalVariable</span> <span class="o">=</span> <span class="n">ns</span><span class="o">.</span><span class="n">args</span><span class="o">.</span><span class="n">length</span><span class="p">;</span>
|
|
<span class="k">while</span><span class="p">(</span><span class="n">true</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="n">ns</span><span class="o">.</span><span class="n">tprint</span><span class="p">(</span><span class="n">globalVariable</span><span class="p">);</span>
|
|
<span class="k">await</span> <span class="n">ns</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">3000</span><span class="p">);</span>
|
|
<span class="p">}</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Then, you ran multiple instances of <em>foo.ns</em>:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span>$ run foo.ns 1
|
|
$ run foo.ns 1 2 3
|
|
$ run foo.ns 1 2 3 4 5
|
|
</pre></div>
|
|
</div>
|
|
<p>Then all three instances of foo.ns will share the same instance of <code class="code docutils literal"><span class="pre">globalVariable</span></code>.
|
|
(In this example, the value of <code class="code docutils literal"><span class="pre">globalVariable</span></code> will be set to 5 because the
|
|
last instance of <em>foo.ns</em> to run has 5 arguments. This means that all three instances of
|
|
the script will repeatedly print the value 5).</p>
|
|
<p>These global variables can be thought of as <a class="reference external" href="https://www.tutorialspoint.com/cplusplus/cpp_static_members.htm">C++ static class members</a>,
|
|
where a NetscriptJS script is a class and a global variable is a static member within that class.</p>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="warnings">
|
|
<h2>Warnings<a class="headerlink" href="#warnings" title="Permalink to this headline">¶</a></h2>
|
|
<p>The NetscriptJS evaluation engine works by converting your code into a blob URL and then
|
|
using a dynamic import to load your code as a module. Every unique NetscriptJS script
|
|
is loaded as its own module. This means that
|
|
making a small edit to a NetscriptJS script results in a new module being generated.</p>
|
|
<p>At this point, we have been unable to find a method for deleting modules from browsers so that
|
|
they get garbage collected.</p>
|
|
<p>The result is that these modules from NetscriptJS scripts accumulate in your browser,
|
|
using memory that never gets released. Over time, this results in a memory-leak type
|
|
situation that can slow down your computer.</p>
|
|
<p>Therefore, there are two recommendations for those who decide to use NetscriptJS:</p>
|
|
<p>1. Every now and then, close and re-open the game. This will clear all of the modules.
|
|
To be safe, I recommend <strong>completely</strong> closing the game's tab and then re-opening it.
|
|
Depending on your browser, a refresh or page reload does not always clear the modules.</p>
|
|
<p>2. Only use NetscriptJS scripts when needed. It is very unlikely that NetscriptJS
|
|
is needed for very simple scripts. By doing this, you will reduce the number of modules
|
|
that are loaded.</p>
|
|
</div>
|
|
<div class="section" id="examples">
|
|
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
|
|
<p><strong>DOM Manipulation (tprintColored.ns)</strong></p>
|
|
<p>Directly alter the game's terminal and print colored text:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">export</span> <span class="n">function</span> <span class="n">tprintColored</span><span class="p">(</span><span class="n">txt</span><span class="p">,</span> <span class="n">color</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="n">let</span> <span class="n">terminalInput</span> <span class="o">=</span> <span class="n">document</span><span class="o">.</span><span class="n">getElementById</span><span class="p">(</span><span class="s2">"terminal-input"</span><span class="p">);</span>
|
|
<span class="n">let</span> <span class="n">rowElement</span> <span class="o">=</span> <span class="n">document</span><span class="o">.</span><span class="n">createElement</span><span class="p">(</span><span class="s2">"tr"</span><span class="p">);</span>
|
|
<span class="n">let</span> <span class="n">cellElement</span> <span class="o">=</span> <span class="n">document</span><span class="o">.</span><span class="n">createElement</span><span class="p">(</span><span class="s2">"td"</span><span class="p">);</span>
|
|
|
|
<span class="n">rowElement</span><span class="o">.</span><span class="n">classList</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"posted"</span><span class="p">);</span>
|
|
<span class="n">cellElement</span><span class="o">.</span><span class="n">classList</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">"terminal-line"</span><span class="p">);</span>
|
|
<span class="n">cellElement</span><span class="o">.</span><span class="n">style</span><span class="o">.</span><span class="n">color</span> <span class="o">=</span> <span class="n">color</span><span class="p">;</span>
|
|
<span class="n">cellElement</span><span class="o">.</span><span class="n">innerText</span> <span class="o">=</span> <span class="n">txt</span><span class="p">;</span>
|
|
|
|
<span class="n">rowElement</span><span class="o">.</span><span class="n">appendChild</span><span class="p">(</span><span class="n">cellElement</span><span class="p">);</span>
|
|
<span class="n">terminalInput</span><span class="o">.</span><span class="n">before</span><span class="p">(</span><span class="n">rowElement</span><span class="p">);</span>
|
|
<span class="p">}</span>
|
|
|
|
<span class="n">export</span> <span class="k">async</span> <span class="n">function</span> <span class="n">main</span><span class="p">(</span><span class="n">ns</span><span class="p">)</span> <span class="p">{</span>
|
|
<span class="n">tprintColored</span><span class="p">(</span><span class="s2">"Red Text!"</span><span class="p">,</span> <span class="s2">"red"</span><span class="p">);</span>
|
|
<span class="n">tprintColored</span><span class="p">(</span><span class="s2">"Blue Text!"</span><span class="p">,</span> <span class="s2">"blue"</span><span class="p">);</span>
|
|
<span class="n">tprintColored</span><span class="p">(</span><span class="s2">"Use Hex Codes!"</span><span class="p">,</span> <span class="s2">"#3087E3"</span><span class="p">);</span>
|
|
<span class="p">}</span>
|
|
</pre></div>
|
|
</div>
|
|
<p><strong>Script Scheduler (scriptScheduler.ns)</strong></p>
|
|
<p>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:</p>
|
|
<div class="highlight-default"><div class="highlight"><pre><span></span>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");
|
|
}
|
|
|
|
this.fn = params.fn;
|
|
this.threads = params.threads ? params.threads : 1;
|
|
this.args = params.args ? params.args : [];
|
|
}
|
|
|
|
ScriptJob.prototype.run = async function(ns) {
|
|
let runArgs = [this.fn, this.threads].concat(this.args);
|
|
await ns.run.apply(this, runArgs);
|
|
tprintColored("Running " + this.fn + " on " + ns.getHostname(), "blue");
|
|
}
|
|
|
|
ScriptJob.prototype.exec = async function(ns, target) {
|
|
ns.scp(this.fn, target);
|
|
|
|
let execArgs = [this.fn, target, this.threads].concat(this.args);
|
|
await ns.exec.apply(this, execArgs);
|
|
|
|
tprintColored("Executing " + this.fn + " on " + target, "blue");
|
|
}
|
|
|
|
export async function main(ns) {
|
|
tprintColored("Starting scriptScheduler.ns", "red");
|
|
try {
|
|
let job = new ScriptJob({
|
|
fn: "test.js",
|
|
threads: 1,
|
|
args: ["foodnstuff"]
|
|
});
|
|
await job.run(ns);
|
|
await job.exec(ns, "foodnstuff");
|
|
} catch (e) {
|
|
ns.tprint("Exception thrown in scriptScheduler.ns: " + e);
|
|
}
|
|
}
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="final-note">
|
|
<h2>Final Note<a class="headerlink" href="#final-note" title="Permalink to this headline">¶</a></h2>
|
|
<p>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.</p>
|
|
<p>With great power comes great responsibility</p>
|
|
<p>Happy hacking</p>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sidebar">
|
|
<h3>Table Of Contents</h3>
|
|
<p class="caption"><span class="caption-text">Contents:</span></p>
|
|
<ul class="current">
|
|
<li class="toctree-l1 current"><a class="reference internal" href="netscript.html"> Netscript</a><ul class="current">
|
|
<li class="toctree-l2 current"><a class="current reference internal" href="#"> NetscriptJS (Netscript 2.0)</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="#netscriptjs-in-mozilla-firefox">NetscriptJS in Mozilla Firefox</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#how-to-use-netscriptjs">How to use NetscriptJS</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#warnings">Warnings</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#examples">Examples</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#final-note">Final Note</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="netscriptdatatypes.html"> Data Types and Variables</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="netscriptoperators.html"> Operators</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="netscriptloopsandconditionals.html"> Loops and Conditionals</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="netscriptscriptarguments.html"> Script Arguments</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="netscriptfunctions.html"> Basic Functions</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="netscriptadvancedfunctions.html"> Advanced Functions</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="netscripthacknetnodeapi.html"> Hacknet Node API</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="netscriptixapi.html"> Trade Information eXchange (TIX) API</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="netscriptsingularityfunctions.html"> Singularity Functions</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="netscriptmisc.html"> Miscellaneous</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="terminal.html"> Terminal</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="shortcuts.html"> Keyboard Shortcuts</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="changelog.html"> Changelog</a></li>
|
|
</ul>
|
|
|
|
<div role="search">
|
|
<h3 style="margin-top: 1.5em;">Search</h3>
|
|
<form class="search" action="search.html" method="get">
|
|
<input type="text" name="q" />
|
|
<input type="submit" value="Go" />
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|
<input type="hidden" name="area" value="default" />
|
|
</form>
|
|
</div>
|
|
</div>
|
|
<div class="clearer"></div>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="footer-wrapper">
|
|
<div class="footer">
|
|
<div class="left">
|
|
<div role="navigation" aria-label="related navigaton">
|
|
<a href="netscript.html" title="Netscript Documentation"
|
|
>previous</a> |
|
|
<a href="netscriptdatatypes.html" title="Netscript Data Types and Variables"
|
|
>next</a> |
|
|
<a href="genindex.html" title="General Index"
|
|
>index</a>
|
|
</div>
|
|
<div role="note" aria-label="source link">
|
|
<br/>
|
|
<a href="_sources/netscriptjs.rst.txt"
|
|
rel="nofollow">Show Source</a>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="right">
|
|
|
|
<div class="footer" role="contentinfo">
|
|
© Copyright 2017, Bitburner.
|
|
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.4.
|
|
</div>
|
|
</div>
|
|
<div class="clearer"></div>
|
|
</div>
|
|
</div>
|
|
|
|
</body>
|
|
</html> |