Loader: Intro, fabric.mod.json, Dependency Overrides

.vitepress/sidebars/develop.ts

@@ -362,6 +362,20 @@ export default [
       },
     ],
   },
+  {
+    text: "develop.loader",
+    collapsed: true,
+    items: [
+      {
+        text: "develop.loader.index",
+        link: "/develop/loader/",
+      },
+      {
+        text: "develop.loader.fabric.mod.json",
+        link: "/develop/loader/fabric-mod-json",
+      },
+    ],
+  },
   {
     text: "develop.porting",
     collapsed: true,

.vitepress/sidebars/players.ts

@@ -36,6 +36,10 @@ export default [
             text: "players.troubleshooting.crash_reports",
             link: "/players/troubleshooting/crash-reports",
           },
+          {
+            text: "players.troubleshooting.dependency_overrides",
+            link: "/players/troubleshooting/dependency-overrides",
+          },
         ],
       },
       {

.vitepress/theme/style.css

@@ -52,6 +52,7 @@
 code,
 pre {
   tab-size: 2 !important;
+  font-variant-ligatures: none;
 }
 
 /* Sidebar Scrollbar - Styles scrollbars within the side navigation pane for improved visibility. */

develop/getting-started/project-structure.md

@@ -3,16 +3,13 @@ title: Project Structure
 description: An overview of the structure of a Fabric mod project.
 authors:
   - IMB11
-resources:
-  https://wiki.fabricmc.net/documentation:fabric_mod_json: fabric.mod.json v1 Specification - Fabric Wiki
-  https://github.com/FabricMC/fabric-loom/blob/dev/1.15/src/main/java/net/fabricmc/loom/api/fmj/FabricModJsonV1Spec.java: Source Code for fabric.mod.json v1 Spec
 ---
 
 This page will go over the structure of a Fabric mod project, and the purpose of each file and folder in the project.
 
 ## `fabric.mod.json` {#fabric-mod-json}
 
-The `fabric.mod.json` file is the main file that describes your mod to Fabric Loader. It contains information such as the mod's ID, version, and dependencies.
+The [`fabric.mod.json`](../loader/fabric-mod-json) file is the main file that describes your mod to Fabric Loader. It contains information such as the mod's ID, version, and dependencies.
 
 The most important fields in the `fabric.mod.json` file are:
 
@@ -23,17 +20,9 @@ The most important fields in the `fabric.mod.json` file are:
 - `depends`: The mods that your mod depends on.
 - `mixins`: The mixins that your mod provides.
 
-You can see an example `fabric.mod.json` file below - this is the `fabric.mod.json` file for the mod that powers this documentation site.
-
-::: details `fabric.mod.json` of the Example Mod
-
-@[code lang=json](@/reference/latest/src/main/resources/fabric.mod.json)
-
-:::
-
 ## Entrypoints {#entrypoints}
 
-As mentioned before, the `fabric.mod.json` file contains a field called `entrypoints` - this field is used to specify the entrypoints that your mod provides.
+As mentioned before, the [`fabric.mod.json`](../loader/fabric-mod-json) file contains a field called `entrypoints` - this field is used to specify the entrypoints that your mod provides.
 
 The template mod generator creates both a `main` and `client` entrypoint by default:
 

develop/loader/fabric-mod-json.md

@@ -0,0 +1,283 @@
+---
+title: fabric.mod.json
+description: A guide to the `fabric.mod.json` specification.
+authors:
+  - cassiancc
+  - falseresync
+  - jamieswhiteshirt
+  - IMB11
+  - SolidBlock-cn
+authors-nogithub:
+  - skyland1a
+resources:
+  https://github.com/FabricMC/fabric-loom/blob/dev/1.16/src/main/java/net/fabricmc/loom/api/fmj/FabricModJsonV1Spec.java: Source Code for fabric.mod.json v1 Spec
+  https://github.com/FabricMC/fabric-language-kotlin: Fabric Language Kotlin's Language Provider
+  https://spdx.org/licenses/: SPDX License Identifiers
+  https://semver.org/: Semantic Versioning
+  https://jubianchi.github.io/semver-check/: Semantic Version Comparison Tool
+---
+
+<!-- markdownlint-configure-file { MD033: { allowed_elements: [script, Range] } } -->
+
+<script setup lang="ts">
+import { h } from "vue";
+
+const Range = ({ r }) => h(
+  "a",
+  {
+    href: `https://jubianchi.github.io/semver-check/#/${encodeURIComponent(r)}/26.1.2`,
+    target: "_blank",
+    rel: "noreferrer",
+  },
+  h("code", r)
+);
+</script>
+
+The `fabric.mod.json` file is a metadata file used by Fabric Loader to load mods. It must be placed in the JAR's root directory for the mod to get loaded.
+
+A predefined `fabric.mod.json` file is included in the template mod, or it can be [generated by Fabric Loom](../loom/tasks#fabric-mod-json).
+
+You can consult the [source code of the specification for `fabric.mod.json` v1](https://github.com/FabricMC/fabric-loom/blob/-/src/main/java/net/fabricmc/loom/api/fmj/FabricModJsonV1Spec.java). You will also find the `fabric.mod.json` file used by this website's Example Mod below.
+
+::: details `fabric.mod.json` of the Example Mod
+
+<<< @/reference/latest/src/main/resources/fabric.mod.json
+
+:::
+
+## Mandatory Fields {#mandatory-fields}
+
+The following fields are mandatory for Fabric to load your mod.
+
+- **`schemaVersion`** Must be the first entry, and the value must always be `1`. Required for Fabric Loader to parse the file correctly.
+- **`id`** A string value that defines the mod's identifier. Must start with a letter. May only contain ASCII letters, digits, underscores, or hyphens. 2 to 64 characters.
+- **`version`** A string value that defines the mod's version, expected to match the [Semantic Versioning 2.0.0](https://semver.org/) specification.
+
+```json
+"schemaVersion": 1,
+"id": "example-mod",
+"version": "1.0.0"
+```
+
+## Mod Loading {#mod-loading}
+
+### Environment {#environment}
+
+- **`environment`**: A string value that defines which environments the mod should be run on:
+  - **`*`**: Runs in all environments. Default.
+  - **`client`**: Runs on the physical client side. If set, your mod will not be loaded on dedicated servers.
+  - **`server`**: Runs on the physical server side. If set, your mod will not be loaded on clients, this includes singleplayer and LAN.
+
+```json
+"environment": "*"
+```
+
+### Entrypoints {#entrypoints}
+
+- **`entrypoints`** An object that defines the main classes that your mod will load.
+  - **`main`** An array of string class names that implement `ModInitializer`.
+  - **`client`** An array of string class names that implement `ClientModInitializer`. This entrypoint is run after `main`, and only on the physical client side.
+  - **`server`** An array of string class names that implement `DedicatedServerModInitializer`. This entrypoint is run after `main`, and only on the physical server side.
+
+Fabric Loader provides those three main entrypoints, but other mods may provide their own. For example, Fabric API provides `fabric-datagen` for data generator entrypoints.
+
+Each entrypoint can load multiple classes, and even methods or static fields. For example:
+
+```json
+"main": [
+    "net.fabricmc.example.ExampleMod",
+    "net.fabricmc.example.ExampleMod::handle"
+]
+```
+
+::: tip
+
+If you're not using Java, you should consult the language adapter's documentation. For Kotlin, that's in the [Fabric Language Kotlin's README](https://github.com/FabricMC/fabric-language-kotlin/blob/master/README.md).
+
+:::
+
+### JARs {#jars}
+
+- **`jars`**: An array of JARs to be nested inside your mod. When using `include` on your dependencies, Loom will automatically populate this. Each entry is an object containing a `file` key, with a path to the nested JAR from within your mod's. For example:
+
+```json
+"jars": [
+   {
+      "file": "nested/vendor/dependency.jar"
+   }
+]
+```
+
+### Language Adapters {#language-adapters}
+
+- **`languageAdapters`**: A dictionary of classes that implement `LanguageAdapter`.
+
+```json
+"languageAdapters": {
+   "kotlin": "net.fabricmc.language.kotlin.KotlinAdapter"
+}
+```
+
+### Mixins {#mixins}
+
+- **`mixins`**: A list of mixin configuration files. Each entry is either a path to a mixin configuration file within your mod's JAR, or an object containing the following fields:
+  - **`config`**: The path to the mixin configuration file inside your mod's JAR.
+  - **`environment`**: Behaves just like the [upper level **environment** field](#environment). For example:
+
+```json
+"mixins": [
+   "example-mod.mixins.json",
+   {
+      "config": "example-mod.client-mixins.json",
+      "environment": "client"
+   }
+]
+```
+
+### Access Wideners {#accesswideners}
+
+- **`accessWidener`**: A string identifying an [access widener or class tweaker](../class-tweakers/) file.
+
+```json
+"accessWidener": "example-mod.classtweaker"
+```
+
+### Provides {#provides}
+
+- **`provides`**： An array of mod IDs that will be aliases for the mod. Fabric Loader will treat these IDs as if the respective mods exist. If any other mod uses one of them, it will not be loaded.
+
+```json
+"provides": [
+   "example_mod"
+]
+```
+
+## Dependency Resolution {#dependency-resolution}
+
+The following keys will accept a dictionary of dependencies. For more details on how to structure the dictionary, see below:
+
+- **`depends`**: For dependencies required to run. **If any are missing, Fabric Loader will trigger a crash**.
+- **`recommends`**: For dependencies not required to run. For each missing dependency, Fabric Loader will log a warning.
+- **`suggests`**: For dependencies not required to run. Use this as a kind of metadata.
+- **`breaks`**: For mods whose together with yours might cause a game crash. **If any are present, Fabric Loader will trigger a crash**.
+- **`conflicts`**: For mods whose together with yours cause some kind of bugs, etc. For each conflicting mod present, Fabric Loader will log a warning.
+
+### Semantic Versioning {#semantic-versioning}
+
+The key of each entry is the mod ID of the dependency.
+
+The value of each key is a string or array of strings declaring supported version ranges of the dependency. If it's an array, only one of the ranges has to match for the constraint to be satisfied.
+
+Here are some examples of ranges and what they indicate. Try using [jubianchi's Semver check](https://jubianchi.github.io/semver-check/#/) to test which values will satisfy the constraint.
+
+::: details Semantic Versioning Examples
+
+| Range | Description | Matches | Clashes |
+| ----- | ----------- | ------- | ------- |
+| <Range r="*" /> | Any version (not recommended) | `26.1.2`, `24w14potato`... | _none_ |
+| <Range r="26.1.2" /> | Exact version only | `26.1.2` | `26.1`, `26.1.1`, `26.2`... |
+| <Range r="26.1.0 \|\| 26.1.1" /> | Either range | `26.1.0`, `26.1.1` | `26.1.2`, `26.2`... |
+| <Range r="[26.1.0, 26.1.1]" /> | Equivalent to `26.1.0 \|\| 26.1.1` | `26.1`, `26.1.1` | `26.1.2`, `26.2`... |
+| <Range r=">26" /> | Above a version (exclusive) | `26.1.2`, `26.2`... | `26`, `25.x`... |
+| <Range r=">=26.1" /> | At or above a version (inclusive) | `26.1`, `26.1.2`, `26.2`... | `26.0`, `25.x`... |
+| <Range r="<=26.1" /> | At or below a version (inclusive) | `26.1`, `26.0`, `25.x`... | `26.1.2`, `26.2`... |
+| <Range r=">26 <26.2" /> | Between two versions (both exclusive) | `26.1`, `26.1.2`, snapshots... | `26`, `26.2`... |
+| <Range r=">=26.1 <26.2" /> | Between two versions (inclusive lower bound) | `26.1`, `26.1.2`, snapshots... | `26.0`, `26.2`... |
+| <Range r="26.1.x" /> | Any patch of a minor version | `26.1`, `26.1.2`, snapshots... | `26.2`, `27.x`... |
+| <Range r="~26.1" /> | Same as `26.1.x` | `26.1`, `26.1.2`, snapshots... | `26.2`, `27.x`... |
+| <Range r="^26.1" /> | Any version in the same major | `26.1.2`, `26.2`, `26.3`... | `25.x`, `27.x`... |
+
+:::
+
+```json
+"depends": {
+    "example-mod": "*",
+    "minecraft": [
+        "26.1",
+        "26.1.1"
+    ]
+}
+"suggests": {
+    "another-mod": ">1.0.0"
+}
+```
+
+## Metadata {#metadata}
+
+- **`name`**: A string that defines the user-friendly mod's name. If not present, assume it matches **id**.
+- **`description`**: A string that defines the mod's description. If not present, assume empty string.
+
+```json
+"name": "Example Mod",
+"description": "This is an example description! Tell everyone what your mod is about!",
+```
+
+### Contact {#contact}
+
+**`contact`**: A dictionary that defines the contact information for the project. Some common fields include:
+
+- **`email`**: A string that defines the contact e-mail pertaining to the mod. Must be a valid e-mail address.
+- **`homepage`**: A string that defines the project or user's homepage. Must be a valid HTTP/HTTPS address.
+- **`irc`**: A string that defines the IRC channel pertaining to the mod. Must be of a valid URL format - for example: `irc://irc.esper.net:6667/charset` for `#charset` at EsperNet - the port is optional, and assumed to be 6667 if not present.
+- **`issues`**: A string that defines the project's issue tracker. Must be a valid HTTP/HTTPS address.
+- **`sources`**: A string that defines the project's source code repository. Must be a valid URL - it can, however, be a specialized URL for a given VCS (such as Git or Mercurial).
+
+The list is not exhaustive - mods may provide additional non-standard keys, such as **`discord`**, **`slack`**, **`twitter`**... If possible, those should be valid URLs.
+
+```json
+"contact": {
+    "homepage": "https://fabricmc.net",
+    "sources": "https://github.com/FabricMC/fabric-example-mod"
+}
+```
+
+### Authors and Contributors {#authors-contributors}
+
+- **`authors`** An array of authors of the mod. Entries can be either a string or an object with the fields listed below.
+- **`contributors`** An array of contributors to the mod. Entries can be either a string or an object with the fields listed below.
+
+Fields:
+
+- **`name`** A mandatory string for the person's real name, or username.
+- **`contact`** An optional object for the person's contact information. The same as upper level [**`contact`**](#contact).
+
+```json
+"authors": [
+    "Me!",
+    {
+        "name": "Tiny Potato",
+        "contact": {
+          "homepage": "https://fabricmc.net",
+          "sources": "https://github.com/FabricMC/fabric-example-mod"
+        }
+    }
+]
+```
+
+### License {#license}
+
+- **`license`** A string or array that defines the licensing information.
+
+This should provide the complete set of preferred licenses conveying the entire mod package. In other words, compliance with all listed licenses should be sufficient for usage, redistribution, etc. of the mod package as a whole.
+
+For cases where a part of code is dual-licensed, choose the preferred license. The list is not exhaustive, serves primarily as a kind of hint, and does not prevent you from granting additional rights/licenses on a case-by-case basis.
+
+To aid automated tools, it is recommended to use [SPDX License Identifiers](https://spdx.org/licenses/) for open-source licenses.
+
+```json
+"license": "CC0-1.0"
+```
+
+### Icon {#icon}
+
+- **`icon`** A string or dictionary that defines the mod's icon. Icons are square PNG files. Minecraft resource packs use 128×128, but that is not a hard requirement - a power of two is, however, recommended. Can be provided in one of two forms:
+  - A path to a single PNG file.
+  - A dictionary of images widths to their files' paths.
+
+```json
+"icon": "assets/example-mod/icon.png"
+```
+
+## Custom Fields {#custom-fields}
+
+You can add any field you want to add inside `custom` field. Loader would ignore them. However, it's highly recommended to namespace your fields to avoid conflicts with other mods.