UV-Aware Texturing and Atlasing

Bridge procedural mesh and texture generation with UV-aware workflows.

Overview

This skill covers:

• Reading UV bounds from meshes
• Generating textures mapped to UV regions
• Texture atlas creation and UV remapping
• Character texturing workflows
• Decal and detail projection

Key principle: All generation is BUILD-TIME tooling. Output files are bundled into ROM.

Quick Decision Guide

Task	Approach	Reference
Single mesh texture	UV-aware generation	references/uv-mapping.md
Multiple meshes	Atlas packing	references/atlas-packing.md
Character skins	Region-based	references/character-texturing.md
Damage/wear	Decal projection	references/decal-projection.md

ZX Texture Resolution Guidelines

Use Case	Resolution	Texel Density
Character main	256x256	~64 texels/unit
Character detail	128x128	~32 texels/unit
Props	64-128	~24-32 texels/unit
Terrain tiles	128x128	Varies

Basic UV Bounds Reading

from dataclasses import dataclass
import numpy as np

@dataclass
class UvBounds:
    min_u: float
    max_u: float
    min_v: float
    max_v: float

def get_uv_bounds(uvs: np.ndarray) -> UvBounds:
    """Calculate UV bounds from mesh UV coordinates."""
    return UvBounds(
        min_u=float(np.min(uvs[:, 0])),
        max_u=float(np.max(uvs[:, 0])),
        min_v=float(np.min(uvs[:, 1])),
        max_v=float(np.max(uvs[:, 1]))
    )

For detailed implementation, see references/uv-mapping.md.

Texture Resolution Calculation

Match texture resolution to mesh detail:

import math

def calculate_texture_resolution(
    mesh_area: float,
    uv_bounds: UvBounds,
    target_density: float
) -> tuple[int, int]:
    """Calculate optimal texture resolution for mesh."""
    desired_texels = math.sqrt(mesh_area * target_density**2)
    uv_coverage = (uv_bounds.max_u - uv_bounds.min_u) * (uv_bounds.max_v - uv_bounds.min_v)
    size = desired_texels / math.sqrt(uv_coverage)

    # Round to next power of 2, clamp to 64-512
    size = 2 ** math.ceil(math.log2(size))
    size = max(64, min(512, size))

    return (size, size)

Character Workflow Summary

1. Generate mesh with UVs (procedural-meshes)
2. Calculate texture resolution (64 texels/unit)
3. Identify UV regions (body, head, limbs)
4. Generate albedo (skin + clothing)
5. Generate MRE/SSE (per-region roughness)
6. Export coordinated set

See references/character-texturing.md for complete workflow.

Atlas Workflow Summary

1. Generate individual textures for props
2. Pack into atlas using shelf algorithm
3. Remap mesh UVs to atlas coordinates
4. Export single atlas + remapped meshes

See references/atlas-packing.md for packing algorithms.

nether.toml Integration

# Character with coordinated textures
[[assets.meshes]]
id = "player"
path = "generated/meshes/player.gltf"

[[assets.textures]]
id = "player_albedo"
path = "generated/textures/player_albedo.png"

# Atlased props (single texture for multiple meshes)
[[assets.textures]]
id = "props_atlas"
path = "generated/textures/props_atlas.png"

[[assets.meshes]]
id = "crate"
path = "generated/meshes/crate.gltf"  # UVs remapped to atlas

References

• references/uv-mapping.md - UV bounds, islands, per-island texturing
• references/character-texturing.md - Character regions, skin tones
• references/atlas-packing.md - Shelf packing, UV remapping
• references/decal-projection.md - Decals, wear overlays

Related Skills

• procedural-meshes - Generating meshes with UVs
• procedural-textures - Base texture generation