Document plugin API

Author: Su5eD

README.md

@@ -120,6 +120,14 @@ dependencies {
 }
 ```
 
+### Transformer Plugins
+
+Developers can create addons that register their own jar transformers and Mixin method patches in addition to those
+provided by Connector.
+
+See the [Plugins](https://moddedmc.wiki/en/project/connector/latest/docs/plugins) documentation page for a guide. Code
+documentation is available in the `org.sinytra.connector.transformer.api` package.
+
 ## ⚙️ Configuration
 
 All information regarding Connector's configuration options can be found on

build.gradle.kts

@@ -117,6 +117,7 @@ dependencies {
     implementation("org.sinytra.adapter:core:$versionAdapterCore") { isTransitive = false }
     implementation("net.fabricmc:class-tweaker:$versionClassTweaker") { isTransitive = false }
     implementation("org.sinytra:AutoRenamingTool:$versionAutoRenamingTool") { isTransitive = false }
+    api(project(":transformer"))
     implementation(project(":transformer")) { isTransitive = false }
 
     jarJar(implementation(group = "org.sinytra.adapter", name = "runtime", version = versionAdapterRuntime))

docs/.assets/item/connector/placeholder_mod_dependencies.png

@@ -2,5 +2,6 @@
   "introduction.mdx": "Introduction",
   "configuration.mdx": "Configuration",
   "developers.mdx": "Developers",
+  "plugins.mdx": "Plugins",
   "faq.mdx": "Frequently Asked Questions"
 }

…ssets/item/connector/mixin_safeguard.png docs/assets/connector/mixin_safeguard.pngdocs/.assets/item/connector/mixin_safeguard.png renamed to docs/assets/connector/mixin_safeguard.png docs/.assets/item/connector/mixin_safeguard.png renamed to docs/assets/connector/mixin_safeguard.png

@@ -0,0 +1,112 @@
+---
+title: Developers
+hide_meta: true
+---
+
+Connector provides various APIs and configuration options for developers to make it easier to bring their mod onto
+the platform.
+
+## Detecting Connector's presence
+
+You can use the APIs provided by Fabric's `FabricLoader` and FML's `ModList` to detect Connector's presence in your
+mods.
+
+- Connector's FML modid is `connector`.
+
+- The Forgified Fabric API uses `fabric_api` as its main mod id.
+  All of its modules follow upstream mod id's where dashes (`-`) are replaced by underscores (`_`) to comply with FML's
+  requirements.<br/> (e.g. `fabric-transfer-api-v1` -> `fabric_transfer_api_v1`)
+
+## Consider Launchpad
+
+If you're a mod developer looking to make your Fabric mod run on NeoForge through Connector, we recommend using
+[Launchpad](https://github.com/Sinytra/Launchpad) instead.
+
+Unlike Connector, Launchpad requires explicit opt-in and doesn't make any changes to the mod,
+keeping the developer fully in control. It offers the same features in a lighter and predictable package.
+
+## Placeholder mods
+
+### Motivation
+
+As a developer, you may be interested in officially supporting your mod on Forge via Connector. One possibility is
+publishing a "Forge" labelled release to platforms such as CurseForge and Modrinth. Under the hood, this is still a
+Fabric mod jar, except it has an additional dependency added on Connector.
+
+While this is a clever way to trick the modpack manager into running Fabric mods on Forge, it doesn't offer any way of
+informing the user about the Connector dependency in case it is downloaded manually. The mod file is still a Fabric jar
+that gets ignored by FML, leaving users potentially confused about why the "Forge" mod they installed is not loading.
+
+Including a dummy FML mod metadata file might help resolve this issue, but at the same time, it would lead Connector to
+ignore the mod completely, as it does with all FML mod jars.
+
+### Integration
+
+To overcome this issue, Connector offers a placeholder mod feature that allows developers to safely depend on Connector
+and notify users of missing dependencies without causing issues with duplicate mod IDs. To enable this feature, include
+a standard FML metadata file in your Forge release modmfile with the following lines:
+
+```toml copy title="neoforge.mods.toml"
+[properties]
+"connector:placeholder"=true
+```
+
+This will let Connector know the mod's FML metadata only acts as a placeholder, and it won't consider the file a FML
+mod, proceeding to load it as a Fabric mod instead. You can now safely declare a dependency on Connector without having
+to worry about it being ignored. FML will promptly alert the user in case Connector is missing.
+
+```toml copy title="neoforge.mods.toml"
+[[dependencies.examplemod]]
+modId="connector"
+type="required"
+versionRange="*"
+ordering="NONE"
+side="BOTH"
+```
+
+<p/>
+
+<details>
+  <summary>Show full example</summary>
+
+  ```toml {5-6,29-34} title="neoforge.mods.toml"
+  modLoader="javafml"
+  loaderVersion="*"
+  license="CC0-1.0"
+
+  [properties]
+  "connector:placeholder"=true
+
+  [[mods]]
+  modId="examplemod"
+  version="1.0.0"
+  displayName="Example Mod"
+  authors="example"
+  description='''Example Mod'''
+
+  [[dependencies.examplemod]]
+  modId="neoforge"
+  type="required"
+  versionRange="[26.1,)"
+  ordering="NONE"
+  side="BOTH"
+
+  [[dependencies.examplemod]]
+  modId="minecraft"
+  type="required"
+  versionRange="[26.1,)"
+  ordering="NONE"
+  side="BOTH"
+
+  [[dependencies.examplemod]]
+  modId="connector"
+  type="required"
+  versionRange="*"
+  ordering="NONE"
+  side="BOTH"
+  ```
+</details>
+
+Here's how the resulting FML dependency error looks like:
+
+<Asset width="966" title="FML Dependency Error" location="connector:placeholder_deps" />

docs/assets/connector/placeholder_deps.png

@@ -10,8 +10,8 @@ to reflect the current state of the mod. If your question is not listed, we'll b
 ## ❌️ Backports
 
 Backports to Minecraft versions older than 1.20.1 are **not planned**. Our focus is on future versions where
-compatibility will improve over time as major blockers are patched upstream, such as [Mixin](https://github.com/Sinytra/Connector/discussions/383) or transformable mc
-libraries.
+compatibility will improve over time as major blockers are patched upstream, such as
+[Mixin](https://github.com/Sinytra/Connector/discussions/383) or transformable mc libraries.
 
 ## ❌️ Is OptiFine compatible?
 
@@ -26,15 +26,15 @@ Instead, we recommend using some of the available alternatives:
 
 This largely depends on how the mod's codebase and API are structured.
 
-#### Multiloader mods
+### Multiloader mods
 
 Some mods use a multiloader setup in which most code is shared between platforms, including the public API.
 In these cases, the chances of proper cross-platform behavior are higher.
 
 A good example of this is [Cloth Config](https://github.com/shedaniel/cloth-config), which only contains a platform-specific classes, none of
 which are considered public API.
 
-#### Standalone ports
+### Standalone ports
 
 Other mods may consist of completely independent codebases for each modloader. This may be the case if you're playing
 an unofficial port of the mod (such as [Farmer's Delight Fabric](https://www.curseforge.com/minecraft/mc-mods/farmers-delight-fabric)) or the author intended so themselves.
@@ -77,21 +77,23 @@ regardless of the mod, increasing the chances of getting other mods working in t
 
 #### 🛠️ Modpack / general issues and crashes
 
-If you're having trouble running Connector, feel free to join our community on [Discord](https://discord.sinytra.org), where we'll be happy to
-help you out in the [#support](https://discord.com/channels/1141048834177388746/1141062824265793650) channel. When opening a thread, please make sure
-to provide a description of your issue and include the necessary game logs.
+If you're having trouble running Connector, feel free to join our community on [Discord](https://discord.sinytra.org),
+where we'll be happy to help you out in the
+[#support](https://discord.com/channels/1141048834177388746/1141062824265793650) channel. When opening a thread, please
+make sure to provide a description of your issue and include the necessary game logs.
 
 #### 🐞 Confirmed bugs / Forge mod interference
 
-Connector bugs should be submitted on our [issue tracker](https://github.com/Sinytra/Connector/issues). Each issue is reviewed and processed equally,
-so even if we can't get to you immediately, please bear with us.
+Connector bugs should be submitted on our [issue tracker](https://github.com/Sinytra/Connector/issues). Each issue is
+reviewed and processed equally, so even if we can't get to you immediately, please bear with us.
 
 Here's a few tips to follow when reporting issues:
 
 1. Make sure you are using latest available version. Look for existing issues that might've already been
 answered / fixed. Think about whether the issue is caused by Connector itself and not another mod you've installed.
 To test this, try reproducing the same issue on Fabric.
-2. Navigate to [the issues tab](https://github.com/Sinytra/Connector/issues) and open a [new issue](https://github.com/Sinytra/Connector/issues/new/choose).
+2. Navigate to [the issues tab](https://github.com/Sinytra/Connector/issues) and open a
+[new issue](https://github.com/Sinytra/Connector/issues/new/choose).
 Select one of the available templates depending on the topic. Read the template carefully and thoroughly.
 Fill in the required fields. In order to increase our chances of identifying and reproducing the issue, please make sure
 to include as many details as possible.