Merge pull request #2541 from Feodoric/documentation-updates

Documentation updates

doc/source/basicgameplay/codingcontracts.rst

@@ -113,7 +113,7 @@ The list contains the name of (i.e. the value returned by
 |                                    | | to any position from i to i+n.                                                         |
 |                                    | |                                                                                        |
 |                                    | | Assuming you are initially positioned at the start of the array, determine             |
-|                                    | | whether you are able to reach the last index of the array EXACTLY.                     |
+|                                    | | whether you are able to reach the last index of the array.                     |
 +------------------------------------+------------------------------------------------------------------------------------------+
 | Merge Overlapping Intervals        | | Given an array of intervals, merge all overlapping intervals. An interval              |
 |                                    | | is an array with two numbers, where the first number is always less than               |

doc/source/basicgameplay/infiltration.rst

@@ -17,9 +17,16 @@ says 'Infiltrate Company'.
 When infiltrating a company you will be presented with short active challenges.
 None of the challenges use the mouse.
 
-The difficulty at the top lowers with better combat stats. It is not recommended
+The difficulty at the top lowers with better combat stats and charisma. It is not recommended
 to attempt infiltrations above mid-normal.
 
+The "maximum level" is the number of challenges you will need to pass to receive
+the infiltration reward.
+
+Every time you fail an infiltration challenge, you will take damage based on the
+difficulty of the infiltration. If you are reduced to 0 hp or below, the
+infiltration will immediately end.
+
 * Most use spacebar as "action"
 * Some use WASD or arrows interchangeably.
 * A few others use the rest of the keyboard.

doc/source/basicgameplay/stats.rst

@@ -16,7 +16,6 @@ Affects:
 * Chance to successfully hack a server
 * Percent money stolen when hacking a server
 * Success rate of certain crimes
-* Success rate of Hacking option during Infiltration
 * Time it takes to create a program
 * Faction reputation gain when carrying out Hacking Contracts or Field Work
 * Company reputation gain for certain jobs
@@ -26,7 +25,6 @@ Gain experience by:
 * Manually hacking servers through Terminal
 * Executing hack(), grow(), or weaken() through a script
 * Committing certain crimes
-* Infiltration
 * Carrying out Hacking Contracts or doing Field work for Factions
 * Working certain jobs at a company
 * Studying at a university
@@ -38,14 +36,12 @@ Represents the player's physical offensive power
 Affects:
 
 * Success rate of certain crimes
-* Success rate of Combat options during Infiltration
 * Faction reputation gain for Security and Field Work
 * Company reputation gain for certain jobs
 
 Gain experience by:
 
 * Committing certain crimes
-* Infiltration
 * Working out at a gym
 * Doing Security/Field Work for a faction
 * Working certain jobs at a company
@@ -58,15 +54,12 @@ Affects:
 
 * Success rate of certain crimes
 * The player's HP
-* Success rate of Combat options during Infiltration
-* How much damage the player takes during Infiltration
 * Faction reputation gain for Security and Field Work
 * Company reputation gain for certain jobs
 
 Gain experience by:
 
 * Committing certain crimes
-* Infiltration
 * Working out at a gym
 * Doing Security/Field Work for a faction
 * Working certain jobs at a company
@@ -78,14 +71,12 @@ Represents the player's skill and adeptness in performing certain tasks
 Affects:
 
 * Success rate of certain crimes
-* Success rate of Combat, Lockpick, and Escape options during Infiltration
 * Faction reputation gain for Security and Field Work
 * Company reputation gain for certain jobs
 
 Gain experience by:
 
 * Committing certain crimes
-* Infiltration
 * Working out at a gym
 * Doing Security/Field Work for a faction
 * Working certain jobs at a company
@@ -97,14 +88,12 @@ Represents the player's speed and ability to move
 Affects:
 
 * Success rate of certain crimes
-* Success rate of Combat, Sneak, and Escape options during Infiltration
 * Faction reputation gain for Security and Field Work
 * Company reputation gain for certain jobs
 
 Gain experience by:
 
 * Committing certain crimes
-* Infiltration
 * Working out at a gym
 * Doing Security/Field Work for a faction
 * Working certain jobs at a company
@@ -116,14 +105,12 @@ Represents the player's social abilities
 Affects:
 
 * Success rate of certain crimes
-* Success rate of Bribe option during Infiltration
 * Faction reputation gain for Field Work
 * Company reputation gain for most jobs
 
 Gain experience by:
 
 * Committing certain crimes
-* Infiltration
 * Studying at a university
 * Working a relevant job at a company
 * Doing Field work for a Faction

doc/source/guidesandtips/gettingstartedguideforbeginnerprogrammers.rst

@@ -806,8 +806,7 @@ startup script. Feel free to adjust it to your liking.
 
     // Array of all servers that don't need any ports opened
     // to gain root access. These have 16 GB of RAM
-    var servers0Port = ["n00dles",
+    var servers0Port = ["sigma-cosmetics",
-                        "sigma-cosmetics",
                         "joesguns",
                         "nectar-net",
                         "hong-fang-tea",

doc/source/netscript/netscriptmisc.rst

@@ -66,8 +66,7 @@ And the data in port 1 will look like::
 WARNING: Port Handles only work in :ref:`netscriptjs`. They do not work in :ref:`netscript1`
 
 The :js:func:`getPortHandle` Netscript function can be used to get a handle to a Netscript Port.
-This handle allows you to access several new port-related functions and the
+This handle allows you to access several new port-related functions. The functions are:
-port's underlying data structure, which is just a JavaScript array. The functions are:
 
 .. js:method:: NetscriptPort.writePort(data)
 
@@ -111,22 +110,11 @@ port's underlying data structure, which is just a JavaScript array. The function
 
     Clears all data from the port. Works the same as the Netscript function `clear`
 
-.. js:attribute:: NetscriptPort.data
-
-    The Netscript port underlying data structure, which is just a Javascript array. All
-    valid Javascript Array methods can be called on this.
-
 Port Handle Example::
 
     port = getPortHandle(5);
     back = port.data.pop(); //Get and remove last element in port
 
-    //Remove an element from the port
-    i = port.data.findIndex("foo");
-    if (i != -1) {
-        port.data.slice(i, 1);
-    }
-
     //Wait for port data before reading
     while(port.empty()) {
         sleep(10000);

src/ScriptEditor/NetscriptDefinitions.d.ts

@@ -109,32 +109,6 @@ interface RunningScript {
   threads: number;
 }
 
-/**
- * Interface of a netscript port
- * @public
- */
-export interface IPort {
-  /** write data to the port and removes and returns first element if full */
-  write: (value: any) => any;
-  /** add data to port if not full.
-   * @returns true if added and false if full and not added */
-  tryWrite: (value: any) => boolean;
-  /** reads and removes first element from port
-   * if no data in port returns "NULL PORT DATA"
-   */
-  read: () => any;
-  /** reads first element without removing it from port
-   * if no data in port returns "NULL PORT DATA"
-   */
-  peek: () => any;
-  /** check if port is full */
-  full: () => boolean;
-  /** check if port is empty */
-  empty: () => boolean;
-  /** removes all data from port */
-  clear: () => void;
-}
-
 /**
  * Data representing the internal values of a crime.
  * @public
@@ -280,6 +254,24 @@ export interface AugmentPair {
   cost: number;
 }
 
+/**
+ * @public
+ */
+export enum PositionTypes {
+  Long = "L",
+  Short = "S",
+}
+
+/**
+ * @public
+ */
+export enum OrderTypes {
+  LimitBuy = "Limit Buy Order",
+  LimitSell = "Limit Sell Order",
+  StopBuy = "Stop Buy Order",
+  StopSell = "Stop Sell Order",
+}
+
 /**
  * Value in map of {@link StockOrder}
  * @public
@@ -290,17 +282,18 @@ export interface StockOrderObject {
   /** Price per share */
   price: number;
   /** Order type */
-  type: string;
+  type: OrderTypes;
   /** Order position */
-  position: string;
+  position: PositionTypes;
 }
 
 /**
  * Return value of {@link TIX.getOrders | getOrders}
+ *
+ * Keys are stock symbols, properties are arrays of {@link StockOrderObject}
  * @public
  */
 export interface StockOrder {
-  /** Stock Symbol */
   [key: string]: StockOrderObject[];
 }
 
@@ -488,6 +481,8 @@ export interface BitNodeMultipliers {
   FourSigmaMarketDataApiCost: number;
   /** Influences how much it costs to unlock the stock market's 4S Market Data (NOT API) */
   FourSigmaMarketDataCost: number;
+  /** Influences the respect gain and money gain of your gang. */
+  GangSoftcap: number;
   /** Influences the experienced gained when hacking a server. */
   HackExpGain: number;
   /** Influences how quickly the player's hacking level (not experience) scales */
@@ -508,10 +503,14 @@ export interface BitNodeMultipliers {
   PurchasedServerLimit: number;
   /** Influences the maximum allowed RAM for a purchased server */
   PurchasedServerMaxRam: number;
+  /** Influences cost of any purchased server at or above 128GB */
+  PurchasedServerSoftCap: number;
   /** Influences the minimum favor the player must have with a faction before they can donate to gain rep. */
   RepToDonateToFaction: number;
-  /** Influences how much money can be stolen from a server when a script performs a hack against it. */
+  /** Influences how much the money on a server can be reduced when a script performs a hack against it. */
   ScriptHackMoney: number;
+  /** Influences how much of the money stolen by a scripted hack will be added to the player's money. */
+  ScriptHackMoneyGain: number;
   /** Influences the growth percentage per cycle against a server. */
   ServerGrowthRate: number;
   /** Influences the maxmimum money that a server can grow to. */
@@ -524,6 +523,12 @@ export interface BitNodeMultipliers {
   ServerWeakenRate: number;
   /** Influences how quickly the player's strength level (not exp) scales */
   StrengthLevelMultiplier: number;
+  /** Influences the power of the gift */
+  StaneksGiftPowerMultiplier: number;
+  /** Influences the size of the gift */
+  StaneksGiftExtraSize: number;
+  /** Influences the hacking skill required to backdoor the world daemon. */
+  WorldDaemonDifficulty: number;
 }
 
 /**
@@ -535,9 +540,9 @@ export interface NodeStats {
   name: string;
   /** Node's level */
   level: number;
-  /** Node's RAM */
+  /** Node's RAM (GB) */
   ram: number;
-  /** Node's used RAM */
+  /** Node's used RAM (GB) */
   ramUsed: number;
   /** Node's number of cores */
   cores: number;
@@ -956,6 +961,78 @@ export interface SleeveTask {
   factionWorkType: string;
 }
 
+/**
+ * Object representing a port. A port is a serialized queue.
+ * @public
+ */
+export interface NetscriptPort {
+  /**
+   * Write data to a port.
+   * @remarks
+   * RAM cost: 0 GB
+   *
+   * @returns The data popped off the queue if it was full.
+   */
+  write(value: string|number): null|string|number;
+
+  /**
+   * Attempt to write data to the port.
+   * @remarks
+   * RAM cost: 0 GB
+   *
+   * @returns True if the data was added to the port, false if the port was full
+   */
+  tryWrite(value: string|number): boolean;
+
+  /**
+   * Shift an element out of the port.
+   * @remarks
+   * RAM cost: 0 GB
+   *
+   * This function will remove the first element from the port and return it.
+   * If the port is empty, then the string “NULL PORT DATA” will be returned.
+   * @returns the data read.
+   */
+  read(): string|number;
+
+  /**
+   * Retrieve the first element from the port without removing it.
+   * @remarks
+   * RAM cost: 0 GB
+   *
+   * This function is used to peek at the data from a port. It returns the
+   * first element in the specified port without removing that element. If
+   * the port is empty, the string “NULL PORT DATA” will be returned.
+   * @returns the data read
+   */
+  peek(): string|number;
+
+  /**
+   * Check if the port is full.
+   * @remarks
+   * RAM cost: 0 GB
+   *
+   * @returns true if the port is full, otherwise false
+   */
+  full(): boolean;
+
+  /**
+   * Check if the port is empty.
+   * @remarks
+   * RAM cost: 0 GB
+   *
+   * @returns true if the port is empty, otherwise false
+   */
+  empty(): boolean;
+
+  /**
+   * Empties all data from the port.
+   * @remarks
+   * RAM cost: 0 GB
+   */
+  clear(): void;
+}
+
 /**
  * Stock market API
  * @public
@@ -1213,6 +1290,8 @@ export interface TIX {
    * @remarks
    * RAM cost: 2.5 GB
    * This is an object containing information for all the Limit and Stop Orders you have in the stock market.
+   * For each symbol you have a position in, the returned object will have a key with that symbol's name.
+   * The object's properties are each an array of {@link StockOrderObject}
    * The object has the following structure:
    *
    * ```ts
@@ -4440,11 +4519,11 @@ export interface NS extends Singularity {
    * //Get logs from foo.script on the foodnstuff server that was run with the arguments [1, "test"]
    * ns.tail("foo.script", "foodnstuff", 1, "test");
    * ```
-   * @param fn - Optional. Filename of the script being tailed. If omitted, the current script is tailed.
+   * @param fn - Optional. Filename or PID of the script being tailed. If omitted, the current script is tailed.
    * @param host - Optional. Hostname of the script being tailed. Defaults to the server this script is running on. If args are specified, this is not optional.
    * @param args - Arguments for the script being tailed.
    */
-  tail(fn?: string, host?: string, ...args: any[]): void;
+  tail(fn?: FilenameOrPID, host?: string, ...args: any[]): void;
 
   /**
    * Get the list of servers connected to a server.
@@ -5094,7 +5173,7 @@ export interface NS extends Singularity {
    * const [totalRam, ramUsed] = ns.getServerRam("helios");
    * ```
    * @param host - Host of target server.
-   * @returns Array with total and used memory on the specified server.
+   * @returns Array with total and used memory on the specified server, in GB.
    */
   getServerRam(host: string): [number, number];
 
@@ -5104,7 +5183,7 @@ export interface NS extends Singularity {
    * RAM cost: 0.05 GB
    *
    * @param host - Hostname of the target server.
-   * @returns max ram
+   * @returns max ram (GB)
    */
   getServerMaxRam(host: string): number;
   /**
@@ -5113,7 +5192,7 @@ export interface NS extends Singularity {
    * RAM cost: 0.05 GB
    *
    * @param host - Hostname of the target server.
-   * @returns used ram
+   * @returns used ram (GB)
    */
   getServerUsedRam(host: string): number;
 
@@ -5187,6 +5266,7 @@ export interface NS extends Singularity {
    * RAM cost: 0.1 GB
    *
    * Returns a boolean indicating whether the specified script is running on the target server.
+   * If you use a PID instead of a filename, the hostname and args parameters are unnecessary.
    * Remember that a script is uniquely identified by both its name and its arguments.
    *
    * @example
@@ -5213,12 +5293,12 @@ export interface NS extends Singularity {
    * //The function call will return true if there is a script named foo.script running with the arguments 1, 5, and “test” (in that order) on the joesguns server, and false otherwise:
    * ns.isRunning("foo.script", "joesguns", 1, 5, "test");
    * ```
-   * @param script - Filename of script to check. This is case-sensitive.
+   * @param script - Filename or PID of script to check. This is case-sensitive.
    * @param host - Host of target server.
    * @param args - Arguments to specify/identify which scripts to search for.
    * @returns True if specified script is running on the target server, and false otherwise.
    */
-  isRunning(script: string, host: string, ...args: string[]): boolean;
+  isRunning(script: FilenameOrPID, host: string, ...args: string[]): boolean;
 
   /**
    * Get general info about a running script.
@@ -5226,10 +5306,14 @@ export interface NS extends Singularity {
    * RAM cost: 0.3 GB
    *
    * Running with no args returns curent script.
+   * If you use a PID as the first parameter, the hostname and args parameters are unnecessary.
    *
+   * @param filename - Optional. Filename or PID of the script.
+   * @param hostname - Optional. Name of host server the script is running on.
+   * @param args  - Arguments to identify the script
    * @returns info about a running script
    */
-  getRunningScript(filename?: string | number, hostname?: string, ...args: (string | number)[]): RunningScript;
+  getRunningScript(filename?: FilenameOrPID, hostname?: string, ...args: (string | number)[]): RunningScript;
 
   /**
    * Get cost of purchasing a server.
@@ -5252,7 +5336,7 @@ export interface NS extends Singularity {
    *     ns.tprint(i + " -- " + ns.getPurchasedServerCost(Math.pow(2, i)));
    * }
    * ```
-   * @param ram - Amount of RAM of a potential purchased server. Must be a power of 2 (2, 4, 8, 16, etc.). Maximum value of 1048576 (2^20).
+   * @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.
    */
   getPurchasedServerCost(ram: number): number;
@@ -5300,7 +5384,7 @@ export interface NS extends Singularity {
    * }
    * ```
    * @param hostname - Host of the purchased server.
-   * @param ram - Amount of RAM of the purchased server. Must be a power of 2 (2, 4, 8, 16, etc.). Maximum value of 1048576 (2^20).
+   * @param ram - Amount of RAM of the purchased server, in GB. Must be a power of 2 (2, 4, 8, 16, etc.). Maximum value of 1048576 (2^20).
    * @returns The hostname of the newly purchased server.
    */
   purchaseServer(hostname: string, ram: number): string;
@@ -5341,7 +5425,7 @@ export interface NS extends Singularity {
    * Returns the maximum RAM that a purchased server can have.
    *
    * @remarks RAM cost: 0.05 GB
-   * @returns Returns the maximum RAM that a purchased server can have.
+   * @returns Returns the maximum RAM (in GB) that a purchased server can have.
    */
   getPurchasedServerMaxRam(): number;
 
@@ -5350,7 +5434,7 @@ export interface NS extends Singularity {
    * @remarks
    * RAM cost: 0 GB
    *
-   * This function can be used to either write data to a text file (.txt).
+   * This function can be used to write data to a text file (.txt).
    *
    * This function will write data to that text file. If the specified text file does not exist,
    * then it will be created. The third argument mode, defines how the data will be written to
@@ -5359,7 +5443,7 @@ export interface NS extends Singularity {
    * then the data will be written in “append” mode which means that the data will be added at the
    * end of the text file.
    *
-   * @param handle - Port or text file that will be written to.
+   * @param handle - Filename of the text file that will be written to.
    * @param data - Data to write.
    * @param mode - Defines the write mode. Only valid when writing to text files.
    */
@@ -5385,13 +5469,13 @@ export interface NS extends Singularity {
    * @remarks
    * RAM cost: 0 GB
    *
-   * This function is used to read data from a port or from a text file (.txt).
+   * This function is used to read data from a text file (.txt).
    *
    * This function will return the data in the specified text
    * file. If the text file does not exist, an empty string will be returned.
    *
-   * @param handle - Port or text file to read from.
+   * @param handle - Filename to read from.
-   * @returns Data in the specified text file or port.
+   * @returns Data in the specified text file.
    */
   read(handle: string): any;
 
@@ -5463,9 +5547,8 @@ export interface NS extends Singularity {
    *
    * @see https://bitburner.readthedocs.io/en/latest/netscript/netscriptmisc.html#netscript-ports
    * @param port - Port number. Must be an integer between 1 and 20.
-   * @returns Data in the specified port.
    */
-  getPortHandle(port: number): IPort;
+  getPortHandle(port: number): NetscriptPort;
 
   /**
    * Delete a file.
@@ -5548,7 +5631,7 @@ export interface NS extends Singularity {
    *
    * @param script - Filename of script. This is case-sensitive.
    * @param host - Host of target server the script is located on. This is optional, If it is not specified then the function will se the current server as the target server.
-   * @returns Amount of RAM required to run the specified script on the target server, and 0 if the script does not exist.
+   * @returns Amount of RAM (in GB) required to run the specified script on the target server, and 0 if the script does not exist.
    */
   getScriptRam(script: string, host?: string): number;
 

src/data/codingcontracttypes.ts

@@ -279,7 +279,7 @@ export const codingContractTypesMetadata: ICodingContractTypeMetadata[] = [
         "i to i+n.",
         "\n\nAssuming you are initially positioned",
         "at the start of the array, determine whether you are",
-        "able to reach the last index exactly.\n\n",
+        "able to reach the last index.\n\n",
         "Your answer should be submitted as 1 or 0, representing true and false respectively",
       ].join(" ");
     },