Open SansForSSBU opened 2 days 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!
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:
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.getHackTime
tells you the time it takes to hack a server without having to hack it.
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: