BlockyRenderer:File Format

This page describes how Blocky Renderer reads .blockymodel and .blockyanim files. The format is not officially documented. The rules here follow the official Hytale plugin for Blockbench and the vanilla files. They have not been compared with the game itself.

Both file types are JSON. Comments and trailing commas are tolerated when reading.

Models (.blockymodel)

Top level

Field	Meaning
nodes	List of top-level nodes. Required.
lod	auto, off, disappear or billboard. Usually auto.
format	character or prop. Often missing.

Units and axes

• 1 block = 32 units. Y points up.
• The origin is the bottom center of a block, so x and z run from -16 to 16.
• front faces +Z, right faces +X, top faces +Y.

Node

Field	Meaning
id	A number as text in vanilla files. Not always unique. The preview does not use it.
name	Node name. Animations address nodes by name.
position	Pivot of the node. The node rotates around it.
orientation	Rotation as a quaternion. No rotation is x = y = z = 0, w = 1.
shape	The shape of the node, see below.
children	Child nodes. They are placed relative to position + shape.offset of this node.

Shape

Field	Meaning
type	box, quad (a single face) or none (a plain group or pivot)
offset	Moves the shape away from the pivot.
stretch	Scales the shape around its center without changing the UVs. A negative value mirrors it. A value of 0 hides it.
settings.size	Size of the box. A quad uses only x and y.
settings.normal	Quad only: +X, -X, +Y, -Y, +Z (default) or -Z. With ±X, size.x becomes the z extent. With ±Y, size.y becomes the z extent.
visible	Whether the shape is drawn. Children are not affected.
doubleSided	Draws the back of the faces too.
shadingMode	flat, standard, fullbright or reflective. In the preview, only fullbright is self-lit.
textureLayout	Position of each face in the texture. Faces without an entry are not drawn. A quad always uses front.
unwrapMode, settings.isPiece, settings.isStaticBox	Not used by the preview.

Texture layout

Each face in textureLayout (front, back, left, right, top, bottom) has:

• offset: the corner of the face in the texture, in pixels.
• mirror: x and y reverse the reading direction from that corner (to the left or up).
• angle: 0, 90, 180 or 270. Rotates the texture on the face. 90 and 270 swap width and height.

The size of a face in the texture comes from the box size: front and back use x × y, left and right z × y, top and bottom x × z.

Animations (.blockyanim)

Top level

Field	Meaning
formatVersion	Format version, 1.
duration	Length in frames, 60 frames per second. If missing or 0, the time of the last keyframe is used, or 120 frames.
holdLastKeyframe	false: the animation loops. true: the last value stays.
nodeAnimations	Tracks per node, keyed by node name. The tracks apply to all nodes with that name.

Tracks

Each node can have five tracks. A track is a list of keyframes { time, delta, interpolationType }. interpolationType is smooth or linear, and linear if missing.

Track	Delta	Effect
position	{x, y, z}	Added to the position of the node
orientation	quaternion	Applied after the rotation of the node
shapeStretch	{x, y, z}	Multiplies the stretch of the node's own shape
shapeVisible	true / false	Shows or hides the node's own shape, not its children
shapeUvOffset	{x, y}	Moves the texture of the node's own shape in whole pixels. Negative y moves down in the image.

Between keyframes

• Rotation: spherical interpolation. Between two smooth keyframes, an asymmetric easing curve from the Blockbench plugin is used.
• Position and stretch: linear if both keyframes are linear, otherwise a Catmull-Rom curve over the neighboring keyframes.
• Visibility and UV offset: they jump. The last keyframe up to the current time applies.
• When the animation loops, position, rotation and stretch run from the last keyframe past the end to the first one.