nccgs 2.1.1 → 3.0.0-rc.2

package/unity-skills/migrate-birp-to-urp/references/migration-workflow.md

@@ -0,0 +1,265 @@
+# Built-in to URP Migration Workflow
+
+Use this workflow to follow the official Unity migration flow and identify when to slow down, branch, or stop.
+
+## Table of Contents
+
+- [Official References](#official-references)
+- [Safety First](#safety-first)
+- [Project Preparation](#project-preparation)
+- [Phased Migration Model](#phased-migration-model)
+- [Standard 3D Path: Built-in Render Pipeline to URP](#standard-3d-path-built-in-render-pipeline-to-urp)
+- [What Each Converter Does](#what-each-converter-does)
+- [Targeted Material-Only Path](#targeted-material-only-path)
+- [2D Path: Built-in Render Pipeline 2D to URP 2D](#2d-path-built-in-render-pipeline-2d-to-urp-2d)
+- [2D Lighting Note](#2d-lighting-note)
+- [Baked Lighting, Lightmaps, And Reflection Probes](#baked-lighting-lightmaps-and-reflection-probes)
+- [Manual Follow-Up Hot Spots](#manual-follow-up-hot-spots)
+- [When To Stop And Escalate](#when-to-stop-and-escalate)
+
+## Official References
+
+- [Upgrading from the Built-in Render Pipeline to URP](https://docs.unity3d.com/Manual/urp/upgrading-from-birp.html)
+- [Convert assets using the Render Pipeline Converter](https://docs.unity3d.com/Manual/urp/features/rp-converter.html)
+- [Upgrade material assets to URP or HDRP](https://docs.unity3d.com/Manual/upgrade-material.html)
+- [URP asset](https://docs.unity3d.com/Manual/urp/urp-asset-and-renderer.html)
+- [Prepare and upgrade sprites for 2D lighting in URP](https://docs.unity3d.com/Manual/urp/PrepShader.html)
+- [Set up a render pipeline](https://docs.unity3d.com/Manual/render-pipelines-set-up.html)
+- [Update believable visuals in URP and HDRP](https://docs.unity3d.com/Manual/BestPracticeMakingBelievableVisuals0.html)
+
+## Safety First
+
+- Render Pipeline Converter changes are one-way. Run conversion only after the user has confirmed a backup, branch, or rollback point.
+- Installing URP and assigning a URP asset can also leave the project in a partial magenta state before materials are converted. If rollback safety is not confirmed, stop before package install or Graphics/Quality assignment, not after.
+- If the user has confirmed rollback safety or says this is a disposable copy, treat that confirmation as covering the full migration pass. Do not ask again before each converter unless a new risky decision appears.
+- Inspect warnings before and after conversion instead of treating converter output as success by default.
+- If the project is also moving to a new Unity version, the safer order is: engine upgrade first, render-pipeline migration second.
+
+## Project Preparation
+
+Before conversion:
+
+1. Inspect whether the project is truly still on Built-in or already partially on URP.
+2. Identify likely migration hot spots:
+   - custom shaders
+   - Asset Store rendering packages
+   - Post-processing Stack v2
+   - image effects or camera callbacks
+   - replacement shaders or special camera rendering paths
+   - multiple quality levels with different graphics expectations
+   - baked lighting, lightmaps, light probes, and reflection probes
+3. If rendering plug-ins or packages are clearly Built-in-specific, do not assume they will survive the migration unchanged.
+
+Do this even when the user gives a short prompt like "upgrade this project to URP." The skill, not the user, is responsible for discovering these common migration surfaces.
+
+## Phased Migration Model
+
+Use phases for real project upgrades. A generic "migrate this project to URP" prompt starts or resumes the next phase; it does not require finishing every fragile subsystem in one response.
+
+| Phase | Goal | Completion gate |
+| --- | --- | --- |
+| Phase 0: Inspect and plan | Detect pipeline state, representative scene, rollback safety, PPv2, materials, Quality levels, lighting/probes, custom render code | Findings are reported and rollback safety is confirmed before mutation |
+| Phase 1: URP setup and materials | Install/reuse URP, create/assign URP asset/renderer, assign Graphics/Quality, convert supported opaque and particle/effect materials | Saved Graphics/Quality and material shader assignments verify correctly |
+| Phase 2: Post-processing and cameras | Convert PPv2 to persistent URP Volumes/profiles, wire cameras, disable legacy PPv2 for validation, classify unsupported PPv2 effects | Saved URP profile has non-null expected overrides, scene references it, legacy PPv2 is disabled or clearly preserved for comparison |
+| Phase 3: Lighting and probes | Resolve stale Built-in lighting data, configure URP lighting/probe settings, rebake/refresh where feasible | Saved scene lighting/probe state is verified, or the phase is explicitly partial/blocked |
+| Phase 4: Final validation | Save/reload/re-query, capture representative scenes, check Console, report complete/incomplete/manual items | Every success gate passes before using "complete" |
+
+At the end of each phase, report:
+
+- `Completed`: saved-state evidence for that phase.
+- `Incomplete`: specific failed checks and whether they are repairable.
+- `Manual follow-up`: unsupported or intentionally deferred items.
+- `Next phase`: the exact phase to run next.
+
+Continue into the next phase only when Unity remains stable, the next phase does not introduce a new costly/risky operation, and the user has already authorized that scope. Prefer a clear phase boundary over a rushed final answer.
+
+## Standard 3D Path: Built-in Render Pipeline to URP
+
+Use this path for normal 3D Built-in projects moving to URP.
+
+For a generic "migrate/upgrade to URP" request, treat the following as part of the standard phased path unless inspection proves they are absent: URP asset/renderer setup, Graphics and Quality assignment, material conversion, particle/VFX material verification, PPv2-to-URP Volume verification, baked-lighting/lightmap/probe verification, representative scene capture, saved-state re-query, and a final complete/incomplete/manual report.
+
+Do not downgrade common migration surfaces into manual follow-up just because the user used a short prompt. Discover PPv2, stale baked lighting, lightmaps, reflection probes, particle materials, and Quality-level assignments. A generic migration can be called complete only after these surfaces are either verified in saved project state or precisely reported as unsupported/manual edge cases. Until then, report the current phase as complete or partial instead of reporting the whole migration as complete.
+
+Before step 1, confirm rollback safety. If no backup, branch, archive, or disposable copy is confirmed, do not install URP or assign a URP asset. Explain that those steps can immediately make supported Built-in materials render magenta until material conversion runs.
+
+Before and after pipeline assignment, deliberately open or inspect the representative scene(s). Do not infer that baked lighting, PPv2, reflection probes, or lightmaps are absent from a default/test scene.
+
+1. Ensure URP is installed.
+   - Package installation is a phase boundary. It may trigger package refresh, compilation, and domain reload.
+   - Do not rely on a single `PackageManager.Client.Add` tool call to complete the rest of the migration. If the chat/tool call stops or returns `null`, wait for Unity to finish compiling, then resume by inspecting the partial project state.
+   - If `Packages/manifest.json` already contains `com.unity.render-pipelines.universal`, do not reinstall URP; continue from asset setup and validation.
+2. Create the URP asset and renderer asset if they do not already exist.
+3. Assign the URP asset in Graphics settings. Assign it in relevant Quality levels as well.
+   - If the Console reports "Default Renderer is missing", do not stop at setup. Re-query the saved URP asset's renderer list/default index, validate a fresh scene/camera render after save/reload, and either repair the renderer asset or mark the migration partial.
+4. Open `Window > Rendering > Render Pipeline Converter`.
+5. Select `Built-in Render Pipeline to URP`.
+6. Initialize converters and inspect the result set.
+7. Run the converters that apply to the project:
+   - `Rendering Settings`
+   - `Material Upgrade`
+   - `Animation Clip Converter`
+   - `Read-only Material Converter`
+   - `Post-processing Stack v2 Converter`
+8. Re-open representative scenes and validate before doing broad cleanup.
+9. Verify saved assets after conversion. Do not rely only on converter or command logs.
+   - If the migration changed scene objects, camera components, PPv2 enable states, active Lighting Settings, or reflection probes, save the open scene as well as project assets. `AssetDatabase.SaveAssets()` does not prove scene changes persisted.
+10. For Quality levels, verify saved `customRenderPipeline` entries or re-query `QualitySettings.GetRenderPipelineAssetAt(i)`. A tool log that says Quality levels were assigned is not enough.
+11. If a script must assign Quality-level URP assets, follow URP's converter pattern: cache the current quality level, call `QualitySettings.SetQualityLevel(index)` for each target level, set `QualitySettings.renderPipeline = urpAsset`, restore the original level, save, and verify the saved `customRenderPipeline` entries. Do not use guessed APIs such as `QualitySettings.SetRenderPipelineAssetAt`.
+12. If representative scenes use baked lighting, verify the baked-lighting state separately. Do not treat a clean compile or material conversion as proof that lightmaps and probes look correct in URP.
+13. Before the final response, run a success gate:
+   - Saved Graphics and relevant Quality levels point at the intended URP asset.
+   - The saved URP asset has a valid default renderer and current validation is not blocked by renderer errors.
+   - Saved material assets, including particles/fog/smoke/VFX materials, use URP-compatible shaders or are listed as unresolved custom/package shader cases. Materials that had source textures/colors still have mapped URP textures/colors; white/gray untextured output is not a successful material conversion.
+   - If PPv2 existed, the saved URP Volume profile has persistent non-null `components` entries and the scene references the URP `Volume`; `components: []` means incomplete.
+   - If baked/mixed lighting, Enlighten/realtime-GI settings, Lighting Data, lightmaps, light probes, or reflection probes existed, lighting/probe repair has been attempted or the migration is explicitly partial because that phase is still running/incomplete.
+   - If a new URP `.lighting` asset was created, the saved scene's `m_LightingSettings` reference points to that asset after save/reload. Creating the asset and calling `Lightmapping.lightingSettings = target` is not sufficient evidence.
+   - A representative scene was inspected or captured after saving/reloading.
+   - If the representative capture is materially too dark, blown out, or high contrast, post-processing wiring and exposure/tonemapping/ambient balance have been verified and adjusted, or visual parity is explicitly partial.
+   - The final status wording matches the gate result. Say "complete" only when every required item passes. Say "partial" when URP setup/material conversion succeeded but PPv2, baked lighting, probes, or saved-state validation still need repair.
+
+If only Phase 1 is complete, say "Phase 1 complete" and list Phase 2/3/4 as next work. Do not label the whole migration complete from Phase 1 evidence.
+
+## What Each Converter Does
+
+- `Rendering Settings`: creates URP assets and maps Built-in settings to URP equivalents.
+- `Material Upgrade`: converts supported Built-in materials. It does not solve custom shader compatibility.
+- Particle and VFX materials need explicit verification. If they still point at built-in particle shaders or built-in shader IDs after conversion, migrate them to URP particle shaders such as `Universal Render Pipeline/Particles/Unlit` where appropriate.
+- Do not blindly force particle, fog, smoke, steam, decal, additive, VFX, or transparent effect materials to `Universal Render Pipeline/Lit`. Preserve transparent/additive behavior where possible, and validate off-screen/inactive particle systems by asset inspection rather than only by the current camera.
+- `Animation Clip Converter`: runs after material conversion and helps when animation clips affect material properties or Post-processing Stack v2 properties.
+- `Read-only Material Converter`: handles built-in read-only materials such as `Default-Diffuse` and can take longer because it indexes the project.
+- `Post-processing Stack v2 Converter`: converts PPv2 volumes, profiles, and related camera data to URP equivalents and can also take longer because it indexes the project.
+
+## Post-Processing Verification
+
+PPv2 conversion is successful only if the saved project state proves it.
+
+After any PPv2 migration attempt:
+
+1. Re-open or re-query the converted scene.
+2. Inspect old `PostProcessVolume`, `PostProcessLayer`, and `PostProcessProfile` usage.
+3. Inspect the resulting URP `VolumeProfile` asset. A profile with `components: []` is empty and should not be reported as migrated. A profile with `components` entries that point to `{fileID: 0}` is also invalid and should not be reported as migrated.
+   - If the profile was created by script, `VolumeProfile.Add<T>()` must be paired with `AssetDatabase.AddObjectToAsset(component, profile)` for persistent assets. Mark both the component and profile dirty, save assets, reload it from `AssetDatabase`, and verify the non-null component count persisted.
+   - If the saved profile contains `{fileID: 0}` entries where Bloom, Tonemapping, Vignette, or Depth Of Field should be, treat that as broken persistence. Repair or recreate the profile before claiming PPv2 parity.
+4. Confirm representative cameras have URP camera data and post-processing enabled when the visual target depends on it.
+5. Confirm the scene has the intended URP `Volume` setup, or explicitly document that the PPv2 setup still needs manual migration.
+   - If the scene still serializes only the old PPv2 `sharedProfile` and no URP `Volume` references the new `VolumeProfile`, PPv2 migration is incomplete even if a URP profile asset exists.
+   - If a scene URP `Volume` references a profile with `components: []`, the scene has empty URP post-processing plumbing, not migrated post-processing. Repair the profile or mark PPv2 as incomplete.
+6. If PPv2 effects include Screen Space Reflections, call out that URP has no direct equivalent in the same built-in PPv2 form. Recommend reflection probes, screen-space reflection alternatives, or a custom/third-party solution when required.
+7. For common mappable PPv2 effects, create persistent URP overrides instead of leaving a vague manual parity task. Typical mappings include Bloom -> `UnityEngine.Rendering.Universal.Bloom`, Color Grading/exposure -> `ColorAdjustments` plus `Tonemapping`, Vignette -> `Vignette`, and Depth Of Field -> `DepthOfField`.
+8. It is acceptable to mark unsupported or structurally different effects as manual follow-up, such as PPv2 Screen Space Reflections or Ambient Occlusion that should be handled through reflection probes, SSAO renderer features, or custom/third-party rendering.
+9. If old PPv2 components remain as a reference while a URP Volume is active, disable the old PPv2 layer/component during URP visual validation to avoid double post-processing. Do not delete it until the saved URP replacement has been verified and the user approves cleanup.
+10. Do not uninstall PPv2 or remove `PostProcessLayer` / `PostProcessVolume` components until the saved URP replacement has been verified, unless the user explicitly accepts effect loss or manual follow-up.
+
+If a command log says effects were added but the saved profile is empty, report the result as a failed or incomplete post-processing migration and do not claim success. If legacy PPv2 is still active while an empty URP profile exists, do not claim URP post-processing is active; state that the old PPv2 setup is preserved but the URP replacement is incomplete.
+
+## Material And Particle Verification
+
+After material conversion:
+
+1. Re-query material shader assignments on disk or through `AssetDatabase`.
+2. Confirm standard opaque materials use URP-compatible shaders, usually `Universal Render Pipeline/Lit`.
+3. Confirm particle, fog, smoke, steam, decal, VFX, and transparent effect materials are not left on Built-in particle shaders.
+4. Do not rely only on "no magenta in the current camera" as proof. Some particle systems may be off-screen, inactive, or visually subtle.
+5. If a material is custom, package-owned, or effect-heavy, classify it as manual follow-up instead of forcing it to URP Lit.
+6. For vegetation, grass, tree, terrain-detail, SpeedTree, billboard, leaf-card, and wind-driven materials, verify more than the shader name. Preserve alpha cutoff/clipping, face/culling intent, textures, tint, normals, and expected wind/billboard behavior where possible. If foliage becomes solid opaque cards, static when it was wind-driven, or visually loses its specialized behavior, report the foliage set as partial/manual instead of calling material conversion complete.
+7. For any converter or manual shader-assignment fallback, prove source material data survived from a pre-conversion snapshot. Cache `_MainTex`, `_Color`, normal, metallic/specular, emission, alpha/cutoff, texture tiling/offset, and source shader before conversion, then verify representative converted assets have non-null `_BaseMap`/expected textures and non-default color values when the source did.
+8. Do not run a "repair" that copies `_MainTex` to `_BaseMap` after conversion unless the value comes from the pre-conversion snapshot. Once a shader has changed, `_MainTex` may already be null/default; copying it later can silently preserve the broken state.
+9. Do not edit immutable package materials under `Packages/` or `Library/PackageCache`. If those assets appear in the conversion set, classify them as package-owned/read-only and use a local material copy or scoped custom replacement instead.
+10. If a representative capture shows broad white/gray untextured objects after conversion, or if snapshot comparison shows source materials had albedo textures but converted materials have null `_BaseMap`, treat the material phase as incomplete even if the materials are no longer magenta.
+
+If rollback safety was already confirmed, continue repairing ordinary material, renderer, PPv2, lighting, or probe failures instead of asking the user whether to continue. Ask only when a new destructive cleanup choice, unsupported custom shader strategy, long-running phase boundary, or repeated validation failure requires the user's decision.
+
+## Partial Migration Resume Checklist
+
+If a migration stops after installing URP, after a domain reload, after a phase boundary, or after a long-running bake:
+
+1. Re-check whether URP is now installed in `Packages/manifest.json`.
+2. Check whether a URP asset and renderer asset exist and are valid.
+3. Verify Graphics settings and every relevant Quality level point to the intended URP asset.
+4. Re-query material shader assignments, including particle/fog/smoke/VFX materials. If supported Built-in shader GUIDs or names still dominate after URP is assigned, material conversion is the immediate next incomplete phase; do not stop at "URP setup complete" when the scene is still magenta.
+5. Inspect PPv2 state and URP Volume profiles. Empty `components: []` profiles are incomplete.
+6. Inspect baked lighting/lightmap state. If old lightmaps blow out the scene, preserve them as reference, clear active baked data, rebake under URP, and refresh reflection probes.
+   - If a new URP-compatible Lighting Settings asset exists, verify the saved scene actually references it. A scene that still references the old Enlighten/realtime-GI `.lighting` asset is not fully repaired.
+   - If old `LightingData.asset` remains assigned and old reflection-probe EXRs are unchanged, do not say lighting or probes were refreshed. Report them as preserved reference data or partial until a URP bake/probe refresh completes.
+7. If a previous run ended at "would you like me to continue?" but rollback safety was already confirmed, resume from the first incomplete item instead of restarting or asking again.
+8. Capture a representative scene and report exactly which items are complete, incomplete, or manual follow-up.
+9. Name the next phase instead of restarting. For example: "Resume at Phase 2: Post-processing and cameras" or "Resume at Phase 3: Lighting and probes."
+
+## Targeted Material-Only Path
+
+Use this only when the user wants selected materials converted instead of a full migration.
+
+1. Confirm the project is already on URP.
+2. Select the Built-in materials in the Project window.
+3. Use `Edit > Rendering > Materials > Convert Selected Built-in Materials to URP`.
+4. If a material still errors in the Inspector or stays magenta, treat it as a shader triage case rather than retrying blindly.
+5. Validate one or two representative scenes after conversion because selected material upgrades can still create visual drift.
+
+## 2D Path: Built-in Render Pipeline 2D to URP 2D
+
+Use this path when the project is primarily 2D and the target is URP 2D.
+
+1. Ensure URP is installed.
+2. Create and assign a 2D Renderer asset.
+3. Open `Window > Rendering > Render Pipeline Converter`.
+4. Select `Built-in Render Pipeline 2D to URP 2D`.
+5. Use `Material and Material Reference Upgrade`.
+6. If the user wants 2D lighting, verify that sprites and materials are using URP-compatible lit materials after conversion.
+
+## 2D Lighting Note
+
+For 2D lighting in URP, Unity can assign `Sprite-Lit-Default` when sprites are dragged into the scene. Existing project materials still need to be upgraded if they should react to 2D lights.
+
+## Baked Lighting, Lightmaps, And Reflection Probes
+
+Baked lighting does not become visually correct just because the project compiles after URP setup.
+
+For scenes with baked or mixed lighting:
+
+1. Preserve existing Lighting Data, lightmaps, light probes, and reflection probes as reference data until visual parity is accepted.
+2. Inventory `Lightmapping.lightingSettings`, scene `LightmapSettings`, baked/mixed lights, light probes, reflection probes, and the scene's Lighting Data asset.
+3. Check whether the migrated scene is overexposed or too dark because both old PPv2 and new URP Volume effects are active. For URP validation, disable legacy PPv2 components/layers but do not delete them.
+4. Review URP Volume exposure, tonemapping, bloom, and color adjustments before changing light intensities.
+5. If the scene is still too dark, blown out, or high contrast after PPv2/URP Volume migration, run an exposure-balance check before the final report. Verify renderer `PostProcessData`, camera `renderPostProcessing`, `volumeLayerMask`, active Volume weight/priority/layer, and non-empty saved Volume overrides before changing values. Then tune exposure, tonemapping, lift/gamma/gain, bloom, ambient fill, additional-light limits, and shadows in bounded steps with captures between attempts.
+6. If clearing baked data makes the scene stop being blown out, treat the previous lightmaps/Lighting Data as stale active data for URP. Keep them as reference/rollback evidence, but do not tune final URP lighting against them.
+7. If parity matters, clear/rebake lighting under URP and refresh reflection probes after URP assets, renderer features, volumes, and quality settings are finalized when the user has permitted changes. If the bake is too long or interrupted, report a partial migration and resume from this phase later rather than claiming completion.
+8. When assigning new URP-compatible `LightingSettings`, remember that the active lighting-settings reference is scene state. Mark the settings and active scene dirty, save the scene, reload or re-query, and verify the saved scene references the intended asset before reporting it as active. `AssetDatabase.SaveAssets()` alone does not prove the scene's `m_LightingSettings` reference changed.
+9. If the saved scene still references the old Enlighten/realtime-GI `.lighting` asset, the lighting phase is incomplete even if a new URP lighting settings asset exists on disk.
+10. Report baked lighting as one of: preserved as reference, stale active bake cleared, visually checked and acceptable, rebaked/refreshed under URP, exposure-balanced with remaining bake risk, or manual follow-up. Do not report it as fully migrated from compile success alone.
+11. Do not claim visual parity is preserved while old Built-in `LightingData.asset` and old reflection-probe EXRs remain active without a URP rebake/probe refresh or explicit saved-state visual verification.
+12. Do not claim reflection probes were refreshed from intent alone. Verify successful probe-render output, changed probe assets, or a saved-state visual check. Unchanged old EXR files mean probe refresh is still partial/manual.
+
+## Manual Follow-Up Hot Spots
+
+Even when the converter succeeds, these areas often still need attention:
+
+- custom shaders and package shaders
+- PPv2 and fullscreen image effects
+- replacement-shader camera workflows
+- baked lighting, lightmaps, light probes, reflection probes, and shadow tuning
+- quality-level assignments
+- 2D lit materials and sprite workflows
+- visual parity around tone mapping, exposure, and light falloff
+
+For real project upgrades, explicitly verify:
+
+- material shader assignments on disk
+- particle/VFX material shader assignments
+- Graphics settings and each relevant Quality level
+- URP renderer features that were added
+- persistent URP Volume profile components
+- representative scene camera data and active legacy post-processing components
+- baked-lighting state and whether a URP rebake/probe refresh is still required
+
+## When To Stop And Escalate
+
+Stop and explain the blocker instead of guessing when:
+
+- custom shaders drive important visuals
+- complex shader situations such as surface shaders, `GrabPass`, replacement shaders, or fullscreen camera callbacks are involved
+- package-owned shaders are involved and the safe fix is unclear
+- converter results contain unresolved warnings or failures
+- baked lighting is important to the scene and no URP bake/visual parity check has been performed; for a generic full migration, this means the migration is partial, not complete
+- the project mixes 2D and 3D requirements and the target renderer choice is unclear
+- the user has not confirmed rollback safety for irreversible conversion

package/unity-skills/migrate-birp-to-urp/references/quality-settings-map.md

@@ -0,0 +1,69 @@
+# Quality Settings Map
+
+Use this map to explain where common Built-in quality settings end up after URP migration.
+
+## Official References
+
+- [Convert Built-in quality settings to URP](https://docs.unity3d.com/Manual/urp/birp-onboarding/quality-presets.html)
+- [Find Built-in quality settings in URP](https://docs.unity3d.com/Manual/urp/birp-onboarding/quality-settings-location.html)
+- [Universal Render Pipeline asset](https://docs.unity3d.com/Manual/urp/urp-asset-and-renderer.html)
+- [Change how lights fade to match the Built-In Render Pipeline](https://docs.unity3d.com/Manual/urp/birp-onboarding/birp-light-falloff-in-urp.html)
+
+## Common Mappings
+
+| Built-in concept | URP location |
+| --- | --- |
+| Render Pipeline Asset | `Project Settings > Quality > Rendering > Render Pipeline Asset` |
+| Default pipeline assignment | `Project Settings > Graphics > Render Pipeline Asset` |
+| MSAA | `URP Asset > Quality > Anti-aliasing (MSAA)` |
+| Camera anti-aliasing | `Camera > Rendering > Anti-aliasing` |
+| Main light shadows | `URP Asset > Lighting > Main Light > Cast Shadows` |
+| Additional light shadows | `URP Asset > Lighting > Additional Lights > Cast Shadows` |
+| Main light shadow resolution | `URP Asset > Lighting > Main Light > Shadow Resolution` |
+| Additional light shadow atlas and tiers | `URP Asset > Lighting > Additional Lights > Shadow Atlas Resolution` and `Shadow Resolution Tiers` |
+| Shadow distance | `URP Asset > Shadows > Max Distance` |
+| Shadow cascades | `URP Asset > Shadows > Cascade Count` and split controls |
+| HDR | `URP Asset > Quality > HDR` |
+| Depth texture | `URP Asset > Rendering > Depth Texture` |
+| Opaque texture | `URP Asset > Rendering > Opaque Texture` |
+| Real-time reflection probes | `Project Settings > Quality > Rendering > Real-time Reflection Probes` |
+| Resolution scaling | `Project Settings > Quality > Rendering > Resolution Scaling Fixed DPI Factor` and `URP Asset > Quality > Render Scale` |
+| LOD cross fade | `URP Asset > Quality > LOD Cross Fade` |
+| Baked GI / lightmaps | Scene Lighting Settings, `LightmapSettings`, Lighting Data asset; verify visually and rebake under URP when parity matters |
+| Reflection probe bake data | Scene reflection probes; refresh/rebake after URP lighting and post-processing settings are finalized |
+
+## Guidance
+
+- Many settings that used to live only in Built-in quality settings are split between Project Settings and the URP asset.
+- Treat the official URP values as a starting point, not a promise of identical performance or visuals.
+- After migration, verify the user's important quality levels explicitly instead of assuming Low and High presets still behave the same way.
+- A Quality level with no custom render pipeline asset may fall back to Graphics settings. That can be acceptable, but state this explicitly instead of claiming that Quality was fully assigned.
+- For full-project migrations, prefer assigning the intended URP asset to all relevant runtime Quality levels unless the project deliberately relies on Graphics settings fallback.
+- When validating on disk, look for each Quality level's saved `customRenderPipeline` entry. `{fileID: 0}` means that level has no explicit pipeline asset, even if Graphics Settings has a URP asset.
+- If using scripts or serialized project settings to assign Quality assets, verify by re-querying after saving. Do not trust a guessed serialized field name or a command log that says assignment happened.
+- In Unity versions without a direct per-index setter, use the converter-style assignment pattern: store `QualitySettings.GetQualityLevel()`, call `QualitySettings.SetQualityLevel(index)`, set `QualitySettings.renderPipeline = urpAsset`, repeat for each target level, restore the original level, then verify saved `customRenderPipeline` references. Do not invent APIs such as `QualitySettings.SetRenderPipelineAssetAt`.
+- Light falloff and overall scene brightness can differ between Built-in and URP. Treat that as a tuning step, not automatically a failed migration.
+- Baked GI, lightmaps, light probes, and reflection probes are visual-parity risks. Preserve existing baked data as reference, but recommend a URP rebake/refresh when the scene depends on baked lighting.
+- If a migrated scene is extremely bright or washed out, check for double post-processing first: retained PPv2 components/layers plus an active URP Volume can stack exposure, bloom, tonemapping, or color grading during validation.
+- If a migrated scene is too dark, too flat, or still high contrast after material and PPv2 migration, treat exposure balance as part of visual validation. Verify URP post-processing wiring first, then tune Volume exposure/tonemapping/lift-gamma-gain, ambient fill, additional-light limits, and shadow settings with representative captures.
+- If clearing baked data makes the scene stop being washed out, classify the old Built-in lightmaps or Lighting Data as stale active data. Preserve them as reference, but clear active baked data and rebake under URP before final tuning.
+- If a new Lighting Settings asset is created for URP baked GI, verify the saved scene references it after saving/reloading. A `.lighting` asset with baked GI enabled is not active if the scene still points to the old Enlighten/realtime-GI settings asset.
+- Do not claim baked lighting parity from compile success, material conversion, or URP asset assignment alone.
+
+## Validation Checklist
+
+After migration or troubleshooting:
+
+1. Confirm the correct URP asset is assigned in Graphics settings.
+2. Confirm each relevant Quality level points to the expected URP asset.
+   - If it does not, report whether this is intentional fallback behavior or an incomplete migration item.
+3. Compare shadow distance, cascades, and shadow resolution against the user's expected look.
+4. If fullscreen effects depend on them, verify whether depth texture and opaque texture are enabled.
+5. If the user reports blurrier or sharper visuals, review MSAA, render scale, and camera anti-aliasing.
+6. If lighting looks "off," review light falloff, post-processing, active PPv2/URP volumes, and ambient/environment settings before rewriting content.
+7. For baked-lighting scenes, inspect Lighting Settings, `LightmapSettings`, baked/mixed lights, light probes, reflection probes, and Lighting Data assets.
+8. If old lightmaps are causing severe overexposure, clear active baked data before final URP validation.
+9. If visual parity matters, rebake lighting under URP and refresh reflection probes after URP renderer, Quality, and Volume settings are finalized.
+10. After assigning new Lighting Settings, save the scene and verify the scene reference, not only the settings asset contents.
+11. If the final capture is too dark or too bright, verify renderer `PostProcessData`, camera `renderPostProcessing`, camera volume layer mask, active Volume weight/priority/layer, and saved VolumeProfile overrides before changing lighting.
+12. When exposure balance is required, prefer bounded changes to `ColorAdjustments.postExposure`, contrast, saturation, `Tonemapping`, `LiftGammaGain`, Bloom, ambient sky color/intensity, additional-light count, and shadow settings. If extreme values are only compensating for missing GI or an unfinished bake, report lighting parity as partial.

package/unity-skills/new-unity-project/SECURITY.md

@@ -0,0 +1,26 @@
+# Security notes: new-unity-project
+
+This skill has the agent install Unity Editors and packages, create a cloud-linked project, run C#
+inside the user's Editor (the visual baseline), write one small bootstrap script into the project,
+and append one line to the project's CLAUDE.md or AGENTS.md. Automated skill scanners flag several
+of these as powerful capabilities. They are intentional, and limited by the safeguards below.
+
+## Accepted risks
+
+| Risk | Capability | Why it is accepted |
+|---|---|---|
+| `SEC_POWER_CAP` | Runs C# in the user's Editor | It only reaches the Editor the user already has open, on their own machine, as that user; the commands sit behind the Pipeline capability gate. No code fetched from a remote source is run — the agent runs C# it writes from this skill's and its delegated skills' own recipes. |
+| `SEC_FILE_WRITE` | Writes one bootstrap script (Step 6) and appends one line to CLAUDE.md/AGENTS.md (Step 9) | Both writes land inside the project the skill just created and both are surfaced before they run: in paved mode as notice with an opt-out on the assumptions manifest ("say the word to change any of these"), in guided mode as per-step asks that are true consent. Both are reversible on a word, and the scope section caps the skill at exactly one bootstrap script. |
+| `SEC_INSTALL` | Installs Editors, modules, packages, and (with the user's yes) agent skills | Installs go through the Unity CLI's own commands and the PackageManager API — never `curl \| sh`, never hand-edited manifests. Skill installs always ask first (Before Step 1). Versions and the package list are declared before installing. |
+| `SEC_CLOUD` | Creates a cloud-linked Unity project with diagnostics per the CLI's defaults | The link is `projects create`'s own default behavior, narrated to the user from the create result. Sign-in is a human gate: it runs only after the user's yes, and the user completes it in the browser. `--bare` and the link opt-outs are honored on the user's word. |
+
+## Mitigations
+
+- **The manifest is the notice-and-opt-out surface** in paved mode: every assumption — the file
+  writes and the cloud-link narration included — prints in one block before the create launches,
+  and any line reverses on a word. Consent in the strict sense comes from guided mode's per-step
+  asks; paved mode's bar is that nothing runs unannounced and nothing is irreversible.
+- **Human gates are never consumed.** Sign-in, license activation (including accepting the Unity Personal EULA) and publishing each run only after the user says yes to a question the agent asks and waits on.
+- **Only the user's own Editor and account.** Everything runs on this machine as this user.
+- **No remote code.** All executed C# comes from this skill's text and its delegated skills.
+- **Named commands first.** Where a dedicated `unity` command covers a step, the skill uses it.