Breaking changes in v3

[catloversg]

There are many breaking changes in v3.0.0. This issue documents all these changes. I'll update this issue when we merge new breaking changes.

@d0sboots Please pin this issue.

Manual Breaking Changes

The changes in this section will unfortunately require manual effort by you, if you are affected by them.

Remove API server (#2084)

You cannot use the deprecated VSCode extension to connect to the Steam app via API server now. You have to use Remote API to connect your external editors to Bitburner. For more information, please check the pinned message in #external-editors on Discord (https://discord.gg/TFc3hKD).

Remove fuzzy matching when checking params (#2091)

With some APIs, when you pass values to their params, you can pass a value that is not an exact match. For example, with ns.singularity.commitCrime, you can pass Rob Store, rob store, RobStore, robstore, robStore, etc. This is called "fuzzy matching". Now, you must pass an exact value (i.e., Rob Store). This change affects:

• Bladeburner action and type: BladeburnerActionType, BladeburnerGeneralActionName, BladeburnerContractName, BladeburnerOperationName, BladeburnerBlackOpName, SpecialBladeburnerActionTypeForSleeve, BladeburnerActionTypeForSleeve.
• Crime: CrimeType
• Faction work: FactionWorkType
• University class: UniversityClassType
• Gym stat: GymType
• Job field: JobField
• Stock position: PositionType
• Stock order: OrderType

You can access these values via ns.enums and Bladeburner APIs.

Remove long-deprecated support for running NS1 scripts (#2083)

You cannot run .script files now. Please convert them to .js (or .ts for TypeScript).
Instructions: https://github.com/bitburner-official/bitburner-src/blob/dev/src/Documentation/doc/en/migrations/ns2.md

Remove APIs that were deprecated a long time ago (#2088)

• ns.nFormat was removed. Use ns.format.number, ns.format.ram, ns.format.percent, or JS built-in objects/functions (e.g., Intl.NumberFormat, Intl.PluralRules, Intl.Locale) instead.

Enforce stricter param check on ns.getBitNodeMultipliers and ns.hacknet.spendHashes (#2085)

• ns.getBitNodeMultipliers: n and lvl must be positive integers.
• ns.hacknet.spendHashes: count must be a non-negative integer.

Nuke and port cracking APIs return false instead of throwing an error (#2153)

ns.nuke, ns.brutessh, ns.ftpcrack, ns.relaysmtp, ns.httpworm, and ns.sqlinject now do not throw an error when you do not have the required .exe file or enough opened ports.

This should not be a problem with most scripts. However, if you were catching errors and branching on the result of success/failure, you will need to use the return value instead.

Make ns.bladeburner.getActionRepGain return the expected reputation gain (#2186)

ns.bladeburner.getActionRepGain returned the average rank gain instead of the average reputation gain.
This bug was fixed. Please check your code to see if it still works as you expect.

Make some APIs throw error when server is invalid (#2261)

Some APIs returned a default value when you passed the hostname of a non-hackable server (e.g., hacknet server) to them. These APIs now throw an error. The affected APIs are:

• ns.hackAnalyzeThreads
• ns.hackAnalyze
• ns.hackAnalyzeSecurity
• ns.hackAnalyzeChance
• ns.growthAnalyze
• ns.growthAnalyzeSecurity
• ns.nuke
• ns.brutessh
• ns.ftpcrack
• ns.relaysmtp
• ns.httpworm
• ns.sqlinject
• ns.getServerMoneyAvailable
• ns.getServerSecurityLevel
• ns.getServerBaseSecurityLevel
• ns.getServerMinSecurityLevel
• ns.getServerRequiredHackingLevel
• ns.getServerMaxMoney
• ns.getServerGrowth
• ns.getServerNumPortsRequired
• ns.cloud.deleteServer
• ns.getHackTime
• ns.getGrowTime
• ns.getWeakenTime

Make TIX access independent from WSE account (#2342)

You have to purchase a WSE account before purchasing 4S Market Data UI access via ns.stock.purchase4SMarketData().
Note that this change does not affect 4S Market Data TIX API access (ns.stock.purchase4SMarketDataTixApi()).

ns.codingcontract.createDummyContract may return null (#2399)

ns.codingcontract.createDummyContract might generate a contract with the same name of another contract.
This bug was fixed. Now this function will return null and not generate a contract if the randomized contract name is the same as another contract's name.

Make ns.go.analysis methods evaluate the given board as-is (#2415)

ns.go.analysis methods no longer apply captures to custom board states passed to them, and instead evaluate the given board exactly as-is.

Darkweb is darknet server (#2139)

We added a new feature called Dark Net. The "darkweb" server is a darknet server now.
Some APIs that require the target host to be a normal server do not work with darkweb. This should not be a problem with most scripts. The most potentially affected API is ns.scan(). Darkweb does not appear in the result of this API anymore. If you want to find darknet servers, you need to use ns.dnet.probe().

Remove RAM cost of hacknet namespace and set RAM cost of each hacknet API (#2502)

Accessing the hacknet namespace incurred a one-time cost of 4 GB of RAM, and each hacknet API did not incur
RAM cost. Now the hacknet namespace does not incur RAM cost, but each hacknet API incurs a 0.5GB RAM cost.

Cancel sleeve's current task when calling ns.sleeve.travel() (#2559)

ns.sleeve.travel() did not cancel the sleeve's current task. It does now.

Make ns.cloud.purchaseServer() and ns.cloud.deleteServer() use hostname as provided (#2560)

ns.cloud.purchaseServer() and ns.cloud.deleteServer() previously removed whitespace from the provided hostname inconsistently.
They now use the hostname as provided.

Make implicit string conversion consistent across all coding contracts (#2608)

If you pass a string to ns.codingcontract.attempt() for contracts that require a non-string answer, the game will convert that string to the expected format. This string conversion was inconsistent and had many undocumented behaviors.

Now the rules are consistent and well-documented. Please check the "Coding Contracts" page for more information.
There are 7 contracts that are affected by this change:

• Find All Valid Math Expressions
• Generate IP Addresses
• Largest Rectangle in a Matrix
• Merge Overlapping Intervals
• Proper 2-Coloring of a Graph
• Sanitize Parentheses in Expression
• Spiralize Matrix

Note that this change only affects the string conversion. The solution format of these contracts is an array, so if you pass the solution, which is an array, as is, you will not have any problems.

If your code converts the array to a string, you should check these contracts, especially the "Sanitize Parentheses in Expression" contract and others that require a string array.

• Sanitize Parentheses in Expression: Previously, if you passed an empty string to this contract, it was converted to an array containing an empty string. Now, it's converted to an empty array.
• Read the "General rules", "String conversion", and "Tips" sections on the "Coding Contracts" page carefully.

Auto-migrations

These changes will be automatically migrated for you, but there may be spots that the automation misses, so it is good to be aware of them:

Remove APIs that were deprecated a long time ago (#2088)

• ns.getTimeSinceLastAug was removed. Use (Date.now() - ns.getResetInfo().lastAugReset) instead.
• ns.getPlayer().playtimeSinceLastAug was removed. Use (Date.now() - ns.getResetInfo().lastAugReset) instead.
• ns.getPlayer().playtimeSinceLastBitnode was removed. Use (Date.now() - ns.getResetInfo().lastNodeReset) instead.
• ns.getPlayer().bitNodeN was removed. Use ns.getResetInfo().currentNode instead.
• ns.corporation.getCorporation().state was removed. Use ns.corporation.getCorporation().nextState instead.

Moved formatting functions to their own interface (#1635)

• ns.formatNumber was removed. Use ns.format.number instead.
• ns.formatRam was removed. Use ns.format.ram instead.
• ns.formatPercent was removed. Use ns.format.percent instead.
• ns.tFormat was removed. Use ns.format.time instead.

Remove deprecated tail-related APIs (#2143)

• ns.tail was removed. Use ns.ui.openTail instead.
• ns.moveTail was removed. Use ns.ui.moveTail instead.
• ns.resizeTail was removed. Use ns.ui.resizeTail instead.
• ns.closeTail was removed. Use ns.ui.closeTail instead.
• ns.setTitle was removed. Use ns.ui.setTailTitle instead.

Rename setAutoJobAssignment API to setJobAssignment (#2146)

• ns.corporation.setAutoJobAssignment was removed. Use ns.corporation.setJobAssignment instead.

Standardize names of Stock APIs (#2173)

• ns.stock.getConstants().WSEAccountCost was removed. Use ns.stock.getConstants().WseAccountCost instead.
• ns.stock.getConstants().TIXAPICost was removed. Use ns.stock.getConstants().TixApiCost instead.
• ns.stock.hasWSEAccount was removed. Use ns.stock.hasWseAccount instead.
• ns.stock.hasTIXAPIAccess was removed. Use ns.stock.hasTixApiAccess instead.
• ns.stock.has4SDataTIXAPI was removed. Use ns.stock.has4SDataTixApi instead.

Rename BN multiplier RepToDonateToFaction to FavorToDonateToFaction (#2178)

• ns.getBitNodeMultipliers().RepToDonateToFaction was removed. Use ns.getBitNodeMultipliers().FavorToDonateToFaction instead.

Rename the key of "Bachman & Associates" faction in the FactionName enum (#2183)

• ns.enums.FactionName.BachmanAssociates was removed. Use ns.enums.FactionName.BachmanAndAssociates instead.

Corporation: Remove the DreamSense upgrade (#2232)

Corporation: Rename dividendTax to tributeModifier (#2237)

• ns.corporation.getCorporation().dividendTax was removed. Use ns.corporation.getCorporation().tributeModifier instead.

Corporation: Remove the Spring Water industry (#2240)

Corporation: Remove the VeChain upgrade (#2245)

Gang: Rename equipment that uses real brand names (#2293)

Many gang's equipments were renamed.

• "Glock 18C" was renamed to "Malorian-3516".
• "P90C" was renamed to "Hansen-HA7".
• "Steyr AUG" was renamed to "Arasaka-HJSH18".
• "AK-47" was renamed to "Militech-M251s".
• "M15A10 Assault Rifle" was renamed to "Nokota-D5".
• "AWM Sniper Rifle" was renamed to "Techtronika-SPT32".
• "Ford Flex V20" was renamed to "Herrera Outlaw GTS".
• "ATX1070 Superbike" was renamed to "Yaiba ASM-R250 Muramasa".
• "Mercedes-Benz S9001" was renamed to "Rayfield Caliburn".
• "White Ferrari" was renamed to "Quadra Sport R-7".

Move and rename purchased server functions (#2367)

The cloud server (purchased server) functions have been moved to their own interface, ns.cloud.

• ns.getPurchasedServerCost() was removed. Use ns.cloud.getServerCost() instead.
• ns.purchaseServer() was removed. Use ns.cloud.purchaseServer() instead.
• ns.getPurchasedServerUpgradeCost() was removed. Use ns.cloud.getServerUpgradeCost() instead.
• ns.upgradePurchasedServer() was removed. Use ns.cloud.upgradeServer() instead.
• ns.renamePurchasedServer() was removed. Use ns.cloud.renameServer() instead.
• ns.deleteServer() was removed. Use ns.cloud.deleteServer() instead.
• ns.getPurchasedServers() was removed. Use ns.cloud.getServerNames() instead.
• ns.getPurchasedServerLimit() was removed. Use ns.cloud.getServerLimit() instead.
• ns.getPurchasedServerMaxRam() was removed. Use ns.cloud.getRamLimit() instead.

ns.getBitNodeMultipliers() Purchased Server properties have been renamed to CloudServers with the creation of the cloud API.

• ns.getBitNodeMultipliers().PurchasedServerCost was removed. Use ns.getBitNodeMultipliers().CloudServerCost instead.
• ns.getBitNodeMultipliers().PurchasedServerSoftcap was removed. Use ns.getBitNodeMultipliers().CloudServerSoftcap instead.
• ns.getBitNodeMultipliers().PurchasedServerLimit was removed. Use ns.getBitNodeMultipliers().CloudServerLimit instead.
• ns.getBitNodeMultipliers().PurchasedServerMaxRam was removed. Use ns.getBitNodeMultipliers().CloudServerMaxRam instead.

ns.codingcontract.createDummyContract generates a contract on the current server instead of home (#2417)

ns.codingcontract.createDummyContract generated a dummy contract on home. Now you can specify the host that gets the generated contract with a new optional parameter. Your code was migrated to specify "home" as the host.

Rename ns.gang.getOtherGangInformation to getAllGangInformation (#2635)

ns.gang.getOtherGangInformation() was renamed to ns.gang.getAllGangInformation().
The function was renamed because it returns information about all gangs, including the player's own gang.

Standardize "nextCompletion" promise in tasks (#2687)

Task objects returned from ns.singularity.getCurrentWork() and ns.sleeve.getTask() previously had an optional promise property named either "completion" or "nextCompletion", depending on the task.
Now, these task objects always include this property, and it is consistently named "nextCompletion".

Rename ns.dnet.getServerAuthDetails and deprecate dnet-only properties in ns.getServer (#2746)

ns.dnet.getServerAuthDetails was renamed to ns.dnet.getServerDetails.
Dnet-only properties in ns.getServer were deprecated. Use ns.dnet.getServerDetails to retrieve them instead.

[d0sboots]

I reordered some of the sections based on (my perceived) importance/likelihood that people will trip over them. In particular, all the purely auto-migrated ones are at the bottom and in their own section.

[CrafterKolyan]

Should we also rework autocomplete() function to implement e.g. suggestion from

• script autocomplete only works in really simple cases #522

where arguments that are passed in case of:
Terminal (| shows where the cursor is):

./foo.js n00dles |

are

["n00dles", ""]

[d0sboots]

I don't think there's any fundamental issues with that, but let's discuss details on specific issues and keep this for detailing the breaking changes.

[gmcew]

@catloversg with 3.0.0 and 3.0.1 now in stable - is it ok to close this? If we start another pile of breaking changes it expect we'd open a standalone v4 issue at this stage.

[catloversg]

Let's keep it open a bit longer. Technically, we may still make some breaking changes. I'll close this after v3.0.2 or v3.1.0.

[d0sboots]

Yeah, since this is pinned I'd like to keep this open for at least a month after the release.

[lucy9tran]

Regarding Nuke and port cracking APIs return false instead of throwing an error #2153:

Could Getting Started Guide for Beginner early-hack-template.js be updated to reflect this breaking change?
Right now the script contains a check for file existence, before running port cracking API.

if (ns.fileExists("BruteSSH.exe", "home")) {
  ns.brutessh(target);
}

[catloversg]

In terms of logic, performing that check is actually the "correct" way. Skipping the check now or wrapping code inside a try-catch block in the past are tricks that depend on the specific behavior of ns.brutessh. Using those tricks reduces RAM usage, but the basic guide does not need to be optimized for RAM usage.