Skip to content

Models - Geometry Module

anvil.api.models.geometry

Builders for Bedrock geometry files (*.geo.json).

The tree structure is enforced by the API itself: a :class:Geometry only creates root bones, and a :class:_Bone creates child bones, cubes and locators. A child bone always knows its parent, so the parent field of the compiled output is never written by hand.

Example
geo = Geometry("my_mob", texture_size=(64, 64))

body = geo.bone("body", pivot=(0, 12, 0))
body.cube(origin=(-4, 12, -2), size=(8, 12, 4), uv=(16, 16))

arm = body.bone("arm", pivot=(5, 22, 0))  # parent is "body"
arm.cube(origin=(4, 12, -2), size=(4, 12, 4), uv=(40, 16))
arm.locator("hand", offset=(6, 12, 0))

geo.queue()

Documentation reference

Geometry

Bases: JsonFile[_GeometryFile]

A Bedrock geometry file (*.geo.json) built from a tree of bones.

Documentation reference

bones property

All bones, parents always before their children.

geometry_identifier property

How entities and blocks reference this geometry: geometry.<namespace>.<name>.

identifier property

The file's identifier.

item_display_transforms property

How a block geometry is shown as an item.

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.

bone(name, pivot=(0, 0, 0), *, rotation=(0, 0, 0), mirror=False, inflate=None, binding=None, render_group_id=None, debug=None)

Creates a root bone (no parent) and returns it.

Parameters:

Name Type Description Default
name str

The bone name, unique in the geometry.

required
pivot Sequence[float]

The point the bone rotates around.

(0, 0, 0)
rotation Sequence[float]

The rotation before animation, in degrees.

(0, 0, 0)
mirror bool

Mirrors the UV of the bone's unrotated cubes.

False
inflate float

Grows every cube of the bone.

None
binding str

Molang naming the parent skeleton's bone to follow.

None
render_group_id int

The render group of the bone.

None
debug bool

The bone's debug flag.

None

clone(name=None)

Returns an independent copy, optionally under a new name.

merge(other, *, parent=None, prefix='')

Copies the bones of other into this geometry.

They become root bones, or children of parent. prefix is added to every copied bone name to avoid clashes. Texture size and bounds of this geometry are kept.

queue(directory=None)

Queues the addon object for processing and logs the event.

Parameters:

Name Type Description Default
directory str

The directory of the addon object.

None

Returns:

Name Type Description
self 'JsonFile[D]'

The instance of the current JsonFile.

scale(factor, origin=(0, 0, 0))

Scales the whole model by factor around origin.

set_cape(cape)

Sets the cape texture of the geometry.

set_item_display_transforms(item_display_transforms)

Sets how a block geometry is shown as an item, or None to remove it.

set_texture_size(width, height)

Sets the size of the texture, in texels.

set_visible_bounds(width, height)

Sets the size of the visibility box, in blocks.

set_visible_offset(x, y, z)

Sets the offset of the visibility box from the entity, in blocks.

translate(offset)

Moves the whole model by offset. Pivots, cube origins and locator offsets are model-space positions, so they all move together.

ItemDisplayGuiTransform

Bases: ItemDisplayTransform

The gui display slot, the only one that accepts fit_to_frame. It also takes every option of ItemDisplayTransform.

Parameters:

Name Type Description Default
fit_to_frame bool

True is written as {}, which is how Blockbench exports it; False as false, which Minecraft may reject from 1.21.130.

required

__required__ = () class-attribute

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

__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.

ItemDisplayTransform

Bases: JsonObject

How a block's item is shown in one display slot. Vectors are (x, y, z).

Parameters:

Name Type Description Default
rotation tuple[float, float, float]

The rotation, in degrees.

required
translation tuple[float, float, float]

The offset.

required
scale tuple[float, float, float]

The scale.

required
rotation_pivot tuple[float, float, float]

The point the rotation turns around.

required
scale_pivot tuple[float, float, float]

The point the scale grows from.

required

__required__ = () class-attribute

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

__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.

ItemDisplayTransforms

Bases: JsonObject

How a block's item is shown in each display slot.

Parameters:

Name Type Description Default
thirdperson_righthand ItemDisplayTransform

The transform of the thirdperson_righthand slot.

required
thirdperson_lefthand ItemDisplayTransform

The transform of the thirdperson_lefthand slot.

required
firstperson_righthand ItemDisplayTransform

The transform of the firstperson_righthand slot.

required
firstperson_lefthand ItemDisplayTransform

The transform of the firstperson_lefthand slot.

required
head ItemDisplayTransform

The transform of the head slot.

required
ground ItemDisplayTransform

The transform of the ground slot.

required
fixed ItemDisplayTransform

The transform of the fixed slot.

required
gui ItemDisplayGuiTransform

The transform of the gui slot.

required

__required__ = () class-attribute

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

__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.