Minecraft 26.1.2 · Fabric Dev

# Core versions
minecraft_version=26.1.2
loader_version=0.18.4
fabric_version=0.149.1+26.1.2

# Mod metadata
mod_version=1.0.0
maven_group=com.yourname
archives_base_name=mymod

# Java 25 — point Gradle at your JDK 25 install
org.gradle.java.home=/path/to/jdk-25
org.gradle.jvmargs=-Xmx2G

plugins {
  id 'net.fabricmc.fabric-loom' version "${loom_version}"
  id 'java'
}

java {
  sourceCompatibility = JavaVersion.VERSION_25
  targetCompatibility = JavaVersion.VERSION_25
}

dependencies {
  minecraft "com.mojang:minecraft:${minecraft_version}"
  // No mappings line — game is unobfuscated

  // Fabric API: use implementation (not modImplementation)
  implementation "net.fabricmc.fabric-api:fabric-api:${fabric_version}"

  // Fabric Loader: still uses modImplementation
  modImplementation "net.fabricmc:fabric-loader:${loader_version}"
}

// Use 'jar' not 'remapJar'
jar {
  from("LICENSE") { into "META-INF" }
}

{
  "schemaVersion": 1,
  "id": "mymod",
  "version": "1.0.0",
  "name": "My Mod",
  "description": "Does cool stuff",
  "environment": "*",
  "entrypoints": {
    "main":   ["com.mymod.MyMod"],
    "client": ["com.mymod.MyModClient"]
  },
  "mixins": ["mymod.mixins.json"],
  "depends": {
    "fabric-api": ">=0.149.1",
    "fabricloader": ">=0.18.4",
    "minecraft": ">=26.1.2"
  }
}

src/main/resources/
├── fabric.mod.json
├── mymod.mixins.json
├── assets/mymod/
│   ├── models/item/        ← item models (.json)
│   ├── models/block/       ← block models (.json)
│   ├── textures/item/      ← item textures (.png)
│   ├── textures/block/
│   ├── textures/entity/
│   ├── blockstates/        ← blockstate definitions
│   ├── sounds.json
│   └── lang/en_us.json     ← display names
└── data/mymod/
    ├── recipe/             ← crafting recipes
    ├── loot_table/         ← loot tables
    ├── advancement/
    ├── villager_trade/     ← new in 26.1!
    └── trade_set/          ← new in 26.1!

src/main/java/com/mymod/
├── MyMod.java              ← main entrypoint
├── MyModClient.java        ← client entrypoint
├── block/ModBlocks.java
├── item/ModItems.java
├── entity/ModEntities.java
└── mixin/

// Main entrypoint — runs on BOTH sides
public class MyMod implements ModInitializer {
  public static final String MOD_ID = "mymod";
  public static final Logger LOGGER =
    LoggerFactory.getLogger(MOD_ID);

  @Override
  public void onInitialize() {
    ModItems.register();
    ModBlocks.register();
    ModEntities.register();
    LOGGER.info("Mymod loaded!");
  }
}

// Client entrypoint — client ONLY (rendering, UI)
public class MyModClient implements ClientModInitializer {
  @Override
  public void onInitializeClient() {
    EntityRendererRegistry.register(
      ModEntities.MY_ENTITY, MyEntityRenderer::new);
  }
}

A record is a class that holds data and nothing else. Java auto-generates constructor, getters, equals, hashCode, and toString. Great for config values, data packets, and snapshots.

// Define a record
public record SpawnData(ResourceLocation entityId, int count) {}

// Create one
SpawnData data = new SpawnData(
  ResourceLocation.parse("minecraft:zombie"), 3);

// Access fields (auto-generated getter = field name)
data.entityId(); // → minecraft:zombie
data.count();    // → 3

// Records are immutable — no setters, can't change fields
// Perfect for custom packet payloads (StreamCodec records)

A supercharged switch that can match on type and destructure objects. Replaces long if/instanceof chains.

// Old way
if (entity instanceof Player) {
  Player p = (Player) entity;
  p.sendMessage(...);
} else if (entity instanceof Zombie) { ... }

// New way — cleaner, no manual casts
switch (entity) {
  case Player p          -> p.sendMessage(...);
  case Zombie z          -> z.setTarget(null);
  case LivingEntity l
    when l.isOnFire()    -> doFireStuff(l);
  default                -> {}
}
// The 'when' clause adds an extra condition to a case

A sealed class/interface declares exactly which classes can extend it. Great for representing a fixed set of states or outcomes that you want to pattern-match over.

// Declare sealed — only listed classes may implement it
public sealed interface UseResult
    permits UseResult.Success, UseResult.Fail, UseResult.Pass {

  record Success(int cooldown) implements UseResult {}
  record Fail(String reason) implements UseResult {}
  record Pass() implements UseResult {}
}

// Now switch is exhaustive — no default needed
switch (result) {
  case UseResult.Success s -> applyCooldown(s.cooldown());
  case UseResult.Fail f    -> logFailure(f.reason());
  case UseResult.Pass p   -> {}
}

Multi-line strings with """. Indentation is automatically stripped. Great for inline JSON, data generation, or debug output.

// Triple-quote string — preserves formatting
String recipe = """
    {
      "type": "minecraft:crafting_shaped",
      "pattern": ["XXX", "XYX", "XXX"],
      "key": {
        "X": { "item": "minecraft:iron_ingot" },
        "Y": { "item": "mymod:magic_gem" }
      }
    }
    """;

// Useful for multi-line log messages too
LOGGER.info("""
    Mod loaded!
    Version: {}
    Blocks registered: {}
    """, mod_version, blockCount);

Virtual threads are lightweight threads managed by the JVM rather than the OS. Useful for async tasks — but never use them for Minecraft tick logic, which must stay on the main thread.

// Platform thread (old, heavy)
new Thread(() -> doWork()).start();

// Virtual thread (Java 25, lightweight)
Thread.ofVirtual().start(() -> {
  fetchDataFromExternalAPI();
});

// With a name (useful for debugging)
Thread.ofVirtual()
     .name("mymod-loader")
     .start(() -> loadConfigAsync());

// instanceof with capture (Java 16+, fully standard in 25)
if (entity instanceof Player p) {
  // 'p' is already cast — no manual cast needed
  p.getCooldowns().addCooldown(...);
}

// var — infers type automatically
var pos = entity.blockPosition();
// pos is BlockPos — Java figures it out

// String formatting (no more concat mess)
String msg = String.format("Entity %s at %s", entity, pos);
// or using formatted() shorthand:
String msg2 = "Entity %s at %s".formatted(entity, pos);

public class ModItems {
  public static final Item MAGIC_SWORD =
    register("magic_sword",
      new SwordItem(
        ToolMaterial.NETHERITE,
        7, -2.4f,
        new Item.Properties()));

  public static final Item MAGIC_FOOD =
    register("magic_food",
      new Item(new Item.Properties()
        .food(new FoodProperties.Builder()
          .nutrition(6).saturationModifier(1.2f)
          .build())));

  private static Item register(String name, Item item) {
    return Registry.register(
      BuiltInRegistries.ITEM,
      ResourceLocation.fromNamespaceAndPath(MyMod.MOD_ID, name),
      item);
  }

  public static void register() {
    MyMod.LOGGER.info("Registering items");
  }
}

public class ModBlocks {
  public static final Block CRYSTAL_BLOCK =
    register("crystal_block",
      new Block(BlockBehaviour.Properties
        .ofFullCopy(Blocks.AMETHYST_BLOCK)
        .lightLevel(state -> 10)
        .strength(3.0f, 6.0f)));

  private static Block register(String name, Block block) {
    ResourceLocation id =
      ResourceLocation.fromNamespaceAndPath(MyMod.MOD_ID, name);
    // Register BlockItem alongside the block
    Registry.register(BuiltInRegistries.ITEM, id,
      new BlockItem(block, new Item.Properties()));
    return Registry.register(
      BuiltInRegistries.BLOCK, id, block);
  }

  public static void register() {}
}

// Add items to an existing tab
CreativeModeTabEvents.MODIFY_ENTRIES.register(
  CreativeModeTabs.COMBAT,
  (content, canAdd) -> {
    content.addAfter(Items.NETHERITE_SWORD,
      ModItems.MAGIC_SWORD);
  });

// Create a custom tab
Registry.register(BuiltInRegistries.CREATIVE_MODE_TAB,
  ResourceLocation.fromNamespaceAndPath(MyMod.MOD_ID, "main"),
  CreativeModeTab.builder()
    .title(Component.translatable("itemGroup.mymod"))
    .icon(() -> new ItemStackTemplate(ModItems.MAGIC_SWORD))
    .displayItems((params, output) -> {
      output.accept(ModItems.MAGIC_SWORD);
      output.accept(ModItems.MAGIC_FOOD);
    })
    .build());

ColorProviderRegistry was removed. Use the new BlockColorRegistry.

// OLD (pre-26.1)
ColorProviderRegistry.BLOCK.register(
  (state, level, pos, tint) -> 0x66FF99,
  ModBlocks.MY_BLOCK);

// NEW (26.1)
BlockColorRegistry.register(
  List.of(new BlockTintSource() {
    @Override
    public int calculate(
        BlockState state,
        BlockAndTintGetter level,
        BlockPos pos,
        int tintIndex) {
      return 0x66FF99;
    }
  }),
  ModBlocks.MY_BLOCK);

// In MyModClient.onInitializeClient()
EntityRendererRegistry.register(
  ModEntities.MY_ENTITY,
  MyEntityRenderer::new);

// Minimal renderer extending MobRenderer
public class MyEntityRenderer
    extends MobRenderer<MyEntity, MyEntityModel<MyEntity>> {

  public MyEntityRenderer(EntityRendererProvider.Context ctx) {
    super(ctx, new MyEntityModel<>(
      ctx.bakeLayer(ModEntityModelLayers.MY_ENTITY)), 0.5f);
  }

  @Override
  public ResourceLocation getTextureLocation(MyEntity e) {
    return ResourceLocation.fromNamespaceAndPath(
      MyMod.MOD_ID, "textures/entity/my_entity.png");
  }
}

{
  "required": true,
  "package": "com.mymod.mixin",
  "compatibilityLevel": "JAVA_25",
  "mixins": [
    "LivingEntityMixin"   // both sides
  ],
  "client": [
    "GameRendererMixin"   // client only
  ],
  "injectors": {
    "defaultRequire": 1   // fail build if inject point not found
  }
}

@Mixin(LivingEntity.class)
public abstract class LivingEntityMixin {

  // Cancel fall damage
  @Inject(
    method = "hurt(Lnet/minecraft/world/damagesource/DamageSource;F)Z",
    at = @At("HEAD"), cancellable = true)
  private void onHurt(
      DamageSource src, float amount,
      CallbackInfoReturnable<Boolean> cir) {
    if (src.is(DamageTypes.FALL)) {
      cir.setReturnValue(false);
    }
  }

  // Run code at method exit (TAIL = before return)
  @Inject(method = "tick()V", at = @At("TAIL"))
  private void afterTick(CallbackInfo ci) {
    // runs at end of every LivingEntity tick
  }
}

// @Accessor — get/set a private field
@Mixin(LivingEntity.class)
public interface LivingEntityAccessor {
  @Accessor("lastHurtMob")
  LivingEntity getLastHurtMob();

  @Accessor("lastHurtMob")
  void setLastHurtMob(LivingEntity mob);
}

// Usage — cast to the accessor interface
LivingEntity lastHurt =
  ((LivingEntityAccessor) entity).getLastHurtMob();

// @Invoker — call a private method
@Mixin(LivingEntity.class)
public interface LivingEntityInvoker {
  @Invoker("dropAllDeathLoot")
  void callDropAllDeathLoot(ServerLevel level, DamageSource src);
}

# OLD (pre-26.1)
accessWidener v2 named

# NEW (26.1)
accessWidener v2 official

# Format: accessible/mutable/extendable <type> <class> [member] [descriptor]
accessible field net.minecraft.world.entity.LivingEntity
  lastHurtMob Lnet/minecraft/world/entity/LivingEntity;

accessible method net.minecraft.world.level.block.Block
  updateShape (Lnet/minecraft/world/level/block/state/BlockState;Lnet/minecraft/core/Direction;Lnet/minecraft/world/level/block/state/BlockState;Lnet/minecraft/world/LevelAccessor;Lnet/minecraft/core/BlockPos;Lnet/minecraft/core/BlockPos;)Lnet/minecraft/world/level/block/state/BlockState;

Access wideners are a compile-time alternative to @Accessor/@Invoker. They make private members publicly accessible to all your code — not just inside a mixin class.

All Fabric events use the same pattern: find the event, call .register(), pass a lambda.

// In onInitialize() or a dedicated method

// Server tick example
ServerTickEvents.END_SERVER_TICK.register(server -> {
  if (server.getTickCount() % 100 == 0) {
    MyMod.LOGGER.info("100 ticks passed");
  }
});

// Block break (cancellable)
PlayerBlockBreakEvents.BEFORE.register(
    (level, player, pos, state, entity) -> {
  if (state.is(Blocks.BEDROCK)) {
    return false; // cancel the break
  }
  return true;
});

// Loot injection
LootTableEvents.MODIFY.register((key, table, source, lookup) -> {
  if (key.equals(BuiltInLootTables.SIMPLE_DUNGEON)) {
    table.pool(LootPool.lootPool()
      .add(LootItem.lootTableItem(ModItems.MAGIC_SWORD))
      .setRolls(ConstantValue.exactly(1)));
  }
});

DimensionEvents.MODIFY_ATTRIBUTES.register(
  (dimension, attributes, registries) -> {
    if (dimension.is(BuiltinDimensionTypes.OVERWORLD)) {
      attributes.set(
        EnvironmentAttributes.CLOUD_COLOR,
        0xFF99FF);  // purple clouds!
    }
  });

These modifications have lower priority than biome-specific definitions, so they won't override biome mods.

// 1 — Define payload (record = great for this)
public record SyncPayload(String data)
    implements CustomPacketPayload {
  public static final CustomPacketPayload.Type<SyncPayload> TYPE =
    new CustomPacketPayload.Type<>(
      ResourceLocation.fromNamespaceAndPath(
        MyMod.MOD_ID, "sync"));
  public static final StreamCodec<FriendlyByteBuf, SyncPayload>
      CODEC = StreamCodec.composite(
        ByteBufCodecs.STRING_UTF8, SyncPayload::data,
        SyncPayload::new);
  @Override public Type<?> type() { return TYPE; }
}

// 2 — Register in onInitialize()
PayloadTypeRegistry.playS2C()
  .register(SyncPayload.TYPE, SyncPayload.CODEC);

// 3 — Send from server
ServerPlayNetworking.send(serverPlayer,
  new SyncPayload("hello!"));

// 4 — Receive on client (in ClientModInitializer)
ClientPlayNetworking.registerGlobalReceiver(
  SyncPayload.TYPE, (payload, ctx) -> {
    ctx.client().execute(() -> {
      // ctx.client().execute() = safely back on client thread
      MyMod.LOGGER.info(payload.data());
    });
  });

Several systems moved to datapacks in 26.1. Just create JSON files — no API registration required.

• Calling methods on null — always check if (x != null) or use instanceof before using a value that might be absent. Most common crash cause.
• Doing game logic on the wrong side — rendering code on the server crashes. World-modifying code from a client thread corrupts state. Use !level.isClientSide() guards.
• Forgetting to call register() — declaring a static final block/item but forgetting to call ModBlocks.register() in onInitialize() means it's never added to the registry.
• Missing import — if VS Code shows "cannot find symbol," you probably need to import the class. Use the quick-fix lightbulb or Ctrl+.
• Wrong method signature in @Inject — Mixin won't find the injection point and will warn or crash. Copy the exact method descriptor from generated sources.
• Forgetting f on float literals — 0.5 is a double. 0.5f is a float. Minecraft uses floats a lot for block/entity sizing.
• Using == on Strings — str == "hello" compares identity, not content. Use str.equals("hello").

• Read the crash report top-to-bottom. The cause is near the bottom under "Caused by:". Ignore the stack of indirection above it.
• Use MyMod.LOGGER.info(...) liberally. Logs show in the console during runClient.
• Run ./gradlew genSourcesWithVineflower once after setup. This lets your IDE navigate directly into Minecraft source — invaluable for understanding what methods do and finding correct signatures.
• Right-click → "Go to Definition" in VS Code (with Java extension) or IntelliJ to jump to any Minecraft class or method.
• If Gradle fails with a dependency error, try ./gradlew --refresh-dependencies to clear the cache.
• Mixin injection not firing? Check your mymod.mixins.json has the class listed and compatibilityLevel is "JAVA_25".