BLADEBURNER: Add APIs to get rank gain and rank loss of an action (#2572)

markdown/bitburner.bladeburner.getactionrankgain.md

@@ -0,0 +1,94 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [bitburner](./bitburner.md) &gt; [Bladeburner](./bitburner.bladeburner.md) &gt; [getActionRankGain](./bitburner.bladeburner.getactionrankgain.md)
+
+## Bladeburner.getActionRankGain() method
+
+Get the rank gain of an action.
+
+**Signature:**
+
+```typescript
+getActionRankGain(type: BladeburnerActionType, name: BladeburnerActionName, level?: number): number;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+type
+
+
+</td><td>
+
+[BladeburnerActionType](./bitburner.bladeburneractiontype.md)
+
+
+</td><td>
+
+Type of action.
+
+
+</td></tr>
+<tr><td>
+
+name
+
+
+</td><td>
+
+[BladeburnerActionName](./bitburner.bladeburneractionname.md)
+
+
+</td><td>
+
+Name of action. Must be an exact match.
+
+
+</td></tr>
+<tr><td>
+
+level
+
+
+</td><td>
+
+number
+
+
+</td><td>
+
+_(Optional)_ Optional. Action level at which to calculate the gain. Defaults to the action's current level if not specified.
+
+
+</td></tr>
+</tbody></table>
+
+**Returns:**
+
+number
+
+Average rank gain for successfully completing the specified action.
+
+## Remarks
+
+RAM cost: 4 GB
+
+Returns the average rank gain for successfully completing the specified action. Note that this value is an "average" and the actual rank gain may vary slightly from this value.
+

markdown/bitburner.bladeburner.getactionrankloss.md

@@ -0,0 +1,94 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [bitburner](./bitburner.md) &gt; [Bladeburner](./bitburner.bladeburner.md) &gt; [getActionRankLoss](./bitburner.bladeburner.getactionrankloss.md)
+
+## Bladeburner.getActionRankLoss() method
+
+Get the rank loss of an action.
+
+**Signature:**
+
+```typescript
+getActionRankLoss(type: BladeburnerActionType, name: BladeburnerActionName, level?: number): number;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+type
+
+
+</td><td>
+
+[BladeburnerActionType](./bitburner.bladeburneractiontype.md)
+
+
+</td><td>
+
+Type of action.
+
+
+</td></tr>
+<tr><td>
+
+name
+
+
+</td><td>
+
+[BladeburnerActionName](./bitburner.bladeburneractionname.md)
+
+
+</td><td>
+
+Name of action. Must be an exact match.
+
+
+</td></tr>
+<tr><td>
+
+level
+
+
+</td><td>
+
+number
+
+
+</td><td>
+
+_(Optional)_ Optional. Action level at which to calculate the loss. Defaults to the action's current level if not specified.
+
+
+</td></tr>
+</tbody></table>
+
+**Returns:**
+
+number
+
+Average rank loss for failing to complete the specified action.
+
+## Remarks
+
+RAM cost: 4 GB
+
+Returns the average rank loss for failing to complete the specified action. Note that this value is an "average" and the actual rank loss may vary slightly from this value.
+

markdown/bitburner.bladeburner.getactionrepgain.md

@@ -74,7 +74,7 @@ number
 
 </td><td>
 
-_(Optional)_ Optional number. Action level at which to calculate the gain. Will be the action's current level if not given.
+_(Optional)_ Optional. Action level at which to calculate the gain. Defaults to the action's current level if not specified.
 
 
 </td></tr>
@@ -84,11 +84,11 @@ _(Optional)_ Optional number. Action level at which to calculate the gain. Will
 
 number
 
-Average Bladeburner reputation gain for successfully completing the specified action.
+Average reputation gain for successfully completing the specified action.
 
 ## Remarks
 
 RAM cost: 4 GB
 
-Returns the average Bladeburner reputation gain for successfully completing the specified action. Note that this value is an ‘average’ and the real reputation gain may vary slightly from this value.
+Returns the average reputation gain for successfully completing the specified action. Note that this value is an "average" and the actual reputation gain may vary slightly from this value.
 

markdown/bitburner.bladeburner.md

@@ -94,6 +94,28 @@ Get estimate success chance of an action.
 Get the maximum level of an action.
 
 
+</td></tr>
+<tr><td>
+
+[getActionRankGain(type, name, level)](./bitburner.bladeburner.getactionrankgain.md)
+
+
+</td><td>
+
+Get the rank gain of an action.
+
+
+</td></tr>
+<tr><td>
+
+[getActionRankLoss(type, name, level)](./bitburner.bladeburner.getactionrankloss.md)
+
+
+</td><td>
+
+Get the rank loss of an action.
+
+
 </td></tr>
 <tr><td>
 

src/Bladeburner/Bladeburner.ts

@@ -55,7 +55,7 @@ import { assertObject } from "../utils/TypeAssertion";
 import { throwIfReachable } from "../utils/helpers/throwIfReachable";
 import { loadActionIdentifier } from "./utils/loadActionIdentifier";
 import { pluralize } from "../utils/I18nUtils";
-import { calculateActionRankGain, calculateActionReputationGain } from "./Formulas";
+import { calculateActionRankGain, calculateActionRankLoss, calculateActionReputationGain } from "./Formulas";
 import { processWorkStats } from "../Work/Formulas";
 
 export const BladeburnerPromise: PromisePair<number> = { promise: null, resolve: null };
@@ -941,7 +941,7 @@ export class Bladeburner implements OperationTeam {
             let loss = 0,
               damage = 0;
             if (action.rankLoss) {
-              loss = addOffset(action.rankLoss * rewardMultiplier, 10);
+              loss = addOffset(calculateActionRankLoss(action), 10);
               this.changeRank(person, -1 * loss);
             }
             if (action.hpLoss) {
@@ -1019,7 +1019,7 @@ export class Bladeburner implements OperationTeam {
           let rankLoss = 0;
           let damage = 0;
           if (action.rankLoss) {
-            rankLoss = addOffset(action.rankLoss, 10);
+            rankLoss = addOffset(calculateActionRankLoss(action), 10);
             this.changeRank(person, -1 * rankLoss);
           }
           if (action.hpLoss) {

src/Bladeburner/Formulas.ts

@@ -27,6 +27,22 @@ export function calculateActionRankGain(action: Action, level?: number): number
   return 0;
 }
 
+export function calculateActionRankLoss(action: Action, level?: number): number {
+  switch (action.type) {
+    case BladeburnerActionType.Contract:
+    case BladeburnerActionType.Operation: {
+      if (level == null) {
+        level = action.level;
+      }
+      const rewardMultiplier = Math.pow(action.rewardFac, level - 1);
+      return action.rankLoss * rewardMultiplier;
+    }
+    case BladeburnerActionType.BlackOp:
+      return action.rankLoss;
+  }
+  return 0;
+}
+
 export function calculateActionReputationGain(person: Person, rankGain: number): number {
   const favorBonus = 1 + Factions[FactionName.Bladeburners].favor / 100;
   return BladeburnerConstants.RankToFactionRepFactor * rankGain * person.mults.faction_rep * favorBonus;

src/Documentation/pages.ts

@@ -169,6 +169,8 @@ import nsDoc_bitburner_bladeburner_getactioncurrentlevel_md from "../../markdown
 import nsDoc_bitburner_bladeburner_getactioncurrenttime_md from "../../markdown/bitburner.bladeburner.getactioncurrenttime.md?raw";
 import nsDoc_bitburner_bladeburner_getactionestimatedsuccesschance_md from "../../markdown/bitburner.bladeburner.getactionestimatedsuccesschance.md?raw";
 import nsDoc_bitburner_bladeburner_getactionmaxlevel_md from "../../markdown/bitburner.bladeburner.getactionmaxlevel.md?raw";
+import nsDoc_bitburner_bladeburner_getactionrankgain_md from "../../markdown/bitburner.bladeburner.getactionrankgain.md?raw";
+import nsDoc_bitburner_bladeburner_getactionrankloss_md from "../../markdown/bitburner.bladeburner.getactionrankloss.md?raw";
 import nsDoc_bitburner_bladeburner_getactionrepgain_md from "../../markdown/bitburner.bladeburner.getactionrepgain.md?raw";
 import nsDoc_bitburner_bladeburner_getactionsuccesses_md from "../../markdown/bitburner.bladeburner.getactionsuccesses.md?raw";
 import nsDoc_bitburner_bladeburner_getactiontime_md from "../../markdown/bitburner.bladeburner.getactiontime.md?raw";
@@ -1762,6 +1764,8 @@ AllPages["nsDoc/bitburner.bladeburner.getactioncurrentlevel.md"] = nsDoc_bitburn
 AllPages["nsDoc/bitburner.bladeburner.getactioncurrenttime.md"] = nsDoc_bitburner_bladeburner_getactioncurrenttime_md;
 AllPages["nsDoc/bitburner.bladeburner.getactionestimatedsuccesschance.md"] = nsDoc_bitburner_bladeburner_getactionestimatedsuccesschance_md;
 AllPages["nsDoc/bitburner.bladeburner.getactionmaxlevel.md"] = nsDoc_bitburner_bladeburner_getactionmaxlevel_md;
+AllPages["nsDoc/bitburner.bladeburner.getactionrankgain.md"] = nsDoc_bitburner_bladeburner_getactionrankgain_md;
+AllPages["nsDoc/bitburner.bladeburner.getactionrankloss.md"] = nsDoc_bitburner_bladeburner_getactionrankloss_md;
 AllPages["nsDoc/bitburner.bladeburner.getactionrepgain.md"] = nsDoc_bitburner_bladeburner_getactionrepgain_md;
 AllPages["nsDoc/bitburner.bladeburner.getactionsuccesses.md"] = nsDoc_bitburner_bladeburner_getactionsuccesses_md;
 AllPages["nsDoc/bitburner.bladeburner.getactiontime.md"] = nsDoc_bitburner_bladeburner_getactiontime_md;

src/Netscript/RamCostGenerator.ts

@@ -349,6 +349,8 @@ const bladeburner = {
   getActionCurrentTime: RamCostConstants.BladeburnerApiBase,
   getActionEstimatedSuccessChance: RamCostConstants.BladeburnerApiBase,
   getActionRepGain: RamCostConstants.BladeburnerApiBase,
+  getActionRankGain: RamCostConstants.BladeburnerApiBase,
+  getActionRankLoss: RamCostConstants.BladeburnerApiBase,
   getActionCountRemaining: RamCostConstants.BladeburnerApiBase,
   getActionMaxLevel: RamCostConstants.BladeburnerApiBase,
   getActionCurrentLevel: RamCostConstants.BladeburnerApiBase,

src/NetscriptFunctions/Bladeburner.ts

@@ -19,7 +19,11 @@ import { assertStringWithNSContext } from "../Netscript/TypeAssertion";
 import { BlackOperations, blackOpsArray } from "../Bladeburner/data/BlackOperations";
 import { checkSleeveAPIAccess, checkSleeveNumber } from "../NetscriptFunctions/Sleeve";
 import { canAccessBitNodeFeature } from "../BitNode/BitNodeUtils";
-import { calculateActionRankGain, calculateActionReputationGain } from "../Bladeburner/Formulas";
+import {
+  calculateActionRankGain,
+  calculateActionRankLoss,
+  calculateActionReputationGain,
+} from "../Bladeburner/Formulas";
 import { CONSTANTS } from "../Constants";
 
 export function NetscriptBladeburner(): InternalAPI<INetscriptBladeburner> {
@@ -156,6 +160,18 @@ export function NetscriptBladeburner(): InternalAPI<INetscriptBladeburner> {
       const rankGain = calculateActionRankGain(action, level);
       return calculateActionReputationGain(Player, rankGain);
     },
+    getActionRankGain: (ctx) => (type, name, _level) => {
+      checkBladeburnerAccess(ctx);
+      const action = getAction(ctx, type, name);
+      const level = isLevelableAction(action) ? helpers.number(ctx, "level", _level ?? action.level) : 1;
+      return calculateActionRankGain(action, level);
+    },
+    getActionRankLoss: (ctx) => (type, name, _level) => {
+      checkBladeburnerAccess(ctx);
+      const action = getAction(ctx, type, name);
+      const level = isLevelableAction(action) ? helpers.number(ctx, "level", _level ?? action.level) : 1;
+      return calculateActionRankLoss(action, level);
+    },
     getActionCountRemaining: (ctx) => (type, name) => {
       const bladeburner = getBladeburner(ctx);
       const action = getAction(ctx, type, name);

src/ScriptEditor/NetscriptDefinitions.d.ts

@@ -3564,17 +3564,46 @@ export interface Bladeburner {
    * @remarks
    * RAM cost: 4 GB
    *
-   * Returns the average Bladeburner reputation gain for successfully
-   * completing the specified action.
-   * Note that this value is an ‘average’ and the real reputation gain may vary slightly from this value.
+   * Returns the average reputation gain for successfully completing the specified action.
+   * Note that this value is an "average" and the actual reputation gain may vary slightly from this value.
    *
    * @param type - Type of action.
    * @param name - Name of action. Must be an exact match.
-   * @param level - Optional number. Action level at which to calculate the gain. Will be the action's current level if not given.
-   * @returns Average Bladeburner reputation gain for successfully completing the specified action.
+   * @param level - Optional. Action level at which to calculate the gain. Defaults to the action's current level if not specified.
+   * @returns Average reputation gain for successfully completing the specified action.
    */
   getActionRepGain(type: BladeburnerActionType, name: BladeburnerActionName, level?: number): number;
 
+  /**
+   * Get the rank gain of an action.
+   * @remarks
+   * RAM cost: 4 GB
+   *
+   * Returns the average rank gain for successfully completing the specified action.
+   * Note that this value is an "average" and the actual rank gain may vary slightly from this value.
+   *
+   * @param type - Type of action.
+   * @param name - Name of action. Must be an exact match.
+   * @param level - Optional. Action level at which to calculate the gain. Defaults to the action's current level if not specified.
+   * @returns Average rank gain for successfully completing the specified action.
+   */
+  getActionRankGain(type: BladeburnerActionType, name: BladeburnerActionName, level?: number): number;
+
+  /**
+   * Get the rank loss of an action.
+   * @remarks
+   * RAM cost: 4 GB
+   *
+   * Returns the average rank loss for failing to complete the specified action.
+   * Note that this value is an "average" and the actual rank loss may vary slightly from this value.
+   *
+   * @param type - Type of action.
+   * @param name - Name of action. Must be an exact match.
+   * @param level - Optional. Action level at which to calculate the loss. Defaults to the action's current level if not specified.
+   * @returns Average rank loss for failing to complete the specified action.
+   */
+  getActionRankLoss(type: BladeburnerActionType, name: BladeburnerActionName, level?: number): number;
+
   /**
    * Get action count remaining.
    * @remarks