For Developers

This wiki page provides information on how to use Embeddium in a mod development environment, and some guidance on how to write any integrations in as compatible of a manner as possible.

If you are just looking for the Maven coordinates, you may skip to that section. However, if you are not just testing how your mod works with Embeddium, and are looking to either patch Embeddium, or call into its code, it is recommended to read the information below carefully.

How to add integration

Most mods tend to add integration either by mixing into Embeddium where needed or just calling public methods (not necessarily designated as API) to accomplish what they want. This is a bad idea, for two main reasons:

• The mod integration is often done poorly, and a more generic approach often exists that doesn't require the mod to integrate with Embeddium at all.
• We provide no guarantee of internal code remaining stable. (An exception is currently made for situations in which no proper API exists, since the API is still being defined over time.)

We recommend mods follow one of the following approaches instead. If you are unsure of what the best approach to use is, please talk to us on Discord - we don't bite. :)

Approach 1: Use or Add Platform APIs

The (Neo)Forge/Fabric APIs are quite expansive, and allow for quite a bit of control over rendering. In general, mods modifying Embeddium's renderer already need to patch the vanilla renderer themselves to accomplish what they need. The better solution is to add a standard API to your platform for the feature, and then use that API rather than writing custom mixins for vanilla yourself. Embeddium can then natively support that API, and it can be shared among mods, rather than being tailored to your specific mod. This makes the modding ecosystem better for everyone.

An example of this being done in practice is NeoForge PR #642. With this PR, NeoForge gained a standard way to append custom geometry to chunk sections, allowing Immersive Engineering wires to render with Embeddium present out of the box without either mod needing to code specific integration.

Approach 2: Use or Add Embeddium APIs

If your use case is too niche to fit an existing (or new) platform API, the next best solution is to add an API to Embeddium for the desired functionality. This is better than a direct mixin because we can ensure the API will continue working indefinitely, even as we make other code changes. It provides a well-defined contract between our renderer and other mods.

Some examples of our current APIs can be found here. More will be added if/when the need arises.

Approach 3: Direct Patch + Version Lock

This approach should be considered a last resort, as it is the most likely to introduce compatibility problems, and we are much less likely to provide support for it.

If there is absolutely no way to solve your use case with a platform or Embeddium API, the final option is to directly patch Embeddium's renderer for your purposes. This was the status quo for many Sodium/Rubidium/Embeddium integrations on Minecraft 1.20.1 and older.

Note for 1.21+: If you choose to go this route, you will be required to make your mod depend on a specific version of Embeddium, and not allow running with any other version. (You can use an optional dependency rather than a required one, though.) This prevents unnecessary support requests when your mixin inevitably breaks with a future change. Versions of Embeddium prior to 1.21 may show a warning, but will not enforce this restriction.

Obviously, this has the major downside that your mod will require an update to continue working with newer versions of Embeddium. However, it is provided as an escape hatch, and should be of particular value for versions of Minecraft we no longer support.

Maven information

Huge thanks to Jared for hosting Embeddium builds on his Maven repository. They can be accessed by adding the lines below to your Gradle buildscript. You can find a listing of all published Maven identifiers and versions here; the examples below are for 1.20.1 & 1.20.2.

repositories {
    maven {
        url "https://maven.blamejared.com"
    }
}

dependencies {
    // Example for ForgeGradle
    implementation fg.deobf("org.embeddedt:embeddium-1.20.1:0.2.11-git.23aedfb+mc1.20.1")
    // Example for Architectury Loom
    modImplementation("org.embeddedt:embeddium-1.20.1:0.2.11-git.23aedfb+mc1.20.1")
    // Example for NeoGradle 7+
    implementation("org.embeddedt:embeddium-1.20.2:0.2.11-git.9f6321d+mc1.20.2")
}