Maintenance script: PrefabRenderer wiki

2026-10-20T21:29:32Z

PrefabRenderer wiki

New page

This page explains how Prefab Renderer turns a prefab into 3D blocks. Where it finds the block definitions, models and textures is described on [[PrefabRenderer:Asset Sources|Asset Sources]].

== What is read from the prefab ==
{| class="wikitable"
! Field !! Use
|-
| <code>blocks</code> || Required. Each entry with numeric <code>x</code>, <code>y</code>, <code>z</code> and a <code>name</code> becomes one block. Entries without these fields are skipped.
|-
| <code>blocks[].rotation</code> || Rotation of the block, see [[#Rotation|Rotation]].
|-
| <code>blocks[].filler</code> || Cells with a value other than 0 belong to a multi-block model whose origin is elsewhere. They are skipped.
|-
| <code>blocks[].components</code> || <code>Components.ItemContainerBlock</code> marks a chest. Its <code>Droplist</code> and <code>Capacity</code> are shown in the sidebar.
|-
| <code>fluids</code> || Optional. Fluid cells, see [[#Fluids|Fluids]].
|-
| <code>anchorX</code>, <code>anchorY</code>, <code>anchorZ</code> || Shown in the sidebar. They do not move the model.
|}

Blocks named <code>Empty</code> or <code>Air</code> and blocks with an empty name are not drawn. Entities (<code>entities</code>) are not shown.

== Block names ==
A block name in a prefab is split into the item ID, an optional state and an optional extra rotation:
* A leading <code>*</code> is removed.
* <code>_State_Definitions_</code> separates item ID and state. <code>*Rock_Stone_Brick_Smooth_Half_State_Definitions_Block</code> is the item <code>Rock_Stone_Brick_Smooth_Half</code> in the state <code>Block</code>.
* Options after a vertical bar add a rotation in degrees, as used in blueprints: <code>Name|Yaw=90|Pitch=90|Roll=0</code>. Upper and lower case of the option names do not matter.

== Item definitions ==
For every item ID the extension looks for <code>Server/Item/Items/**/<ItemID>.json</code> in the asset sources. If no file has exactly that name, a match that differs only in upper and lower case is used.

* '''Parent chains:''' if the item has a <code>Parent</code>, the parent's fields are loaded first and the item's own fields override them. Fields inside <code>BlockType</code> are merged the same way, one level deep.
* '''States:''' the state is looked up in <code>BlockType.State.Definitions</code>. Its fields override the fields of <code>BlockType</code>. If the state does not exist, the base block is drawn and a warning is shown.

== Draw types ==
{| class="wikitable"
! <code>DrawType</code> !! How it is drawn
|-
| <code>Empty</code> || Not drawn
|-
| <code>Model</code> || Model from <code>CustomModel</code>
|-
| <code>CubeWithModel</code> || Cube from <code>Textures</code> plus the model from <code>CustomModel</code>
|-
| not set || Cube if <code>Textures</code> is set, otherwise the model from <code>CustomModel</code>
|-
| any other value || Cube if <code>Textures</code> is set, otherwise an unknown block
|}

== Cube blocks ==
Cube textures come from the '''first''' entry of <code>Textures</code>. For each face the first key that is set is used:
{| class="wikitable"
! Face !! Keys, in order
|-
| Top || <code>Up</code>, <code>UpDown</code>, <code>All</code>
|-
| Bottom || <code>Down</code>, <code>UpDown</code>, <code>All</code>
|-
| North, South, East, West || <code>North</code> / <code>South</code> / <code>East</code> / <code>West</code>, then <code>Sides</code>, then <code>All</code>
|}
Texture paths are relative to <code>Common/</code>. Only PNG files are read. A face whose texture is missing is drawn magenta and a warning is shown.

Faces between two cubes are hidden when the neighbour is a solid cube (no <code>RequiresAlphaBlending</code> and <code>Opacity</code> unset or <code>Solid</code>) or the same block type. This keeps large prefabs fast.

== Model blocks ==
Models are read from <code>Common/<CustomModel></code> (<code>.blockymodel</code> files).
* Boxes and quads are supported, including the node hierarchy, offsets, stretch and orientation.
* Texture coordinates follow the Hytale Blockbench plugin, including UV offset, mirror and angle.
* 32 model units are one block. Models stand on the bottom of their cell and are centred on X and Z.
* <code>CustomModelScale</code> scales the model.
* The texture is the first entry of <code>CustomModelTexture</code>. If it is missing, the model is drawn magenta and a warning is shown.

== Rotation ==
The prefab field <code>rotation</code> packs three quarter turns into one number:
<pre>
rotation = roll × 16 + pitch × 4 + yaw
</pre>
Each part is 0 to 3 for 0°, 90°, 180° or 270°. Yaw +90° turns north (−Z) to west (−X). Pitch turns around +X, roll around +Z. The rotations are applied as yaw · pitch · roll around the centre of the cell. Rotation options in the block name are added on top.

== Transparency and tint ==
* '''Cut-out textures''' such as leaves and plants: transparent pixels are cut away (alpha test).
* '''Blended blocks:''' blocks with <code>RequiresAlphaBlending</code> are drawn semi-transparent and do not hide faces behind them.
* '''Tint:''' if the block definition has <code>TintUp</code>, <code>TintDown</code>, <code>TintNorth</code>, <code>TintSouth</code>, <code>TintEast</code>, <code>TintWest</code> or <code>Tint</code>, the first color of that list is multiplied onto the texture. The face-specific key wins over <code>Tint</code>. Only colors in the form <code>#rrggbb</code> are used.
* '''Grayscale textures''' (<code>_GS</code> in the file name) without a tint get a fixed green: a leaf green for leaves (<code>Group</code> is <code>Leaves</code> or the texture name contains "leaf" or "leaves"), a grass green for everything else. Biome colors are not used.

== Fluids ==
Fluids from the <code>fluids</code> array are drawn as translucent full cubes. The level of the fluid is ignored. Faces between two cells of the same fluid and faces against solid cubes are hidden.

The color is chosen from the fluid name:
{| class="wikitable"
! Name contains !! Color
|-
| <code>lava</code> || Orange, almost opaque
|-
| <code>poison</code> || Green
|-
| <code>slime</code> || Light green
|-
| <code>tar</code> || Almost black, almost opaque
|-
| anything else || Blue
|}

== Unknown blocks ==
A block that cannot be resolved is drawn as a '''magenta cube''' and listed under ''Unknown blocks'' in the sidebar with the reason. See [[PrefabRenderer:FAQ and Troubleshooting#Unknown blocks|FAQ and Troubleshooting]].

== Limits ==
The view is an approximation of the game:
* Lighting is simple: a sky light and one sun. There is no ambient occlusion, no block light and no biome color.
* Only the first texture variant (<code>Textures[0]</code>, <code>CustomModelTexture[0]</code>) is used. <code>RandomRotation</code> is ignored.
* Connected-block rules (<code>ConnectedBlockRuleSet</code>, for example double chests, fences and roofs) are ignored. Each block is drawn exactly as it is named in the prefab.
* Transition textures, side masks (<code>TextureSideMask</code>) and animations are not drawn.
* The direction of pitch and roll has been checked against the asset data, but not in the game for every block.
* Fluids are always full cubes. Entities are not shown.

{{PrefabRenderer Nav}}

PrefabRenderer:Rendering - Revision history

Maintenance script: PrefabRenderer wiki