blockymodel-texture

Texture application and UV mapping for BlockyModel format.

This package provides the core texture rendering logic for Hytale's BlockyModel 3D format, including:

• Per-face UV mapping with offset, mirror, and rotation support
• Pixel-art texture configuration (nearest-neighbor filtering)
• Box and quad geometry texture layout application

Installation

npm install blockymodel-texture three

Note: three is a peer dependency and must be installed separately.

Usage

Apply texture to a loaded model

import { applyTextureToModel } from "blockymodel-texture";
import * as THREE from "three";

// Load your model and texture...
const model: THREE.Group = /* loaded BlockyModel */;
const texture = new THREE.TextureLoader().load("texture.png");

// Apply texture with pixel-art settings
applyTextureToModel(model, texture);

// Or with custom options
applyTextureToModel(model, texture, {
  pixelArt: true,      // Use nearest-neighbor filtering (default: true)
  transparent: true,   // Enable PNG alpha support (default: true)
  alphaTest: 0.1,      // Alpha threshold (default: 0.1)
});

Apply UV layout to a single geometry

import { applyTextureLayoutToBox, applyTextureLayoutToQuad } from "blockymodel-texture";
import type { TextureLayout } from "blockymodel-texture";

const layout: TextureLayout = {
  front: { offset: { x: 0, y: 0 }, mirror: { x: false, y: false }, angle: 0 },
  back: { offset: { x: 8, y: 0 }, mirror: { x: false, y: false }, angle: 0 },
  // ... other faces
};

// For box geometries
applyTextureLayoutToBox(
  boxGeometry,
  layout,
  64,  // texture width
  64,  // texture height
  { x: 8, y: 8, z: 8 }  // box size in pixels
);

// For quad/plane geometries
applyTextureLayoutToQuad(
  planeGeometry,
  layout,
  64,
  64,
  { x: 8, y: 8, z: 1 },
  "+Z"  // normal direction
);

Calculate UV coordinates directly

import { calculateFaceUVs } from "blockymodel-texture";
import type { FaceUV } from "blockymodel-texture";

const faceUV: FaceUV = {
  offset: { x: 16, y: 8 },
  mirror: { x: false, y: false },
  angle: 90,
};

const [u1, v1, u2, v2] = calculateFaceUVs(
  faceUV,
  8,   // face width in pixels
  4,   // face height in pixels
  64,  // texture width
  64   // texture height
);

Types

interface FaceUV {
  offset: Vec2;                        // Top-left pixel coordinate
  mirror: { x: boolean; y: boolean };  // Flip sampling direction
  angle: 0 | 90 | 180 | 270;           // Rotation in degrees
}

interface TextureLayout {
  front?: FaceUV;   // +Z face
  back?: FaceUV;    // -Z face
  left?: FaceUV;    // -X face
  right?: FaceUV;   // +X face
  top?: FaceUV;     // +Y face
  bottom?: FaceUV;  // -Y face
}

UV Mapping Algorithm

Based on Hytale's Blockbench Plugin implementation:

1. Offset: Specifies top-left corner of texture region in pixel coordinates
2. Mirror: Flips the sampling direction (reverses UV range)
3. Angle: Rotates the UV region:
   • 0°: No rotation
   • 90°: Swap dimensions, adjust mirrors
   • 180°: Flip both axes
   • 270°: Swap dimensions, flip different axis

The V coordinate is flipped during application because Hytale uses image coordinates (top-left origin, Y increases downward) while Three.js UV uses bottom-left origin (V increases upward).

License

MIT