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

``bash
npm install blockymodel-texture three
`

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

Usage

$3

`typescript
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)
});
`

$3

`typescript
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
);
`

$3

`typescript
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

`typescript
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