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.

[SansForSSBU]

[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:

I agree that it's bad practice for a user to re-invent the wheel and reimplement these formulae themselves. The reason I think they should be documented is because knowing whether thing X scales linearly, exponentially, logarithmically etc with thing Y is important information which fundamentally changes what the best way to allocate resources is, so players need to know that information. I didn't want to upgrade cores in my playthrough because I couldn't find out whether their effects are linear, exponential or logarithmic and so didn't know how to account for them in my system, and I also really wanted to confirm with threads that it was all linear but couldn't find the documentation saying this.

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

I can see why this is a problem for spoilers, but at least for why I wanted to know the formulae it's not an issue. If endgame data is multipliers put on top of the base results, I think it would be fine to provide the formula without these as a formula for BASE hacking XP, money, weakening, etc... If it's far more complicated, maybe including formulae is not really possible.

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.

Yes, this is the main reason I think this should be documented. When someone has to reverse-engineer something to find a piece of information a user would commonly want to know, I think that means the documentation has failed. I don't think having to dig through the source code is a fun challenge we should be making the player do.

[ficocelliguy]

knowing whether thing X scales linearly, exponentially, logarithmically

It looks like that is already mentioned in the documentation, for the places I'm skimming, but if you find places where it is not that would be useful to add.
e.g. https://github.com/bitburner-official/bitburner-src/blob/dev/markdown/bitburner.ns.grow.md

I don't think having to dig through the source code is a fun challenge we should be making the player do

That's an explicit part of the game design in a number of mechanics, including casino rng and all of the SF -1 achievements. [It's also a highly applicable real-world skill]. That being said, it's not required for any of the main game mechanics. It's probably faster to make some quick test scripts that e.g. check what grow does with different numbers of threads than it is to dig through the source.

[datner]

I also want to add that much more than a coding exercise, this is still a game, if you wanted to 'solve' it then just look for scripts other people wrote and copy-pasta the best of them. A lot of the fun is working with the hidden unknown subtleties of the system and its methods, creating something simple, reaching a limit or desiring to improve, and iterating on the solution. The discovery and hypothesizing of arcane 3rd party libs is usually the most soul-sucking part of programming because its a hindrance to doing your job, here it's part of the immersion. What does .hack() do? It breaches the server and steals their money ofc! Being a 1337h4X0r prodigy, you can just do that.
Demystifying that abstraction would be a bit of a cognitive dissonance IMHO, the game being like

Hack runs this bit of arbitrary math [math], with sufficiently large (or numerous) results of the aforementioned you will be permitted to increment one of the exponents by some decimal amount. This is generally desirable over incrementing the linear variables.

Is just not as fun 😄
I also find that keeping the illusion makes finding patterns and optimizing that much more fun as it feels like you're optimizing stealing money, spoofing funds, and installing backdoors rather than playing a more tedious and dramatically less streamlined exponential idle with a black/green retro-future skin

[nanogyth]

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

hack_time_in_seconds =
    (50 + 0.25 * requiredHackingSkill * difficulty)
    / (1 + 0.02 * hack_level)
    * multipliers

If multipliers is the only unknown, you can solve for it.