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:

pythonCopy code
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:

pythonCopy code
# 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.

UV Islands (Most Robust Per-Region Filter)

Use identify_uv_islands + transform_uv_island when normal-direction or polygon-group filters can't cleanly separate the regions you want to operate on (e.g. an irregular mesh, or a UV layout where similar-normal faces are still distinct islands).

identify_uv_islands(mesh, lod, channel) returns an array of FUVIslandInfo, one per connected UV island. Two vertex instances are in the same island iff they're reachable through triangles with no UV seam between them.

pythonCopy code
islands = unreal.UVMappingService.identify_uv_islands("/Game/Meshes/SM_Disc", 0, 0)
for i in islands:
    n, c = i.average_normal, i.world_center
    print(f"Island {i.island_id}: tris={i.triangle_count} VIs={i.vertex_instance_count} "
          f"bounds=({i.min_u:.2f},{i.min_v:.2f})..({i.max_u:.2f},{i.max_v:.2f}) "
          f"normal=({n.x:.2f},{n.y:.2f},{n.z:.2f}) center=({c.x:.0f},{c.y:.0f},{c.z:.0f})")

Each island carries its own bounds, area, average world-space center and average normal — use those fields to identify which island is which. For a simple cylinder you'll get 3 islands: top cap (normal ≈ +Z), bottom cap (normal ≈ -Z), and the side strip (largest triangle count).

Once you've identified the island, transform just it:

pythonCopy code
# Example: scale only the side strip's UV U by 4x — caps and other islands untouched
side = max(islands, key=lambda i: i.triangle_count)
unreal.UVMappingService.transform_uv_island(
    "/Game/Meshes/SM_Disc", 0, 0, side.island_id,
    scale_u=4.0, scale_v=1.0)

Island ids are stable as long as the mesh's UV topology hasn't changed since identify_uv_islands was called. If you re-run an auto_unwrap / pack / structural change, call identify_uv_islands again for fresh ids before transforming.

Filter By Polygon Group (Material Slot)

transform_u_vs_by_polygon_group(mesh, lod, channel, polygon_group_name, scale_u, scale_v, rotation_degrees, offset_u, offset_v)

Applies the transform only to triangles in the named polygon group (typically a material slot). Use when the mesh has clean per-section slots — e.g. a wall with separate body and trim material slots, where you want different tiling per slot but the same base material.

list_polygon_groups(mesh, lod) returns the slot names available on a LOD. The engine basic shapes have just one slot (DefaultMaterial), so this filter is most useful on imported meshes with authored slots.

pythonCopy code
groups = unreal.UVMappingService.list_polygon_groups("/Game/Meshes/SM_Wall", 0)
# ['Body', 'Trim']
unreal.UVMappingService.transform_u_vs_by_polygon_group(
    "/Game/Meshes/SM_Wall", 0, 0, "Trim",
    scale_u=2.0, scale_v=2.0,  # 2x denser bricks on trim only
)

Common Mistakes to Avoid

Return Types — Exact Properties

FUVMappingResult (every mutating call)

FUVChannelInfo (list_uv_channels, get_uv_channel_info)

FUVHealthReport (get_uv_health)

FUVLightmapSettings (get_lightmap_settings)

Workflows

Workflow: Generate Lightmap UVs for a Newly Imported Mesh

pythonCopy code
import unreal

mesh = "/Game/Meshes/SM_Wall"

# 1. Health check
ok, health = unreal.UVMappingService.get_uv_health(mesh)
print(f"Channels found: {len(health.channels)}, lightmap idx: {health.lightmap_coordinate_index}")

# 2. Generate the lightmap channel (creates channel 1 if needed, sets LightMapCoordinateIndex=1)
result = unreal.UVMappingService.generate_lightmap_uvs(
    mesh,
    source_uv_index=0,
    dest_uv_index=1,
    min_chart_spacing_percent=1.0,
)
print(f"GENERATED: {result.message}")

# 3. Configure lightmap resolution (256 for hero props, 64 for background)
unreal.UVMappingService.set_lightmap_settings(mesh, 1, 0, 128, True)

# 4. Save
unreal.EditorAssetLibrary.save_asset(mesh)

# 5. Verify
ok, health = unreal.UVMappingService.get_uv_health(mesh)
assert not health.b_lightmap_has_overlaps, "Lightmap still has overlaps after generation"

Workflow: Add a Detail-Texture UV Channel and Tile It

pythonCopy code
import unreal

mesh = "/Game/Meshes/SM_Wall"

# Add channel 2 if not present
if not unreal.UVMappingService.mesh_has_uv_channel(mesh, 0, 2):
    r = unreal.UVMappingService.add_uv_channel(mesh, 0)
    print(f"ADDED: {r.message}")

# Copy material UVs (channel 0) into channel 2 as a starting point
r = unreal.UVMappingService.copy_uv_channel(mesh, 0, 0, 2)
print(f"COPIED: {r.message}")

# Tile by 4 (scale UVs)
r = unreal.UVMappingService.transform_uvs(mesh, 0, 2, scale_u=4.0, scale_v=4.0)
print(f"TILED: {r.message}")

unreal.EditorAssetLibrary.save_asset(mesh)

Workflow: Auto-Unwrap a Mesh That Imported with Bad UVs

pythonCopy code
import unreal

mesh = "/Game/Meshes/SM_RuinPiece"

# Box projection produces clean per-face charts on chunky props
r = unreal.UVMappingService.auto_unwrap_uvs(
    mesh, lod_index=0, channel_index=0,
    projection_type="Box",
    hard_angle_threshold=66.0,
)
print(f"UNWRAPPED: {r.message}")

# Pack the result tightly
r = unreal.UVMappingService.pack_uvs(mesh, 0, 0, padding_percent=1.0)
print(f"PACKED: {r.message}")

# Regenerate the lightmap channel from the new charts
unreal.UVMappingService.generate_lightmap_uvs(mesh, 0, 1, 1.0)

unreal.EditorAssetLibrary.save_asset(mesh)

Workflow: Visual UV Inspection (AI-Friendly)

pythonCopy code
import unreal, os

mesh = "/Game/Meshes/SM_Wall"
out = os.path.join(os.environ["TEMP"], "uv_layout.png")

r = unreal.UVMappingService.export_uv_layout_image(
    mesh, lod_index=0, channel_index=1, output_path=out, image_size=1024)
print(f"EXPORTED: {r.message}")
# Then read the PNG back to inspect it visually (Read the file path directly,
# or surface it through the engine's screenshot/image toolset).

Workflow: Batch Lightmap Pass on All Meshes in a Folder

pythonCopy code
import unreal

results = unreal.EditorAssetLibrary.list_assets("/Game/Meshes/Architecture")
for asset in results["assets"]:
    if asset["asset_class"] != "StaticMesh":
        continue
    path = asset["asset_path"]

    ok, health = unreal.UVMappingService.get_uv_health(path)
    if health.b_lightmap_has_overlaps or not health.b_generate_lightmap_uvs:
        unreal.UVMappingService.generate_lightmap_uvs(path, 0, 1, 1.0)
        unreal.UVMappingService.set_lightmap_settings(path, 1, 0, 128, True)
        unreal.EditorAssetLibrary.save_asset(path)
        print(f"FIXED: {path}")
    else:
        print(f"OK:    {path}")

Property Formats

Projection Types (auto_unwrap_uvs)

String, case-insensitive:

• "Planar" — projects along world +Z. Best for flat panels.
• "Box" — six-axis projection with seams along sharp edges. Best general-purpose unwrap.
• "Cylindrical" — wraps around world Z axis. Best for tubes / columns.

Min Chart Spacing (generate_lightmap_uvs)

Float, percent of UV space (0.5..2.0 typical):

• 0.5 — tight packing, risk of bleeding at low lightmap resolution
• 1.0 — default, safe for 64–128 lightmap resolution
• 2.0 — generous, good for 32 resolution background props

Lightmap Resolution (set_lightmap_settings)

Power of two preferred:

• 32–64 — background / non-hero
• 128 — typical world geometry
• 256–512 — hero props, large architecture

Verification After Edits

For lightmap-related changes, always re-run get_uv_health after the save to verify:

pythonCopy code
ok, health = unreal.UVMappingService.get_uv_health(mesh)
assert ok
assert not health.b_lightmap_has_overlaps
assert health.lightmap_coordinate_index == 1

For unwrap operations, export the layout PNG and visually inspect it (read the PNG back, or surface it through the engine's screenshot/image toolset) — the cheapest way to confirm the unwrap looks reasonable.

Sample scripts (run via execute_python_code)

• scripts/inspect_uvs.txt — inspect UV channels/health and export a UV layout image.