felixfoertsch/bitburner-src
1
0
Fork 0
mirror of https://github.com/bitburner-official/bitburner-src.git synced 2026-04-21 08:42:53 +02:00
Code Issues Packages Projects Releases Wiki Activity

DOCUMENTATION: Better npm run doc, plus minor folder reorganization (#693)

Browse Source
This commit is contained in:
Snarling
2023-08-01 00:59:33 -04:00
committed by GitHub
parent e624db5238
commit 83b7c380ff
44 changed files with 40 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/Documentation/doc/programming/game_frozen.md
+61
View File
@@ -0,0 +1,61 @@
# Game Frozen or Stuck?
## Infinite Loop in Scripts
If your game is frozen or stuck in any way, then the most likely culprit is an infinitely running loop in your script.
To get past the freezing, run the game with `?noScripts` in the URL:
[Link to no freeze](https://bitburner-official.github.io?noScripts)
Then, to fix your script, make sure you have a `sleep()` or any other timed function like `hack()` or `grow()` in any infinite loops:
while(true) {
// This is an infinite loop that does something
...
await ns.sleep(1000); // Add a 1s sleep to prevent freezing
}
Also make sure that each while loop gets to the `await`ed function or `break`, for example the next snippet has a `sleep()` function, but it nor any possible conditional breaks are never reached and therefore will crash the game:
while(true) {
let currentMoney = ns.getServerMoneyAvailable("n00dles");
let maxMoney = ns.getServerMaxMoney("n00dles");
if (currentMoney < maxMoney/2){
await ns.grow("n00dles");
}
if (currentMoney === maxMoney){
break;
}
}
If `n00dles` current money is, for example, 75% of the maximum money, the script will reach neither `grow()` nor `break` and the game will crash.
Adding a sleep like in the first example, or changing the code so that the `awaited` function or `break` is always reached, would prevent the crash.
Common infinite loop when translating the server purchasing script in starting guide to scripts is to have a while loop, where the condition's change is conditional:
var ram = 8;
var i = 0;
while (i < ns.getPurchasedServerLimit()) {
if (ns.getServerMoneyAvailable("home") > ns.getPurchasedServerCost(ram)) {
var hostname = ns.purchaseServer("pserv-" + i, ram);
ns.scp("early-hack-template.script", hostname);
ns.exec("early-hack-template.script", hostname, 3);
++i;
}
}
If the player does not currently have enough money to purchase a server, the `if`'s condition will be false and `++i` will not be reached.
Since the script doesn't have `sleep()` and value `i` will not change without the `if` being true, this will crash the game.
Adding a `sleep()` that is always reached would prevent the crash.
## Blackscreen
If the game window becomes a black screen without the game itself crashing, this is caused by the game running too many concurrent scripts (the game runs on a browser and each tab can only use so much ram until it crashes).
Depending on which scripts are running and your hardware, this number can vary between 50000 to 100000 instances (in version 2.0.2. In prior versions this number was about 1/5th of that).
To prevent this from happening make sure to multithread the scripts as much as possible.
## Bug
Otherwise, the game is probably frozen/stuck due to a bug.
To report a bug, follow the guidelines [here](https://github.com/bitburner-official/bitburner-src/blob/master/doc/CONTRIBUTING.md#reporting-bugs).
src/Documentation/doc/programming/hackingalgorithms.md
+131
View File
@@ -0,0 +1,131 @@
# Hacking algorithms
There are three primary families of hacking algorithms.
This guide will go over each of them and advise on how they can be implemented.
## Self-contained algorithms
**Difficulty**: Easy
Pros:
- Easy to implement
- Does not require other scripts to work
- Works at any stage of the game
Cons:
- Limits income generation
- Extremely [RAM](../basic/ram.md) inefficient
- Utilizes script online time poorly
- Risk of over hacking
Self-contained algorithms are the simplest family of hacking algorithms to implement.
Each script is tasked with choosing which function to execute based on the status of the target server.
Because of this, they guarantee a consistent, but relatively small, flow of money.
The general logic goes like this:
loop forever {
if security is not minimum {
await ns.weaken(target)
} else if money is not maximum {
await ns.grow(target)
} else {
await ns.hack(target)
}
}
This algorithm is perfectly capable of paving the way through the majority of the game, but it has a few significant issues.
- It tends to make all your scripts on every server do the same thing.
(e.g. If the target is 0.01 security above the minimum, all scripts will decide to weaken, when only a handful of threads should be devoted to the task)
- At higher thread counts, these scripts have the potential to hack the server to $0, or maximum security, requiring a long setup time while the scripts return the server to the best stats.
- Requires function calls such as `getServerSecurityLevel` and `getServerMoneyAvailable`, as well as calling all three hacking functions, increasing RAM cost which is multiplied by the number of allocated threads
## Loop algorithms
**Difficulty**: Easy to Medium
Pros:
- Simple to understand
- Works at any stage of the game
- Maximize RAM usage
Cons:
- Requires a script that handles deployment
By splitting our hack, weaken, and grow functions into three separate scripts, we can both remove our reliance on functions such as `getServerSecurityLevel` as well as removing functions that cannot work concurrently, reducing RAM requirements, and thus increasing our thread limits.
Loop scripts are formatted like this:
loop forever {
await ns.hack(target) // or grow, or weaken
}
Now we can take the total amount of threads available and split it and allocate, for example:
- 1 part to the hack scripts
- 10 parts to the grow scripts
- 2 parts to the weaken scripts
Meaning if we have space for 100 threads across the entire network 7 threads will go to the hack scripts, 76 threads will go to the grow scripts and 15 threads will go to the weaken scripts.
The ratios described here are arbitrary and can be greatly improved through the use of the analyze functions, and later, through the use of Formulas.exe.
When utilizing this strategy, monitor the amount of money and security on the target server, if the money is not hovering around maximum and the security around the minimum, the ratios should be tweaked until that is the case.
Utilizing `sleep` or `asleep` to ensure that your scripts do not all start at the same time can decrease the chance of issues associated with overhacking occurring.
Both functions have a ram cost of zero.
## Batch algorithms (HGW, HWGW, or Cycles)
**Difficulty**: Hard
Pros:
- Maximum potential income
Cons:
- Very difficult to implement without prior programming knowledge
- Very difficult to make work on servers with less than 1TB of RAM
Batch algorithms utilize a master script that uses `exec` many scripts which utilize a relevant hacking function in batches.
The scripts used to execute the hacking functions are even simpler than the previous algorithms but a complex controller is required to calculate the effect, time taken, and the necessary delay.
await ns.sleep(a bit)
await ns.hack(target) // or grow, or weaken
A few things need to be known before this algorithm can be implemented:
- The effects of hack and grow depend on the server security level, a higher security level results in a reduced effect.
You only want these effects to occur when the security level is minimized.
- The time taken to execute hack, grow, or weaken is determined when the function is called and is based on the security level of the target server and your hacking level.
You only want these effects to start when the security level is minimized.
- The effects of hack, grow, and weaken, are determined when the time is completed, rather than at the beginning.
Hack should finish when security is minimum and money is maximum.
Grow should finish when security is minimum, shortly after a hack occurred.
Weaken should occur when security is not at a minimum due to a hack or grow increasing it.
A single batch consists of four actions:
1. A hack script removes a predefined, precalculated amount of money from the target server.
2. A weaken script counters the security increase of the hack script.
3. A grow script counters the money decrease caused by the hack script.
4. A weaken script counters the security increase caused by the grow script.
It is also important that these 4 scripts finish in the order specified above, and all of their effects be precalculated to optimize the ratios between them.
This is the reason for the delay in the scripts.
|= hack ====================|
|=weaken 1======================================|
|= grow ==========================|
|=weaken 2======================================|
Batches only function predictably when the target server is at minimum security and maximum money, so your script must also handle preparing a server for your batches.
You can utilize batches to prepare a server by using no hack threads during preparation.
Depending on your computer's performance as well as a few other factors, the necessary delay between script execution times may range between 20ms and 200ms, you want to fine-tune this value to be as low as possible while also avoiding your scripts finishing out of order.
Anything lower than 20ms will not work due to JavaScript limitations.
src/Documentation/doc/programming/learn.md
+35
View File
@@ -0,0 +1,35 @@
# Learn to Program in JavaScript
## For Beginner Programmers
If you have little to no programming experience, that's okay!
You don't need to be a great programmer in order to enjoy or play this game.
In fact, this game could help you learn some basic programming concepts.
Here are some good tutorials for learning programming/JavaScript as a beginner:
- [Learn-JS](http://www.learn-js.org/en/Welcome)
- [programiz](https://www.programiz.com/javascript/get-started)
- [Speaking JavaScript](https://exploringjs.com/es5/)
This is a bit on the longer side.
You can skip all of the historical background stuff.
Recommended chapters: 1, 7-18
## For Experienced Programmers
The following section lists several good tutorials/resources for those who have experience programming but who have not worked extensively with JavaScript before.
Before that, however, it's important to clarify some terminology about the different versions of JavaScript.
These are summarized in this article:
[WTF is ES6, ES8, ES2017, ECMAScript...](https://codeburst.io/javascript-wtf-is-es6-es8-es-2017-ecmascript-dca859e4821c)
An important takeaway from this article is that ES6, also known as ES2015, introduced many major features that are commonly seen in modern JavaScript programming.
However, this means that ES5 engines and interpreters will fail if they encounters these ES6 features.
You'll see why this is important further down.
- [MDN Introduction to JS](https://developer.mozilla.org/en-US/docs/Web/JavaScript/A_re-introduction_to_JavaScript)
- [Eloquent JavaScript (ES6+)](http://eloquentjavascript.net/)
Recommended Chapters: Introduction, 1-6
- [Modern JavaScript Tutorial (ES6+)](https://javascript.info/)
Recommended Chapters: 2, 4-6
src/Documentation/doc/programming/remote_api.md
+174
View File
@@ -0,0 +1,174 @@
# Remote API
All versions of Bitburner can use websockets to connect to a server.
That server can then perform a number of actions.
Most commonly this is used in conjunction with an external text editor or API
in order to make writing scripts easier, or even use typescript.
To make use of this Remote API through the official server, look [here](https://github.com/bitburner-official/typescript-template).
If you want to make your own server, see below for API details.
This API uses the JSON RPC 2.0 protocol. Inputs are in the following form:
{
"jsonrpc": "2.0",
"id": number,
"method": string,
"params": any
}
Outputs:
{
"jsonrpc": "2.0",
"id": number,
"result": any,
"error": any
}
## Methods
## `pushFile`
Create or update a file.
{
"jsonrpc": "2.0",
"id": number,
"method": "pushFile",
"params": {
filename: string;
content: string;
server: string;
}
}
{
"jsonrpc": "2.0",
"id": number,
"result": "OK"
}
## `getFile`
Read a file and its content.
{
"jsonrpc": "2.0",
"id": number,
"method": "getFile",
"params": {
filename: string;
server: string;
}
}
{
"jsonrpc": "2.0",
"id": number,
"result": string
}
## `deleteFile`
Delete a file.
{
"jsonrpc": "2.0",
"id": number,
"method": "deleteFile",
"params": {
filename: string;
server: string;
}
}
{
"jsonrpc": "2.0",
"id": number,
"result": "OK"
}
## `getFileNames`
List all file names on a server.
{
"jsonrpc": "2.0",
"id": number,
"method": "getFileNames",
"params": {
server: string;
}
}
{
"jsonrpc": "2.0",
"id": number,
"result": string[]
}
## `getAllFiles`
Get the content of all files on a server.
{
"jsonrpc": "2.0",
"id": number,
"method": "getAllFiles",
"params": {
server: string;
}
}
{
"jsonrpc": "2.0",
"id": number,
"result": {
filename: string,
content: string
}[]
}
## `calculateRam`
Calculate the in-game ram cost of a script.
{
"jsonrpc": "2.0",
"id": number,
"method": "calculateRam",
"params": {
filename: string;
server: string;
}
}
{
"jsonrpc": "2.0",
"id": number,
"result": number
}
## `getDefinitionFile`
Get the definition file of the API.
{
"jsonrpc": "2.0",
"id": number,
"method": "getDefinitionFile"
}
{
"jsonrpc": "2.0",
"id": number,
"result": string
}