DOCUMENTATION: Convert old rst files to md files

src/Documentation/doc/advanced/netscripthacknetnodeapi.md

@@ -0,0 +1,123 @@
+# Netscript Hacknet Node API
+
+## Warning
+
+Not all functions in the Hacknet Node API are immediately available. For this reason, the documentation for this API may contain spoilers for the game.
+
+Netscript provides the following API for accessing and upgrading your Hacknet Nodes through scripts.
+
+Note that none of these functions will write to the script's logs. If you want to see what your script is doing, you will have to print to the logs yourself.
+
+Hacknet Node API functions must be accessed through the `hacknet` namespace.
+
+### In Netscript 1.0:
+```javascript
+hacknet.purchaseNode();
+hacknet.getNodeStats(3).level;
+```
+
+### In NetscriptJS:
+```javascript
+ns.hacknet.purchaseNode();
+ns.hacknet.getNodeStats(3).level;
+```
+
+## Hacknet Nodes API Functions
+
+- [`numNodes()`](hacknetnodeapi/numNodes)
+- [`purchaseNode()`](hacknetnodeapi/purchaseNode)
+- [`getPurchaseNodeCost()`](hacknetnodeapi/getPurchaseNodeCost)
+- [`getNodeStats()`](hacknetnodeapi/getNodeStats)
+- [`upgradeLevel()`](hacknetnodeapi/upgradeLevel)
+- [`upgradeRam()`](hacknetnodeapi/upgradeRam)
+- [`upgradeCore()`](hacknetnodeapi/upgradeCore)
+- [`getLevelUpgradeCost()`](hacknetnodeapi/getLevelUpgradeCost)
+- [`getRamUpgradeCost()`](hacknetnodeapi/getRamUpgradeCost)
+- [`getCoreUpgradeCost()`](hacknetnodeapi/getCoreUpgradeCost)
+
+## Referencing a Hacknet Node
+
+Most of the functions in the Hacknet Node API perform an operation on a single node. Therefore, a numeric index is used to identify and specify which Hacknet Node a function should act on. This index number corresponds to the number at the end of the name of the Hacknet Node.
+
+For example:
+- The first Hacknet Node you purchase will have the name `hacknet-node-0` and is referenced using index `0`.
+- The fifth Hacknet Node you purchase will have the name `hacknet-node-4` and is referenced using index `4`.
+
+## RAM Cost
+
+Accessing the `hacknet` namespace incurs a one-time cost of **4 GB of RAM**. In other words, using multiple Hacknet Node API functions in a script will not cost more than 4 GB of RAM.
+
+## Utilities
+
+The following function is not officially part of the Hacknet Node API, but it can be useful when writing Hacknet Node-related scripts. Since it is not part of the API, it does not need to be accessed using the `hacknet` namespace.
+
+- `getHacknetMultipliers`
+
+## Example Script
+
+The following is an example of one way a script can be used to automate the purchasing and upgrading of Hacknet Nodes.
+
+This script attempts to purchase Hacknet Nodes until the player has a total of 8. Then, it gradually upgrades those nodes to **level 80**, **16 GB RAM**, and **8 cores**.
+
+```javascript
+export async function main(ns) {
+    function myMoney() {
+        return ns.getServerMoneyAvailable("home");
+    }
+
+    ns.disableLog("getServerMoneyAvailable");
+    ns.disableLog("sleep");
+
+    const cnt = 8;
+
+    while (ns.hacknet.numNodes() < cnt) {
+        let res = ns.hacknet.purchaseNode();
+        if (res != -1) ns.print("Purchased Hacknet Node with index " + res);
+        await ns.sleep(1000);
+    }
+
+    ns.tprint("All " + cnt + " nodes purchased");
+
+    for (let i = 0; i < cnt; i++) {
+        while (ns.hacknet.getNodeStats(i).level <= 80) {
+            let cost = ns.hacknet.getLevelUpgradeCost(i, 1);
+            while (myMoney() < cost) {
+                ns.print("Need $" + cost + " . Have $" + myMoney());
+                await ns.sleep(3000);
+            }
+            ns.hacknet.upgradeLevel(i, 1);
+        }
+    }
+
+    ns.tprint("All nodes upgraded to level 80");
+
+    for (let i = 0; i < cnt; i++) {
+        while (ns.hacknet.getNodeStats(i).ram < 16) {
+            let cost = ns.hacknet.getRamUpgradeCost(i, 1);
+            while (myMoney() < cost) {
+                ns.print("Need $" + cost + " . Have $" + myMoney());
+                await ns.sleep(3000);
+            }
+            ns.hacknet.upgradeRam(i, 1);
+        }
+    }
+
+    ns.tprint("All nodes upgraded to 16GB RAM");
+
+    for (let i = 0; i < cnt; i++) {
+        while (ns.hacknet.getNodeStats(i).cores < 8) {
+            let cost = ns.hacknet.getCoreUpgradeCost(i, 1);
+            while (myMoney() < cost) {
+                ns.print("Need $" + cost + " . Have $" + myMoney());
+                await ns.sleep(3000);
+            }
+            ns.hacknet.upgradeCore(i, 1);
+        }
+    }
+
+    ns.tprint("All nodes upgraded to 8 cores");
+}
+```
+
+This script ensures that the player's Hacknet Nodes are upgraded efficiently while maintaining sufficient funds.
+

src/Documentation/doc/advanced/netscriptmisc.md

@@ -0,0 +1,228 @@
+# Netscript Miscellaneous
+
+## Netscript Ports
+
+Netscript Ports are endpoints that can be used to communicate between scripts and across servers. A port is implemented as a serialized queue, where you can only write and read one element at a time from the port. Only string and number types may be written to ports. When you read data from a port, the element that is read is removed from the port.
+
+The following Netscript functions can be used to interact with ports:
+
+- `read`
+- `write`
+- `tryWrite`
+- `clear`
+- `peek`
+
+Ports are specified by passing the port number as the first argument and the value as the second. The default maximum capacity of a port is 50, but this can be changed in **Options > System**. Setting this too high can cause the game to use a lot of memory.
+
+### Important
+
+The data inside ports are **not saved**! If you close and re-open the game or reload the page, all data in the ports will be lost.
+
+### Example Usage
+
+Here's a brief example of how ports work. For simplicity, we'll only deal with port 1.
+
+Let's assume Port 1 starts out empty:
+
+```plaintext
+[]
+```
+
+Now assume we run the following script:
+
+```javascript
+export async function main(ns) {
+    for (var i = 0; i < 10; ++i) {
+        ns.writePort(1, i); // Writes the value of i to port 1
+    }
+}
+```
+
+After execution, Port 1 will contain:
+
+```plaintext
+[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+```
+
+Now, running the following script:
+
+```javascript
+export async function main(ns) {
+    for (var i = 0; i < 3; ++i) {
+        ns.print(ns.readPort(1)); // Reads a value from port 1 and prints it
+    }
+}
+```
+
+Will print:
+
+```plaintext
+0
+1
+2
+```
+
+And the remaining data in Port 1 will be:
+
+```plaintext
+[3, 4, 5, 6, 7, 8, 9]
+```
+
+### Warning
+
+In **NetscriptJS**, do not try writing base Promises to a port.
+
+## Port Handles
+
+### Warning
+
+Port Handles only work in **NetscriptJS**. They do not work in **Netscript1**.
+
+The `getPortHandle` Netscript function can be used to get a handle to a Netscript Port. This handle allows access to several new port-related functions:
+
+### Methods
+
+#### `NetscriptPort.writePort(data)`
+
+- **Parameter:** `data` - Data to write to the port
+- **Returns:** If the port is full, the item that is removed from the port is returned. Otherwise, `null` is returned.
+- Works the same as the Netscript function `write`.
+
+#### `NetscriptPort.tryWritePort(data)`
+
+- **Parameter:** `data` - Data to try to write to the port
+- **Returns:** `true` if the data is successfully written, `false` otherwise.
+- If the port is full, the data will **not** be written.
+
+#### `NetscriptPort.full()`
+
+- **Returns:** `true` if the Netscript Port is full, `false` otherwise.
+
+#### `NetscriptPort.empty()`
+
+- **Returns:** `true` if the Netscript Port is empty, `false` otherwise.
+
+#### `NetscriptPort.clear()`
+
+- Clears all data from the port.
+- Works the same as the Netscript function `clear`.
+
+### Port Handle Example
+
+```javascript
+export async function main(ns) {
+    port = ns.getPortHandle(5);
+    back = port.data.pop(); // Get and remove last element in port
+
+    // Wait for port data before reading
+    while (port.empty()) {
+        await ns.sleep(10000);
+    }
+    res = port.read();
+
+    // Wait for room in the port before writing
+    while (!port.tryWrite(5)) {
+        await ns.sleep(5000);
+    }
+
+    // Successfully wrote to port!
+}
+```
+
+## Comments
+
+Netscript supports comments using JavaScript syntax. Comments are ignored by the interpreter and can be used to document code:
+
+```javascript
+// This is a comment and will not get executed
+/* Multi-line
+ * comment */
+ns.print("This code will be executed");
+```
+
+## Importing Functions
+
+In Netscript, you can import functions declared in other scripts. The script will incur the RAM usage of all imported functions. There are two ways to do this:
+
+```javascript
+import * as namespace from "script filename"; // Import all functions
+import {fn1, fn2, ...} from "script filename"; // Import specific functions
+```
+
+### Example
+
+Consider a library script called `testlibrary.js`:
+
+```javascript
+export function foo1(args) {
+    // function definition...
+}
+
+export function foo2(args) {
+    // function definition...
+}
+
+export async function foo3(args) {
+    // function definition...
+}
+
+export function foo4(args) {
+    // function definition...
+}
+
+export async function main(ns) {
+    // main function definition, can be empty but must exist...
+}
+```
+
+To use these functions in another script:
+
+```javascript
+import * as testlib from "testlibrary.js";
+
+export async function main(ns) {
+    const values = [1,2,3];
+
+    // Use imported functions with the namespace
+    const someVal1 = await testlib.foo3(...values);
+    const someVal2 = testlib.foo1(values[0]);
+
+    if (someVal1 > someVal2) {
+        // ...
+    } else {
+        // ...
+    }
+}
+```
+
+To import only certain functions and save RAM:
+
+```javascript
+import {foo1, foo3} from "testlibrary.js"; // Saves RAM
+
+export async function main(ns) {
+    const values = [1,2,3];
+
+    // No namespace needed
+    const someVal1 = await foo3(...values);
+    const someVal2 = foo1(values[1]);
+
+    if (someVal1 > someVal2) {
+        // ...
+    } else {
+        // ...
+    }
+}
+```
+
+### Warning
+
+The `export` keyword **cannot** be used in **Netscript1** as it's not supported. It can, however, be used in **NetscriptJS** (but it's not required).
+
+## Standard JavaScript Objects
+
+Standard built-in JavaScript objects such as `Math`, `Date`, `Number`, and others are supported based on the Netscript version you are using:
+
+- **Netscript1**: Supports built-in objects defined in ES5.
+- **NetscriptJS**: Supports objects based on your browser's JavaScript engine.
+