Differences

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

--- tutorial:colorprovider [2019/10/25 17:48] – draylar
+++ tutorial:colorprovider [2025/04/01 12:10] (current) – solidblock
@@ Line 1: / Line 1: @@
-====== Color Providers ======
+======= Color Providers =======
-Ever wonder how grass and leaves change hues depending on the biome, or how leather armor can have seemingly infinite color patterns? Meet color providers, which allow you to hue and tint block & item model textures based on properties such as location, NBT, or block states.
+Ever wonder how grass and leaves change hues depending on the biome, or how leather armor can have seemingly infinite color patterns? Meet **color providers**, which allow you to hue and tint block & item model textures based on properties such as location, NBT, or block states.
-=== Existing Examples ===
+===== Vanilla Examples =====
 First, what existing vanilla content uses color providers? A few examples include:
   * grass
@@ Line 8: / Line 8: @@
   * leather armor dying
   * redstone wire
-  * plants such as melons, sugarcane, and lilypads
+  * plants such as melons, sugarcane, and lily pads
   * tipped arrows
@@ Line 17: / Line 17: @@
 Remember that the color provider is a client-side mechanic. Make sure to put any code related to it inside a client initializer.
-===== Registering a Block Color Provider =====
+===== 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.
-<code java [enable_line_numbers="false"]>
-ColorProviderRegistry.BLOCK.register(new BlockColorProvider() {
+At first, we create the block in ''TutorialBlocks'' class. For how to create the block, see [[blocks]]:
-        @Override
+<code java TutorialBlocks.class>
-	public int getColor(BlockState state, ExtendedBlockView world, BlockPos pos, int layer) {
+public final class TutorialBlocks {
-		return 0x3495eb;
+  [...]
-	}
+  // Before 1.21.2
-}, MY_BLOCK);
+  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>
-All we do here is say, "Hi, ''MY_BLOCK'' should be colored 0x3495eb," which is a blue color. You have BlockState, World, and BlockPos context, which is how you can change colors based on biome or position. The final int is the layer; each one asks for a color individually, but in this case, we're always returning blue.
+Then add a simple block states file:
+<code javascript src/main/resources/assets/tutorial/blockstates/color_block.json>
+{
+  "variants": {
+    "": {
+      "model": "tutorial:block/color_block"
+    }
+  }
+}
+</code>
+In your ''ClientModInitializer'':
+<code java ExampleModClient.java>
+@Environment(EnvType.CLIENT)
+public class ExampleModClient implements ClientModInitializer {
+  @Override
+  public void onInitializeClient() {
+    // ...
+    ColorProviderRegistry.BLOCK.register((state, view, pos, tintIndex) -> 0x3495eb, TutorialBlocks.COLOR_BLOCK);
+  }
+}
+</code>
-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:
+If you haven't do so, remember to register it in your [[documentation:fabric_mod_json|fabric.mod.json]]:
-<code json [enable_line_numbers="false"]>
+<code javascript>
+{
+  // ...
+  "entrypoints": {
+    // ...
+    "client": [
+      "net.fabricmc.example.ExampleModClient"
+    ]
+  },
+  // ...
+}
+</code>
+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:
+<code javascript src/main/resources/assets/tutorial/models/block/color_block.json>
 {
   "parent": "block/block",
@@ Line 39: / Line 79: @@
   },
   "elements": [
-    {   "from": [ 0, 0, 0 ],
+    { "from": [ 0, 0, 0 ],
       "to": [ 16, 16, 16 ],
       "faces": {
@@ Line 53: / Line 93: @@
 }
 </code>
-In this instance, we're adding a single tintindex, which is what would appear in the `layer` parameter (layer 0).
+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>
+{
+  "parent": "block/leaves",
+  "textures": {
+    "all": "block/white_concrete"
+  }
+}
+</code>
+> **Note:** the color of the block is cached. If you privded a color that changes among time, the changes will not take effect immediately unless there are block updates nearby.
 Here's the final result-- note that the original model used the ''white_concrete'' texture:
 {{https://i.imgur.com/fZLS10g.png}}
-===== Registering an Item Color Provider =====
+===== Block Entity with Color Provider =====
-Items are similar; the difference is the context provided. Instead of having a state, world, or position, you have access to the ''ItemStack''.
-<code java [enable_line_numbers="false"]>
+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.
-ColorProviderRegistry.ITEM.register((itemStack, layer) -> {
-	return 0x3495eb;
+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.
-}, COLORED_ITEM);
+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.
+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''.
+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>
+{
+  "parent": "tutorial:block/color_block"
+}
+</code>
+<code java ExampleModClient.java>
+@Environment(EnvType.CLIENT)
+public class ExampleModClient implements ClientModInitializer {
+  @Override
+  public void onInitializeClient() {
+    // ...
+    ColorProviderRegistry.ITEM.register((stack, tintIndex) -> 0x3495eb, TutorialBlocks.COLOR_BLOCK);
+  }
+}
 </code>
 This would hue the item in our inventory in the same fashion as the block.
-=== Limitations ===
+===== Limitations =====
 One key issue with using the color provider is the lack of context in the item provider. This is why vanilla grass doesn't change colors in your inventory depending on where you stand. For implementing things such as color variants of blocks (concrete, glass, wool, etc.), you're encouraged to simply provide an individual texture for each version.