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 |
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 |
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 |
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 |
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 |
required |
thirdperson_lefthand
|
ItemDisplayTransform
|
The transform of the |
required |
firstperson_righthand
|
ItemDisplayTransform
|
The transform of the |
required |
firstperson_lefthand
|
ItemDisplayTransform
|
The transform of the |
required |
head
|
ItemDisplayTransform
|
The transform of the |
required |
ground
|
ItemDisplayTransform
|
The transform of the |
required |
fixed
|
ItemDisplayTransform
|
The transform of the |
required |
gui
|
ItemDisplayGuiTransform
|
The transform of the |
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 |
required |
__validate__()
Cross-field checks, run on export after the fields are checked.