Maintenance script: BlockyRenderer wiki

2026-10-20T21:29:21Z

BlockyRenderer wiki

New page

This page describes how Blocky Renderer reads <code>.blockymodel</code> and <code>.blockyanim</code> 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 ===
{| class="wikitable"
! Field !! Meaning
|-
| <code>nodes</code> || List of top-level nodes. Required.
|-
| <code>lod</code> || <code>auto</code>, <code>off</code>, <code>disappear</code> or <code>billboard</code>. Usually <code>auto</code>.
|-
| <code>format</code> || <code>character</code> or <code>prop</code>. 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.
* <code>front</code> faces +Z, <code>right</code> faces +X, <code>top</code> faces +Y.

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

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

=== Texture layout ===
Each face in <code>textureLayout</code> (<code>front</code>, <code>back</code>, <code>left</code>, <code>right</code>, <code>top</code>, <code>bottom</code>) has:
* <code>offset</code>: the corner of the face in the texture, in pixels.
* <code>mirror</code>: <code>x</code> and <code>y</code> reverse the reading direction from that corner (to the left or up).
* <code>angle</code>: 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 ===
{| class="wikitable"
! Field !! Meaning
|-
| <code>formatVersion</code> || Format version, 1.
|-
| <code>duration</code> || Length in frames, 60 frames per second. If missing or 0, the time of the last keyframe is used, or 120 frames.
|-
| <code>holdLastKeyframe</code> || <code>false</code>: the animation loops. <code>true</code>: the last value stays.
|-
| <code>nodeAnimations</code> || 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 <code>{ time, delta, interpolationType }</code>. <code>interpolationType</code> is <code>smooth</code> or <code>linear</code>, and <code>linear</code> if missing.
{| class="wikitable"
! Track !! Delta !! Effect
|-
| <code>position</code> || <code>{x, y, z}</code> || Added to the position of the node
|-
| <code>orientation</code> || quaternion || Applied after the rotation of the node
|-
| <code>shapeStretch</code> || <code>{x, y, z}</code> || Multiplies the stretch of the node's own shape
|-
| <code>shapeVisible</code> || <code>true</code> / <code>false</code> || Shows or hides the node's own shape, not its children
|-
| <code>shapeUvOffset</code> || <code>{x, y}</code> || 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 <code>smooth</code> keyframes, an asymmetric easing curve from the Blockbench plugin is used.
* '''Position and stretch''': linear if both keyframes are <code>linear</code>, 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.

{{BlockyRenderer Nav}}

BlockyRenderer:File Format - Revision history

Maintenance script: BlockyRenderer wiki