> For the complete documentation index, see [llms.txt](https://2yeet.gitbook.io/anvilcsg/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://2yeet.gitbook.io/anvilcsg/validation-and-build/lighting-and-uv2.md).

# Lighting and UV2

Build + Bake first generates the map, then runs Unity lighting and packages the result with the Anvil Baked Map.

## Lighting quality

The Build Map window provides these starting points:

| Quality |   Lightmap page |     UV2 density |         Padding |
| ------- | --------------: | --------------: | --------------: |
| Preview |             512 |   4 texels/unit |            8 px |
| Good    |            1024 |   8 texels/unit |            8 px |
| Better  |            2048 |  16 texels/unit |           16 px |
| Best    |            4096 |  32 texels/unit |           16 px |
| Custom  | User controlled | User controlled | User controlled |

**Build Only** skips the light bake.

Preview is useful for checking placement and broad lighting. Use Good, Better, or Best when you need progressively denser lightmaps and higher sample counts. The final choice still depends on map size, target hardware, and acceptable bake time.

Custom mode exposes:

* UV2 Padding from 1 to 128 px
* Lightmap Page Size from 256 to 4096
* UV2 Texels/Unit from 1 to 128
* Bounces
* Direct Samples
* Indirect Samples
* Environment Samples

## Light-bake controls

The public Light Mode is **Unity Default**.

Bake Mode:

* Auto
* GPU
* CPU

Denoiser:

* Auto
* None
* Optix
* OpenImageDenoise

**Default Skybox Reflection** includes the active skybox in the expected reflection setup.

The available GPU device, denoiser, and final bake behavior come from the active Unity version and lighting backend.

Custom sample controls are under **Advanced**:

* **Direct Samples** affect direct lights and baked shadows.
* **Indirect Samples** affect bounced lighting and are usually the first value to raise when indirect light looks cloudy or smeared after denoising.
* **Environment Samples** affect skybox and environment lighting.

Higher sample counts reduce noise but increase bake time. Tooltips in the Build Map window repeat this guidance beside each control.

## Ambient occlusion

Enable **Baked AO** to add contact darkening during the bake.

Controls:

* Strength, 0 to 4
* Distance, 0.01 to 32
* Samples, 64 to 4096
* Direct Light Influence under Advanced

The defaults are Strength `1`, Distance `1`, Samples `256`, and Direct Light Influence `0`.

Keep Distance near the scale of the corners and gaps you want AO to affect. A large value can darken broad areas instead of only contact points. More samples reduce noise but increase bake time.

## Choosing a UV2 mode

### Unity Default

Uses Unity's secondary-UV generation path. It is the simpler fallback when Anvil Unwrap is not suitable for a particular project or platform.

Anvil requests a small packing safety guard in addition to the chosen padding. This prevents Unity's packing and texel rounding from turning an otherwise valid margin into a borderline UV2 validation failure.

### Anvil Unwrap

Generates and packs lightmap UVs for Anvil output. The pipeline includes brush-projection packing, native xatlas attempts where available, padding retries, Unity fallback generation, world-scale fallback, stair seam handling, and rectangular decal charts.

The build validates the final UV2 before replacing the current map.

## Prefab UV2

Prefabs placed in the Anvil workspace use their own lightmap UV2 path. During Build Map, Anvil creates generated copies of the prefab meshes and prepares UV2 on those copies. The original prefab and its source meshes are not changed.

Under **Prefab UV2 Settings**, choose one of these modes:

### Use Map Settings

Uses the map UV2 padding, page size, and texel density. This is the normal starting point when props should match the lighting detail of the surrounding map.

### Custom

Provides three prefab-only controls:

* **Prefab UV2 Padding** controls the space between charts.
* **Prefab Lightmap Page Size** controls the final size of each prefab lightmap page.
* **Prefab UV2 Texels/Unit** controls lighting detail on prefab surfaces.

Bounces, ambient occlusion, denoising, and the remaining bake settings are still shared with the map.

During Build + Bake, prefab renderers are kept separate from brush and decal lightmap pages. Several prefabs share the selected prefab page until it is full. Anvil creates another page only when more space is needed. A 512 prefab page therefore means a final 512 by 512 packaged page, not one 512 page for every prefab.

Unity uses one scene-wide atlas size while it bakes. Anvil may temporarily place a prefab page inside that larger bake atlas, then crop and remap it to the requested physical page size when the lighting is packaged. Renderer scale and offset data are updated with the cropped page.

Prefab UV2 generation prefers xatlas, validates the result, and can fall back to a clean imported UV2 or Unity generation when required. UV0 and material mapping are unaffected. Source UV channels used by custom shaders are preserved on the generated prefab copy where possible.

Run a new Build + Bake after changing prefab UV2 settings. Previously packaged lightmaps are not resized in place.

## What UV2 validation checks

Anvil checks for:

* Missing UV2
* Coordinates outside the 0 to 1 range
* Degenerate UV triangles
* Geometric overlap
* Texel-padding overlap
* Unsafe distance from the atlas edge
* Very small charts
* Grid error
* Large density differences

Diagnostics can include chart count, minimum gap, edge distance, minimum chart size, grid error, and density range.

A final UV2 failure blocks the normal build unless **Ignore UV2 Validation** is enabled deliberately.

Validator success means the UV layout passed its structural checks. It does not guarantee that every bake is visually free of seams or light leaks. Inspect stairs, decals, arches, grouped chunks, and low-resolution bakes in the actual scene before shipping.

There is no separate Anvil UV2 viewer. Use Unity's mesh and lightmap views, Check Map diagnostics, and the build report's generated-asset actions.

## What happens during Build + Bake

Anvil performs this sequence:

1. Checks the source scene and build request.
2. Creates a recovery checkpoint.
3. Saves the active scene so Unity can associate its lighting data.
4. Builds generated output.
5. Temporarily hides editable brush renderers and source probes.
6. Keeps source lights active.
7. Runs Unity lighting.
8. Validates and packages the result.
9. Restores the editable workspace state.

A restore journal under `Library/Anvil/LightBakeRestoreJournal.asset` protects renderer, probe, and skybox state if a bake is interrupted or scripts reload.

Packaged lighting can include:

* Lightmap color pages
* Direction pages
* Shadow-mask pages
* Reflection-probe textures
* Portable light-probe data
* Renderer lightmap assignments and scale-offset data

## Several maps in one scene

Anvil registers a map's lightmap pages without replacing pages already registered by other generated Anvil maps.

The scene skybox is global. When several maps are present, normally only one Map Build component should have **Apply Map Skybox** enabled.

Portable multi-map light-probe composition is strongest on Unity 6. Test the complete workflow on every Unity version listed as supported by your project.