Guide · Making models

YSM Model UV Rules and Standards

Blockbench handles texture mapping in ways that can cause visual glitches inside Minecraft. Starting with YSM 2.6.0, you must follow strict UV rules regarding coordinate alignment and minimum face sizes to guarantee your models render accurately in-game.

Why UV Standards Matter

Blockbench's UV behavior can be counterintuitive, making it difficult for Minecraft's rendering engine to reproduce certain texture mappings reliably. Since version 2.2.2, these discrepancies have caused recurring visual bugs across various updates.

To resolve this permanently, YSM 2.6.0 introduces a strict UV standard alongside an updated rendering fix. Following these rules prevents the three most common culprits behind broken textures: zero-size UVs, unaligned decimal UV coordinates, and Box UV cubes with dimensions between 0 and 1.

If your model violates these rules, it might still look fine in-game by pure luck. Fix it anyway—future YSM updates will not maintain compatibility for non-compliant UV setups.

Affected Versions and Models

These UV rules apply strictly to YSM 2.6.0 and above. However, to prevent breaking legacy content, the new UV rendering logic only affects specific model formats:

All unencrypted models are affected immediately, as well as encrypted models exported in version 2.2.1 or earlier, and encrypted models exported in version 2.6.0 or later.

Encrypted models exported between versions 2.2.2 and 2.5.x continue to use the older UV handling method. If your model strictly follows every rule in this guide but still renders differently in-game compared to Blockbench, that is considered a mod bug and should be reported on the official GitHub issue tracker.

Understanding UV Units

Before adjusting your textures, you need to know how to calculate your model's UV Unit. This value determines the smallest allowed grid step for your UV coordinates and sizes.

In Blockbench, look at two numbers: the Project UV Resolution (shown in the top-right corner of the UV panel) and the Actual Texture Resolution (shown next to the file name in the Textures panel).

Your UV Unit is calculated as Project UV Resolution divided by Actual Texture Resolution. For example, if your project resolution is 128x128 and your actual texture file is 256x256, your UV Unit is 0.5. If both resolutions match, your UV Unit is 1.

UV Unit = Project UV Resolution / Actual Texture Resolution
Example: 128 / 256 = 0.5

UV Coordinates and Minimum Size Rules

For any cube face whose surface area is not zero, both its UV coordinates and its UV dimensions must be exact integer multiples of the UV Unit. For instance, if your UV Unit is 1, you cannot have a UV coordinate at 14.5 or a width of 3.5. If your UV Unit is 0.5, increments of 0.5 are completely valid.

Additionally, for any face with a non-zero area, the absolute value of its UV size must be at least 1 UV Unit and can never be 0. Zero-size UVs are the single most common cause of texture rendering errors in YSM.

Always enable snapping in Blockbench's UV editor so your coordinates and sizes automatically align to your UV Unit grid.

Rules for Box UV Cubes

When a cube uses Box UV mode, you cannot manually resize individual face UVs—Blockbench calculates them automatically from the cube's 3D size. If a cube is too thin, Blockbench rounds the UV size down to 0, breaking the model in-game.

For Box UV cubes, if an axis has a size of 0, the faces along that axis have zero area and are safely ignored. However, for any face with a non-zero area, both of the cube axes forming that face must have an absolute size of 1 or greater.

Do not set a cube axis to a tiny decimal like 0.0001 to bypass visual glitches. Even though a near-zero face is invisible, the game still renders it and wastes performance. Instead, if you need a cube smaller than 1 unit (or with negative sizes), choose one of these two workarounds:

  1. Method 1: Set the cube's base dimensions to 1 or greater, then apply a negative Inflate value in Blockbench to shrink its visual size.
  2. Method 2: Switch the cube from Box UV to Per-face UV mode, where 3D cube dimensions no longer restrict your UV sizes.

Rules for Per-face UV Cubes

When using Per-face UV mode, your 3D cube dimensions can be any size you want, including decimals between 0 and 1. You only need to ensure that every active face has a UV size of at least 1 UV Unit and aligns to the UV Unit grid.

Be very careful when converting an existing Box UV cube whose size is less than 1 into a Per-face UV cube. During conversion, Blockbench will automatically set the UV size of those thin faces to 0. You must manually resize those 0-size UV faces to at least 1 UV Unit, or delete the unused faces entirely.

Deleting hidden or zero-area faces in Per-face UV mode is the cleanest way to avoid UV errors and improve in-game framerate.

Automatic Repair with UV0Fixer

If you have an existing model with hundreds of 0-size UV faces or non-compliant Box UV cubes, fixing them by hand in Blockbench can be tedious.

You can use the official UV0Fixer tool (distributed as UV0Fixer_v0.3.zip on the YSM documentation site) to scan and repair these violations automatically. Make sure to back up your model files and read the included instructions before running the utility.

Questions

Why does my model look fine in Blockbench but have broken textures in Minecraft?

Your model likely has 0-size UV faces, fractional UV coordinates that do not match your UV Unit, or Box UV cubes with dimensions between 0 and 1. Blockbench displays these loosely, while YSM 2.6.0 requires strict grid alignment.

How do I make a very thin cube (smaller than 1 pixel) when using Box UV?

Make the cube at least 1x1x1 in size so its Box UV generates valid texture dimensions, then give it a negative Inflate value to shrink it down. Alternatively, switch the cube to Per-face UV mode.

What happens when I convert a thin Box UV cube to Per-face UV?

Blockbench will automatically assign a UV size of 0 to any axis that was smaller than 1. You must manually stretch those 0-size UV boxes to at least 1 UV Unit or delete the unneeded faces.

Do these UV rules affect older models I already exported?

In YSM 2.6.0+, the new rules apply to all unencrypted models, encrypted models exported in 2.2.1 or older, and encrypted models exported in 2.6.0 or newer. Encrypted models exported between 2.2.2 and 2.5.x still use the legacy renderer.

Next: Armor Animations →

More in Making models

M
Adding sounds to a YSM modelSince version 2.3.0, Yes Steve Model (YSM) allows you to trigger custom or vanilla Minecraft audio directly inside your animations. This guide explains how to prepare audio files, link them in Blockbench, and control playback using Molang and playback contexts introduced in 2.5.3.
M
Adding translations (multi-language) to a YSM modelSince version 2.5.0, Yes Steve Model (YSM) supports multi-language localization through simple JSON language files. This guide walks you through setting up a language folder and writing translation keys for your model's metadata, animations, textures, and configuration menus so players worldwide can understand your model.
M
Animation controllers in YSMBefore YSM 2.3.0, animation playback rules were completely hardcoded. Starting from version 2.3.0, YSM supports Bedrock Edition animation controllers, allowing model creators to customize exactly when and how animations trigger using state machines and Molang.
M
Custom Animation Wheel and Config Menus for YSM ModelsStarting from version 2.3.0, Yes Steve Model (YSM) allows model creators to expand the standard animation roulette wheel with nested sub-wheels and interactive configuration panels. By editing the ysm.json file, you can organize extra animations into categories and let players toggle model parts or adjust values using sliders, checkboxes, and radio buttons.
M
Foreground and Background Images in the Model MenuStarting from version 2.5.0, Yes Steve Model (YSM) allows you to set custom foreground and background images for your model cards in the selection menu. This feature makes it much easier to create decorative frames and backdrops without having to build static 2D planes directly inside your 3D model geometry.
M
Make YSM models with the Blockbench YSM pluginLearning the raw Yes Steve Model (YSM) pack format manually can be complex and overwhelming for beginners. The easiest way to create YSM models is by installing the ysm-utils plugin for Blockbench, which automates the setup and export process. This guide covers how to choose, install, and update the plugin for your specific mod version.