bitburner-official / bitburner-src

Bitburner source code.
Other
813 stars 270 forks source link

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

Open SansForSSBU opened 2 days ago

SansForSSBU commented 2 days ago

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:

For ns.weaken(), changes needed are:

For ns.grow(), changes needed are:

ficocelliguy commented 1 day ago

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 commented 17 hours ago

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:

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