Actors - Materials Module
anvil.api.actors.materials
Material
A class representing a material with customizable states and definitions.
Attributes:
| Name | Type | Description |
|---|---|---|
Material_name |
str
|
The name of the material. |
Material |
dict
|
The attributes and states of the material. |
__init__(material_name, baseMaterial)
Initializes a Material instance.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
material_name
|
str
|
The name of the material. |
required |
baseMaterial
|
str
|
The base material's name, if any. |
required |
add_defines(*defines)
Adds defines to the material.
Enables additional features like emulation or multi-texturing on top of the base material's configuration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
defines
|
MaterialDefinitions
|
The defines to add. |
()
|
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
add_samplerStates(states)
Adds additional sampler states.
Appends to existing sampler states inherited from the base material.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
states
|
list[dict]
|
A list of sampler state objects to add. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
add_states(*states)
Adds rendering states to the existing material configuration.
This appends to the states inherited from the base material instead of replacing them.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
states
|
MaterialStates
|
The material states to add. |
()
|
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
backFace(stencilFunc=None, stencilFailOp=None, stencilDepthFailOp=None, stencilPassOp=None, stencilPass=None)
Configures stencil testing for back-facing polygons.
Functionally identical to frontFace, but applied to the back side of geometry.
This allows for double-sided stencil effects (e.g. treating the inside of a volume differently).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
stencilFunc
|
MaterialFunc
|
The comparison function. |
None
|
stencilFailOp
|
MaterialOperation
|
Operation on stencil fail. |
None
|
stencilDepthFailOp
|
MaterialOperation
|
Operation on stencil pass but depth fail. |
None
|
stencilPassOp
|
MaterialOperation
|
Operation on both pass. |
None
|
stencilPass
|
MaterialOperation
|
(Legacy/Alternative name). |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
blendDst(blendDst)
Sets the blending factor for the destination color (the background).
Together with blendSrc, this determines the final pixel color.
Example: OneMinusSrcAlpha is commonly used for standard transparency (inverted alpha).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
blendDst
|
str
|
The destination blend factor (e.g., "OneMinusSrcAlpha", "Zero"). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
blendSrc(blendSrc)
Sets the blending factor for the source color (the pixel being drawn).
Blending combines the source color with the destination color (the pixel already in the buffer).
Example: SourceAlpha uses the texture's alpha channel for transparency.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
blendSrc
|
str
|
The source blend factor string (e.g., "SourceAlpha", "One"). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
defines(*defines)
Sets the shader preprocessor defines.
Defines toggle features in the shader code, such as enabling alpha testing (ALPHA_TEST),
glint effects (GLINT), or color masking (USE_COLOR_MASK).
Overwrites all existing defines.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
defines
|
MaterialDefinitions
|
Variable arguments of |
()
|
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
depthBias(bias)
Sets the depth bias.
Offsets the depth value of the rendered geometry. Positive values pull the geometry "closer" to the camera without changing its actual position. Used to prevent z-fighting (flickering) when two surfaces overlap.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bias
|
float
|
The bias value (typically small, e.g., 100.0). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
depthBiasOGL(bias)
Sets the OpenGL-specific depth bias.
Similar to depthBias, but specifically for the OpenGL backend (some platforms).
Usually kept consistent with depthBias.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bias
|
float
|
The OpenGL depth bias value. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
depthFunc(depthFunc)
Sets the function used for the depth test.
The depth test determines if a pixel is obscured by other objects.
Standard depth testing uses LessEqual (draw if closer or equal).
Changing this allows valid rendering of objects behind others (e.g. Greater) or always drawing on top (Always).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
depthFunc
|
MaterialFunc
|
The comparison function to use (e.g. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
fragmentShader(shader)
Sets the path to the fragment (pixel) shader file.
The fragment shader calculates the color of each pixel, applying textures, lighting, and effects.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
shader
|
str
|
The relative path to the fragment shader (e.g., "shaders/entity.fragment"). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
frontFace(stencilFunc=None, stencilFailOp=None, stencilDepthFailOp=None, stencilPassOp=None, stencilPass=None)
Configures stencil testing for front-facing polygons.
The stencil buffer is used to mask pixels and control drawing based on custom rules. This method defines how the stencil test behaves for the front side of the geometry.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
stencilFunc
|
MaterialFunc
|
The comparison function (e.g. Equal, Always) used to determine if the stencil test passes. |
None
|
stencilFailOp
|
MaterialOperation
|
The operation to perform on the stencil buffer value if the stencil test fails. |
None
|
stencilDepthFailOp
|
MaterialOperation
|
The operation to perform if the stencil test passes but the depth test fails. |
None
|
stencilPassOp
|
MaterialOperation
|
The operation to perform if both stencil and depth tests pass. |
None
|
stencilPass
|
MaterialOperation
|
(Legacy/Alternative name for stencilPassOp). |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
geometryShader(shader)
Sets the path to the geometry shader file.
Geometry shaders can generate new geometry (vertices/primitives) on the fly. (Less commonly used in standard Bedrock entity materials).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
shader
|
str
|
The relative path to the geometry shader file. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
msaaSupport(support)
Configures Multisample Anti-Aliasing (MSAA) support.
Controls whether the material benefits from MSAA to smooth jagged edges.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
support
|
str
|
The support mode (e.g., "Both", "None", "MSAA"). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
primitiveMode(mode)
Sets the geometric primitive drawing mode.
Determines how vertices are interpreted. - "Triangle": Standard mesh rendering. - "Line": Draws wireframe lines. - "Quad": Draws quads.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mode
|
str
|
The primitive mode string. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
remove_defines(*defines)
Removes specific defines from the material.
Use this to disable features inherited from a base material.
Example: Removing USE_OVERLAY to stop an entity from flashing red when hit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
defines
|
MaterialDefinitions
|
The defines to remove. |
()
|
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
remove_states(*states)
Removes specific rendering states from the material configuration.
Use this to disable default behaviors inherited from a base material.
For example, removing DisableCulling to restore backface culling.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
states
|
MaterialStates
|
The material states to remove. |
()
|
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
samplerStates(states)
Configures texture sampling.
Defines how textures are filtered (Nearest/Linear) and wrapped (Repeat/Clamp). Example: Setting filter to 'Point' creates a pixelated look (Minecraft default).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
states
|
list[dict]
|
A list of sampler state objects. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
slopeScaledDepthBias(bias)
Sets the slope-scaled depth bias.
Offsets depth based on the polygon's angle to the camera. Surfaces viewed at a steep angle need more bias
to prevent z-fighting. Works in conjunction with depthBias.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bias
|
float
|
The slope-scale factor (e.g., 0.1). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
slopeScaledDepthBiasOGL(bias)
Sets the OpenGL-specific slope-scaled depth bias.
Similar to slopeScaledDepthBias, but for the OpenGL backend.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bias
|
float
|
The OpenGL slope-scale factor. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
states(*states)
Sets the rendering states for the material.
Rendering states control basic graphics pipeline settings, such as whether to enable blending, disable culling (rendering backfaces), or write to the depth buffer.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
states
|
MaterialStates
|
One or more |
()
|
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
stencilRef(stencilRef)
Sets the reference value for the stencil test.
This value is compared against the value in the stencil buffer using the stencilFunc.
For example, if stencilFunc is Equal and stencilRef is 1, pixels are only drawn where the stencil buffer is 1.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
stencilRef
|
int
|
The integer reference value (0-255). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
variants(variants)
Defines shader variants.
Variants allow switching between different shader setups (defines, vertex fields) based on conditions, such as skinning support or specific defines being active.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
variants
|
list[dict]
|
A list of variant configuration dictionaries. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
vertexFields(fields)
Defines the data layout for vertices passed to the shader.
Specifies what information (Position, Normal, UVs, Color/BoneWeights) is available in the shader input attributes. Must match the shader's expectation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fields
|
list[dict]
|
List of field objects (e.g., |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
vertexShader(shader)
Sets the path to the vertex shader file.
The vertex shader processes each vertex's position and attributes (UVs, normals). It transforms 3D model coordinates into screen space.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
shader
|
str
|
The relative path to the vertex shader (e.g., "shaders/entity.vertex"). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
vrGeometryShader(shader)
Sets the path to the VR-specific geometry shader.
Used when playing in Virtual Reality mode to handle stereo rendering adjustments.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
shader
|
str
|
The relative path to the shader (e.g., "shaders/entity.geometry"). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
Material |
The instance of the class to enable method chaining. |
MaterialsObject
Bases: AddonObject
Handles materials as a singleton.
Attributes:
| Name | Type | Description |
|---|---|---|
Materials |
list[Material]
|
A list of materials. Defaults to empty list. |
identifier
property
Returns the identifier of the addon object in the format 'namespace:name'.
Returns:
| Name | Type | Description |
|---|---|---|
str |
Identifier
|
The identifier of the addon object. |
name
property
Returns the name of the addon object.
Returns:
| Name | Type | Description |
|---|---|---|
str |
str
|
The name of the addon object. |
content(content)
Sets the content of the addon object and returns the object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
content
|
any
|
The content to be set for the addon object. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
self |
AddonObject
|
The instance of the current AddonObject. |
queue()
Returns the queue for the materials.
Returns:
| Name | Type | Description |
|---|---|---|
queue |
The queue for the materials. |
set_identifier_data(data)
Sets the data of the addon object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
data
|
any
|
The data to be set for the addon object. |
required |