Layer Manager

Export

Set up the UCC layers before building characters so movement, targeting, first-person rendering, child colliders, effects, and moving platforms use the intended collision rules.

Before you begin

The released Version 3 package reserves Unity user-layer indices 26 through 31. Check Edit > Project Settings > Tags and Layers before applying the defaults, especially in a project that already has gameplay layers.

Commit or back up ProjectSettings/TagManager.asset and the affected prefabs or scenes first. A Unity layer is stored as an index, so renaming or moving a layer can change the meaning of every GameObject and LayerMask that uses it.

Required layers

Index	Exact layer name	Main UCC use
26	`Enemy`	Default target layer for Enemy Layers, Crosshairs Monitor, and Assist Aim.
27	`MovingPlatform`	Marks moving platforms so locomotion and trajectory objects can preserve platform-relative movement.
28	`VisualEffect`	Keeps projectiles, dropped reload clips, explosions, decals, and other temporary effects out of character and item collision queries.
29	`Overlay`	Holds first-person arms, items, muzzle flashes, and other objects rendered by the first-person overlay path.
30	`SubCharacter`	Holds most character children and secondary colliders so they do not interfere with the main locomotion collider.
31	`Character`	Holds the character root and primary character colliders used by triggers, moving platforms, and character queries.

These names have no spaces. UCC runtime code uses the fixed indices, while the names make the assignments readable in the Unity Editor.

Apply the defaults in a new project

Open Edit > Project Settings > Tags and Layers and confirm that user layers 26 through 31 are empty or already contain the exact UCC names above.
Open Tools > Opsive > Ultimate Character Controller > Setup Manager and select Project.
Under Layers, select Update Layers. A new project can instead use Update Buttons and Layers for the Built-in Render Pipeline or Update Buttons, Layers, and Render Pipeline for URP or HDRP.
Return to Tags and Layers and verify all six indices. The update action fills only empty entries; it does not replace a different name already stored in a slot.
In Setup Manager > Scene, select Add Managers under Manager Setup. The Game GameObject should now contain Layer Manager.
Create or update the character with the Character Manager. It assigns the character root and primary colliders to Character, and most other children to SubCharacter while preserving first-person and item-placement objects that need special handling.

Run this project setup before creating characters, items, moving platforms, or trajectory objects. Their builders serialize layer indices and masks when they create those objects.

Recover occupied layer slots

Do not select Update Layers expecting it to replace an existing layer. If any slot from 26 through 31 belongs to another system, choose one of these recovery paths before building UCC content:

Migrate the existing project layers

This is usually the safer long-term option because UCC can keep its released defaults.

Identify every GameObject, prefab, scene, LayerMask, physics query, camera culling mask, and project collision setting that uses the occupied index.
Create a replacement user layer in a free index.
Reassign the affected objects and masks to that replacement.
Rename indices 26 through 31 to the exact UCC names.
Reopen representative prefabs and scenes to confirm that no serialized mask still points at the old index.

Version-control the migration as one reviewable change. Renaming a layer does not move the objects that used its index.

Maintain custom UCC indices

If the existing indices cannot move, embed or otherwise maintain a controlled copy of the Version 3 package and change the custom constants in Game/LayerManager.cs. Create matching layer names at the new indices, then rebuild or audit every existing character, item, effect, moving platform, prefab, and serialized LayerMask.

This is an advanced maintenance choice: package updates can restore the released constants, and existing serialized values do not automatically follow a source-code change. Changing only Character Layer Manager > Character Layer at runtime is not a complete layer-index migration because other UCC systems also read the static LayerManager indices.

Configure each character’s masks

The Character Manager adds Character Layer Manager to each character. Its three editable masks answer different questions:

Enemy Layers identifies valid enemies for systems such as Crosshairs Monitor and Assist Aim. Its default is Enemy only. Add another project layer here when that layer should also count as a target.
Invisible Layers identifies layers that character, camera, aiming, and crosshairs raycasts should look through. The default contains TransparentFX, Ignore Raycast, UI, VisualEffect, Overlay, and SubCharacter.
Solid Object Layers identifies surfaces that block or support locomotion and related abilities. The default includes every layer except Ignore Raycast, Water, UI, VisualEffect, Overlay, and SubCharacter.

"Invisible" here means ignored by the relevant physics queries; it does not change Renderer visibility. The invisible and solid masks are independent. For example, a transparent object can be ignored by a camera query while still remaining solid for locomotion if the masks deliberately say so.

At runtime, Character Layer Manager > Character Layer is derived from the actual layer of the character GameObject during Awake. Keep the character root and its primary collider hierarchy consistent instead of using that runtime value to compensate for incorrect project-layer setup.

Runtime collision rules

The scene Layer Manager applies these global Physics.IgnoreLayerCollision pairs in Awake:

Layer	Does not collide with
`VisualEffect`	`Ignore Raycast`, `VisualEffect`
`SubCharacter`	`Default`, `VisualEffect`
`Overlay`	`Default`, `VisualEffect`, `Enemy`, `SubCharacter`, `Character`

These are runtime rules; Update Layers does not rewrite the collision matrix displayed in Project Settings. Setup Manager > Scene > Add Managers places Layer Manager on the Game GameObject. If it is missing, Character Layer Manager calls LayerManager.Initialize() and creates a fallback LayerManager GameObject, but keeping the manager on Game makes scene setup explicit and easier to verify.

Practical scenarios

Enemies use an existing project layer: Keep that layer and add it to each relevant character’s Enemy Layers mask. Use the reserved Enemy layer only where the fixed UCC default is useful.
An invisible stair ramp should guide locomotion: Put it on a layer included in Invisible Layers but also included in Solid Object Layers. Camera and aim queries can look through it while the character still walks on it.
Water should be visible but not ground: The default solid mask excludes Unity’s Water layer. Add or remove it only when the game’s water geometry should physically support the character.
A platform should carry the character: Add Moving Platform to the platform object. The Moving Platform component warns and corrects the layer at runtime, but the prefab should be correct before Play Mode.
Ragdoll or model colliders push the main capsule: Keep secondary character objects on SubCharacter; keep the root and primary locomotion colliders on Character.
First-person arms or weapons interact with world physics: Verify they use Overlay and that the first-person View Type and camera culling masks still use the released overlay index.

Verify in Play Mode

Confirm that Game has an enabled Layer Manager component and that no unexpected fallback LayerManager GameObject appears.
Select the character. Its root and primary collider objects should use Character; ordinary model children and secondary colliders should use SubCharacter unless a first-person or item component requires another layer.
Walk over Default-layer ground, slopes, steps, and any custom ground layer. The character should stay grounded and should not pass through a layer included in Solid Object Layers.
Step onto a MovingPlatform object. The character and a resting trajectory object should preserve platform-relative motion without a layer warning in the Console.
Aim at an object included in Enemy Layers. Crosshairs or Assist Aim should recognize it; an object outside that mask should not be treated as an enemy.
Spawn a projectile, reload clip, muzzle flash, or other effect. VisualEffect and Overlay objects should not block or push the character.
Switch between first- and third-person views when both are available. First-person overlay objects should render through the intended camera path without appearing as world collision.
Test respawn and ragdoll. The primary and secondary collider layers should return to their intended states.

Troubleshooting

Symptom	Check	Fix
Update Layers finishes but a required name is missing.	The target index already contains another layer name.	Resolve the occupied index, then rename it or rerun Update Layers after it is empty. Verify all six indices manually.
The character falls through ground or cannot move through open space.	Solid Object Layers may omit the ground layer or include a non-solid helper/effect layer.	Add real ground layers and remove layers that should not block locomotion.
Crosshairs or Assist Aim does not recognize a target.	The target’s layer may be absent from Enemy Layers.	Add the target layer to the character’s Enemy Layers mask or move the target to an included layer.
A moving platform does not carry the character.	The platform may not use layer 27 `MovingPlatform`, or that layer may have another name.	Restore the required layer and assign it to the platform prefab.
Child or inactive ragdoll colliders interfere with locomotion.	Those objects may use `Default` or `Character` instead of `SubCharacter`, or a custom character query mask may include `SubCharacter`.	Correct the child layers and exclude `SubCharacter` from the relevant collider and solid-object masks.
First-person arms or items disappear, render in the world camera, or collide with the character.	Their layer or the View Type culling masks may not use `Overlay`.	Restore layer 29 `Overlay`, update the affected objects, and verify the first-person camera setup.
Effects stop projectiles or block movement.	The effect object may not use `VisualEffect`, or a custom mask may include it.	Assign `VisualEffect` and exclude it from the relevant impact or solid masks.
A custom layer-index fork breaks after updating UCC.	`LayerManager.cs` constants or serialized masks may have returned to released values.	Reapply the maintained package change and audit existing serialized layers before opening or saving production scenes.

Developer reference

Opsive.UltimateCharacterController.Game.LayerManager exposes the built-in and custom indices through static properties such as Default, IgnoreRaycast, Water, UI, Enemy, MovingPlatform, VisualEffect, Overlay, SubCharacter, and Character.

Use LayerManager.IgnoreCollision(mainCollider, otherCollider) when a temporary collision exclusion should be tracked by UCC. Later, LayerManager.RevertCollision(mainCollider) restores every active collider pair recorded for that main collider. This bookkeeping is separate from the global layer-pair rules installed in Awake.

CharacterLayerManager exposes EnemyLayers, InvisibleLayers, SolidObjectLayers, and CharacterLayer. Its derived IgnoreInvisibleLayers, IgnoreInvisibleCharacterLayers, and IgnoreInvisibleCharacterWaterLayers masks are used throughout movement, camera, aiming, footstep, item, and ability queries.

using Opsive.UltimateCharacterController.Character;
using UnityEngine;

public class AddEnemyLayer : MonoBehaviour
{
    [SerializeField] private CharacterLayerManager m_CharacterLayerManager;
    [SerializeField] private string m_AdditionalEnemyLayer = "Boss";

    private void Awake()
    {
        var layer = LayerMask.NameToLayer(m_AdditionalEnemyLayer);
        if (layer >= 0) {
            m_CharacterLayerManager.EnemyLayers =
                m_CharacterLayerManager.EnemyLayers.value | (1 << layer);
        }
    }
}