# 3. Lightmap UVs and Texel Density
Part of [[Lighting and Baking]]. Previous: [[2.GPU Lightmapper Workflow]]. Next: [[4.Light Probes and Adaptive Probe Volumes]].
Baked lightmaps sample a unique UV layout in **`Mesh.uv2`** (also called UV1 in some DCC / Unity UI wording). Bad UVs produce streaks, black edges, overlapping burns, and "my lightmap is 4k but this prop is muddy."
Official: [Generate lightmap UVs](https://docs.unity.com/en-us/engine/6000.0/manual/lighting-overview/direct-and-indirect-lighting/lightmapping/lighting-gi-uvs/generating-lightmapping-uvs) · [Model Lightmap UVs settings reference](https://docs.unity3d.com/6000.6/Documentation/Manual/LightingGiUvs-Reference.html)
## 3.1 Rules for a good lightmap UV set
From Unity's Manual:
- Stay in **[0,1] × [0,1]** UV space.
- Keep **enough margin** between charts (see UV overlap feedback / padding).
- **No overlapping faces** in the lightmap UV.
- Low angular distortion vs the 3D mesh.
- Low relative-scale distortion unless you *intentionally* densify an area.
**Authored vs generated**
| Approach | Channel | When |
|---|---|---|
| Author in DCC | Pack into mesh UV2 | Hero assets, modular kits, anything that must match texel density across kits |
| **Generate Lightmap UVs** on import | Unity writes `Mesh.uv2` | Prototypes, KitBash, most environment midground |
Real-time lightmaps (if used) may share UV2 or use UV3 — see the Manual's real-time UV notes. This URP bake series focuses on **baked** UV2.
## 3.2 Generate Lightmap UVs on import
1. Select the Model in the Project window.
2. Model Import Settings > **Model** tab > **Geometry**.
3. Enable **Generate Lightmap UVs**.
4. Configure **Lightmap UVs settings** (Margin Method, Min Lightmap Resolution, Min Object Scale, etc.).
5. **Apply**.
Unity documents **Margin Method: Calculate** with Min Lightmap Resolution / Min Object Scale to reduce chart bleeding when resolution is known ahead of time.
## 3.3 Texel density
**Lightmap Resolution** (Lighting Settings) = texels per world unit. Doubling it multiplies texel count by **four** (width and height).
**Per-object control:** Mesh Renderer > **Scale in Lightmap**.
| Goal | Action |
|---|---|
| Hero prop sharper | Scale in Lightmap 2–4 (watch atlas packing) |
| Distant building shell | Scale in Lightmap 0.25–0.5 |
| Tiny debris | Scale 0 **or** disable Contribute GI and use probes |
**Occupied texels** in the Lighting window statistics tell you whether the atlas is full of useful samples or empty padding.
Rough desktop starting points *(art-dependent, not official presets)*:
| Content | Resolution (texels/unit) |
|---|---|
| Large exterior blockout | 10–20 |
| Midsize interior | 20–40 |
| Small hero diorama | 40–80 |
Quest / mobile: prefer lower resolution + Non-directional + smaller Max Lightmap Size (part 6).
## 3.4 Padding, bleeding, and seams
**Lightmap Padding** (Lighting Settings, default **2** texels) separates charts in the atlas. Raise it if neighboring charts bleed color into each other.
**Seam symptoms**
- Hard lines along UV chart edges on flat walls.
- Checker of light/dark across modular wall pieces that should be continuous.
- "Stitching" failures on continuous surfaces split into many charts.
**Fixes (in order)**
1. Confirm UV2 has no overlaps (UV Overlap draw mode / Lighting visualization — exact overlay name can vary; use Lighting window debug views available in your version).
2. Increase padding; regenerate.
3. For authored UVs: weld charts that should share lighting across modular edges, or bake modular pieces as larger combined meshes when seams are unacceptable.
4. Ensure normals are continuous where you expect smooth lighting; hard edges create lighting discontinuities that look like UV seams.
5. Avoid extreme Scale in Lightmap differences on adjacent modular pieces.
> [!tip] UV2 visualization
> Use the Mesh Renderer / UV display tools and Lighting visualization modes while iterating. Prefer fixing UVs over cranking samples — samples cannot heal overlaps.
## 3.5 Secondary UV from script (Editor)
Unity exposes `UnityEditor.Unwrapping.GenerateSecondaryUVSet` for Editor tooling. Official scripting reference: [GenerateSecondaryUVSet](https://docs.unity.com/en-us/engine/6000.0/script-reference/unityeditor/unwrapping/generatesecondaryuvset).
```csharp
#if UNITY_EDITOR
using UnityEditor;
using UnityEngine;
public static class LightmapUvTools
{
[MenuItem("Tools/Lighting/Generate Secondary UVs On Selection Meshes")]
static void Generate()
{
foreach (var filter in Selection.GetFiltered<MeshFilter>(SelectionMode.Editable))
{
var mesh = filter.sharedMesh;
if (mesh == null) continue;
if (!AssetDatabase.Contains(mesh))
{
Debug.LogWarning(
quot;Skip non-asset mesh on {filter.name}", filter);
continue;
}
Unwrapping.GenerateSecondaryUVSet(mesh);
EditorUtility.SetDirty(mesh);
}
AssetDatabase.SaveAssets();
}
}
#endif
```
> [!warning] Not compiled
> Prefer Model Importer **Generate Lightmap UVs** for imported FBX/glTF. Calling `GenerateSecondaryUVSet` on shared meshes mutates assets — use only with version control awareness.
## 3.6 Checklist before every bake
1. Every Contribute-GI mesh has valid UV2 (authored or generated).
2. No intentional UV2 overlaps.
3. Lightmap Resolution and Scales match art priorities.
4. Max Lightmap Size fits target memory (especially Quest).
5. Directional vs Non-directional chosen (part 1 / 6).
6. Then Generate Lighting (part 2).
Next: [[4.Light Probes and Adaptive Probe Volumes]].