DOCSEARCHbyAlgolia
Submit Docs

Fabric API Documentation

repository·26.2·Indexed 25 days ago

https://github.com/fabricmc/fabric-api

A library providing essential hooks, interoperability mechanisms, and APIs for Fabric mods. It includes systems for lifecycle events (client and server), loot table modification, resource loading, tag alias groups, and a Transfer API for atomic item and fluid storage operations. It also provides API lookup mechanisms for blocks, items, and entities, as well as transitive access wideners to bypass Minecraft source code visibility restrictions.

Tokens
4.9K
Snippets
6
Records
46
Agent score
84%

What's inside Fabric API

  1. Use Fabric Lifecycle Events (V1)

    26.2

    Fabric Lifecycle Events (V1) provide hooks to respond to changes in the lifecycle of the Minecraft client, the Minecraft server, and various objects (worlds, chunks, entities, block entities) within them.

    Events are organized into category-specific classes. To use an event, you must implement the specific callback interface nested within that category class. For example, to listen to ServerLifecycleEvents.SERVER_STARTING, you implement the ServerLifecycleEvents.ServerStarting interface.

  3. Define Tag Alias Groups in data packs

    26.2

    You can merge multiple tags so they refer to the same set of registry entries using Tag alias groups. When tags are aliased in a group, they are linked together and share the combined set of entries from all tags in that group.

    To define alias groups, create JSON files in your data pack at the following location: data/<mod namespace>/fabric/tag_alias/<registry>

    Note: <registry> is the path of the registry's ID. If the registry is not minecraft, prefix the ID with <registry's namespace>/.

    The JSON format must be an object containing a tags list of plain tag IDs.

  4. Include specific Fabric API modules in a development environment

    26.2

    Instead of the full API, you can include individual modules. This approach allows you to include the module jar directly into your mod jar using the include configuration. Replace FABRIC_API_VERSION with your target version.

    Groovy DSL

    // Make a collection of all api modules we wish to use
Set<String> apiModules = [
    "fabric-api-base",
    "fabric-command-api-v1",
    "fabric-lifecycle-events-v1",
    "fabric-networking-api-v1"
]

// Add each module as a dependency
apiModules.forEach {
    include(implementation(fabricApi.module(it, FABRIC_API_VERSION)))
}

    Kotlin DSL

    // Make a set of all api modules we wish to use
setOf(
    "fabric-api-base",
    "fabric-command-api-v1",
    "fabric-lifecycle-events-v1",
    "fabric-networking-api-v1"
).forEach {
    // Add each module as a dependency
    implementation(fabricApi.module(it, FABRIC_API_VERSION))
}

  5. Include the full Fabric API in a development environment

    26.2

    To include the complete Fabric API (all modules) in your Gradle project, add the following dependency to your dependencies block. Replace FABRIC_API_VERSION with the desired version.

    Groovy DSL

    implementation "net.fabricmc.fabric-api:fabric-api:FABRIC_API_VERSION"

    Kotlin DSL

    implementation("net.fabricmc.fabric-api:fabric-api:FABRIC_API_VERSION")

  6. Implement custom API lookups for custom objects

    26.2

    The net.fabricmc.fabric.api.lookup.v1.custom subpackage provides helper classes to implement custom ApiLookup logic for objects other than blocks, items, or entities.

    • Use ApiLookupMap as backing storage for custom ApiLookup instances to implement functionality similar to BlockApiLookup#get.
    • Use ApiProviderMap as a fast, thread-safe, copy-on-write map to serve as backing storage for registered providers.

  8. Remove entries from tags using fabric:remove

    26.2

    To exclude specific entries from a tag (such as removing values from gameplay-facing tags or excluding entries from referenced tags), use the fabric:remove field in your tag JSON files.

    This field accepts an array of entries following the same syntax as the standard values field.

  9. Register client-side commands using ClientCommands

    26.2

    Client-side commands are executed fully on the client, allowing them to work in both singleplayer and multiplayer environments. To register commands, use the ClientCommandRegistrationCallback.EVENT.

    Important Considerations:

    • Threading: Commands run on the client game thread by default. Avoid heavy calculations here to prevent freezing the game's rendering; move heavy logic to another thread if necessary.
    • Security: For commands performing destructive or privileged operations, use FabricClientCommandSource#attended() to ensure they only run when explicitly entered by the user and not via server-provided text components.
    • Precedence: If a client-side command and a server-side command share the same name, the behavior is an implementation detail, though the API aims to prioritize server-side commands in the future.
    ClientCommandRegistrationCallback.EVENT.register((dispatcher, buildContext) -> {
	dispatcher.register(
		ClientCommands.literal("hello").executes(context -> {
			context.getSource().sendFeedback(Component.literal("Hello, world!"));
			return 0;
		})
	);
});

  11. Handle Fluid transfer with FluidVariant

    26.2

    Fluid storage is implemented as a Storage<FluidVariant>, where FluidVariant is an immutable combination of a Fluid and additional components.

    Key details:

    • Access fluid storage instances via FluidStorage API lookups.
    • The unit of measurement is droplets (1/81000th of a bucket). Use FluidConstants for droplet-related constants.
    • For custom client-side rendering of fluids based on their components, register a FluidVariantRenderHandler.

  12. Access Client Lifecycle Events

    26.2

    Client-side lifecycle events are located in net.fabricmc.fabric.api.client.event.lifecycle.v1.

    CRITICAL: These events are only available on a client. Attempting to access these events on a dedicated server will cause the game to crash.

    Available event categories include:

    • ClientLifecycleEvents: Minecraft Client starting or stopping.
    • ClientTickEvents: Beginning and end of ticks for the client and the ClientWorld (if in-game).
    • ClientWorldEvents: Occurs after a ClientWorld has been changed.
    • ClientChunkEvents: Loading and unloading of chunks in a ClientWorld.
    • ClientEntityEvents: Entity loading into a ClientWorld.
    • ClientBlockEntityEvents: Loading and unloading of block entities in a ClientWorld.