Materials and Entity-Types

class MaterialFilter

The MaterialFilter filteres materials, which includes types of blocks, items and other materials, by querying the server. The exact materials that are available depend on the Minecraft version and plugins/mods that are installed on the Minecraft instance.

Typically, we would like to get a certain subtype of material, which can be filtered directly on this class. Once we have done this, we can iterate over it, return a list of applied filters or choose a random block from the filtered materials:

from mcpq import Minecraft
mc = Minecraft()

# get all blocks that contain the word "wool"
wool = mc.materials.block().contains("wool")
# equivalent to:
wool = mc.blocks.contains("wool")

print(wool.first())
# >>> 'black_wool'
print(wool.len())
# >>> 16
print(wool.get())
# >>> ['black_wool', 'blue_wool', 'brown_wool', ...]

# get all non-solid blocks
solids = mc.materials.block().solid(False)
# get all items
items = mc.materials.item()

# once you have your filtered materials you can iterate over them:
for block in mc.blocks.contains("wool"):
   mc.postToChat(block)
# or select randomly
random_wool = mc.blocks.contains("wool").choice()
# or turn the filter into a list for something else
wool_list = mc.blocks.contains("wool").get()

Most filteres can be inverted, either directly, e.g., mc.materials.item(False) to get all non-item materials, or by using the inverted keyword for string filters, e.g., mc.materials.contains("yellow", "orange", negate=True) to get all materials that do not contain the words yellow or orange.

Additionally, filters can be combined in a number of ways. Let’s say we want to get all block types that contain the words “wool” or “concrete” but NOT the word “yellow”. There are multiple ways how we could filter the material list:

from mcpq import Minecraft
mc = Minecraft()

# method chaining
mc.materials.block().contains("wool", "concrete").contains("yellow", negate=True)
# method chaining with or_ (or_ binds strongly, i.e., only the two contains calls are or-ed)
mc.materials.block().contains("wool").or_.contains("concrete").contains("yellow", negate=True)
# binary operators (short form)
(mc.materials.contains("wool", "concrete") & ~mc.materials.contains("yellow")).block()
# binary operators (explicit form)
wool_concrete = mc.materials.block().contains("wool") | mc.materials.block().contains("concrete")
wool_concrete & ~mc.materials.contains("yellow")

Plus there are many more filters:

# get exactly the block called "red_wool"
red_wool_block = mc.materials.getById("red_wool")
# get exactly the blocks "red_wool" and "green_wool"
red_green = mc.materials.equals("red_wool", "green_wool")
# number of "cut_copper" blocks (does NOT include, e.g., "cut_copper_stairs")
number_of_cut_copper = mc.materials.block().endswith("cut_copper").len()
# and many more...
property or_: MaterialFilter

Or the next filter with the previous one (this is strongly binding) thus (potentially) widening the selection of materials. mc.materials.block().contains("wool").or_.contains("concrete") can be read as block AND (wool OR concrete) thus giving all blocks that contain either “wool” or “concrete” or both.

get() → list[Block]

Apply all filters and return a Python list of filtered blocks

getById(id: str) → Block

Apply all filters and return the block with id. If the block does not exist in the current selection raise an error.

first() → Block | None

Apply all filters and return the first element if one exists else None

choice() → Block

Apply all filters and return a random element

len() → int

Apply all filters and return the number of elements in the selection

air(value: bool = True, /) → MaterialFilter

Filter for air blocks, e.g., like air and void_air

block(value: bool = True, /) → MaterialFilter

Filter for blocks, i.e., anything that can be set using setBlock()

burnable(value: bool = True, /) → MaterialFilter

Filter for blocks that can burn away

edible(value: bool = True, /) → MaterialFilter

Filter for edible materials

flammable(value: bool = True, /) → MaterialFilter

Filter for blocks that can catch fire

fuel(value: bool = True, /) → MaterialFilter

Filter for materials that can be used as fuel in a furnace

interactable(value: bool = True, /) → MaterialFilter

Filter for interactable materials. Interactable materials include those with functionality when they are interacted with by a player such as chests, furnaces, etc. It counts as interactable if there is at least one state in which additional interact handling is performed for the material.

item(value: bool = True, /) → MaterialFilter

Filter for obtainable items.

occluding(value: bool = True, /) → MaterialFilter

Filter for blocks that occlude light. Most full blocks will occlude light while non-full blocks are non-occluding. Check the wiki on opacity.

solid(value: bool = True, /) → MaterialFilter

Filter for blocks that are solid, i.e., can be built upon.

gravity(value: bool = True, /) → MaterialFilter

Filter for materials that are affected by gravity.

vanilla(value: bool = True, /) → MaterialFilter

Filter for vanilla block, i.e., block with namespace minecraft

namespace(*namespaces: str, negate: bool = False) → MaterialFilter

Filter for any number of namespaces. Providing multiple namespace means any block having any of the given namespaces is considered a match

equals(*strings: str, negate: bool = False) → MaterialFilter

Filter for any number of exact block matches. Providing multiple means any block equaling any of the given strings is considered a match

contains(*substrings: str, negate: bool = False) → MaterialFilter

Filter for blocks that contain a substring. Providing multiple means any block containing any of the given substrings is considered a match

startswith(*substrings: str, negate: bool = False) → MaterialFilter

Filter for blocks that start with a substring. Providing multiple means any block starting with any of the given substrings is considered a match

endswith(*substrings: str, negate: bool = False) → MaterialFilter

Filter for blocks that end with a substring. Providing multiple means any block ending with any of the given substrings is considered a match

class EntityTypeFilter

Works the same as MaterialFilter only for entity-types instead.

Note

The interface and functions for entities is very similar to blocks, such that we are aliasing EntityType to Block at the moment. If at a later point the functionality between the two diverges then we will split the classes as well.

property or_: EntityTypeFilter
get() → list[Block]
getById(id: str) → Block
first() → Block | None
choice() → Block
len() → int
spawnable(value: bool = True, /) → EntityTypeFilter
vanilla(value: bool = True, /) → EntityTypeFilter
namespace(*namespaces: str, negate: bool = False) → EntityTypeFilter
equals(*strings: str, negate: bool = False) → EntityTypeFilter
contains(*substrings: str, negate: bool = False) → EntityTypeFilter
startswith(*substrings: str, negate: bool = False) → EntityTypeFilter
endswith(*substrings: str, negate: bool = False) → EntityTypeFilter