mirror of
https://github.com/bitburner-official/bitburner-src.git
synced 2026-05-03 14:27:03 +02:00
Updated documentation for new Netscript. Added new polyfills for new JS interpreter
This commit is contained in:
danielyxie
@@ -14,10 +14,9 @@ to reach out to the developer!
|
||||
:maxdepth: 5
|
||||
:caption: Sections:
|
||||
|
||||
Learn to Program <netscriptlearntoprogram>
|
||||
Netscript 1.0 <netscript1>
|
||||
NetscriptJS (Netscript 2.0) <netscriptjs>
|
||||
Data Types and Variables <netscriptdatatypes>
|
||||
Operators <netscriptoperators>
|
||||
Loops and Conditionals <netscriptloopsandconditionals>
|
||||
Script Arguments <netscriptscriptarguments>
|
||||
Basic Functions <netscriptfunctions>
|
||||
Advanced Functions <netscriptadvancedfunctions>
|
||||
|
||||
@@ -0,0 +1,32 @@
|
||||
.. _netscript1:
|
||||
|
||||
Netscript 1.0
|
||||
=============
|
||||
Netscript 1.0 is implemented using modified version of Neil Fraser's
|
||||
`JS-Interpreter <https://github.com/NeilFraser/JS-Interpreter>`_.
|
||||
|
||||
This interpreter was created for ES5, which means that the code written
|
||||
for Netscript 1.0 must be compliant for that version. However, some additional
|
||||
ES6+ features are implemented through polyfills.
|
||||
|
||||
Netscript 1.0 scripts end with the ".script" extension.
|
||||
|
||||
Which ES6+ features are supported?
|
||||
----------------------------------
|
||||
|
||||
Netscript 1.0 is a ES5 interpreter, but the following features from versions ES6 and
|
||||
above are supported as well.
|
||||
|
||||
If there is an additional ES6+ feature you would like to see implemented with a polyfill,
|
||||
feel free to `open an issue <https://github.com/danielyxie/bitburner/issues>`_ (and provide
|
||||
the polyfill if possible).
|
||||
|
||||
* import - See :ref:`netscriptimporting`
|
||||
* `Array <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array>`_
|
||||
* `find() <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/find>`_
|
||||
* `findIndex() <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/findIndex>`_
|
||||
* `includes() <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/includes>`_
|
||||
* `String <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String>`_
|
||||
* `endsWith() <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith>`_
|
||||
* `includes() <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes>`_
|
||||
* `startsWith() <https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith>`_
|
||||
@@ -1,44 +0,0 @@
|
||||
Netscript Data Types and Variables
|
||||
==================================
|
||||
|
||||
|
||||
Data Types
|
||||
----------
|
||||
Netscript supports three primitive data types:
|
||||
|
||||
**Numbers** - Positive numerics, such as integers and floats. Examples: 6, 0, 10.5
|
||||
|
||||
**Strings** - A sequence of characters that represents text. The characters must be encapsulated by single or
|
||||
double quotes. Example: "This is a string" or equivalently 'This is a string'.
|
||||
*Strings are fully functional* `Javascript strings <https://www.w3schools.com/jsref/jsref_obj_string.asp>`_,
|
||||
*which means that all of the member functions of Javascript strings such as toLowerCase() and includes() are also available in Netscript!*
|
||||
|
||||
**Boolean** - true or false
|
||||
|
||||
**Array** - An array is a special container object that is capable of holding many different values. Arrays are simply Javascript
|
||||
arrays, and most Javascript array methods can be used in Netscript as well (join(), pop(), splice(), etc.). You can read more about
|
||||
`Javascript arrays here <https://www.w3schools.com/js/js_arrays.asp>`_
|
||||
|
||||
Variables
|
||||
---------
|
||||
|
||||
Variables can be thought of as named containers. Their purpose is to label and store data. The data stored in the
|
||||
variable can then be accessed and changed by referring to the variable's name. The name of a variable must start with
|
||||
either a letter or an underscore. The rest of the variable name can contain any alphanumeric (letters and numbers),
|
||||
as well as hyphens and underscores.
|
||||
|
||||
The Netscript language is untyped, meaning that any variable can hold any of the data types above. The value type of a variable
|
||||
can also change. For example, if a variable initially holds a number, it can later hold a string.
|
||||
|
||||
The following shows how you can declare and initialize variables::
|
||||
|
||||
i = 1;
|
||||
s = "This is a string";
|
||||
b = false;
|
||||
|
||||
After declaring a variable, the values in variables can be used simply by referencing the name. For example::
|
||||
|
||||
j = i + 5;
|
||||
s2 = s + " Adding more letters onto the string"
|
||||
|
||||
The first command above will store the value 6 in the variable j. The second command will store the string "This is a string Adding more letters onto the string" into the variable s2.
|
||||
@@ -8,7 +8,7 @@ still being able to access the Netscript functions.
|
||||
|
||||
NetscriptJS 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
|
||||
On top of having almost all of the features and capabilities of JavaScript, NetscriptJS is also
|
||||
significantly faster than Netscript 1.0.
|
||||
|
||||
This documentation will not go over any of the additional features of NetscriptJS, since
|
||||
|
||||
@@ -0,0 +1,70 @@
|
||||
.. _netscriptlearntoprogram:
|
||||
|
||||
Learn to Program in Netscript
|
||||
=============================
|
||||
Netscript is simply a subset of
|
||||
`JavaScript <https://developer.mozilla.org/en-US/docs/Web/JavaScript>`_,
|
||||
with some additional functions added in to allow interaction with the game.
|
||||
|
||||
For Beginner Programmers
|
||||
------------------------
|
||||
If you have little to no programming experience, that's okay! You don't need to be
|
||||
a great programmer in order to enjoy or play this game. In fact, this game could
|
||||
help you learn some basic programming concepts.
|
||||
|
||||
Here are some good tutorials for learning programming/JavaScript as a beginner:
|
||||
|
||||
* `Learn-JS <http://www.learn-js.org/en/Welcome>`_
|
||||
* `Speaking JavaScript <http://speakingjs.com/es5/index.html>`_
|
||||
This is a bit on the longer side. You can skip all of the historical
|
||||
background stuff. Recommended chapters: 1, 7-18
|
||||
|
||||
For Experienced Programmers
|
||||
---------------------------
|
||||
The following section lists several good tutorials/resources for those who have experience
|
||||
programming but who have not worked extensively with JavaScript before.
|
||||
|
||||
Before that, however, it's important to clarify some terminology about the different
|
||||
versions of JavaScript. These are summarized in this article:
|
||||
|
||||
`WTF is ES6, ES8, ES2017, ECMAScript... <https://codeburst.io/javascript-wtf-is-es6-es8-es-2017-ecmascript-dca859e4821c>`_
|
||||
|
||||
An important takeaway from this article is that ES6, also known as ES2015, introduced
|
||||
many major features that are commonly seen in modern JavaScript programming. However, this
|
||||
means that ES5 engines and interpreters will fail if they encounters these ES6 features. You'll see why this
|
||||
is important further down.
|
||||
|
||||
* `MDN Introduction to JS <https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript>`_
|
||||
* `Eloquent JavaScript (ES6+) <http://eloquentjavascript.net/>`_
|
||||
Recommended Chapters: Introduction, 1-6
|
||||
* `Modern Javascript Tutorial (ES6+) <https://javascript.info/>`_
|
||||
Recommended Chapters: 2, 4-6
|
||||
|
||||
Netscript 1.0 vs Netscript 2.0
|
||||
------------------------------
|
||||
There are two versions of Netscript:
|
||||
|
||||
* :doc:`netscript1`
|
||||
* :doc:`netscriptjs`
|
||||
|
||||
Visit the pages above to get more details about each version. If you are new
|
||||
to programming or unfamiliar with JavaScript, I would recommend starting out
|
||||
with :doc:`netscript1`. Experienced web developers can use :doc:`netscriptjs`
|
||||
to take advantage of faster speeds and additional features.
|
||||
|
||||
Here is a short summary of the differences between Netscript 1.0 and Netscript 2.0:
|
||||
|
||||
**Netscript 1.0**
|
||||
|
||||
* ES5
|
||||
* Some ES6 features implemented with polyfills
|
||||
* Slow compared to NetscriptJS (interpreter runs at the "Netscript Exec Time" speed configured in options)
|
||||
* Compatible with all browsers
|
||||
|
||||
**Netscript JS (Netscript 2.0)**
|
||||
|
||||
* Supports (almost) all features of modern JavaScript
|
||||
* Extremely fast - code is executed as an Async Function
|
||||
* Currently only works with Google Chrome browser
|
||||
* Each script becomes a module and therefore all instances of that script can easily
|
||||
share data between each other (essentially global/static variables)
|
||||
@@ -1,39 +0,0 @@
|
||||
Netscript Loops and Conditionals
|
||||
================================
|
||||
|
||||
|
||||
Netscript loops and conditionals are the same as Javascript. However, the one caveat is that when declaring variables such as the
|
||||
iterator for traversing a loop, you should not use the 'var' or 'let' keyword. For reference, you can see the Javascript
|
||||
documentation for loops/conditionals here:
|
||||
|
||||
`While loops <https://www.w3schools.com/js/js_loop_while.asp>`_
|
||||
|
||||
`For loops <https://www.w3schools.com/js/js_loop_for.asp>`_
|
||||
|
||||
`Conditionals (If/Else statements) <https://www.w3schools.com/js/js_if_else.asp>`_
|
||||
|
||||
Here are some simple code examples that show the use of loops and conditionals in Netscript.
|
||||
|
||||
The following is a while loop that runs the hack() Netscript function ten times::
|
||||
|
||||
i = 0;
|
||||
while (i < 10) {
|
||||
hack('foodnstuff');
|
||||
i = i + 1;
|
||||
}
|
||||
|
||||
The following is a for loop that runs the hack() Netscript function ten times::
|
||||
|
||||
for (i = 0; i < 10; ++i) {
|
||||
hack("foodnstuff");
|
||||
}
|
||||
|
||||
The following is a conditional that uses the getServerMoneyAvailable() Netscript function to check how much money
|
||||
exists on the 'foodnstuff' server. If there is more than $200,000 on the server, then the server will be hacked.
|
||||
Otherwise, the money available on the server will be grown using the grow() Netscript function::
|
||||
|
||||
if (getServerMoneyAvailable('foodnstuff') > 200000) {
|
||||
hack("foodnstuff");
|
||||
} else {
|
||||
grow("foodnstuff");
|
||||
}
|
||||
@@ -142,6 +142,8 @@ Comments are not evaluated as code, and can be used to document and/or explain c
|
||||
* comment */
|
||||
print("This code will actually get executed");
|
||||
|
||||
.. _netscriptimporting:
|
||||
|
||||
Importing Functions
|
||||
-------------------
|
||||
|
||||
@@ -201,7 +203,7 @@ to specify a namespace for the import::
|
||||
//...
|
||||
}
|
||||
|
||||
Note that exporting functions is not required.
|
||||
Note that exporting functions is not required.
|
||||
|
||||
|
||||
Javascript Math Module
|
||||
|
||||
@@ -1,53 +0,0 @@
|
||||
Netscript Operators
|
||||
===================
|
||||
|
||||
Operators
|
||||
---------
|
||||
|
||||
Binary Operators
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
Binary operators require two operands and produce a result based on their values. In general, binary
|
||||
operators do not change the value of the operands.
|
||||
|
||||
=========== =========================== ==============================================================
|
||||
Operator Name Example/Comments
|
||||
=========== =========================== ==============================================================
|
||||
= Assignment i = 5 would assign the value 5 to the variable i
|
||||
\+ Addition 5 + 12 would return 17
|
||||
\- Subtraction 20 - 8 would return 12
|
||||
\* Multiplication 4 * 5 would return 20
|
||||
\/ Division 50 / 10 would return 5
|
||||
% Modulo 50 % 9 would return 5
|
||||
&& Logical AND true && false would return false
|
||||
|| Logical OR true || false would return true
|
||||
< Less than 4 < 5 would return true
|
||||
> Greater than 4 > 5 would return false
|
||||
<= Less than or equal to 5 <= 5 would return true
|
||||
>= Greater than or equal to 5 >= 4 would return true
|
||||
== Equality 1 == 1 would return true
|
||||
!= Inequality 4 != 5 would return true
|
||||
=== Strict equality 1 === "1" would return false
|
||||
!== Strict inequality 1 !== "1" would return true
|
||||
=========== =========================== ==============================================================
|
||||
|
||||
Unary Operators
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
Unary operators require only a single operand and produce a result based on their values. Some unary operators will
|
||||
change the value of their operands. For example::
|
||||
|
||||
i = 0;
|
||||
++i;
|
||||
|
||||
Running the pre-increment unary operator (++) in the code above changes the value of the variable i.
|
||||
|
||||
|
||||
=============== =========================== ==============================================================================================
|
||||
Operator Name Example/comments
|
||||
=============== =========================== ==============================================================================================
|
||||
! Logical NOT operator !true would return false, and !false would return true. Does not change operand's value
|
||||
\- Negation Negates a number. Only works for numerics. Does not change operand's value
|
||||
++ Pre-increment ++i or i++. WARNING: This only pre-increments, even if you put i++. Changes operand's value
|
||||
-- Pre-decrement --i or i--. WARNING: This only pre-decrements, even if you put i--. Changes operand's value
|
||||
=============== =========================== ==============================================================================================
|
||||
Reference in New Issue
Block a user