Package net.fabricmc.fabric.api.renderer.v1.model

Interface FabricBlockStateModel

public interface FabricBlockStateModel
Interface for baked block state models that output geometry with enhanced rendering features. Can also be used to generate or customize geometry output based on world state.

Implementors should have a look at ModelHelper as it contains many useful functions.

Note: This interface is automatically implemented on BlockStateModel via Mixin and interface injection.

  • Method Details

    • emitQuads

      default void emitQuads(QuadEmitter emitter, BlockRenderView blockView, BlockPos pos, BlockState state, Random random, Predicate<@Nullable Direction> cullTest)
      Produces this model's geometry. This method must be called instead of BlockStateModel.addParts(Random, List) or BlockStateModel.getParts(Random); the vanilla methods should be considered deprecated as they may not produce accurate results. However, it is acceptable for a custom model to only implement the vanilla methods as the default implementation of this method will delegate to one of the vanilla methods.

      Like BlockStateModel.addParts(Random, List), this method may be called outside of chunk rebuilds. For example, some entities and block entities render blocks. In some such cases, the provided position may be the nearest position and not actual position. In others, the provided world may be empty.

      If multiple independent subtasks use the provided random, it is recommended that implementations reseed the random using a predetermined value before invoking each subtask, so that one subtask's operations do not affect the next subtask. For example, if a model collects geometry from multiple submodels, each submodel is considered a subtask and thus the random should be reseeded before collecting geometry from each submodel. See MultipartBlockStateModel.addParts(Random, List) for an example implementation of this.

      Implementations should rely on pre-baked meshes as much as possible and keep dynamic transformations to a minimum for performance.

      Implementations should generally also override createGeometryKey(net.minecraft.world.BlockRenderView, net.minecraft.util.math.BlockPos, net.minecraft.block.BlockState, net.minecraft.util.math.random.Random).

      Parameters:
      emitter - Accepts model output.
      blockView - Access to world state.
      pos - Position of block for model being rendered.
      state - Block state whose model was queried for geometry. This is not guaranteed to be the state corresponding to this model!
      random - Random object seeded per vanilla conventions. Do not cache or retain a reference.
      cullTest - A test that returns true for faces which will be culled and false for faces which may or may not be culled. Meant to be used to cull groups of quads or expensive dynamic quads early for performance. Early culled quads will likely not be added the emitter, so callers of this method must account for this. In general, prefer using MutableQuadView.cullFace(Direction) instead of this test.
      See Also:

    • createGeometryKey

      @Nullable default @Nullable Object createGeometryKey(BlockRenderView blockView, BlockPos pos, BlockState state, Random random)
      Creates a geometry key using the given context. A geometry key represents the exact geometry output from emitQuads(net.fabricmc.fabric.api.renderer.v1.mesh.QuadEmitter, net.minecraft.world.BlockRenderView, net.minecraft.util.math.BlockPos, net.minecraft.block.BlockState, net.minecraft.util.math.random.Random, java.util.function.Predicate<net.minecraft.util.math.Direction>) when given the same parameters as this method and a cull test that always returns false. Geometry keys are intended to be used in a cache to avoid recomputing expensive transformations applied to a certain model's geometry.

      The geometry key must implement Object.equals(Object) and Object.hashCode(). The geometry key may be compared to the geometry key of any other model, not just those produced by this model instance, so care should be taken when selecting the type of the key. Generally, one class of model will want to make its own record class to use for geometry keys.

      A null key means that a geometry key does exist for specifically the given context; a key may exist for a different context. It is always possible to create a key for any context, but some custom models may choose not to if doing so is too complex. Vanilla models correctly implement this method, but may return null when delegating to a submodel that returns null.

      Parameters:
      blockView - The world in which the block exists.
      pos - The position of the block in the world.
      state - The block state whose model was queried for a geometry key. This is not guaranteed to be the state corresponding to this model!
      random - Random object seeded per vanilla conventions.
      Returns:
      the geometry key, or null if one does not exist for the given context
      See Also:

    • particleSprite

      default Sprite particleSprite(BlockRenderView blockView, BlockPos pos, BlockState state)
      Extension of BlockStateModel.particleSprite() that accepts world state. This method will be invoked most of the time, but the vanilla method may still be invoked when no world context is available.

      If your model delegates to other BlockStateModels, ensure that it also delegates invocations of this method to its submodels as appropriate!

      Parameters:
      blockView - The world in which the block exists.
      pos - The position of the block in the world.
      state - The block state whose model was queried for the particle sprite. This is not guaranteed to be the state corresponding to this model!
      Returns:
      the particle sprite