Manual
Manual
Layers
Every entity is on one of a project's 32 layers. A camera draws only the layers its Culling Mask has, the physics packages decide which bodies meet by their layers, and rays and overlaps can look for some layers alone. This page covers naming layers, putting entities on them, and using them from code.
Name the layers
Layers are named in Edit ▸ Project Settings ▸ Tags and Layers, under Layers:
- Builtin Layer 0 is Default. It cannot be renamed, and every entity is on it until it is put on another.
- User Layer 1 to User Layer 31 are yours. Type a name in a layer's box; it is kept when you leave the box. A layer with no name is still there, unnamed.
A name has a letter or a digit in it, is no longer than 64 characters, and is not another layer's, whatever the case of its letters. A name the page refuses is explained under its box. Beside each named layer is what your code calls it, such as Layers.Player.
The page keeps the layers in settings/layers.json, which a built game carries:
{
"abyssLayers": 1,
"layers": [
{ "layer": 8, "name": "Player" },
{ "layer": 9, "name": "Player Bullets" }
]
}The same page holds Sorting Layers, which are something else: the order sprites are drawn in. See Sorting layers.
There are no tags
Despite the page's name, Abyss has no tags. To pick out a group of entities, give them a component of your own and narrow a system's query with With(), as Filters shows.
Put an entity on a layer
The Inspector shows the entity's layer in the Layer row under its name (see Layer). The list has each named layer by its number and name, such as 8: Player, and Add Layer... at the bottom, which opens Project Settings at Tags and Layers.
When the entity has entities under it, picking a layer asks whether they go too: Yes, Change Children, No, This Entity Only or Cancel. Either way it is one change, and one Ctrl+Z. With several entities picked on different layers, the row shows a dash.
A scene saves an entity's layer when it is not Default.
Cameras draw some layers
A camera's Culling Mask is a list of the layers to tick, under Nothing and Everything. It shows Everything until you untick one, and the camera then draws only the layers that are ticked. See Camera.
Some things see every layer whatever the masks say: every light lights entities on every layer, and the Scene view draws all of them, so you can still pick and move what a game's camera does not draw.
Layers in code
Layer names are constants
The build writes a Layers class into your game from settings/layers.json: a constant for each named layer, holding its number. A name is written as one word, each part starting with a capital, so Player Bullets is Layers.PlayerBullets; a name that comes out the same as an earlier one gets a number after it. Default is Layers.Default, 0.
So a layer renamed or taken away is a compile error where your code uses it, not a name that quietly stops matching. For a settings/layers.json that is not layers, the build warns (ABYSS029) and writes Layers.Default alone.
Masks
A LayerMask is some of the 32 layers, a bit each:
| Member | What it is |
|---|---|
LayerMask.Of(Layers.Player, Layers.Enemy) | The mask of those layers. |
LayerMask.Everything, LayerMask.Nothing | Every layer, and none. |
mask.Contains(layer) | Whether the mask has the layer. |
mask.With(layer), mask.Without(layer) | The mask with a layer added, or taken out. |
a | b, a & b, ~a | The layers either has, the layers both have, and the layers it has not. |
mask.Bits | The mask as a number: bit 0 is Default, bit 31 the last layer. |
A field of a component or of project settings that is a LayerMask shows in the Inspector as the Culling Mask does, a list of the layers to tick.
Reading and setting layers
world.SetLayer(bullet, Layers.PlayerBullets);int layer = world.LayerOf(bullet); // Layers.Default for an entity on none
world.SetCullingMask(minimap, LayerMask.Of(Layers.Default, Layers.Terrain));bool seen = world.CullingMaskOf(minimap).Contains(world.LayerOf(bullet));
string? name = world.Layers.NameOf(8); // null for a layer with no nameint found = world.Layers.IndexOf("Player"); // -1 for noneSetLayer and SetCullingMask return whether they changed anything. Neither puts what is under an entity on the layer: set each entity you mean. A number that is not one of the 32 throws.
These are calls on the world, made at once, and they change which components the entity carries. Make them from code that runs between frames, such as a flow or a plugin's hook (see A game's start, flows and services), not from a system: the chunks it is reading would go stale.
world.Layers also lists the named layers with Named(), each a number and a name, Default first.
Layers and physics
The physics packages use the same layers:
- Edit ▸ Project Settings ▸ Physics 2D and Physics 3D each have Collisions, a triangle of ticks with a tick for each pair of named layers. Bodies on two layers whose tick is cleared pass through each other. In code it is a
LayerMatrix:Meet(a, b)asks of a pair,Set(a, b, meet)changes one, both ways, andMetBy(layer)gives the mask of layers a layer meets. - Rays, swept shapes and overlaps take a
LayerMaskof the layers to find, every layer when you leave it out, whatever the Collisions matrix says.
See Layers and what collides and What queries find for Physics 2D, and Layers and what collides and What queries find for Physics 3D. A navmesh surface of the Navigation package bakes only the entities on the layers its Layers mask has; see Nav Mesh Surface 3D.
In the Scripting API
- LayerMask: some of the project's layers.
- LayerMatrix: which layers meet which.
- LayerSettings: the project's layers by name, as
world.Layersgives them. - World:
SetLayer,LayerOf,SetCullingMaskandCullingMaskOf.
