Changelog and markdown update

doc/source/changelog.rst

@@ -3,6 +3,113 @@
 Changelog
 =========
 
+v2.3 Dev - SF3 rework and performance improvements (28 Apr 2023)
+----------------------------------------------------------------
+
+BREAKING CHANGES: These changes may require changes to your scripts.
+
+* Major changes to the SF3 mechanic. See the related section below for the full (spoiler) changes.
+* The same script filename can now be ran multiple times with the same args. If running a script from another script (ns.run/ns.exec/etc), this limitation can be re-imposed with the preventDuplicates RunOption (see general section for info on RunOptions).
+* The same .js script will now be the same js module whether the script was ran directly or used as an import. This means top-level variables (variables defined outside of any function) are shared across all instances of the script.
+* The js module for a script will also be reused by any script that has the exact same compiled text, even if that script is on another server or has a different filename. This can lead to unexpected results when using top-level variables.
+* Some properties removed from ns.getPlayer and added to a separate function ns.getResetInfo. These are still accessible from getPlayer but will produce a warning message the first time they are accessed per game session.
+* hackAnalyzeThreads now returns -1, instead of 0, when no money can be hacked from the targeted server. 
+
+PERFORMANCE:
+
+* Remove requirement for args to be unique. (@d0sboots)
+* Minimize impact of unavoidable memory leak when modules are created, by reusing modules as much as possible (@d0sboots)
+* Internal data structure changes (@d0sboots, @Snarling)
+* Fix memory leak when initializing large number of netscript ports (@Snarling)
+
+NETSCRIPT GENERAL:
+
+* ns.hackAnalyzeThreads no longer indicates infinity any time a single thread would hack less than $1 (@Snarling)
+* ns.renamePurchasedServer no longer crashes if player is connected to the server being renamed (@Snarling)
+* ns.hackAnalyzeThreads now return -1 (instead of 0) if no money can be hacked from the targeted server. (@d0sboots)
+* Fix a possible infinite atExit loop if a script killed itself. (@Snarling)
+* Static timestamps of last resets can be obtained via ns.getResetInfo, replacing playtimeSinceLastX from ns.getPlayer (@G4mingJon4s)
+* Added RunOptions, which can optionally replace the "threads" argument for ns.run/ns.exec/ns.spawn. (@d0sboots)
+
+  * RunOptions.threads: Provide a thread count (since RunOptions can replace the threads argument)
+  * RunOptions.temporary: Prevents the script execution from being included in the save file.
+  * RunOptions.ramOverride: Provide a static ram cost for the script to override what is calculated by the game. Dynamic ram checking is still enforced.
+  * RunOptions.preventDuplicates: If set to true, fail to launch the script if the args are identical to a script already running.
+
+GENERAL / MISC:
+
+* Monaco script editor updated to a newer version and has more config options available now. (@Snarling)
+* Improve Electron's handling of external links (@Snarling) 
+* Improved support for ANSI color codes (@d0sboots)
+* Improved consistency of file paths. Correct names for files no longer start with a / even if they are in a directory. (@Snarling)
+* All Math Expressions contract no longer accepts wrong answers (@Snarling)
+* Faction invites now trigger immediately when backdooring a server. (@Snarling)
+* Fixed issue where duplicate programs could be created. (@Minzenkatze)
+* UI improvements to create program page (@Minzenkatze)
+* Fix inconsistency in skill xp to skill level conversion (@hydroflame)
+* Updated blood donation counter to reflect number of confirmed blood donations. (@hydroflame)
+* Minor improvements to ram calculation process (@Snarling)
+* Improved terminal arguments detection (@Snarling)
+* Improved display for ls terminal command. (@Snarling)
+* Added more internal tests and improved test quality (@d0sboots)
+* Various codebase improvements (@Snarling, @d0sboots)
+* Documentation improvements (Many contributors)
+* Nerf noodle bar
+
+SPOILER SECTIONS:
+
+SF2:
+
+* Corrected the "Next equipment unlock" text for member upgrades. (@LiamGeorge1999)
+
+SF3:
+
+* Product quality now depends on material quality (@Mughur)
+* Product price can be set separately per-city (@Mughur)
+* Exports can be set relative to inventory or production (@Mughur)
+* ns.corporation.getProduct is city-specific (@Mughur)
+* Bulk purchasing is available from the start (@Mughur)
+* Can buy multiple upgrades at a time, similar to hacknet node upgrades (@Mughur)
+* Various UI changes (@Mughur)
+* Removed happiness from employees (@Mughur)
+* Coffee renamed to tea (@Mughur)
+* Training position renamed to intern (@Mughur)
+* More options for SmartSupply (@Mughur)
+* Advertising nerf (@Mughur)
+* Nerfed investors and reduced effectiveness of "fraud" (@Mughur)
+* Various other changes (@Mughur)
+
+SF4:
+
+* Faction invites trigger immediately when running ns.singularity.getFactionInvitations (@Snarling)
+* Added ns.singularity.getCompanyPositionInfo (@jeek)
+
+SF6:
+
+* Failing a contract or operation now consumes the action (@Zelow79)
+
+SF9:
+
+* The SF9.3 bonus is also given to the player when inside of BN9. (@Zelow79)
+* Adjusted the SF1 bonus for hacknet costs (slight nerf), and raised the SF9 bonus to compensate. (@d0sboots)
+* Added option to purchase company favor using hashes. (@jeek)
+
+SF10:
+
+* Sleeve shock recovery now scales with intelligence. (@Tyasuh)
+* Sleeve kills during crimes count towards numPeopleKilled (@Zelow79)
+* Fix a misspelled moneySourceTracker call for sleeves (@zerbosh)
+* ns.sleeve.getTask return value now includes cyclesNeeded where applicable (@Snarling)
+* Internal type refactoring on Sleeve Work. (@Snarling)
+
+SF12:
+
+* Fix inconsistency in how BN12 multipliers were calculated 
+
+SF13:
+
+* Improve performance of Stanek's gift update cycle, and rework (buff) bonus time handling. (@Snarling)
+
 
 v2.2.2 - 21 Feb 2023
 --------------------

markdown/bitburner.bladeburner.getstamina.md

@@ -21,22 +21,10 @@ Array containing current stamina and max stamina.
 
 RAM cost: 4 GB Returns an array with two elements: \* \[Current stamina, Max stamina\]
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
-function getStaminaPercentage() {
-   var res = bladeburner.getStamina();
-   return res[0] / res[1];
-}
-```
-
-## Example 2
-
-
-```ts
-// NS2:
 function getStaminaPercentage() {
    const [current, max] = ns.bladeburner.getStamina();
    return current / max;

markdown/bitburner.codingcontract.attempt.md

@@ -32,22 +32,10 @@ RAM cost: 10 GB
 
 Attempts to solve the Coding Contract with the provided solution.
 
-## Example 1
+## Example
 
 
 ```js
-// NS1
-var reward = codingcontract.attempt(yourSolution, filename, hostname);
-if (reward) {
-  tprint("Contract solved successfully! Reward: " + reward)
-} else tprint("Failed to solve contract.")
-```
-
-## Example 2
-
-
-```js
-// NS2
 const reward = codingcontract.attempt(yourSolution, filename, hostname);
 if (reward) {
   ns.tprint(`Contract solved successfully! Reward: ${reward}`)

markdown/bitburner.hacknet.gethashupgrades.md

@@ -25,19 +25,10 @@ This function is only applicable for Hacknet Servers (the upgraded version of a
 
 Returns the list of all available hash upgrades that can be used in the spendHashes function.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
-var upgrades = hacknet.getHashUpgrades(); // ["Sell for Money","Sell for Corporation Funds",...]
-```
-
-## Example 2
-
-
-```ts
-// NS2:
 const upgrades = ns.hacknet.getHashUpgrades(); // ["Sell for Money","Sell for Corporation Funds",...]
 ```
 

markdown/bitburner.hacknet.hashcost.md

@@ -33,22 +33,10 @@ This function is only applicable for Hacknet Servers (the upgraded version of a
 
 Returns the number of hashes required for the specified upgrade. The name of the upgrade must be an exact match.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
-var upgradeName = "Sell for Corporation Funds";
-if (hacknet.numHashes() > hacknet.hashCost(upgradeName)) {
-   hacknet.spendHashes(upgradeName);
-}
-```
-
-## Example 2
-
-
-```ts
-// NS2:
 const upgradeName = "Sell for Corporation Funds";
 if (ns.hacknet.numHashes() > ns.hacknet.hashCost(upgradeName)) {
   ns.hacknet.spendHashes(upgradeName);

markdown/bitburner.hacknet.spendhashes.md

@@ -36,21 +36,13 @@ Spend the hashes generated by your Hacknet Servers on an upgrade. Returns a bool
 
 The name of the upgrade must be an exact match. The `upgTarget` argument is used for upgrades such as `Reduce Minimum Security`<!-- -->, which applies to a specific server. In this case, the `upgTarget` argument must be the hostname of the server.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
+// For upgrades where no target is required
-hacknet.spendHashes("Sell for Corporation Funds");
-hacknet.spendHashes("Increase Maximum Money", "foodnstuff");
-```
-
-## Example 2
-
-
-```ts
-NS2:
 ns.hacknet.spendHashes("Sell for Corporation Funds");
+// For upgrades requiring a target
 ns.hacknet.spendHashes("Increase Maximum Money", "foodnstuff");
 ```
 

markdown/bitburner.ns.asleep.md

@@ -4,7 +4,7 @@
 
 ## NS.asleep() method
 
-Suspends the script for n milliseconds. Doesn't block with concurrent calls. You should prefer 'sleep' over 'asleep' except when doing very complex UI work.
+Suspends the script for n milliseconds. Doesn't block with concurrent calls.
 
 **Signature:**
 
@@ -22,6 +22,7 @@ asleep(millis: number): Promise<true>;
 
 Promise&lt;true&gt;
 
+A promise that resolves to true when the sleep is completed.
 
 ## Remarks
 

markdown/bitburner.ns.brutessh.md

@@ -28,19 +28,10 @@ RAM cost: 0.05 GB
 
 Runs the BruteSSH.exe program on the target server. BruteSSH.exe must exist on your home computer.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
-brutessh("foodnstuff");
-```
-
-## Example 2
-
-
-```ts
-// NS2:
 ns.brutessh("foodnstuff");
 ```
 

markdown/bitburner.ns.ftpcrack.md

@@ -28,19 +28,10 @@ RAM cost: 0.05 GB
 
 Runs the FTPCrack.exe program on the target server. FTPCrack.exe must exist on your home computer.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
-ftpcrack("foodnstuff");
-```
-
-## Example 2
-
-
-```ts
-// NS2:
 ns.ftpcrack("foodnstuff");
 ```
 

markdown/bitburner.ns.getbitnodemultipliers.md

@@ -33,23 +33,12 @@ Returns an object containing the current (or supplied) BitNode multipliers. This
 
 For example, if the CrimeMoney multiplier has a value of 0.1, then that means that committing crimes in the current BitNode will only give 10% of the money you would have received in BitNode-1.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
+const mults = ns.getBitNodeMultipliers();
-var mults = getBitNodeMultipliers();
+ns.tprint(`ServerMaxMoney: ${mults.ServerMaxMoney}`);
-print(mults.ServerMaxMoney);
+ns.tprint(`HackExpGain: ${mults.HackExpGain}`);
-print(mults.HackExpGain);
-```
-
-## Example 2
-
-
-```ts
-// NS2:
-const {ServerMaxMoney, HackExpGain} = ns.getBitNodeMultipliers();
-print(ServerMaxMoney);
-print(HackExpGain);
 ```
 

markdown/bitburner.ns.gethackingmultipliers.md

@@ -23,25 +23,12 @@ RAM cost: 0.25 GB
 
 Returns an object containing the Player’s hacking related multipliers. These multipliers are returned in fractional forms, not percentages (e.g. 1.5 instead of 150%).
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
+const mults = ns.getHackingMultipliers();
-// Example of how this can be used:
+print(`chance: ${mults.chance}`);
-var mults = getHackingMultipliers();
+print(`growthL ${mults.growth}`);
-print(mults.chance);
-print(mults.growth);
-```
-
-## Example 2
-
-
-```ts
-// NS2:
-// Example of how this can be used:
-const {chance, growth} = ns.getHackingMultipliers();
-print(chance);
-print(growth);
 ```
 

markdown/bitburner.ns.gethacknetmultipliers.md

@@ -23,25 +23,12 @@ RAM cost: 0.25 GB
 
 Returns an object containing the Player’s hacknet related multipliers. These multipliers are returned in fractional forms, not percentages (e.g. 1.5 instead of 150%).
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
+const mults = ns.getHacknetMultipliers();
-// Example of how this can be used:
+ns.tprint(`production: ${mults.production}`);
-var mults = getHacknetMultipliers();
+ns.tprint(`purchaseCost: ${mults.purchaseCost}`);
-print(mults.production);
-print(mults.purchaseCost);
-```
-
-## Example 2
-
-
-```ts
-// NS2:
-// Example of how this can be used:
-const {production, purchaseCost} = ns.getHacknetMultipliers();
-print(production);
-print(purchaseCost);
 ```
 

markdown/bitburner.ns.getpurchasedservercost.md

@@ -30,23 +30,12 @@ RAM cost: 0.25 GB
 
 Returns the cost to purchase a server with the specified amount of ram.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
+const ram = 2 ** 20;
-for (i = 1; i <= 20; i++) {
+const cost = ns.getPurchasedServerCost(ram);
-    tprint(i + " -- " + getPurchasedServerCost(Math.pow(2, i)));
+ns.tprint(`A purchased server with ${ns.formatRam(ram)} costs ${ns.formatMoney(cost)}`);
-}
-```
-
-## Example 2
-
-
-```ts
-// NS2:
-for (i = 1; i <= 20; i++) {
-    ns.tprint(i + " -- " + ns.getPurchasedServerCost(Math.pow(2, i)));
-}
 ```
 

markdown/bitburner.ns.getservermoneyavailable.md

@@ -30,20 +30,10 @@ RAM cost: 0.1 GB
 
 Returns the amount of money available on a server. Running this function on the home computer will return the player’s money.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
-getServerMoneyAvailable("foodnstuff");
-getServerMoneyAvailable("home"); //Returns player's money
-```
-
-## Example 2
-
-
-```ts
-// NS2:
 ns.getServerMoneyAvailable("foodnstuff");
 ns.getServerMoneyAvailable("home"); // Returns player's money
 ```

markdown/bitburner.ns.hack.md

@@ -23,7 +23,7 @@ hack(host: string, opts?: BasicHGWOptions): Promise<number>;
 
 Promise&lt;number&gt;
 
-The amount of money stolen if the hack is successful, and zero otherwise.
+A promise that resolves to the amount of money stolen (which is zero if the hack is unsuccessful).
 
 ## Remarks
 
@@ -35,19 +35,10 @@ A script can hack a server from anywhere. It does not need to be running on the
 
 A successful `hack()` on a server will raise that server’s security level by 0.002.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
-var earnedMoney = hack("foodnstuff");
-```
-
-## Example 2
-
-
-```ts
-// NS2:
 let earnedMoney = await ns.hack("foodnstuff");
 ```
 

markdown/bitburner.ns.hasrootaccess.md

@@ -30,22 +30,11 @@ RAM cost: 0.05 GB
 
 Returns a boolean indicating whether or not the player has root access to the specified target server.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
+if (!ns.hasRootAccess("foodnstuff")) {
-if (hasRootAccess("foodnstuff") == false) {
-   nuke("foodnstuff");
-}
-```
-
-## Example 2
-
-
-```ts
-// NS2:
-if (ns.hasRootAccess("foodnstuff") == false) {
   ns.nuke("foodnstuff");
 }
 ```

markdown/bitburner.ns.hastorrouter.md

@@ -21,19 +21,10 @@ Whether player has access to the dark web.
 
 RAM cost: 0.05GB
 
-## Example 1
+## Example
 
 
 ```js
-// NS1:
+if (ns.hasTorRouter()) ns.tprint("TOR router detected.");
-if (hasTorRouter()) tprint("TOR router detected.");
-```
-
-## Example 2
-
-
-```js
-// NS2:
-if (ns.hasTorRouter()) tprint("TOR router detected.");
 ```
 

markdown/bitburner.ns.httpworm.md

@@ -28,19 +28,10 @@ RAM cost: 0.05 GB
 
 Runs the HTTPWorm.exe program on the target server. HTTPWorm.exe must exist on your home computer.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
-httpworm("foodnstuff");
-```
-
-## Example 2
-
-
-```ts
-// NS2:
 ns.httpworm("foodnstuff");
 ```
 

markdown/bitburner.ns.md

@@ -14,27 +14,19 @@ export interface NS
 
 ## Remarks
 
-<b>Basic ns1 usage example:</b>
+<b>Basic usage example:</b>
 
-```ts
+```js
- // Basic ns functions can be used directly
- getHostname();
- // Some related functions are gathered within a common namespace
- stock.getPrice();
-```
-[ns1 in-game docs](https://bitburner-official.readthedocs.io/en/latest/netscript/netscript1.html) <hr> <b>Basic ns2 usage example:</b>
-
-```ts
 export async function main(ns) {
  // Basic ns functions can be accessed on the ns object
  ns.getHostname();
  // Some related functions are gathered under a sub-property of the ns object
  ns.stock.getPrice();
- // Some functions need to be awaited
+ // Most functions that return a promise need to be awaited.
  await ns.hack('n00dles');
 }
 ```
-[ns2 in-game docs](https://bitburner-official.readthedocs.io/en/latest/netscript/netscriptjs.html) <hr>
+[ns2 in-game docs](https://bitburner-official.readthedocs.io/en/latest/netscript/netscriptjs.html) <hr> For (deprecated) .script usage, see: [ns1 in-game docs](https://bitburner-official.readthedocs.io/en/latest/netscript/netscript1.html) <hr>
 
 ## Properties
 
@@ -62,7 +54,7 @@ export async function main(ns) {
 |  Method | Description |
 |  --- | --- |
 |  [alert(msg)](./bitburner.ns.alert.md) | Open up a message box. |
-|  [asleep(millis)](./bitburner.ns.asleep.md) | Suspends the script for n milliseconds. Doesn't block with concurrent calls. You should prefer 'sleep' over 'asleep' except when doing very complex UI work. |
+|  [asleep(millis)](./bitburner.ns.asleep.md) | Suspends the script for n milliseconds. Doesn't block with concurrent calls. |
 |  [atExit(f)](./bitburner.ns.atexit.md) | Add callback function when the script dies |
 |  [brutessh(host)](./bitburner.ns.brutessh.md) | Runs BruteSSH.exe on a server. |
 |  [clear(handle)](./bitburner.ns.clear.md) | Clear data from a file. |

markdown/bitburner.ns.nuke.md

@@ -28,19 +28,10 @@ RAM cost: 0.05 GB
 
 Running NUKE.exe on a target server gives you root access which means you can execute scripts on said server. NUKE.exe must exist on your home computer.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
-nuke("foodnstuff");
-```
-
-## Example 2
-
-
-```ts
-// NS2:
 ns.nuke("foodnstuff");
 ```
 

markdown/bitburner.ns.print.md

@@ -38,35 +38,10 @@ If the argument is a string, you can color code your message by prefixing your s
 
 For custom coloring, use ANSI escape sequences. The examples below use the Unicode escape code `\u001b`<!-- -->. The color coding also works if `\u001b` is replaced with the hexadecimal escape code `\x1b`<!-- -->. The Bash escape code `\e` is not supported. The octal escape code `\033` is not allowed because the game runs JavaScript in strict mode.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1
-// Default color coding.
-print("ERROR means something's wrong.");
-print("SUCCESS means everything's OK.");
-print("WARN Tread with caution!");
-print("WARNING, warning, danger, danger!");
-print("WARNing! Here be dragons.");
-print("INFO for your I's only (FYI).");
-print("INFOrmation overload!");
-// Custom color coding.
-var cyan = "\u001b[36m";
-var green = "\u001b[32m";
-var red = "\u001b[31m";
-var reset = "\u001b[0m";
-print(red + "Ugh! What a mess." + reset);
-print(green + "Well done!" + reset);
-print(cyan + "ERROR Should this be in red?" + reset);
-tail();
-```
-
-## Example 2
-
-
-```ts
-// NS2
 // Default color coding.
 ns.print("ERROR means something's wrong.");
 ns.print("SUCCESS means everything's OK.");

markdown/bitburner.ns.printf.md

@@ -31,27 +31,10 @@ RAM cost: 0 GB
 
 - For more detail, see: https://github.com/alexei/sprintf.js
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1
-var name = "Bit";
-var age = 4;
-printf("My name is %s.", name);
-printf("I'm %d seconds old.", age);
-printf("My age in binary is %b.", age);
-printf("My age in scientific notation is %e.", age);
-printf("In %d seconds, I'll be %s.", 6, "Byte");
-printf("Am I a nibble? %t", (4 == age));
-tail();
-```
-
-## Example 2
-
-
-```ts
-// NS2
 const name = "Bit";
 const age = 4;
 ns.printf("My name is %s.", name);

markdown/bitburner.ns.prompt.md

@@ -42,39 +42,10 @@ Prompts the player with a dialog box. Here is an explanation of the various opti
 
 - `options.type` has value `"select"`<!-- -->. The player is shown a drop-down field. Choosing type `"select"` will require an array to be passed via the `options.choices` property. The array can be an array of strings, an array of numbers (not BigInt numbers), or a mixture of both numbers and strings. Any other types of array elements will result in an error or an undefined/unexpected behavior. The `options.choices` property will be ignored if `options.type` has a value other than `"select"`<!-- -->. The script's execution is halted until the player chooses one of the provided options and presses the "Confirm" button.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1
-// A Yes/No question. The default is to create a boolean dialog box.
-var queryA = "Do you enjoy Bitburner?";
-var resultA = prompt(queryA);
-tprint(queryA + " " + resultA);
-
-// Another Yes/No question. Can also create a boolean dialog box by explicitly
-// passing the option {"type": "boolean"}.
-var queryB = "Is programming fun?";
-var resultB = prompt(queryB, { type: "boolean" });
-tprint(queryB + " " + resultB);
-
-// Free-form text box.
-var resultC = prompt("Please enter your name.", { type: "text" });
-tprint("Hello, " + resultC + ".");
-
-// A drop-down list.
-var resultD = prompt("Please select your favorite fruit.", {
-    type: "select",
-    choices: ["Apple", "Banana", "Orange", "Pear", "Strawberry"]
-});
-tprint("Your favorite fruit is " + resultD.toLowerCase() + ".");
-```
-
-## Example 2
-
-
-```ts
-// NS2
 // A Yes/No question. The default is to create a boolean dialog box.
 const queryA = "Do you enjoy Bitburner?";
 const resultA = await ns.prompt(queryA);

markdown/bitburner.ns.ps.md

@@ -30,23 +30,10 @@ RAM cost: 0.2 GB
 
 Returns an array with general information about all scripts running on the specified target server.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
-var scripts = ps("home");
-for (var i = 0; i < scripts.length; ++i) {
-    tprint(scripts[i].filename + ' ' + scripts[i].threads);
-    tprint(scripts[i].args);
-}
-```
-
-## Example 2
-
-
-```ts
-// NS2:
 const ps = ns.ps("home");
 for (let script of ps) {
   ns.tprint(`${script.filename} ${script.threads}`);

markdown/bitburner.ns.purchaseserver.md

@@ -37,23 +37,11 @@ Note that there is a maximum limit to the amount of servers you can purchase.
 
 Returns the hostname of the newly purchased server as a string. If the function fails to purchase a server, then it will return an empty string. The function will fail if the arguments passed in are invalid, if the player does not have enough money to purchase the specified server, or if the player has exceeded the maximum amount of servers.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
+// Attempt to purchase 5 servers with 64GB of ram each
-var ram = 64;
-var prefix = "pserv-";
-for (i = 0; i < 5; ++i) {
-   purchaseServer(prefix + i, ram);
-}
-```
-
-## Example 2
-
-
-```ts
-// NS2:
 const ram = 64;
 const prefix = "pserv-";
 for (i = 0; i < 5; ++i) {

markdown/bitburner.ns.relaysmtp.md

@@ -28,19 +28,10 @@ RAM cost: 0.05 GB
 
 Runs the relaySMTP.exe program on the target server. relaySMTP.exe must exist on your home computer.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
-relaysmtp("foodnstuff");
-```
-
-## Example 2
-
-
-```ts
-// NS2:
 ns.relaysmtp("foodnstuff");
 ```
 

markdown/bitburner.ns.scan.md

@@ -30,31 +30,10 @@ RAM cost: 0.2 GB
 
 Returns an array containing the hostnames of all servers that are one node way from the specified target server. The hostnames in the returned array are strings.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1
-// All servers that are one hop from the current server.
-tprint("Neighbors of current server.");
-var neighbor = scan();
-for (var i = 0; i < neighbor.length; i++) {
-    tprint(neighbor[i]);
-}
-// All neighbors of n00dles.
-var target = "n00dles";
-neighbor = scan(target);
-tprintf("Neighbors of %s.", target);
-for (var i = 0; i < neighbor.length; i++) {
-    tprint(neighbor[i]);
-}
-```
-
-## Example 2
-
-
-```ts
-// NS2
 // All servers that are one hop from the current server.
 ns.tprint("Neighbors of current server.");
 let neighbor = ns.scan();

markdown/bitburner.ns.sleep.md

@@ -22,31 +22,19 @@ sleep(millis: number): Promise<true>;
 
 Promise&lt;true&gt;
 
+A promise that resolves to true when the sleep is completed.
 
 ## Remarks
 
 RAM cost: 0 GB
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
 // This will count from 1 to 10 in your terminal, with one number every 5 seconds
-for (var i=0; i<10; i++) {
+for (var i = 1; i <= 10; i++) {
-  tprint(i + 1);
+  ns.tprint(i);
-  sleep(5000);
-}
-```
-
-## Example 2
-
-
-```ts
-// NS2:
-// This will count from 1 to 10 in your terminal, with one number every 5 seconds
-for (var i=0; i<10; i++) {
-  ns.tprint(i + 1);
   await ns.sleep(5000);
 }
 ```

markdown/bitburner.ns.sqlinject.md

@@ -26,19 +26,10 @@ void
 
 RAM cost: 0.05 GB
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
-sqlinject("foodnstuff");
-```
-
-## Example 2
-
-
-```ts
-// NS2:
 ns.sqlinject("foodnstuff");
 ```
 

markdown/bitburner.ns.weaken.md

@@ -23,7 +23,7 @@ weaken(host: string, opts?: BasicHGWOptions): Promise<number>;
 
 Promise&lt;number&gt;
 
-The amount by which the target server’s security level was decreased. This is equivalent to 0.05 multiplied by the number of script threads.
+A promise that resolves to the value by which security was reduced.
 
 ## Remarks
 
@@ -33,20 +33,10 @@ Use your hacking skills to attack a server’s security, lowering the server’s
 
 Like [hack](./bitburner.ns.hack.md) and [grow](./bitburner.ns.grow.md)<!-- -->, `weaken` can be called on any server, regardless of where the script is running. This function requires root access to the target server, but there is no required hacking level to run the function.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
-var currentSecurity = getServerSecurityLevel("foodnstuff");
-currentSecurity = currentSecurity - weaken("foodnstuff");
-```
-
-## Example 2
-
-
-```ts
-// NS2:
 let currentSecurity = ns.getServerSecurityLevel("foodnstuff");
 currentSecurity -= await ns.weaken("foodnstuff");
 ```

markdown/bitburner.singularity.createprogram.md

@@ -35,19 +35,12 @@ This function returns true if you successfully start working on the specified pr
 
 Note that creating a program using this function has the same hacking level requirements as it normally would. These level requirements are: \* BruteSSH.exe: 50 \* FTPCrack.exe: 100 \* relaySMTP.exe: 250 \* HTTPWorm.exe: 500 \* SQLInject.exe: 750 \* DeepscanV1.exe: 75 \* DeepscanV2.exe: 400 \* ServerProfiler.exe: 75 \* AutoLink.exe: 25
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1:
+const programName = "BruteSSH.exe";
-createProgram(“relaysmtp.exe”);
+const success = ns.createProgram(programName);
-```
+if (!success) ns.tprint("ERROR: Failed to start working on ${programName}")
-
-## Example 2
-
-
-```ts
-// NS2:
-ns.createProgram(“relaysmtp.exe”);
 ```
 

markdown/bitburner.singularity.getcompanypositions.md

@@ -32,23 +32,11 @@ This function will return a list of positions at a specific company.
 
 This function will return the position list if the company name is valid.
 
-## Example 1
+## Example
 
 
 ```js
-// NS1:
+const companyName = "Noodle Bar";
-var COMPANY_NAME = "Noodle Bar";
+const jobList = ns.singularity.getCompanyPositions(companyName);
-
-var jobList = singularity.getCompanyPositions(COMPANY_NAME);
-```
-
-## Example 2
-
-
-```js
-// NS2:
-const COMPANY_NAME = "Noodle Bar";
-
-let jobList = ns.singularity.getCompanyPositions(COMPANY_NAME);
 ```
 

markdown/bitburner.singularity.getdarkwebprogramcost.md

@@ -32,19 +32,12 @@ This function allows you to check the price of a darkweb exploit/program. You MU
 
 If the program does not exist, an error is thrown.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1
+const programName = "BruteSSH.exe";
-getDarkwebProgramCost("brutessh.exe");
+const cost = ns.getDarkwebProgramCost(programName);
-```
+if (cost > 0) ns.tprint(`${programName} costs ${ns.formatMoney(cost)}`);
-
-## Example 2
-
-
-```ts
-// NS2
-ns.getDarkwebProgramCost("brutessh.exe");
 ```
 

markdown/bitburner.singularity.getdarkwebprograms.md

@@ -23,21 +23,11 @@ RAM cost: 1 GB \* 16/4/1
 
 This function allows the player to get a list of programs available for purchase on the dark web. Players MUST have purchased Tor to get the list of programs available. If Tor has not been purchased yet, this function will return an empty list.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1
+const programs = ns.getDarkwebPrograms();
-getDarkwebPrograms();
+ns.tprint(`Available programs are: ${programs.split(", ")}`);
-// returns ['BruteSSH.exe', 'FTPCrack.exe'...etc]
-```
-
-## Example 2
-
-
-```ts
-// NS2
-ns.getDarkwebPrograms();
-// returns ['BruteSSH.exe', 'FTPCrack.exe'...etc]
 ```
 

markdown/bitburner.singularity.purchaseprogram.md

@@ -30,19 +30,12 @@ RAM cost: 2 GB \* 16/4/1
 
 This function allows you to automatically purchase programs. You MUST have a TOR router in order to use this function. The cost of purchasing programs using this function is the same as if you were purchasing them through the Dark Web using the Terminal buy command.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1
+const programName = "BruteSSH.exe"
-purchaseProgram("brutessh.exe");
+const success = ns.purchaseProgram(programName);
-```
+if (!success) ns.tprint("ERROR: Failed to purchase ${programName}")
-
-## Example 2
-
-
-```ts
-// NS2
-ns.purchaseProgram("brutessh.exe");
 ```
 

markdown/bitburner.singularity.workforcompany.md

@@ -33,25 +33,12 @@ This function will set you to start working at your current job at a specified c
 
 This function will return true if the player starts working, and false otherwise.
 
-## Example 1
+## Example
 
 
 ```js
-// NS1:
+const companyName = "Noodle Bar";
-var COMPANY_NAME = "Noodle Bar";
+const success = ns.singularity.workForCompany(companyName);
-
+if (!success) ns.tprint(`ERROR: Failed to start work at ${companyName}.`);
-var success = singularity.workForCompany(COMPANY_NAME);
-if (!success) tprint("ERROR: Failed to start work at " + COMPANY_NAME + ".");
-```
-
-## Example 2
-
-
-```js
-// NS2:
-const COMPANY_NAME = "Noodle Bar";
-
-let success = ns.singularity.workForCompany(COMPANY_NAME);
-if (!success) ns.tprint(`ERROR: Failed to start work at ${COMPANY_NAME].`);
 ```
 

markdown/bitburner.singularity.workforfaction.md

@@ -34,25 +34,14 @@ This function will set you to start working for the specified faction. You must
 
 This function will return true if you successfully start working for the specified faction, and false otherwise.
 
-## Example 1
+## Example
 
 
 ```js
-// NS1
+const factionName = "CyberSec";
-var FACTION_NAME = "CyberSec", WORK_TYPE = "hacking";
+const workType = "hacking";
 
-var success = singularity.workForFaction(FACTION_NAME, WORK_TYPE);
+let success = ns.singularity.workForFaction(factionName, workType);
-if (!success) tprint("ERROR: Failed to start work for " + FACTION_NAME + " with work type " + WORK_TYPE);
+if (!success) ns.tprint(`ERROR: Failed to start work for ${factionName} with work type ${workType}.`)
-```
-
-## Example 2
-
-
-```js
-// NS2
-const FACTION_NAME = "CyberSec", WORK_TYPE = "hacking";
-
-let success = ns.singularity.workForFaction(FACTION_NAME, WORK_TYPE);
-if (!success) ns.tprint(`ERROR: Failed to start work for ${FACTION_NAME} with work type ${WORK_TYPE}.`)
 ```
 

markdown/bitburner.tix.getorganization.md

@@ -34,25 +34,10 @@ The organization associated with the corresponding stock symbol. This function r
 
 1. TIX API Access
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1
-stock.getOrganization("FSIG");
-
-// Choose the first stock symbol from the array of stock symbols. Get the
-// organization associated with the corresponding stock symbol
-var sym = stock.getSymbols()[0];
-tprint("Stock symbol: " + sym);
-tprint("Stock organization: " + stock.getOrganization(sym));
-```
-
-## Example 2
-
-
-```ts
-// NS2
 ns.stock.getOrganization("FSIG");
 
 // Choose the first stock symbol from the array of stock symbols. Get the

markdown/bitburner.tix.getposition.md

@@ -34,23 +34,10 @@ The third element in the array is the number of shares the player owns of the st
 
 All elements in the returned array are numeric.
 
-## Example 1
+## Example
 
 
-```ts
+```js
-// NS1
+const [sharesLong, avgLongPrice, sharesShort, avgShortPrice] = ns.stock.getPosition("ECP");
-var pos = stock.getPosition("ECP");
-var shares      = pos[0];
-var avgPx       = pos[1];
-var sharesShort = pos[2];
-var avgPxShort  = pos[3];
-```
-
-## Example 2
-
-
-```ts
-// NS2
-const [shares, avgPx, sharesShort, avgPxShort] = ns.stock.getPosition("ECP");
 ```
 

src/Constants.ts

@@ -228,56 +228,110 @@ export const CONSTANTS: {
   Donations: 79,
 
   LatestUpdate: `
-v2.3 Dev
+v2.3 Dev - SF3 rework and performance improvements (28 Apr 2023)
+----------------------------------------------------------------
 
-General:
+BREAKING CHANGES: These changes may require changes to your scripts.
-* Monaco script editor updated to a newer version + more config options. (@Snarling)
+
-* Revamp of script ram calculation process, should be more reliable now. (@Snarling)
+* Major changes to the SF3 mechanic. See the related section below for the full (spoiler) changes.
-* Improve ns.scp filename recognition when leading slash discrepancy (@lucebac)
+* The same script filename can now be ran multiple times with the same args. If running a script from another script (ns.run/ns.exec/etc), this limitation can be re-imposed with the preventDuplicates RunOption (see general section for info on RunOptions).
-* Fix memory leak when netscript ports were initialized and never used again. (@Snarling)
+* The same .js script will now be the same js module whether the script was ran directly or used as an import. This means top-level variables (variables defined outside of any function) are shared across all instances of the script.
-* Fix a bug that could result in an infinite atExit loop if a script killed itself. (@Snarling)
+* The js module for a script will also be reused by any script that has the exact same compiled text, even if that script is on another server or has a different filename. This can lead to unexpected results when using top-level variables.
-* Fix a bug where numeric terminal arguments were not being detected as strings when enclosed in quote marks. (@LiamGeorge1999)
+* Some properties removed from ns.getPlayer and added to a separate function ns.getResetInfo. These are still accessible from getPlayer but will produce a warning message the first time they are accessed per game session.
-* Fix a bug with hackAnalyzeThreads where infinite threads would be indicated any time a single thread would hack less than $1 (@Snarling)
+* hackAnalyzeThreads now returns -1, instead of 0, when no money can be hacked from the targeted server. 
-* All Math Expressions contract no longer accepts wrong answers (@Snarling)
+
+PERFORMANCE:
+
+* Remove requirement for args to be unique. (@d0sboots)
+* Minimize impact of unavoidable memory leak when modules are created, by reusing modules as much as possible (@d0sboots)
+* Internal data structure changes (@d0sboots, @Snarling)
+* Fix memory leak when initializing large number of netscript ports (@Snarling)
+
+NETSCRIPT GENERAL:
+
+* ns.hackAnalyzeThreads no longer indicates infinity any time a single thread would hack less than $1 (@Snarling)
+* ns.renamePurchasedServer no longer crashes if player is connected to the server being renamed (@Snarling)
+* ns.hackAnalyzeThreads now return -1 (instead of 0) if no money can be hacked from the targeted server. (@d0sboots)
+* Fix a possible infinite atExit loop if a script killed itself. (@Snarling)
+* Static timestamps of last resets can be obtained via ns.getResetInfo, replacing playtimeSinceLastX from ns.getPlayer (@G4mingJon4s)
+* Added RunOptions, which can optionally replace the "threads" argument for ns.run/ns.exec/ns.spawn. (@d0sboots)
+  * RunOptions.threads: Provide a thread count (since RunOptions can replace the threads argument)
+  * RunOptions.temporary: Prevents the script execution from being included in the save file.
+  * RunOptions.ramOverride: Provide a static ram cost for the script to override what is calculated by the game. Dynamic ram checking is still enforced.
+  * RunOptions.preventDuplicates: Fail to launch the script if the args are identical to a script already running.
+
+GENERAL / MISC:
+
+* Monaco script editor updated to a newer version and has more config options available now. (@Snarling)
 * Improve Electron's handling of external links (@Snarling) 
-* Documentation improvements (@Mughur, @quacksouls, @Snarling, @AdityaHegde)
+* Improved support for ANSI color codes (@d0sboots)
-* Performance improvements for shallow typechecking on objects sent into API (e.g. for formulas) (@Snarling)
+* Improved consistency of file paths. Correct names for files no longer start with a / even if they are in a directory. (@Snarling)
-* Faction invites now trigger immediately when backdooring a server.
+* All Math Expressions contract no longer accepts wrong answers (@Snarling)
+* Faction invites now trigger immediately when backdooring a server. (@Snarling)
+* Fixed issue where duplicate programs could be created. (@Minzenkatze)
+* UI improvements to create program page (@Minzenkatze)
+* Fix inconsistency in skill xp to skill level conversion (@hydroflame)
+* Updated blood donation counter to reflect number of confirmed blood donations. (@hydroflame)
+* Minor improvements to ram calculation process (@Snarling)
+* Improved terminal arguments detection (@Snarling)
+* Improved display for ls terminal command. (@Snarling)
+* Added more internal tests and improved test quality (@d0sboots)
+* Various codebase improvements (@Snarling, @d0sboots)
+* Documentation improvements (Many contributors)
+* Nerf noodle bar
+
+SPOILER SECTIONS:
 
 SF2:
+
 * Corrected the "Next equipment unlock" text for member upgrades. (@LiamGeorge1999)
 
+SF3:
+
+* Product quality now depends on material quality (@Mughur)
+* Product price can be set separately per-city (@Mughur)
+* Exports can be set relative to inventory or production (@Mughur)
+* ns.corporation.getProduct is city-specific (@Mughur)
+* Bulk purchasing is available from the start (@Mughur)
+* Can buy multiple upgrades at a time, similar to hacknet node upgrades (@Mughur)
+* Various UI changes (@Mughur)
+* Removed happiness from employees (@Mughur)
+* Coffee renamed to tea (@Mughur)
+* Training position renamed to intern (@Mughur)
+* More options for SmartSupply (@Mughur)
+* Advertising nerf (@Mughur)
+* Nerfed investors and reduced effectiveness of "fraud" (@Mughur)
+* Various other changes (@Mughur)
+
 SF4:
+
 * Faction invites trigger immediately when running ns.singularity.getFactionInvitations (@Snarling)
+* Added ns.singularity.getCompanyPositionInfo (@jeek)
 
 SF6:
+
 * Failing a contract or operation now consumes the action (@Zelow79)
 
 SF9:
+
 * The SF9.3 bonus is also given to the player when inside of BN9. (@Zelow79)
 * Adjusted the SF1 bonus for hacknet costs (slight nerf), and raised the SF9 bonus to compensate. (@d0sboots)
+* Added option to purchase company favor using hashes. (@jeek)
 
 SF10:
+
 * Sleeve shock recovery now scales with intelligence. (@Tyasuh)
 * Sleeve kills during crimes count towards numPeopleKilled (@Zelow79)
 * Fix a misspelled moneySourceTracker call for sleeves (@zerbosh)
 * ns.sleeve.getTask return value now includes cyclesNeeded where applicable (@Snarling)
 * Internal type refactoring on Sleeve Work. (@Snarling)
 
+SF12:
+
+* Fix inconsistency in how BN12 multipliers were calculated 
+
 SF13:
+
 * Improve performance of Stanek's gift update cycle, and rework (buff) bonus time handling. (@Snarling)
-
-Misc:
-* Nerf noodle bar
-
-2.2.2 Hotfixes
-* Fix an issue that prevented the Electron API server from communicating with the VSCode plugin. (credit to u/AnyGiraffe4367 on reddit)
-
-Planned changes remaining in 2.3:
-* 2.3 will include a large planned rework to corporation. This may cause api breaks for any corporation scripts, and there will be large changes in how the corporation mechanic functions.
-* Enum changes, potentially causing API break with some enums. Enums will be more usable and there will be more of them.
-* Constants rework - interenal game constants will be reorganized and will be provided to the player as different categories of constants.
-* Further deprecation of ns1. Removal of more documentation, add ingame notice to prompt player to update scripts to .js.
-* Nerf noodle bar
 `,
 };

src/ScriptEditor/NetscriptDefinitions.d.ts

@@ -1,5 +1,4 @@
-/* TODO: remove ns1-specific documentation for all functions, and just create a basic doc somewhere that says how to
+/** All netscript definitions */
- *       convert examples for use in .script files (e.g. no async/await, var instead of let/const, etc). */
 
 /** @public */
 interface HP {
@@ -1103,19 +1102,7 @@ export interface TIX {
    * 1. TIX API Access
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1
-   * stock.getOrganization("FSIG");
-   *
-   * // Choose the first stock symbol from the array of stock symbols. Get the
-   * // organization associated with the corresponding stock symbol
-   * var sym = stock.getSymbols()[0];
-   * tprint("Stock symbol: " + sym);
-   * tprint("Stock organization: " + stock.getOrganization(sym));
-   * ```
-   * @example
-   * ```ts
-   * // NS2
    * ns.stock.getOrganization("FSIG");
    *
    * // Choose the first stock symbol from the array of stock symbols. Get the
@@ -1164,18 +1151,8 @@ export interface TIX {
    * All elements in the returned array are numeric.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1
+   * const [sharesLong, avgLongPrice, sharesShort, avgShortPrice] = ns.stock.getPosition("ECP");
-   * var pos = stock.getPosition("ECP");
-   * var shares      = pos[0];
-   * var avgPx       = pos[1];
-   * var sharesShort = pos[2];
-   * var avgPxShort  = pos[3];
-   * ```
-   * @example
-   * ```ts
-   * // NS2
-   * const [shares, avgPx, sharesShort, avgPxShort] = ns.stock.getPosition("ECP");
    * ```
    * @param sym - Stock symbol.
    * @returns Array of four elements that represents the player’s position in a stock.
@@ -1587,14 +1564,10 @@ export interface Singularity {
    * Web using the Terminal buy command.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1
+   * const programName = "BruteSSH.exe"
-   * purchaseProgram("brutessh.exe");
+   * const success = ns.purchaseProgram(programName);
-   * ```
+   * if (!success) ns.tprint("ERROR: Failed to purchase ${programName}")
-   * @example
-   * ```ts
-   * // NS2
-   * ns.purchaseProgram("brutessh.exe");
    * ```
    * @param programName - Name of program to purchase.
    * @returns True if the specified program is purchased, and false otherwise.
@@ -1727,17 +1700,8 @@ export interface Singularity {
    *
    * @example
    * ```js
-   * // NS1:
+   * const companyName = "Noodle Bar";
-   * var COMPANY_NAME = "Noodle Bar";
+   * const jobList = ns.singularity.getCompanyPositions(companyName);
-   *
-   * var jobList = singularity.getCompanyPositions(COMPANY_NAME);
-   * ```
-   * @example
-   * ```js
-   * // NS2:
-   * const COMPANY_NAME = "Noodle Bar";
-   *
-   * let jobList = ns.singularity.getCompanyPositions(COMPANY_NAME);
    * ```
    * @param companyName - Name of company to get the position list for. Must be an exact match.
    * @returns The position list if the company name is valid.
@@ -1758,19 +1722,9 @@ export interface Singularity {
    *
    * @example
    * ```js
-   * // NS1:
+   * const companyName = "Noodle Bar";
-   * var COMPANY_NAME = "Noodle Bar";
+   * const success = ns.singularity.workForCompany(companyName);
-   *
+   * if (!success) ns.tprint(`ERROR: Failed to start work at ${companyName}.`);
-   * var success = singularity.workForCompany(COMPANY_NAME);
-   * if (!success) tprint("ERROR: Failed to start work at " + COMPANY_NAME + ".");
-   * ```
-   * @example
-   * ```js
-   * // NS2:
-   * const COMPANY_NAME = "Noodle Bar";
-   *
-   * let success = ns.singularity.workForCompany(COMPANY_NAME);
-   * if (!success) ns.tprint(`ERROR: Failed to start work at ${COMPANY_NAME].`);
    * ```
    * @param companyName - Name of company to work for. Must be an exact match. Optional. If not specified, this
    *   argument defaults to the last job that you worked.
@@ -1895,19 +1849,11 @@ export interface Singularity {
    *
    * @example
    * ```js
-   * // NS1
+   * const factionName = "CyberSec";
-   * var FACTION_NAME = "CyberSec", WORK_TYPE = "hacking";
+   * const workType = "hacking";
    *
-   * var success = singularity.workForFaction(FACTION_NAME, WORK_TYPE);
+   * let success = ns.singularity.workForFaction(factionName, workType);
-   * if (!success) tprint("ERROR: Failed to start work for " + FACTION_NAME + " with work type " + WORK_TYPE);
+   * if (!success) ns.tprint(`ERROR: Failed to start work for ${factionName} with work type ${workType}.`)
-   * ```
-   * @example
-   * ```js
-   * // NS2
-   * const FACTION_NAME = "CyberSec", WORK_TYPE = "hacking";
-   *
-   * let success = ns.singularity.workForFaction(FACTION_NAME, WORK_TYPE);
-   * if (!success) ns.tprint(`ERROR: Failed to start work for ${FACTION_NAME} with work type ${WORK_TYPE}.`)
    * ```
    * @param faction - Name of faction to work for.
    * @param workType - Type of work to perform for the faction.
@@ -1998,14 +1944,10 @@ export interface Singularity {
    * * AutoLink.exe: 25
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
+   * const programName = "BruteSSH.exe";
-   * createProgram(“relaysmtp.exe”);
+   * const success = ns.createProgram(programName);
-   * ```
+   * if (!success) ns.tprint("ERROR: Failed to start working on ${programName}")
-   * @example
-   * ```ts
-   * // NS2:
-   * ns.createProgram(“relaysmtp.exe”);
    * ```
    * @param program - Name of program to create.
    * @param focus - Acquire player focus on this program creation. Optional. Defaults to true.
@@ -2295,16 +2237,9 @@ export interface Singularity {
    * empty list.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1
+   * const programs = ns.getDarkwebPrograms();
-   * getDarkwebPrograms();
+   * ns.tprint(`Available programs are: ${programs.split(", ")}`);
-   * // returns ['BruteSSH.exe', 'FTPCrack.exe'...etc]
-   * ```
-   * @example
-   * ```ts
-   * // NS2
-   * ns.getDarkwebPrograms();
-   * // returns ['BruteSSH.exe', 'FTPCrack.exe'...etc]
    * ```
    * @returns - a list of programs available for purchase on the dark web, or [] if Tor has not
    * been purchased
@@ -2328,14 +2263,10 @@ export interface Singularity {
    *
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1
+   * const programName = "BruteSSH.exe";
-   * getDarkwebProgramCost("brutessh.exe");
+   * const cost = ns.getDarkwebProgramCost(programName);
-   * ```
+   * if (cost > 0) ns.tprint(`${programName} costs ${ns.formatMoney(cost)}`);
-   * @example
-   * ```ts
-   * // NS2
-   * ns.getDarkwebProgramCost("brutessh.exe");
    * ```
    * @param programName - Name of program to check the price of
    * @returns Price of the specified darkweb program
@@ -2639,16 +2570,7 @@ export interface Hacknet {
    * Returns the number of hashes required for the specified upgrade. The name of the upgrade must be an exact match.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
-   * var upgradeName = "Sell for Corporation Funds";
-   * if (hacknet.numHashes() > hacknet.hashCost(upgradeName)) {
-   *    hacknet.spendHashes(upgradeName);
-   * }
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
    * const upgradeName = "Sell for Corporation Funds";
    * if (ns.hacknet.numHashes() > ns.hacknet.hashCost(upgradeName)) {
    *   ns.hacknet.spendHashes(upgradeName);
@@ -2675,15 +2597,10 @@ export interface Hacknet {
    * In this case, the `upgTarget` argument must be the hostname of the server.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
+   * // For upgrades where no target is required
-   * hacknet.spendHashes("Sell for Corporation Funds");
-   * hacknet.spendHashes("Increase Maximum Money", "foodnstuff");
-   * ```
-   * @example
-   * ```ts
-   * NS2:
    * ns.hacknet.spendHashes("Sell for Corporation Funds");
+   * // For upgrades requiring a target
    * ns.hacknet.spendHashes("Increase Maximum Money", "foodnstuff");
    * ```
    * @param upgName - Name of the upgrade of Hacknet Node.
@@ -2703,13 +2620,7 @@ export interface Hacknet {
    *
    * Returns the list of all available hash upgrades that can be used in the spendHashes function.
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
-   * var upgrades = hacknet.getHashUpgrades(); // ["Sell for Money","Sell for Corporation Funds",...]
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
    * const upgrades = ns.hacknet.getHashUpgrades(); // ["Sell for Money","Sell for Corporation Funds",...]
    * ```
    * @returns An array containing the available upgrades
@@ -3187,16 +3098,7 @@ export interface Bladeburner {
    * Returns an array with two elements:
    * * [Current stamina, Max stamina]
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
-   * function getStaminaPercentage() {
-   *    var res = bladeburner.getStamina();
-   *    return res[0] / res[1];
-   * }
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
    * function getStaminaPercentage() {
    *    const [current, max] = ns.bladeburner.getStamina();
    *    return current / max;
@@ -3274,15 +3176,6 @@ export interface CodingContract {
    *
    * @example
    * ```js
-   * // NS1
-   * var reward = codingcontract.attempt(yourSolution, filename, hostname);
-   * if (reward) {
-   *   tprint("Contract solved successfully! Reward: " + reward)
-   * } else tprint("Failed to solve contract.")
-   * ```
-   * @example
-   * ```js
-   * // NS2
    * const reward = codingcontract.attempt(yourSolution, filename, hostname);
    * if (reward) {
    *   ns.tprint(`Contract solved successfully! Reward: ${reward}`)
@@ -4561,28 +4454,21 @@ interface UserInterface {
  * Collection of all functions passed to scripts
  * @public
  * @remarks
- * <b>Basic ns1 usage example:</b>
+ * <b>Basic usage example:</b>
- * ```ts
+ * ```js
- *  // Basic ns functions can be used directly
- *  getHostname();
- *  // Some related functions are gathered within a common namespace
- *  stock.getPrice();
- * ```
- * {@link https://bitburner-official.readthedocs.io/en/latest/netscript/netscript1.html| ns1 in-game docs}
- * <hr>
- * <b>Basic ns2 usage example:</b>
- * ```ts
  * export async function main(ns) {
  *  // Basic ns functions can be accessed on the ns object
  *  ns.getHostname();
  *  // Some related functions are gathered under a sub-property of the ns object
  *  ns.stock.getPrice();
- *  // Some functions need to be awaited
+ *  // Most functions that return a promise need to be awaited.
  *  await ns.hack('n00dles');
  * }
  * ```
  * {@link https://bitburner-official.readthedocs.io/en/latest/netscript/netscriptjs.html| ns2 in-game docs}
  * <hr>
+ * For (deprecated) .script usage, see: {@link https://bitburner-official.readthedocs.io/en/latest/netscript/netscript1.html| ns1 in-game docs}
+ * <hr>
  */
 export interface NS {
   /**
@@ -4710,18 +4596,12 @@ export interface NS {
    * A successful `hack()` on a server will raise that server’s security level by 0.002.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
-   * var earnedMoney = hack("foodnstuff");
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
    * let earnedMoney = await ns.hack("foodnstuff");
    * ```
    * @param host - Hostname of the target server to hack.
    * @param opts - Optional parameters for configuring function behavior.
-   * @returns The amount of money stolen if the hack is successful, and zero otherwise.
+   * @returns A promise that resolves to the amount of money stolen (which is zero if the hack is unsuccessful).
    */
   hack(host: string, opts?: BasicHGWOptions): Promise<number>;
 
@@ -4781,20 +4661,13 @@ export interface NS {
    * there is no required hacking level to run the function.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
-   * var currentSecurity = getServerSecurityLevel("foodnstuff");
-   * currentSecurity = currentSecurity - weaken("foodnstuff");
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
    * let currentSecurity = ns.getServerSecurityLevel("foodnstuff");
    * currentSecurity -= await ns.weaken("foodnstuff");
    * ```
    * @param host - Hostname of the target server to weaken.
    * @param opts - Optional parameters for configuring function behavior.
-   * @returns The amount by which the target server’s security level was decreased. This is equivalent to 0.05 multiplied by the number of script threads.
+   * @returns A promise that resolves to the value by which security was reduced.
    */
   weaken(host: string, opts?: BasicHGWOptions): Promise<number>;
 
@@ -4941,35 +4814,24 @@ export interface NS {
    *
    * @param millis - Number of milliseconds to sleep.
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
    * // This will count from 1 to 10 in your terminal, with one number every 5 seconds
-   * for (var i=0; i<10; i++) {
+   * for (var i = 1; i <= 10; i++) {
-   *   tprint(i + 1);
+   *   ns.tprint(i);
-   *   sleep(5000);
-   * }
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
-   * // This will count from 1 to 10 in your terminal, with one number every 5 seconds
-   * for (var i=0; i<10; i++) {
-   *   ns.tprint(i + 1);
    *   await ns.sleep(5000);
    * }
    * ```
-   * @returns
+   * @returns A promise that resolves to true when the sleep is completed.
    */
   sleep(millis: number): Promise<true>;
 
   /**
    * Suspends the script for n milliseconds. Doesn't block with concurrent calls.
-   * You should prefer 'sleep' over 'asleep' except when doing very complex UI work.
    * @remarks
    * RAM cost: 0 GB
    *
    * @param millis - Number of milliseconds to sleep.
-   * @returns
+   * @returns A promise that resolves to true when the sleep is completed.
    */
   asleep(millis: number): Promise<true>;
 
@@ -5001,29 +4863,7 @@ export interface NS {
    * strict mode.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1
-   * // Default color coding.
-   * print("ERROR means something's wrong.");
-   * print("SUCCESS means everything's OK.");
-   * print("WARN Tread with caution!");
-   * print("WARNING, warning, danger, danger!");
-   * print("WARNing! Here be dragons.");
-   * print("INFO for your I's only (FYI).");
-   * print("INFOrmation overload!");
-   * // Custom color coding.
-   * var cyan = "\u001b[36m";
-   * var green = "\u001b[32m";
-   * var red = "\u001b[31m";
-   * var reset = "\u001b[0m";
-   * print(red + "Ugh! What a mess." + reset);
-   * print(green + "Well done!" + reset);
-   * print(cyan + "ERROR Should this be in red?" + reset);
-   * tail();
-   * ```
-   * @example
-   * ```ts
-   * // NS2
    * // Default color coding.
    * ns.print("ERROR means something's wrong.");
    * ns.print("SUCCESS means everything's OK.");
@@ -5057,21 +4897,7 @@ export interface NS {
    * - For more detail, see: https://github.com/alexei/sprintf.js
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1
-   * var name = "Bit";
-   * var age = 4;
-   * printf("My name is %s.", name);
-   * printf("I'm %d seconds old.", age);
-   * printf("My age in binary is %b.", age);
-   * printf("My age in scientific notation is %e.", age);
-   * printf("In %d seconds, I'll be %s.", 6, "Byte");
-   * printf("Am I a nibble? %t", (4 == age));
-   * tail();
-   * ```
-   * @example
-   * ```ts
-   * // NS2
    * const name = "Bit";
    * const age = 4;
    * ns.printf("My name is %s.", name);
@@ -5287,25 +5113,7 @@ export interface NS {
    * array are strings.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1
-   * // All servers that are one hop from the current server.
-   * tprint("Neighbors of current server.");
-   * var neighbor = scan();
-   * for (var i = 0; i < neighbor.length; i++) {
-   *     tprint(neighbor[i]);
-   * }
-   * // All neighbors of n00dles.
-   * var target = "n00dles";
-   * neighbor = scan(target);
-   * tprintf("Neighbors of %s.", target);
-   * for (var i = 0; i < neighbor.length; i++) {
-   *     tprint(neighbor[i]);
-   * }
-   * ```
-   * @example
-   * ```ts
-   * // NS2
    * // All servers that are one hop from the current server.
    * ns.tprint("Neighbors of current server.");
    * let neighbor = ns.scan();
@@ -5332,14 +5140,7 @@ export interface NS {
    *
    * @example
    * ```js
-   * // NS1:
+   * if (ns.hasTorRouter()) ns.tprint("TOR router detected.");
-   * if (hasTorRouter()) tprint("TOR router detected.");
-   * ```
-   *
-   * @example
-   * ```js
-   * // NS2:
-   * if (ns.hasTorRouter()) tprint("TOR router detected.");
    * ```
    *
    * @returns Whether player has access to the dark web. */
@@ -5353,13 +5154,7 @@ export interface NS {
    * Running NUKE.exe on a target server gives you root access which means you can execute scripts on said server. NUKE.exe must exist on your home computer.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
-   * nuke("foodnstuff");
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
    * ns.nuke("foodnstuff");
    * ```
    * @param host - Hostname of the target server.
@@ -5374,13 +5169,7 @@ export interface NS {
    * Runs the BruteSSH.exe program on the target server. BruteSSH.exe must exist on your home computer.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
-   * brutessh("foodnstuff");
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
    * ns.brutessh("foodnstuff");
    * ```
    * @param host - Hostname of the target server.
@@ -5395,13 +5184,7 @@ export interface NS {
    * Runs the FTPCrack.exe program on the target server. FTPCrack.exe must exist on your home computer.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
-   * ftpcrack("foodnstuff");
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
    * ns.ftpcrack("foodnstuff");
    * ```
    * @param host - Hostname of the target server.
@@ -5416,13 +5199,7 @@ export interface NS {
    * Runs the relaySMTP.exe program on the target server. relaySMTP.exe must exist on your home computer.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
-   * relaysmtp("foodnstuff");
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
    * ns.relaysmtp("foodnstuff");
    * ```
    * @param host - Hostname of the target server.
@@ -5437,13 +5214,7 @@ export interface NS {
    * Runs the HTTPWorm.exe program on the target server. HTTPWorm.exe must exist on your home computer.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
-   * httpworm("foodnstuff");
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
    * ns.httpworm("foodnstuff");
    * ```
    * @param host - Hostname of the target server.
@@ -5458,13 +5229,7 @@ export interface NS {
    * Runs the SQLInject.exe program on the target server. SQLInject.exe must exist on your home computer.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
-   * sqlinject("foodnstuff");
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
    * ns.sqlinject("foodnstuff");
    * ```
    * @remarks RAM cost: 0.05 GB
@@ -5700,17 +5465,7 @@ export interface NS {
    * Returns an array with general information about all scripts running on the specified target server.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
-   * var scripts = ps("home");
-   * for (var i = 0; i < scripts.length; ++i) {
-   *     tprint(scripts[i].filename + ' ' + scripts[i].threads);
-   *     tprint(scripts[i].args);
-   * }
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
    * const ps = ns.ps("home");
    * for (let script of ps) {
    *   ns.tprint(`${script.filename} ${script.threads}`);
@@ -5730,16 +5485,8 @@ export interface NS {
    * Returns a boolean indicating whether or not the player has root access to the specified target server.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
+   * if (!ns.hasRootAccess("foodnstuff")) {
-   * if (hasRootAccess("foodnstuff") == false) {
-   *    nuke("foodnstuff");
-   * }
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
-   * if (ns.hasRootAccess("foodnstuff") == false) {
    *   ns.nuke("foodnstuff");
    * }
    * ```
@@ -5776,20 +5523,10 @@ export interface NS {
    * (e.g. 1.5 instead of 150%).
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
+   * const mults = ns.getHackingMultipliers();
-   * // Example of how this can be used:
+   * print(`chance: ${mults.chance}`);
-   * var mults = getHackingMultipliers();
+   * print(`growthL ${mults.growth}`);
-   * print(mults.chance);
-   * print(mults.growth);
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
-   * // Example of how this can be used:
-   * const {chance, growth} = ns.getHackingMultipliers();
-   * print(chance);
-   * print(growth);
    * ```
    * @returns Object containing the Player’s hacking related multipliers.
    */
@@ -5805,20 +5542,10 @@ export interface NS {
    * (e.g. 1.5 instead of 150%).
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
+   * const mults = ns.getHacknetMultipliers();
-   * // Example of how this can be used:
+   * ns.tprint(`production: ${mults.production}`);
-   * var mults = getHacknetMultipliers();
+   * ns.tprint(`purchaseCost: ${mults.purchaseCost}`);
-   * print(mults.production);
-   * print(mults.purchaseCost);
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
-   * // Example of how this can be used:
-   * const {production, purchaseCost} = ns.getHacknetMultipliers();
-   * print(production);
-   * print(purchaseCost);
    * ```
    * @returns Object containing the Player’s hacknet related multipliers.
    */
@@ -5843,14 +5570,7 @@ export interface NS {
    * Running this function on the home computer will return the player’s money.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
-   * getServerMoneyAvailable("foodnstuff");
-   * getServerMoneyAvailable("home"); //Returns player's money
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
    * ns.getServerMoneyAvailable("foodnstuff");
    * ns.getServerMoneyAvailable("home"); // Returns player's money
    * ```
@@ -6052,18 +5772,10 @@ export interface NS {
    * Returns the cost to purchase a server with the specified amount of ram.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
+   * const ram = 2 ** 20;
-   * for (i = 1; i <= 20; i++) {
+   * const cost = ns.getPurchasedServerCost(ram);
-   *     tprint(i + " -- " + getPurchasedServerCost(Math.pow(2, i)));
+   * ns.tprint(`A purchased server with ${ns.formatRam(ram)} costs ${ns.formatMoney(cost)}`);
-   * }
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
-   * for (i = 1; i <= 20; i++) {
-   *     ns.tprint(i + " -- " + ns.getPurchasedServerCost(Math.pow(2, i)));
-   * }
    * ```
    * @param ram - Amount of RAM of a potential purchased server, in GB. Must be a power of 2 (2, 4, 8, 16, etc.). Maximum value of 1048576 (2^20).
    * @returns The cost to purchase a server with the specified amount of ram.
@@ -6095,17 +5807,8 @@ export interface NS {
    * amount of servers.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
+   * // Attempt to purchase 5 servers with 64GB of ram each
-   * var ram = 64;
-   * var prefix = "pserv-";
-   * for (i = 0; i < 5; ++i) {
-   *    purchaseServer(prefix + i, ram);
-   * }
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
    * const ram = 64;
    * const prefix = "pserv-";
    * for (i = 0; i < 5; ++i) {
@@ -6629,33 +6332,7 @@ export interface NS {
    *   chooses one of the provided options and presses the "Confirm" button.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1
-   * // A Yes/No question. The default is to create a boolean dialog box.
-   * var queryA = "Do you enjoy Bitburner?";
-   * var resultA = prompt(queryA);
-   * tprint(queryA + " " + resultA);
-   *
-   * // Another Yes/No question. Can also create a boolean dialog box by explicitly
-   * // passing the option {"type": "boolean"}.
-   * var queryB = "Is programming fun?";
-   * var resultB = prompt(queryB, { type: "boolean" });
-   * tprint(queryB + " " + resultB);
-   *
-   * // Free-form text box.
-   * var resultC = prompt("Please enter your name.", { type: "text" });
-   * tprint("Hello, " + resultC + ".");
-   *
-   * // A drop-down list.
-   * var resultD = prompt("Please select your favorite fruit.", {
-   *     type: "select",
-   *     choices: ["Apple", "Banana", "Orange", "Pear", "Strawberry"]
-   * });
-   * tprint("Your favorite fruit is " + resultD.toLowerCase() + ".");
-   * ```
-   * @example
-   * ```ts
-   * // NS2
    * // A Yes/No question. The default is to create a boolean dialog box.
    * const queryA = "Do you enjoy Bitburner?";
    * const resultA = await ns.prompt(queryA);
@@ -6759,18 +6436,10 @@ export interface NS {
    * you would have received in BitNode-1.
    *
    * @example
-   * ```ts
+   * ```js
-   * // NS1:
+   * const mults = ns.getBitNodeMultipliers();
-   * var mults = getBitNodeMultipliers();
+   * ns.tprint(`ServerMaxMoney: ${mults.ServerMaxMoney}`);
-   * print(mults.ServerMaxMoney);
+   * ns.tprint(`HackExpGain: ${mults.HackExpGain}`);
-   * print(mults.HackExpGain);
-   * ```
-   * @example
-   * ```ts
-   * // NS2:
-   * const {ServerMaxMoney, HackExpGain} = ns.getBitNodeMultipliers();
-   * print(ServerMaxMoney);
-   * print(HackExpGain);
    * ```
    * @returns Object containing the current BitNode multipliers.
    */