Personal_mirrors/bitburner-src
1
0
Fork 0
mirror of https://github.com/bitburner-official/bitburner-src.git synced 2024-09-21 05:18:46 +02:00
Code Issues Packages Projects Releases Wiki Activity
a97aaf3abb
bitburner-src/doc/build/html/netscriptjs.html
danielyxie 7d149f5f7b Cleaning up NetscriptJS documentation
2018-05-18 10:42:49 -05:00

327 lines
21 KiB
HTML
Raw Blame History

<!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) &#8212; 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">
<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 &quot;.ns&quot; or &quot;.js&quot; extension rather than &quot;.script&quot;. 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(&quot;foo.ns&quot;, &quot;purchasedServer1&quot;, &quot;100&quot;, &quot;randomArg&quot;);
</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 &quot;Netscript environment&quot; 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">&quot;Starting script here&quot;</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">&quot;foodnstuff&quot;</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">&quot;terminal-input&quot;</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">&quot;tr&quot;</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">&quot;td&quot;</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">&quot;posted&quot;</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">&quot;terminal-line&quot;</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">&quot;Red Text!&quot;</span><span class="p">,</span> <span class="s2">&quot;red&quot;</span><span class="p">);</span>
<span class="n">tprintColored</span><span class="p">(</span><span class="s2">&quot;Blue Text!&quot;</span><span class="p">,</span> <span class="s2">&quot;blue&quot;</span><span class="p">);</span>
<span class="n">tprintColored</span><span class="p">(</span><span class="s2">&quot;Use Hex Codes!&quot;</span><span class="p">,</span> <span class="s2">&quot;#3087E3&quot;</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 &quot;tprintColored.ns&quot;; //Importing from other NetscriptJS scripts works!
function ScriptJob(params) {
if (params.fn == null) {
throw new Error(&quot;No Filename (fn) passed into ScriptJob ctor&quot;);
}
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(&quot;Running &quot; + this.fn + &quot; on &quot; + ns.getHostname(), &quot;blue&quot;);
}
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(&quot;Executing &quot; + this.fn + &quot; on &quot; + target, &quot;blue&quot;);
}
export async function main(ns) {
tprintColored(&quot;Starting scriptScheduler.ns&quot;, &quot;red&quot;);
try {
let job = new ScriptJob({
fn: &quot;test.js&quot;,
threads: 1,
args: [&quot;foodnstuff&quot;]
});
await job.run(ns);
await job.exec(ns, &quot;foodnstuff&quot;);
} catch (e) {
ns.tprint(&quot;Exception thrown in scriptScheduler.ns: &quot; + 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>
</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">
&#169; 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>
Reference in New Issue View Git Blame Copy Permalink