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,

develop/loader/fabric-mod-json.md

@@ -0,0 +1,200 @@
+---
+title: fabric.mod.json
+description: A guide to the `fabric.mod.json` specification.
+authors:
+  - cassiancc
+  - falseresync
+  - jamieswhiteshirt
+  - IMB11
+authors-nogithub:
+  - skyland1a
+  - solidblock
+
+---
+
+The `fabric.mod.json` file is a metadata file used by Fabric Loader to load mods. In order to be loaded, a mod must have this file with the exact name placed in the root directory of the mod JAR.
+
+## Mandatory Fields {#mandatory-fields}
+
+- **`schemaVersion`** Must always be `1`. Required for Fabric Loader to parse the file correctly.
+- **`id`** A string value that defines the mod's identifier - allowed characters include Latin letters, digits, underscores, and hyphens, with length from 2 to 64.
+- **`version`** A string value that defines the mod's version, expected to match the [Semantic Versioning 2.0.0](https://semver.org/) specification. The template mod populates this automatically from the version set in `gradle.properties`.
+
+```json
+"schemaVersion": 1,
+"id": "example-mod",
+"version": "${mod_version}",
+```
+
+## Optional Fields {#optional-fields}
+
+### Mod Loading {#mod-loading}
+
+#### 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 or in singleplayer.
+
+```json
+"name": "Example mod",
+"description": "This is an example description! Tell everyone what your mod is about!",
+```
+
+#### Entrypoints
+- **`entrypoints`** An object that defines the main classes of your mod. that will be loaded.
+    - **`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 provides three main entrypoints, but other mods may provide their own (i.e. `modmenu` for Mod Menu entrypoints). Each entry point can contain any number of classes to load. 
+
+Classes (or methods or static fields) could be defined in two ways. If you're using Java, then just list the classes (or else) full names. For example: 
+
+```json
+"main": [
+    "net.fabricmc.example.ExampleMod",
+    "net.fabricmc.example.ExampleMod::handle"
+]
+```
+
+If you're using any other language, consult the language adapter's documentation. The Kotlin one can be found on [Fabric Language Kotlin's README](https://github.com/FabricMC/fabric-language-kotlin/blob/master/README.md).
+
+#### Jars
+
+- **`jars`**: An array of nested JARs inside your mod's JAR to load. When using Loom, using `include` on your dependencies will automatically populate this. Each entry is an object containing `file` key. That should be a path inside your mod's JAR to the nested JAR. For example: 
+
+```json
+"jars": [
+   {
+      "file": "nested/vendor/dependency.jar"
+   }
+]
+```
+
+#### Language Adapaters {#language-adapters}
+
+- **`languageAdapters`**: A dictionary of adapters for used languages to their adapter classes full names. For example: 
+
+```json
+"languageAdapters": {
+   "kotlin": "net.fabricmc.language.kotlin.KotlinAdapter"
+}
+```
+
+#### Mixins {#mixins}
+
+- **`mixins`**: A list of mixin configuration files. Each entry is the path to the mixin configuration file inside your mod's JAR or an object containing following fields:
+    - **`config`**: The path to the mixin configuration file inside your mod's JAR.
+    - **`environment`**: The same as upper level **environment** field. See above. For example: 
+
+``` json
+"mixins": [
+   "modid.mixins.json",
+   {
+      "config": "modid.client-mixins.json",
+      "environment": "client"
+   }
+]
+```
+
+#### Provides {#provides}
+
+- **`provides`**： An array of mod ids Defines the list of ids of mod. It can be seen as the aliases of the mod. Fabric Loader will treat these ids as mods that exist. If there are other mods using that id, they will not be loaded.
+
+``` json
+"provides": [
+   "example_mod"
+]
+```
+
+### Dependency Resolution {#dependency-resolution}
+
+The key of each entry of the objects below is a Mod ID of the dependency.
+
+The value of each key is a string or array of strings declaring supported version ranges. In the case of an array, an "OR" relationship is assumed - that is, only one range has to match for the collective range to be satisfied.
+
+In the case of all versions, * is a special string declaring that any version is matched by the range. In addition, exact string matches must be possible regardless of the version type.
+
+- **`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.
+
+```json
+"depends": {
+    "example-mod": "*"
+}
+"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.
+
+#### Contact {#contact}
+
+- **`contact`**: A dictionary that defines the contact information for the project.
+    - **`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`**, etc) - if possible, they should be valid URLs.
+
+```json
+"contact": {
+    "homepage": "https://fabricmc.net",
+    "sources": "https://github.com/FabricMC/fabric-example-mod"
+}
+```
+
+#### Authors and Contributors {#authors-contributors}
+
+`authors` and `contributors` are both arrays of strings or objects containing following fields:
+- **`name`** The real name, or username, of the person. Mandatory.
+- **`contact`** Person's contact information. The same as upper level **contact**. See above. Optional.
+
+- **`authors`** An array of authors of the mod.
+- **`contributors`** An array of contributors to the mod.
+
+```json
+"authors": [
+    "Me!",
+    {
+        "name": "Tiny Potato"
+    }
+]
+```
+
+#### 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`** 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/modid/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.

develop/loader/index.md

@@ -0,0 +1,67 @@
+---
+title: Fabric Loader
+description: The lightweight mod loader that powers the Fabric project.
+authors:
+  - cassiancc
+  - falseresync
+  - jamieswhiteshirt
+  - Llamalad7
+authors-nogithub:
+  - liach
+  - solidblock
+
+---
+
+Fabric Loader is Fabric's lightweight mod loader. It provides the necessary tools to make Minecraft modifiable without depending on a specific version of the game. Game specific (and game version specific) hooks belong in Fabric API. It is possible to adapt Fabric Loader for many Java applications (for instance games like Slay the Spire and Starmade).
+
+Fabric Loader has services to allow mods to have some code executed during initialization, to transform classes, declare and provide mod dependencies, all in a number of different environments.
+
+For each Fabric Loader version, there is Javadoc available at
+`https://maven.fabricmc.net/docs/fabric-loader-[loader version]`
+For example, Fabric Loader 0.18.6's documentation is at https://maven.fabricmc.net/docs/fabric-loader-0.18.6/
+
+The current instance of Fabric Loader can be retrieved by using `FabricLoader.getInstance()`. As an example, `FabricLoader.getInstance().isModLoaded` can be used to check for the presence of another running mod.
+
+## Mods {#mods}
+
+A mod is a jar with a [`fabric.mod.json`](./fabric-mod-json) mod metadata file in its root declaring how it should be loaded. It primarily declares a mod ID and version as well as [entrypoints](https://wiki.fabricmc.net/documentation:entrypoint) and mixin configurations. The mod ID identifies the mod so that any mod with the same ID is considered to be the same mod. Only one version of a mod may be loaded at a time. A mod may declare other mods that it depends on or conflicts with. Fabric Loader will attempt to satisfy dependencies and load the appropriate versions of mods, or fail to launch otherwise.
+
+Fabric Loader makes all mods equally capable of modifying the game. As an example, anything Fabric API does can be done by any other mod.
+
+Mods are loaded both from the classpath and from the mods directory. They are expected to match the mappings in the current environment, meaning Fabric Loader will not remap any mods.
+
+## Nested JARs {#nested-jars}
+
+Nested JARs allow a mod to provide its own dependencies, so Fabric Loader can pick the best version matching the dependencies instead of requiring separate installation of dependencies. They also allow clean packaging of submodules, so each module can be used separately. Non-mod libraries can be repackaged as mods for nested JAR usage. A mod may bundle a number of other mods within its JAR. A nested JAR must itself also be a mod, which again can have nested JARs. Fabric Loader will load nested JARs while attempting to satisfy dependency constraints.
+
+Nested JARs are not extracted, they are instead loaded in in-memory file system using jimfs. Nested JARs must be declared by their paths relative to the containing JAR's root.
+
+Using Fabric Loom's `include` option will automatically handle nesting the jar.
+
+## Entrypoints {#entrypoints}
+
+Fabric Loader has an [entrypoint](https://wiki.fabricmc.net/documentation:entrypoint) system, which is used by mods to expose parts of the code for usage by Fabric Loader or other mods. Fabric Loader uses it for mod initialization. Initializers are loaded and called early during the game's initialization which allows a mod to run some code to make its modifications. These entrypoints are typically used to bootstrap mods by registering registry objects, event listeners and other callbacks for doing things later.
+
+## Mixin {#mixin}
+
+Mixin allows mods to transform Minecraft classes and even mod classes, and is the only method of class transformation that Fabric Loader officially supports. A mod can declare its own mixin configuration which enables the use of Mixin.
+
+Mixin was not originally made for Fabric, so Fabric Loader uses a modified version of Mixin. However, the documentation of the upstream version is still mostly valid. Fabric's modifications include allowing all default injection points inside constructors, optimizing out unused callback infos, providing fixes for backwards compatibility, fixing static shadows, allowing injectors in interfaces, and more.
+
+<!-- Referenced comments from LlamaLad7 on Fabric Mixin. https://discord.com/channels/507304429255393322/566418023372816394/1002211121903706162 -->
+
+## Mappings {#mappings}
+
+:::info
+
+Mappings are only relevant when using Fabric Loader on obfuscated games, including pre-26.1 versions of Minecraft.
+
+:::
+
+Fabric Loader provides the `MappingResolver` API to determine names of classes, fields and methods with respect to the different environments that mods may be loaded in. This can be used to support reflection in any environment provided Fabric Loader has access to mappings to resolve the name.
+
+```java
+FabricLoader.getInstance().getMappingResolver().mapClassName("intermediary", "net.minecraft.class_5421") // Resolves to `RecipeBookType` on named versions
+```
+
+When launched in a non-development environment on an obfuscated game, Fabric Loader will [remap](/porting/mappings/#mappings) the Minecraft jar and Realms client jar to intermediary names. Mods designed for obfuscated games are expected to be mapped to intermediary, which will be compatible with this environment. The remapped jars are cached and saved in `${gameDir}/.fabric/remappedJars/${minecraftVersion}` for re-use across launches.

sidebar_translations.json

@@ -67,6 +67,9 @@
   "develop.rendering.gui.custom_widgets": "Custom Widgets",
   "develop.rendering.particles": "Particles",
   "develop.rendering.particles.creating_particles": "Creating Custom Particles",
+  "develop.loader": "Fabric Loader",
+  "develop.loader.index": "Introduction",
+  "develop.loader.fabric.mod.json": "fabric.mod.json",
   "develop.loom": "Loom",
   "develop.loom.introduction": "Introduction",
   "develop.loom.fabric_api": "Fabric API DSL",