Uv Mapping

🧠 Brains complement: IF an unreal-engine-skills-manager tool (external MCP) exists in this session, call it with {action: "load", skill: "meshes-static-and-skeletal"} for UE domain knowledge on this topic — correct APIs, architecture, best practices — and treat it as the rubric for any review / "best practices" question. If no such tool is available (e.g. running under Claude Code or Codex without that MCP), skip this line entirely and proceed with this skill alone — do NOT attempt the call.

UV Mapping Skill

For seams on imported organic assets, first distinguish UV boundaries from split corner normals, image-border wrapping and invalid material-section indices. See the materials skill's references/generated-organic-surfaces.md and the asset-management skill's references/mesh-reimport-materials.md. Do not unwrap an approved mesh merely because its shading has a sharp band.

UVMappingService provides automation-grade UV channel manipulation for StaticMesh assets in UE 5.7+. The service is built around mesh-description editing and post-build commits — every mutation marks the package dirty and rebuilds render data, but does not save. Follow with unreal.EditorAssetLibrary.save_asset(mesh_path) once you finish a batch.

When NOT to Use This Service

UV transforms are the wrong tool for fixing a tiling material that looks bad on a basic shape (cube, sphere, cylinder, cone). Symptoms that say "this is not a UV problem":

• "The bricks face the wrong way on this face."
• "The bricks tile fine on the side but look stretched on the cap."
• "It tiles correctly on one shape but not another with the same material."

These are material-orientation problems, not UV-layout problems. A single 2D UV transform can't satisfy multiple face orientations on a 3D shape — whichever projection you pick, at least one face will be wrong. Reach for one of these instead:

1. Per-actor child Material Instance with Tiling overridden. If the parent material exposes a Tiling scalar (Megascans M_MS_Srf does), create a child MI with the right multiplier and assign it to the specific actor. The mesh keeps its stock UVs.
2. World-aligned / triplanar material. A material that samples textures projected from world axes and blends by world normal. Every face on every shape shows correctly oriented bricks at the right size, regardless of mesh UVs. UE provides /Engine/Functions/Engine_MaterialFunctions02/Texturing/WorldAlignedTexture and WorldAlignedNormal for this.

UVMappingService is the right tool for:

• Generating lightmap UVs / fixing lightmap overlaps
• Repairing imported broken UVs (no UVs at all, gigantic UVs, scrambled layouts)
• Adding a detail-texture UV channel that needs different tiling than channel 0
• Texel-density auditing
• UV layout export for documentation
• Channel lifecycle (add / remove / copy / set count)

If the user asks to "fix UVs" on a basic shape with a tiling material, ask whether they want material-side or mesh-side first — defaulting to mesh-side will burn iterations.

Critical Rules

StaticMesh Only (Mostly)

Detailed inspection and all mutating operations target UStaticMesh. SkeletalMesh meshes are accepted by list_uv_channels and mesh_has_uv_channel for read-only channel counts but all other methods will fail on skeletal meshes — the editing path goes through FSkeletalMeshLODModel and is not yet implemented. If you're prompted to UV-map a skeletal mesh, stop and tell the user.

Save After Edits

UVMappingService calls MarkPackageDirty() and PostEditChange() on every successful mutation but does not save. After a batch of edits:

unreal.UVMappingService.set_lightmap_settings("/Game/Meshes/SM_Wall", 1, 0, 128, True)
unreal.UVMappingService.generate_lightmap_uvs("/Game/Meshes/SM_Wall", 0, 1, 1.0)
# Save once at the end:
unreal.EditorAssetLibrary.save_asset("/Game/Meshes/SM_Wall")

Health Check Before Editing

Always run get_uv_health first. It is a single call that tells you channel count, lightmap config, overlap status, and texel density per channel. This prevents wasted work like generating lightmap UVs into an index that already has good UVs.

Lightmap Channel Convention

By UE convention:

• Channel 0 holds the texture/material UVs.
• Channel 1 is the lightmap UV channel.
• LightMapCoordinateIndex on the static mesh must point at the lightmap channel.

generate_lightmap_uvs automatically sets LightMapCoordinateIndex = DestUVIndex for you. remove_uv_channel adjusts it if you remove a channel above or at the lightmap.

Channel 0 Cannot Be Removed

remove_uv_channel rejects channel 0 — every static mesh must have at least one UV channel. To replace channel 0's contents, use auto_unwrap_uvs or copy_uv_channel.

MAX_MESH_TEXTURE_COORDS_MD = 8

Static meshes support at most 8 UV channels. add_uv_channel returns failure beyond this limit; set_uv_channel_count rejects counts > 8.

Overlap Detection Is Heuristic

OverlapPercent uses an O(N²) AABB-overlap heuristic on triangle UV bounding boxes, capped at 5,000 triangles. Above the cap, the field returns -1.0 to signal "skipped." It produces conservative false positives (touching but non-overlapping AABBs) — use it as a smoke test, not a precise measurement.

Pack Is Fit-To-Square, Not True Island Packing

pack_uvs rescales the entire channel's UV bounds into [padding, 1-padding]^2. It does not detect connected islands and shelf-pack them. For real island packing, run auto_unwrap_uvs with Box projection first — that produces island-shaped charts the engine packs internally.

Per-Region UV Edits (Artist-Grade)

For meshes where one face/region needs a different UV transform than the rest (e.g. a thin disc whose side strip distorts a wall texture while the cap looks fine), use the per-region transforms. They apply an affine transform to a subset of vertex instances, leaving everything else untouched.

Filter By Vertex Normal Direction

transform_u_vs_by_normal(mesh, lod, channel, axis_x, axis_y, axis_z, min_dot, max_dot, scale_u, scale_v, rotation_degrees, offset_u, offset_v)

Applies the affine transform only to vertex instances whose normal, dotted with the given axis, falls in [min_dot, max_dot]. Common windows for axis = world +Z (0,0,1):

count_vertices_by_normal(mesh, lod, axis_x, axis_y, axis_z, min_dot, max_dot) previews the selection without modifying anything — call it first to verify your filter is selecting the right region.

Worked example — fix a thin disc's side strip aspect ratio while leaving the cap correct:

# Disc: scale (2.5, 2.5, 0.4), so world dimensions 250cm wide × 40cm tall.
# Side strip is 785cm (circumference) × 40cm (height) — 20:1 aspect.
# Cap is 250×250cm — 1:1 aspect.
# With a uniform brick material at Tiling=4, the cap renders correct bricks
# but the side renders as horizontal pinstripes.

# Step 1: confirm the filter selects only the side
side = unreal.UVMappingService.count_vertices_by_normal(
    "/Game/Meshes/SM_Disc", 0,  0,0,1,  -0.5, 0.5)
print(f"side vertex instances: {side}")  # ~960 for engine cylinder

# Step 2: scale U on the side only by 20x to bring tile aspect back to ~1:1
unreal.UVMappingService.transform_u_vs_by_normal(
    "/Game/Meshes/SM_Disc", 0, 0,
    0,0,1,        # axis = world Z
    -0.5, 0.5,    # side selector
    scale_u=20.0, scale_v=1.0,  # only U
)
unreal.EditorAssetLibrary.save_asset("/Game/Meshes/SM_Disc")

💡 Which axis to scale: figure out the world-space aspect of the misbehaving region, then scale UVs to compensate. If a region is 20× wider than tall in world, scale U by 20× to make the brick texture tile 20× more in U than V — bricks now appear correctly proportioned.