Texture application and UV mapping for BlockyModel format
npm install blockymodel-textureTexture 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
``bash`
npm install blockymodel-texture three
Note: three is a peer dependency and must be installed separately.
`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)
});
`
`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
);
`
`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
);
`
`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
}
``
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).
MIT