implement feedback

docs/gettingstarted/index.md

@@ -18,10 +18,10 @@ Make sure you are using a 64-bit JVM. One way of checking is to run `java -versi
 ## Setting Up the Workspace
 
 - Open the [Mod Developer Kit (MDK)][mdk] GitHub repository, click "Use this template" and clone the newly-created repository to your local machine.
-   - If you do not want to use Git, you can also download the ZIP of the repository (under Code -> Download ZIP) and extract it.
+   - If you do not want to use GitHub, or if you want to get the template for an older commit or a non-default branch (which would be the case e.g. for older versions), you can also download the ZIP of the repository (under Code -> Download ZIP) and extract it.
 - Open your IDE and import the Gradle project. Eclipse and IntelliJ IDEA will do this automatically for you. If you have an IDE that does not do this, you can also do it via the `gradlew` terminal command.
    - When doing this for the first time, Gradle will download all dependencies of NeoForge, including Minecraft itself, and decompile them. This can take a fair amount of time (up to an hour, depending on your hardware and network strength).
-   - Whenever you make a change to the Gradle files, Gradle will need to be reloaded through the same method.
+   - Whenever you make a change to the Gradle files, the Gradle changes will need to be reloaded, either through the "Reload Gradle" button in your IDE, or again through the `gradlew` terminal command.
 
 ## Customizing Your Mod Information
 
@@ -36,7 +36,7 @@ All properties are explained as comments inside the `gradle.properties`, the mos
 - `minecraft_version` and `neo_version` specify the Minecraft and NeoForge version used by your project, respectively. Change these appropriately if you want to update Minecraft or NeoForge.
 - `minecraft_version_range` and `neo_version_range` specify the accompanying version ranges your mod uses. This is done using [Maven Versioning Ranges][mvr].
    - Generally, these should be the Minecraft and NeoForge version your project is on, with the next Minecraft version as the upper bound.
-   - For example, on Minecraft 1.20.1 and NeoForge 20.2.59-beta, the bounds should be `[1.20.2,1.20.3)` (read: anything between Minecraft `1.20.2` (inclusive) and Minecraft `1.20.3` (exclusive)) and `[20.2.59,20.3)` (read: anything between NeoForge `20.2.59` (inclusive) and NeoForge `20.3.*` (exclusive)).
+   - For example, on Minecraft 1.20.2 and NeoForge 20.2.59-beta, the bounds should be `[1.20.2,1.20.3)` (read: anything between Minecraft `1.20.2` (inclusive) and Minecraft `1.20.3` (exclusive)) and `[20.2.59,20.3)` (read: anything between NeoForge `20.2.59` (inclusive) and NeoForge `20.3.*` (exclusive)).
    - See [the page on Versioning][versioning] for more elaborate information on how Minecraft's and NeoForge's versioning systems work.
 - `mod_id` is the mod id of your mod. This shows up in a lot of places, for example as the namespace for all your registered things, or as the namespace for your resource and data packs.
 - `mod_name` is the display name of your mod. By default, this can only be seen in the mod list, however, mods such as [JEI][jei] prominently display mod names in item tooltips as well.
@@ -77,7 +77,11 @@ To build your mod, run `gradlew build`. This will output a file in `build/libs`
 
 To run your mod in a test environment, you can either use the generated run configurations or use the associated tasks (e.g. `gradlew runClient`). This will launch Minecraft from the corresponding runs directory (e.g. `runs/client` or `runs/server`), along with any source sets specified. The default MDK includes the `main` source set, so any code written in `src/main/java` will be applied.
 
-If you are running a dedicated server, whether through the run configuration or `gradlew runServer`, the server will initially shut down immediately. You will need to accept the Minecraft EULA by editing the `eula.txt` file in the run directory. Once accepted, the server will load, which can then be accessed via a direct connect to `localhost` (or `127.0.0.1`).
+### Server Testing
+
+If you are running a dedicated server, whether through the run configuration or `gradlew runServer`, the server will shut down immediately. You will need to accept the Minecraft EULA by editing the `eula.txt` file in the run directory.
+
+Once accepted, the server will load and become available under `localhost` (or `127.0.0.1`). However, you will still not able to join, because the server will be put into online mode by default, which requires authentication (which the Dev player does not have). To fix this, stop your server again and set the `online-mode` property in the `server.properties` file to `false`. Now, start your server, and you should be able to connect.
 
 :::tip
 You should always test your mod in a dedicated server environment. This includes [client-only mods][client], these should not do anything when loaded on the server.

docs/gettingstarted/modfiles.md

@@ -21,7 +21,7 @@ Non-mod-specific properties are properties associated with the JAR itself, indic
 | Property             |  Type   |    Default    |                                                                                                                                                                    Description                                                                                                                                                                     | Example                                                                        |
 |:---------------------|:-------:|:-------------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:-------------------------------------------------------------------------------|
 | `modLoader`          | string  | **mandatory** | The language loader used by the mod(s). Can be used to support alternative language structures, such as Kotlin objects for the main file, or different methods of determining the entrypoint, such as an interface or method. NeoForge provides the Java loader [`"javafml"`][javafml] and the lowcode/nocode loader [`"lowcodefml"`][lowcodefml]. | `modLoader="javafml"`                                                          |
-| `loaderVersion`      | string  | **mandatory** |                                                                             The acceptable version range of the language loader, expressed as a [Maven Version Range][mvr]. For `javafml` and `lowcodefml`, the version is the major version of the NeoForge version.                                                                              | `loaderVersion="[46,)"`                                                        |
+| `loaderVersion`      | string  | **mandatory** |                                                                                           The acceptable version range of the language loader, expressed as a [Maven Version Range][mvr]. For `javafml` and `lowcodefml`, this is currently version `1`.                                                                                           | `loaderVersion="[1,)"`                                                         |
 | `license`            | string  | **mandatory** |                                               The license the mod(s) in this JAR are provided under. It is suggested that this is set to the [SPDX identifier][spdx] you are using and/or a link to the license. You can visit https://choosealicense.com/ to help pick the license you want to use.                                               | `license="MIT"`                                                                |
 | `showAsResourcePack` | boolean |    `false`    |                                                                                     When `true`, the mod(s)'s resources will be displayed as a separate resource pack on the 'Resource Packs' menu, rather than being combined with the 'Mod resources' pack.                                                                                      | `showAsResourcePack=true`                                                      |
 | `services`           |  array  |     `[]`      |                                                                                         An array of services your mod uses. This is consumed as part of the created module for the mod from NeoForge's implementation of the Java Platform Module System.                                                                                          | `services=["net.minecraftforge.forgespi.language.IModLanguageProvider"]`       |
@@ -30,6 +30,8 @@ Non-mod-specific properties are properties associated with the JAR itself, indic
 
 :::note
 The `services` property is functionally equivalent to specifying the [`uses` directive in a module][uses], which allows [loading a service of a given type][serviceload].
+
+Alternatively, it can be defined in a service file inside the `src/main/resources/META-INF/services` folder, where the file name is the fully-qualified name of the service, and the file content is the name of the service to load (see also [this example from the AtlasViewer mod][atlasviewer]).
 :::
 
 ### Mod-Specific Properties
@@ -54,7 +56,7 @@ modId = "examplemod2"
 | `displayName`   | string  |      value of `modId`       |                                                                                    The display name of the mod. Used when representing the mod on a screen (e.g., mod list, mod mismatch).                                                                                     | `displayName"Example Mod"`                                      |
 | `description`   | string  | `'''MISSING DESCRIPTION'''` |                                                                           The description of the mod shown in the mod list screen. It is recommended to use a [multiline literal string][multiline].                                                                           | `description='''This is an example.'''`                         |
 | `logoFile`      | string  |          *nothing*          |                                  The name and extension of an image file used on the mods list screen. The logo must be in the root of the JAR or directly in the root of the source set (e.g. `src/main/resources` for the main source set).                                  | `logoFile="example_logo.png"`                                   |
-| `logoBlur`      | boolean |           `true`            |                                                                                             Whether to use `GL_LINEAR*` (true) or `GL_NEAREST*` (false) to render the `logoFile`.                                                                                              | `logoBlur=false`                                                |
+| `logoBlur`      | boolean |           `true`            |                                          Whether to use `GL_LINEAR*` (true) or `GL_NEAREST*` (false) to render the `logoFile`. In simpler terms, this means whether the logo should be blurred or not when trying to scale the logo.                                           | `logoBlur=false`                                                |
 | `updateJSONURL` | string  |          *nothing*          |                                                                                A URL to a JSON used by the [update checker][update] to make sure the mod you are playing is the latest version.                                                                                | `updateJSONURL="https://example.github.io/update_checker.json"` |
 | `features`      |  table  |            `{}`             |                                                                                                                                See [features].                                                                                                                                 | `features={java_version="17"}`                                  |
 | `modproperties` |  table  |            `{}`             |                                                                                       A table of key/values associated with this mod. Unused by NeoForge, but is mainly for use by mods.                                                                                       | `modproperties={example="value"}`                               |
@@ -74,7 +76,7 @@ The features system allows mods to demand that certain settings, software, or ha
 
 ### Dependency Configurations
 
-Mods can specify their dependencies, which are checked by NeoForge before loading the mods. These configurations are created using the [array of tables][array] `[[dependencies.<modid>]]`, where `modid` is the identifier of the mod the dependency is for.
+Mods can specify their dependencies, which are checked by NeoForge before loading the mods. These configurations are created using the [array of tables][array] `[[dependencies.<modid>]]`, where `modid` is the identifier of the mod that consumes the dependency.
 
 | Property       |  Type   |    Default    |                                                               Description                                                               | Example                                      |
 |:---------------|:-------:|:-------------:|:---------------------------------------------------------------------------------------------------------------------------------------:|:---------------------------------------------|
@@ -107,11 +109,16 @@ public class Example {
 }
 ```
 
+:::note
+There must be a 1-to-1 matching of mods in the `mods.toml` file and `@Mod` entrypoints. This means that for every mod defined, there must be exactly one `@Mod` annotation with that mod's id.
+:::
+
 ### `lowcodefml`
 
 `lowcodefml` is a language loader used as a way to distribute datapacks and resource packs as mods without the need of an in-code entrypoint. It is specified as `lowcodefml` rather than `nocodefml` for minor additions in the future that might require minimal coding.
 
 [array]: https://toml.io/en/v1.0.0#array-of-tables
+[atlasviewer]: https://github.com/XFactHD/AtlasViewer/blob/1.20.2/neoforge/src/main/resources/META-INF/services/xfacthd.atlasviewer.platform.services.IPlatformHelper
 [dist]: ../concepts/sides.md#different-kinds-of-sides
 [events]: ../concepts/events.md
 [features]: #features

docs/gettingstarted/versioning.md

@@ -23,7 +23,7 @@ Similarly, when the pre-release cycle completes, Mojang releases Release Candida
 
 ## NeoForge
 
-NeoForge uses an adapted semver system: The major version is Minecraft's minor version, the minor version is Minecraft's patch version, and the patch version is the "actual" NeoForge version. So for example, NeoForge 20.2.59 is the 60th version (we start at 0) for Minecraft 1.20.2. The `1` at the beginning is omitted because it is very unlikely that it will ever, see [above][minecraft] for why that is the case.
+NeoForge uses an adapted semver system: The major version is Minecraft's minor version, the minor version is Minecraft's patch version, and the patch version is the "actual" NeoForge version. So for example, NeoForge 20.2.59 is the 60th version (we start at 0) for Minecraft 1.20.2. The `1` at the beginning is omitted because it is very unlikely that it will ever change, see [above][minecraft] for why that is the case.
 
 A few places in NeoForge also use [Maven version ranges][mvr], for example the Minecraft and NeoForge version ranges in the [`mods.toml`][modstoml] file. These are mostly, but not fully compatible with semver (the `pre`-tag is not considered by it, for example).
 
@@ -77,7 +77,7 @@ Usually, this is done by including the mod loader somewhere in the name. `jei-ne
 
 ### A Note on Maven
 
-Maven, the system used for dependency hosting, uses a versioning system that differs from semver in some details (though the general `major.minor.patch` pattern remains the same). The related [Maven Versioning Range (MVR)][mvr] system is used in some places in NeoForge (see [above][neoforge]). When choosing your versioning scheme, it is a good idea to make sure it is compatible with MVR.
+Maven, the system used for dependency hosting, uses a versioning system that differs from semver in some details (though the general `major.minor.patch` pattern remains the same). The related [Maven Versioning Range (MVR)][mvr] system is used in some places in NeoForge (see [above][neoforge]). When choosing your versioning scheme, you should make sure it is compatible with MVR, as otherwise, mods will not be able to depend on specific versions of your mod!
 
 [create]: https://www.curseforge.com/minecraft/mc-mods/create
 [infinite]: https://minecraft.wiki/w/Java_Edition_20w14∞