The Layer System allows the game to determine which entities to create at map load time.   This is used to create different experiences in the same map dependent on player data.

System Basics

Every entity in a map file has a list of layers it is associated with.   If that list is empty, then the entity is considered to be in the "Base Layer".

At map load time, a list of layers is passed into the map load system.

An entity is created and loaded if either of the two following conditions are met:

1. The entity has no layers in its list, i.e. it is in the "Base Layer".
2. The entity has one or more layers in its list that are also in the list passed into the map load system.

Working with Layers in the Editor

Layer Window:

The layer window lists all the layers in the map. When the folders are opened, they list all the entities in that layer.  Note: It is possible for an entity to be in multiple layers.

By default, any new entity added to a map will be added with no layers, i.e. in the Base Layer group.  If you add layers to the Default Layers, any new entities will instead be added to those layers.

Layers are decls, so to add a new layer to a map, you must first create a new layer decl.

Layer Popup in World Editor View:

 

To bring up the layer popup in the editor view, you right click in the editor view window and select the Layers option.

 

Determining Which Layers are Loaded at Map Load

When a map is loaded, it determines which layers to load by looking at the value of the si_nextlayer CVar.
Once it grabs the data, it then clears that CVar back to the empty string "".

• If the map is loaded from the devmenu, that system will set the CVar based upon the value of the devMenuLayers setting on the devMenuOption decl
  
• If the map is loaded from the command line,  i.e. "devmap" or "map", the CVar will be empty unless already set from the command line.
• If the map is loaded from a previous map via the "target/leveltransition" target, then the CVar will be set based upon the layer list stored on the player.

• If the CVar is already the empty string, and the map was launched from either the dev menu or by the "devmap" command, the layers will be set to the value of the initialLayers setting on the worldspawn.
• If the CVar is empty and the map was launched from the "map" command, only the entities in the Base Layer group will be created. 

Changing the Players Layer State During a Playthrough

The player stores the list of layers to load on the next map load instigated via a "target/leveltransition".

Usually, this data is determined by the player's job state.

• When a job is accepted, the jobLayerInfo->acceptLayers are added to the players list, and the jobLayerInfo->acceptLayersRemove are removed.
• When a job is set readyToTurnIn, the jobLayerInfo->readyLayers are added to the players list, and the jobLayerInfo->readytLayersRemove are removed.
• When a job is turned in, the jobLayerInfo->completeLayers are added to the players list, and the jobLayerInfo->completetLayersRemove are removed.

There is also a target that can be triggered to add and remove layers from the players state.
This is the "target/layerchange" target.