Actors - Materials Module

anvil.api.actors.materials

The resource pack's materials/entity.material: custom entity materials.

Material

Bases: _MaterialSettings

A custom entity material, written to materials/entity.material when queued. Its identifier is <namespace>.<material_name>, which the entity's client description refers to.

Parameters:

Name	Type	Description	Default
material_name	str	The material's name.	required
baseMaterial	str	The material it builds on, such as entity_alphatest.	required

__required__ = () class-attribute

JSON keys the schema marks required although their field is optional, because __validate__ requires them.

identifier property

The material's identifier, <namespace>.<material_name>.

key property

The material's key in the file, <identifier>:<baseMaterial>.

__from_json__(data) classmethod

Builds the object from its parsed JSON, the inverse of __json__(). Each key goes to the field written under it, read through the field's annotation.

Parameters:

Name	Type	Description	Default
data	Any	The parsed JSON object.	required

Raises:

Type	Description
TypeError	The data is not an object, or a value does not match its field.
ValueError	The data has a key the class does not write, or a constant field holds another value.

__json__()

The JSON payload of this object, built from its fields after checking them.

__json_fields__() classmethod

The compiled fields of this class, compiled on first use.

__post_init__()

Side effects after construction.

__prepare_export__(owner, *, root=True)

Finishes the object for export, where its owner calls it. Components with a localized name override it. root is False for a permutation's components.

__schema__() classmethod

The JSON Schema (draft 2020-12) of this object's JSON, its parts under $defs.

__schema_body__(definitions) classmethod

The schema of this object's JSON, adding the parts it uses to definitions.

Parameters:

Name	Type	Description	Default
definitions	dict[str, JsonSchema]	The $defs of the schema being built.	required

__validate__()

Cross-field checks, run on export after the fields are checked.

add_defines(*defines)

Adds shader defines to the base material's.

Parameters:

Name	Type	Description	Default
defines	MaterialDefinitions	The defines to add.	()

add_samplerState(samplerIndex, textureFilter=None, textureWrap=None)

Adds how a texture is sampled to the base material's sampler states.

Parameters:

Name	Type	Description	Default
samplerIndex	int	The texture's index.	required
textureFilter	str	The filter, "Point" keeping pixels sharp.	None
textureWrap	str	"Repeat" or "Clamp".	None

add_states(*states)

Adds rendering states to the base material's.

Parameters:

Name	Type	Description	Default
states	MaterialStates	The states to add.	()

add_variant(name)

Adds a shader variant, such as skinning, and returns it to set it up with the same builders as the material.

Parameters:

Name	Type	Description	Default
name	str	The variant's name.	required

queue()

Adds the material to materials/entity.material.

remove_defines(*defines)

Removes shader defines of the base material, such as USE_OVERLAY to stop the entity flashing red when hurt.

Parameters:

Name	Type	Description	Default
defines	MaterialDefinitions	The defines to remove.	()

remove_states(*states)

Removes rendering states of the base material, such as DisableCulling to cull backfaces again.

Parameters:

Name	Type	Description	Default
states	MaterialStates	The states to remove.	()

set_backFace(stencilFunc=None, stencilFailOp=None, stencilDepthFailOp=None, stencilPassOp=None, stencilPass=None)

Sets the stencil test of back-facing polygons, like set_frontFace.

Parameters:

Name	Type	Description	Default
stencilFunc	MaterialFunc	The comparison.	None
stencilFailOp	MaterialOperation	On stencil fail.	None
stencilDepthFailOp	MaterialOperation	On stencil pass and depth fail.	None
stencilPassOp	MaterialOperation	When both pass.	None
stencilPass	MaterialOperation	The older name of stencilPassOp.	None

set_blendDst(blendDst)

Sets the blend factor of the color already drawn, such as OneMinusSrcAlpha.

Parameters:

Name	Type	Description	Default
blendDst	str	The factor.	required

set_blendSrc(blendSrc)

Sets the blend factor of the color being drawn, such as SourceAlpha.

Parameters:

Name	Type	Description	Default
blendSrc	str	The factor.	required

set_defines(*defines)

Sets the shader defines, replacing the base material's.

Defines toggle shader features, such as alpha testing (ALPHA_TEST), the enchantment glint (GLINT) or color masking (USE_COLOR_MASK).

Parameters:

Name	Type	Description	Default
defines	MaterialDefinitions	The defines.	()

set_depthBias(bias)

Sets the depth bias, which draws the geometry closer to the camera than it is, to stop two overlapping surfaces flickering.

Parameters:

Name	Type	Description	Default
bias	float	The bias.	required

set_depthBiasOGL(bias)

Sets the depth bias on OpenGL.

Parameters:

Name	Type	Description	Default
bias	float	The bias.	required

set_depthFunc(depthFunc)

Sets the depth test. The usual test is LessEqual (drawn when closer or equal); Always draws on top of everything.

Parameters:

Name	Type	Description	Default
depthFunc	MaterialFunc	The comparison.	required

set_fragmentShader(shader)

Sets the fragment (pixel) shader, such as shaders/entity.fragment.

Parameters:

Name	Type	Description	Default
shader	str	The shader path.	required

set_frontFace(stencilFunc=None, stencilFailOp=None, stencilDepthFailOp=None, stencilPassOp=None, stencilPass=None)

Sets the stencil test of front-facing polygons. The stencil buffer masks pixels and decides what is drawn by custom rules.

Parameters:

Name	Type	Description	Default
stencilFunc	MaterialFunc	Compares the reference value with the buffer to decide if the test passes.	None
stencilFailOp	MaterialOperation	What happens to the buffer when the stencil test fails.	None
stencilDepthFailOp	MaterialOperation	What happens when the stencil test passes but the depth test fails.	None
stencilPassOp	MaterialOperation	What happens when both tests pass.	None
stencilPass	MaterialOperation	The older name of stencilPassOp.	None

set_geometryShader(shader)

Sets the geometry shader.

Parameters:

Name	Type	Description	Default
shader	str	The shader path.	required

set_msaaSupport(support)

Sets the multisample anti-aliasing support, such as "Both".

Parameters:

Name	Type	Description	Default
support	str	The support mode.	required

set_primitiveMode(mode)

Sets how vertices are drawn, such as "Triangle" or "Line".

Parameters:

Name	Type	Description	Default
mode	str	The primitive mode.	required

set_samplerState(samplerIndex, textureFilter=None, textureWrap=None)

Adds how a texture is sampled to samplerStates, which replaces the base material's sampler states.

Parameters:

Name	Type	Description	Default
samplerIndex	int	The texture's index.	required
textureFilter	str	The filter, "Point" keeping pixels sharp.	None
textureWrap	str	"Repeat" or "Clamp".	None

set_slopeScaledDepthBias(bias)

Sets the depth bias scaled by the polygon's angle to the camera.

Parameters:

Name	Type	Description	Default
bias	float	The slope factor.	required

set_slopeScaledDepthBiasOGL(bias)

Sets the slope-scaled depth bias on OpenGL.

Parameters:

Name	Type	Description	Default
bias	float	The slope factor.	required

set_states(*states)

Sets the rendering states, replacing the base material's.

Rendering states control basic graphics pipeline settings, such as blending, culling (rendering backfaces) or writing to the depth buffer.

Parameters:

Name	Type	Description	Default
states	MaterialStates	The states, such as MaterialStates.DisableCulling.	()

set_stencilRef(stencilRef)

Sets the reference value the stencil test compares with the buffer.

Parameters:

Name	Type	Description	Default
stencilRef	int	The value, 0 to 255.	required

set_vertexFields(*fields)

Sets the vertex data passed to the shader, which must match what the shader reads.

Parameters:

Name	Type	Description	Default
fields	str	The fields, such as "Position", "Normal", "UV0".	()

set_vertexShader(shader)

Sets the vertex shader, such as shaders/entity.vertex.

Parameters:

Name	Type	Description	Default
shader	str	The shader path.	required

set_vrGeometryShader(shader)

Sets the geometry shader used in virtual reality, such as shaders/entity.geometry.

Parameters:

Name	Type	Description	Default
shader	str	The shader path.	required

MaterialsObject

Bases: JsonFile[_MaterialsFile]

The project's custom entity materials, materials/entity.material. There is one per pack.

Documentation reference

identifier property

The file's identifier.

name property

The identifier's name, without its namespace.

__export__()

Exports the addon object after potentially shortening its content and replacing backslashes. Logs the event and writes the object to a file.

__schema__() classmethod

The JSON Schema (draft 2020-12) of this file: the schema of its _document_type, with the file's type as title and where it is written under x-anvil-file.

Raises:

Type	Description
TypeError	When the class is an abstract file base, with no document type.

add_material(material)

Adds a material to the file.

queue()

Queues the materials for export, when there is any.