Start

Modding foundations

Learn versions, loaders, dependencies, and the different kinds of Minecraft add-ons.

Two versions of this page follow. Step by step walks through the task in order. In depth explains the underlying behavior. They describe the same product, at different levels of detail.

Step by step

Follow the steps in order. No prior modding knowledge assumed.

Most modding problems come from mixing the wrong Minecraft version, loader, or dependency. Agora exposes these details so you can make compatible choices before files are changed.

After this you will be able to

Read a compatibility label and version list confidently.
Know what each content type changes.
Recognize dependencies and conflicts before installing.

The compatibility triangle

A mod normally has to match three things: the Minecraft version, the mod loader, and the versions of other mods it depends on. A Fabric mod for Minecraft 1.21 should not be assumed to work on Quilt, NeoForge, or Minecraft 1.20.1 unless its version page explicitly says so.

Minecraft version: the game release the file was built for.
Loader: the platform that discovers and starts mods.
Dependencies: other mods or libraries required by the selected file.

Know the content types

Agora can discover more than code mods. Select the content type that matches the result you want.

Mods change game code or behavior and usually require a loader.
Packs create a complete instance from a coordinated set of content.
Resource packs change textures, sounds, fonts, or models.
Shaders change rendering and usually require a compatible shader-support mod.
Data packs change recipes, loot, world generation, or game rules for worlds.
Worlds provide playable world data; servers provide multiplayer destinations or community information.

Read compatibility before popularity

A popular project can still be wrong for your instance. Start from an instance-aware Browse search, look for Compatible, inspect the Versions page, and review the install plan before applying it.

In depth

How the system actually behaves, and why, for readers who prefer the model to a recipe.

Compatibility is a graph, not a label. Advanced modding means reasoning about exact artifacts, transitive dependencies, optional integrations, loader profiles, and configuration state.

After this you will be able to

Evaluate an install plan beyond its top-level mod.
Understand why a file can pass basic filtering and still fail at runtime.
Build repeatable test habits for complex mod sets.

Think in resolved artifacts

A project name is not the installed unit. The installed unit is a specific file with a source, game version, loader set, and hash. When troubleshooting, record the exact artifact rather than saying only that a project is installed.

Required dependencies must resolve before the operation can proceed.
Optional dependencies may unlock integrations but also enlarge the compatibility surface.
Conflicts may be declared by curators, project metadata, or the local health scanner.
A file copied in manually may have less metadata than a file installed through Agora.

Version ranges and build metadata

Loaders and projects use different version schemes. Do not compare versions as plain text. Prefer Agora's exact compatibility result and the publisher's version metadata. Fabric build metadata such as +mc1.21.1 describes the target but is not a newer semantic version by itself.

Change one variable at a time

For large instances, treat changes as experiments. Create a snapshot, install one coherent group, launch, and confirm stability before continuing. Loadout profiles can isolate feature groups without deleting files.

Start from a known-good snapshot.
Apply a reviewed install plan.
Launch and exercise the affected game area.
If stable, name a new snapshot or let a successful session promote the Last Known Good state.
If unstable, restore and revise the dependency or version choice.

This guide is the same text Agora shows in its built-in Help & Guide, which is searchable and links directly to the screens it describes.