Differences

This shows you the differences between two versions of the page.

--- tutorial:colorprovider [2024/08/26 07:11] – solidblock
+++ tutorial:colorprovider [2025/04/01 12:10] (current) – solidblock
@@ Line 18: / Line 18: @@
 ===== Block Color Provider =====
-To register a block to the block color provider, you'll need to use Fabric's ''ColorProviderRegistry''. There is an instance of the ''BLOCK'' and ''ITEM'' provider inside this class, which you can call register on. The register method takes an instance of your color provider and a varargs of every block you want to color with the provider.
+To register a block to the block color provider, you'll need to use Fabric's ''ColorProviderRegistry''. There is an instance of the ''BLOCK'' and ''ITEM'' provider inside this class, which you can call ''register'' on. The ''register'' method takes an instance of your color provider and a varargs of every block you want to color with the provider.
 At first, we create the block in ''TutorialBlocks'' class. For how to create the block, see [[blocks]]:
@@ Line 24: / Line 24: @@
 public final class TutorialBlocks {
   [...]
+  // Before 1.21.2
   public static final Block COLOR_BLOCK = register("color_block", new Block(AbstractBlock.Settings.create()));
+  // 1.21.2 and after:
+  public static final Block COLOR_BLOCK = register("color_block", Block::new, AbstractBlock.Settings.create());
 }
 </code>
@@ Line 67: / Line 70: @@
 </code>
-Then we create the block model with //tintindex//:
+Then we create the block model with //tintindex//. The model is also important: the main note here is that you are //required// to define a tintindex for each portion of the model you want to hue. To see an example of this, check out ''leaves.json'', which is the base model used for vanilla leaves. Here's the model used for our block:
-The model is also important: the main note here is that you are //required// to define a tintindex for each portion of the model you want to hue. To see an example of this, check out ''leaves.json'', which is the base model used for vanilla leaves. Here's the model used for our block:
 <code javascript src/main/resources/assets/tutorial/models/block/color_block.json>
 {
@@ Line 93: / Line 94: @@
 </code>
-In this instance, we're adding a single tintindex, which is what would appear in the ''tintIndex'' parameter (tint index 0). Actually, we can directly inherit the ''minecraft:block/leaves'' model because it also uses a cube with tintindex. Replace the model above, with:
+In this instance, we're adding a single tintindex, which is what would appear in the ''tintIndex'' parameter (tint index 0). Actually, we can directly inherit the ''minecraft:block/leaves'' model because it also uses a cube with tintindex. So you can also replace the model above, with:
 <code javascript src/main/resources/assets/tutorial/models/block/color_block.json>
 {
@@ Line 108: / Line 109: @@
 {{https://i.imgur.com/fZLS10g.png}}
-If you need to access ''BlockEntity'' data in the color provider, you'll want to implement ''RenderAttachmentBlockEntity'' to return the data you need. This is because blocks can be rendered on separate threads, so accessing the data directly is not safe. Additionally, if you query blocks with ''getBlockState'' you won't be able to view the entire world - make sure you only query within ±2 blocks x/y/z of the current position.
+===== Block Entity with Color Provider =====
+If you need to access ''BlockEntity'' data in the color provider, you'll want to override ''getRenderData()'' method from the ''RenderDataBlockEntity'', which is an interface of Fabric API but [[interface_injection|injected]] to ''BlockEntity''. If you're using old versions, try implementing ''RenderAttachmentBlockEntity'' and returning the data you need.
+This is because blocks can be rendered on separate threads, so accessing the data directly is not safe. Additionally, if you query blocks with ''getBlockState'' you won't be able to view the entire world - make sure you only query within ±2 blocks x/y/z of the current position.
+In this case, we create a ''ColorBlock'' class and a ''ColorBlockEntity'' class, and connect the block with block entity (more information see [[blockentity]]).
+<code java ColorBlock.java>
+public class ColorBlock extends BlockWithEntity {
+  public ColorBlock(Settings settings) {
+    super(settings);
+  }
+  @Override
+  protected MapCodec<? extends ColorBlock> getCodec() {
+    return createCodec(ColorBlock::new);
+  }
+  @Nullable
+  @Override
+  public BlockEntity createBlockEntity(BlockPos pos, BlockState state) {
+    return new ColorBlockEntity(pos, state);
+  }
+  // Since 1.21.4, this method is not required anymore, because all block entities use their block model by default.
+  @Override
+  protected BlockRenderType getRenderType(BlockState state) {
+    return BlockRenderType.MODEL;
+  }
+}
+</code>
+<code java ColorBlockEntity.java>
+public class ColorBlockEntity extends BlockEntity {
+  public int color = 0x3495eb;
+  public ColorBlockEntity(BlockPos pos, BlockState state) {
+    super(TutorialBlockEntityTypes.COLOR_BLOCK, pos, state);
+  }
+  // The following two methods specify serialization of color data.
+  @Override
+  protected void readNbt(NbtCompound nbt, RegistryWrapper.WrapperLookup registryLookup) {
+    super.readNbt(nbt, registryLookup);
+    // For versions before 1.21.5, please directly use nbt.getInt("color");
+    color = nbt.getInt("color");
+    // When the data is modified through "/data" command,
+    // or placed by an item with "block_entity_data" component,
+    // the render color will be updated.
+    if (world != null) {
+      world.updateListeners(pos, getCachedState(), getCachedState(), 0);
+    }
+  }
+  @Override
+  protected void writeNbt(NbtCompound nbt, RegistryWrapper.WrapperLookup registryLookup) {
+    super.writeNbt(nbt, registryLookup);
+    nbt.putInt("color", color);
+  }
+  @Nullable
+  @Override
+  public Packet<ClientPlayPacketListener> toUpdatePacket() {
+    return BlockEntityUpdateS2CPacket.create(this);
+  }
+  @Override
+  public NbtCompound toInitialChunkDataNbt(RegistryWrapper.WrapperLookup registryLookup) {
+    return createNbt(registryLookup);
+  }
+  @Override
+  public @Nullable Object getRenderData() {
+    // this is the method from `RenderDataBlockEntity` class.
+    return color;
+  }
+}
+</code>
+In the ''TutorialBlocks'' class, replace ''new Block'' with ''new ColorBlock'':
+<code java>
+  // Before 1.21.2:
+  public static final ColorBlock COLOR_BLOCK = register("color_block", new ColorBlock(AbstractBlock.Settings.create()));
+  // Since 1.21.2:
+  public static final Block COLOR_BLOCK = register("color_block", ColorBlock::new, AbstractBlock.Settings.create());
+</code>
+In the ''TutorialBlockEntityTypes'' class:
+<code java>
+  public static final BlockEntityType<ColorBlockEntity> COLOR_BLOCK = register("color_block",
+      BlockEntityType.Builder.create(ColorBlockEntity::new, TutorialBlocks.COLOR_BLOCK).build());
+</code>
+Now we modify ''onUseWithItem'' method so that the color changes when you interact the block with a dye:
+<code java ColorBlock.java>
+public class ColorBlock extends BlockWithEntity {
+  [...]
+  @Override
+  protected ActionResult onUseWithItem(ItemStack stack, BlockState state, World world, BlockPos pos, PlayerEntity player, Hand hand, BlockHitResult hit) {
+    if (stack.getItem() instanceof DyeItem dyeItem) {
+      if (world.getBlockEntity(pos) instanceof ColorBlockEntity colorBlockEntity) {
+        final int newColor = dyeItem.getColor().getEntityColor();
+        final int originalColor = colorBlockEntity.color;
+        colorBlockEntity.color = ColorHelper.average(newColor, originalColor);
+        stack.decrementUnlessCreative(1, player);
+        colorBlockEntity.markDirty();
+        world.updateListeners(pos, state, state, 0);
+      }
+    }
+    return super.onUseWithItem(stack, state, world, pos, player, hand, hit);
+  }
+  [...]
+}
+</code>
+Finally, modify the color provider to use the render data. We call ''FabricBlockView.getBlockEntityRenderData'' to ensure thread-safety and data-consistency.
+<code java ExampleModClient.java>
+@Environment(EnvType.CLIENT)
+public class ExampleModClient implements ClientModInitializer {
+  [...]
+  @Override
+  public void onInitializeClient() {
+    [...]
+    ColorProviderRegistry.BLOCK.register((state, view, pos, tintIndex) -> view != null && view.getBlockEntityRenderData(pos) instanceof Integer integer ? integer : 0x3495eb, TutorialBlocks.COLOR_BLOCK);
+  }
+}
+</code>
+Now done! Then you can check whether the following work correctly:
+  * When you interact the block with a dye, the color should change.
+  * When you modify the color through ''/data'' command, the color should change.
+  * When you pick (press mouse wheel) the block with ''Ctrl'' pressed, and place the block, it should display as the expected color.
+  * When you leave the world and re-enter, the color should be kept.
+===== Custom item tint (1.21.4 and after) =====
+Since 1.21.4 开始, tints of items are defined in item models definitions. Some common tint source types are provided in vanilla, see [[https://minecraft.wiki/w/Item models definition|Minecraft Wiki]]. In this example, we directly set the color of the item, so we can write the item models definition as follows:
+<code javascript /resources/assets/tutorial/items/color_block.json>
+{
+  "model": {
+    "type": "model",
+    "model": "tutorial:block/color_block",
+    "tints": [
+      {
+        "type": "constant",
+        "value": 3446251
+      }
+    ]
+  }
+}
+</code>
+If you need to specify a custom tint source, you can register with ''TintResourceTypes.//ID_MAPPER//.put(...)'' provided in vanilla. Note that this should be done in client environment. The ID used in the registration is the value of ''%%"type"%%'' in the ''%%"tints"%%'' in the item model definition above.
+> If the tint does not work, check the value of tintindex in the model, which should be consistent with the element subscript in the ''%%"tints"%%'' list in the item models definition. For example, if the tintindex is 2, it uses the third tint source in the item models definition.
-===== Item Color Provider =====
+In version 1.21.3 and before, item model providers are also registered with Fabric API. Different from blocks, the context provided, instead of having a state, world, or position, has access to the ''ItemStack''.
-Items are similar; the difference is the context provided. Instead of having a state, world, or position, you have access to the ''ItemStack''.
-For item models, we can directly inherite the block model, which uses tintindex:
+For item models, we can directly inherite the block model that uses tintindex:
 <code javascript src/main/resources/assets/tutorial/models/item/color_block.json>
 {