docs n stuff

docs/commands/world.md

@@ -0,0 +1,5 @@
+# `mcman world pack|unpack`
+
+## `mcman world unpack <world>`
+
+Unpack

docs/reference/lockfile.md

@@ -0,0 +1,24 @@
+# Lockfile (`.mcman.lock`)
+
+The lockfile, found under the output directory, is generated after every build. It's in the JSON format and contains metadata about the installed mods, plugins and last dates of config files.
+
+While it's primary purpose is to be a cache and speed up building, it also makes sure that the removed mods/plugins from the `server.toml` file also get their jar files deleted.
+
+## Disabling
+
+See [Options/Disabling lockfiles](../tutorials/options.md#disabling-lockfiles)
+
+## Format
+
+```ts
+type Lockfile = {
+    plugins: [Downloadable, ResolvedFile][],
+    mods: [Downloadable, ResolvedFile][],
+    files: BootstrappedFile[],
+}
+
+type BootstrappedFile = {
+    path: string,
+    date: number, // timestamp
+}
+```

docs/tutorials/building.md

@@ -1,22 +1,68 @@
-# Understanding Building
+# Building, Running and Developing
 
-Building is the process of... basically building the entire server.
+After editing `server.toml` or writing configuration files to `config/`, you're probably going to want to run the server.
 
-Before everything else, building requires a [server.toml](../reference/server.toml.md). Check out the [getting started](./getting-started.md) tutorial if you dont have one.
+mcman is not designed to handle running the server itself, but provides a `run` and a `dev` command which we'll explain later.
 
-Before everything, mcman will create a `server/` directory to download everything into if it doesnt exist.
+## Building
 
-## 1. Server Jar
+To start the server, you need the files. The `.jar` files of the server, addons, and other stuff. We call the process of downloading, processing, copying etc. **building**.
 
-First, mcman will download the server jar. And if neccesary (quilt and buildtools) will run the installer.
+Building requires a valid [server.toml](../reference/server.toml.md) file - thats it.
 
-## 2. Plugins/Mods
+To not conflict with everything else, the build output folder is by default the `server/` directory, next to `server.toml` and `config/`. This folder should already be `.gitignore`d by default.
 
-In this stage, mcman downloads every mod and plugin defined in the `server.toml`.
+You can override the output directory with the `--output <path>` option, but this is not recommended.
 
-## 3. Datapacks
+You can also skip some steps if you want using the `--skip`/`-s` option. Possible values are `plugins`, `mods`, `worlds` and `bootstrap`. If you need to skip multiple stages, stack them up like so: `-s mods -s worlds`
+
+### First steps
+
+`mcman` will try to load a [lockfile](../reference/lockfile.md) if present before beginning the build. This is done to speed up build times and skip unnecesary things. (you can ignore this)
+
+First, mcman will download or install the server jar as defined in `server.toml`'s [`jar`](../reference/servertype/index.md) field.
+
+### Java
+
+Some servers (quilt, forge, neoforge, spigot/bukkit) require **java** to be present while building. This is because those server types use an installer mechanism instead of providing a pre-built `server.jar` file that mcman can download.
+
+If the server type is one that requires installation, you can find the installer's output logs under the output directory. The file name is `.S.mcman.log` where `S` is a short identifier for the installer. (`qsi` for quilt, `bt` for buildtools, `fi` and `nfi` for forge/neoforge respectively)
+
+The installer must exit with a non-zero code or mcman considers it a fail and stops building the server.
+
+### Addons (plugins and mods)
+
+Next, `mcman` will download all the addons according to `server.toml`
+
+By default, most downloaded addons get [cached](./caching.md) in your local system. If a Downloadable is cached, mcman will copy it from cache instead of downloading it again.
+
+If possible, mcman will also do size/hash checks on both downloaded and copied/cached files.
+
+Every addon gets 3 attempts, but this can be [overridden](./options.md#addon-download-attempts)
+
+### Worlds
+
+If there are any worlds specified in `server.toml`, they are processed.
+
+See [Using Worlds](./using-worlds.md) to learn more about worlds in mcman.
+
+Datapacks are also downloaded similar to addons in this stage.
+
+### Bootstrapping
+
+See [Variables aka Bootstrapping](./variables.md)
+
+### Finishing up
+
+Some last touches include:
+
+- Generating `start.sh`/`start.bat` scripts (can be disabled with `launcher.disable`)
+- Creating an `eula.txt` if `launcher.eula_args` is set to true and the server doesn't support the argument
+
+## Running
+
+## Developing
 
-Like plugins and mods, if there are any, mcman will download every datapack for every world that exists
 
 ## 4. Configurations (Bootstrapping)
 

docs/tutorials/caching.md

@@ -0,0 +1,30 @@
+# Caching
+
+mcman will try to cache downloaded files and other metadata such as Github API requests.
+
+The cache folder will generally be:
+
+- Windows: `%LocalAppData%/mcman`
+- Linux: `~/.cache/mcman`
+
+You can also manage the cache using the `mcman cache` command.
+
+- `mcman cache path`: Prints the cache path
+- `mcman cache list`: Lists caches
+    - `-d` for detailed
+- `mcman cache open`: Opens the cache folder using a file explorer
+- `mcman cache clear`: Clears the cache without confirmation
+
+## Folders
+
+Most sources have their own folders:
+
+- Modrinth: `modrinth/{project}/{version}/{file}`
+- Curserinth: `curserinth/{project}/{version}/{file}`
+- Github:
+    - Metadata: `github/{owner}/{repo}/releases.json`
+    - Releases: `github/{owner}/{repo}/releases/{tag}/{file}`
+- Hangar: `hangar/{owner}/{proj}/{version}/{file}`
+- Jenkins: `jenkins/{url}/{...job}/{build}/{file}`
+- Maven: `maven/{url}/{...group}/{artifact}/{version}/{file}`
+- PaperMC: `papermc/{proj}/{proj}-{mcver}-{build}.jar`

docs/tutorials/network.md

@@ -0,0 +1,88 @@
+# Networks
+
+If you want to manage multiple servers at once like a network, you can use `network.toml`:
+
+```toml
+name = "CoolNetwork"
+port = 25565
+```
+
+## Servers
+
+In `network.toml`, define servers in the `servers` table:
+
+```toml
+name = "CoolNetwork"
+port = 25565
+
+[servers.lobby]
+port = 25566
+
+[servers.game1]
+port = 25567
+```
+
+In the folder structure, keep the servers under the `servers/` folder:
+
+```yaml
+cool_network
+├─ network.toml
+└─ servers/
+   ├─ lobby
+   │  └─ server.toml
+   └─ game1
+      └─ server.toml
+```
+
+If needed, you can optionally define `ip_address` in servers. This is `"127.0.0.1"` by default.
+
+At the moment, most of these rules aren't used or enforced, but kept in here so other tools could be created around this.
+
+## Variables
+
+Just like the normal `server.toml` variables, you can define custom variables in `network.toml`:
+
+```toml
+[variables]
+SOME = "thing"
+```
+
+Network variables need to be prefixed with `NW_` while accessing them.
+
+So instead of using `${SOME}` to access it, `${NW_SOME}` can be used.
+
+## Special Variables
+
+Here are some more special variables.
+
+!!! note
+    You can use the `PORT_name` and `IP_name` environment variables to override server ip addresses and ports. The `name` must be the name of the server as defined in `server.toml`.
+
+- `SERVER_IP`: the IP address of the server
+- `SERVER_PORT`: the port of the server
+- `NETWORK_NAME`: name of the network
+- `NETWORK_PORT`: the defined port
+- `NETWORK_SERVERS_COUNT`: amount of servers defined
+
+You can also get the port or IP of another server via
+
+- `NW_SERVER_name_IP`
+- `NW_SERVER_name_PORT`
+- `NW_SERVER_name_ADDRESS`: Basically "ip:port"
+
+These generate a table of servers that can be used in proxy server configurations:
+
+- `NETWORK_VELOCITY_SERVERS` for Velocity
+- `NETWORK_BUNGEECORD_SERVERS` for BungeeCord/Waterfall
+
+=== "Usage in Velocity"
+    ```toml
+    #${NETWORK_VELOCITY_SERVERS}
+    ```
+
+=== "Usage in BungeeCord"
+    ```toml
+    #${NETWORK_BUNGEECORD_SERVERS}
+    ```
+
+You can comment the line because it will start with a comment/disclaimer.

docs/tutorials/options.md

@@ -0,0 +1,30 @@
+# Options/Misc
+
+Here are some misc. options of mcman
+
+## Setting the Java binary
+
+If you want `mcman` to use a custom java binary, you can set the environment variable `JAVA_BIN` to its path.
+
+For servers that have the `launcher.java_version` field set, mcman will try to use the `JAVA_*_BIN` environment first before `JAVA_BIN`.
+
+For example, for
+
+```toml
+[launcher]
+java_version = "16"
+```
+
+`mcman` will first check for `JAVA_16_BIN`, then `JAVA_BIN` and if both aren't set, `"java"` will be used as default.
+
+## Disabling lockfiles
+
+To disable [Lockfile](../reference/lockfile.md)s, you can set the `MCMAN_DISABLE_LOCKFILE` environment variable to `true`.
+
+## Addon download attempts
+
+By default, addons get 3 tries to be downloaded. To change this, set the `MAX_TRIES` environment variable to the max amount of tries. For example, set it to `1` if you want `mcman` to try only once.
+
+## Overriding server ports in networks
+
+See the note on [this section](./network.md#special-variables)

docs/tutorials/using-worlds.md

@@ -1,43 +1,37 @@
 # Using Worlds
 
-Worlds are an experimental feature added in `0.4.0`
+mcman can help you manage your server's worlds. You can make mcman [download](#downloading-worlds) a world or keep the world under the [`worlds/`]() directory.
 
-This feature allows you to save, load or download worlds while building.
+Worlds are defined in [`server.toml`](../reference/server.toml.md) under the `worlds` table. The key of the table is the world name. For example, the world with name 'city' would be `worlds.city`.
 
 ## Downloading Worlds
 
-In [`server.toml`](../reference/server.toml.md) under `worlds` you can use the [`World`](../reference/world.md) type to specify a download.
+If you set the `download` field to a [Downloadable](../reference/downloadable/index.md) mcman will download the world zip file and unzip it if the world does not exist in the output directory.
 
-!!! example
-    ```toml
-    [worlds.lobby.download]
-    type = "url"
-    url = "..."
-    ```
+```toml
+[worlds.earth.download]
+type = "url"
+url = "https://example.com/cdn/worlds/earth.zip"
+```
 
-As you can see, the `download` property is just a [`Downloadable`](../reference/downloadable/index.md), so you can go crazy and use... github [releases](https://github.com/ModFest/bc23-pack/releases/tag/world)? Im not the one to judge.
+## The `worlds/` Folder
 
-## Packing a world
+Optionally, you can store your worlds under the `worlds/` folder.
 
-'Packing' is used to refer to zipping the world contents into a zip file and putting it under the `worlds/` directory.
+```yaml
+worlds
+├─ lobby.zip
+└─ arena.zip
+```
 
-Since this is an experimental feature, you unfortunately need to do this manually.
+When building, if the world does not exist in the output directory, mcman will unzip the world file located in the `worlds/` folder.
 
 !!! note
-    The world files shouldnt be inside a folder inside the zip file, rather, be directly inside the zip archive.
-
-## Unpacking a world
+    For your world to be unpacked, there needs to be a world entry in `server.toml` for it:
 
-When building, if the [world](../reference/world.md) is in `worlds` inside [`server.toml`](../reference/server.toml.md) **and** the world does not exist in `server/`, mcman will automatically unpack it.
-
-!!! example
     ```toml
-    [worlds.'my-world']
-    # just the key existing is enough
+    [worlds.city]
+    # just the entry is enough
     ```
 
-To manually unpack the world to `server/`, use:
-
-```
-mcman world unpack <name>
-```
+You can also manually unpack a world using the [`mcman unpack <world>`](../commands/world.md) command.