Documentation for ns.hack(), ns.weaken() and ns.grow()

[SansForSSBU]

I'm referring to the NS API documentation, which is here: https://github.com/bitburner-official/bitburner-src/blob/stable/markdown/bitburner.ns.md

The documentation for ns.hack(), ns.weaken() and ns.grow() should include formulae for outcomes. I don't like that the documentation might only mention that "your hacking level and server security and some inherent factor of the server" play a role. It makes it difficult to anticipate problems with a hacking design you're thinking of which forces you to guess or tediously try to reverse engineer the formula yourself, and when things go wrong you don't have enough information to figure out why. It should also be clear in these formulae when each of these factors are checked (when the promise resolves, or when the function is called?)

Whilst getters such as getHackTime, getWeakenTime and getGrowTime exist, how these values are calculated is also something you need to know to design a good hacking system. You'll be asking questions like "what's the optimal way to grow a server to max money?" and without the formulae, you're going to have a hard time figuring that out because you can't easily figure out if two scripts with 50 threads each will be better than one with 100 threads. You can also be misled into thinking the getters factor in some inherent server factor.

For ns.hack(), changes needed are:

• Include formula for how much money will be stolen
• Convert the line "A successful hack() on a server will raise that server's security level by 0.002" to a formula to clarify whether this is per-thread or per-script.
• Include formula for how much hacking exp will be gained
• Include formula for how long it will take

For ns.weaken(), changes needed are:

• Convert line "This function lowers the security level of the target server by 0.05" to a formula which shows that the server will be weakened by 0.05 * number_of_threads
• Include formula for how much hacking exp will be gained
• Include formula for how long it will take

For ns.grow(), changes needed are:

• Include formula for the new server money after your operation completes
• Include formula for how much the server security will increase
• Include formula for how much hacking exp will be gained
• Include formula for how long it will take

[ficocelliguy]

A simpler and more on-brand change might be to include an example call to ns.hackAnalyze() in the docks for hack() (and similar for weaken and grow) so that players can calculate that themselves. (or maybe just a reference that hackAnalyze, weakenAnalyze, and growthAnalyze exist? and/or hackAnalyzeThreads etc?)

The actual formula for hack, grow, and weaken includes multiple spoilers that the player does not discover until they are out of the midgame and know The Truth, and it would be hard to communicate said formula while being cagey about those aspects.

The code is completely open, though, so players can absolutely look up those formulae and re-implement it in their script or whatnot if they wanted. Looking through the source code is encouraged in this game!

[catloversg]

I agree with ficocelliguy.

In most cases, I'm all for adding more documentation. Nonetheless, in this case, knowing the specific formulas is not as beneficial as you think:

• No access to endgame data. [1]
• Reimplementing those formulas is not an easy task. [2]
• Most (or all ?) relevant formulas have already been exposed via NS API. [3]

[1]
Most formulas include endgame data. If you don't have access to those data, knowing the formulas is useless.

[2]
Without the classic "copy+paste code" trick, reimplementing them is tricky. When you do that, you just increase your sources of bugs. You can take a look at the implementation of formulas.hacking.growThreads to see how complicated it is.

[3]
This is the most important reason. When you need more information to optimize your scripts, you need to ask "Which API do I need to call to get this information?", not "Which formula do I need to reimplement to get this information?".
This is a form of the XY problem. You need the information, not the formula calculating that information. We give the player that information via NS API:

• The description of an API (TSDoc) gives an overview of what that API does. It tells you what kind of thing matters. For example, the description of getHackTime tells you that you should focus on "the security level of the target server" and "the player's hacking level". Later on, if you want to "simulate" more situations, you can use formulas.hacking.hackTime. TSDoc is not always up-to-date or having enough information. If you find any problems in TSDoc (wrong information, lack of useful information, etc.), please report them.
• When you call an API, the returned value shows you what X will be if you do Y with Z. For example, getHackTime tells you the time it takes to hack a server without having to hack it.

[d0sboots]

In addition to what catlover said, I will add a comment about this:

It should also be clear in these formulae when each of these factors are checked (when the promise resolves, or when the function is called?)

The answer is "it's complicated." I know this stuff really well, and I still get parts of it wrong sometimes. Each of the functions (hack(), weaken() and grow()) has subtle differences between them, some that matter a lot, some that don't, and some that matter only in edge cases. I could write pages on these subtleties (and other people have), and in the end I (as a player) would not trust what anyone wrote about the matter (not even me) - I would go to the source. It is the only way to be sure for details as complicated as this.

This is both the benefit and curse of being an open-source game: We can say that the source is the ultimate answer, but it's a response that should be used sparingly.