The Parts and Whole: DR Layers
By Geep 2022
Introduction
In a hurry? See Using Layers, in the DR User Manual.
In what follows, LMB and RMB are abbreviations for left and right mouse buttons.
A "Layer" is any arbitrary collection of map objects; you define it by giving it a name (in the Layers viewer) and assigning each object to it (from the RMB menu). Once established, a Layer’s objects can be quickly made visible or not, or selected/deselected. An object can be assigned to multiple Layers. Unassigned objects are considered to be in the "Default" Layer. Any Layer can be set as the current "Active Layer", to which newly-created objects are automatically assigned.
Unlike Filters, the use of Layers requires active organizing by you, but provides powerful itemized control. Layers, once created, can persist throughout your project, available to use over and over again. Layers only affect DR, not your FM. Their data is stored in the map/<FM>.darkradiant file.
Typical Uses
A Layer can be defined based upon any arbitrary criteria (e.g., location, machine parts, difficulty level, and so on). Thus, a Layer is not necessarily a "layer" in a spatial sense, although it can be used in that way; for example, to create a separate Layer for each floor of a mansion.
One good use of a Layer is to hide geometric objects that are particularly "busy", with a lot of wireframe lines that can obscure other objects in orthogonal views. Some examples:
- Fences and gates with brush bars
- Stairs
- Ground patches
Another use is with complicated ensembles, like a machine with many static and moving parts. This is as an alternative - or even supplement - to putting the parts in an anonymous DR Group.
Layer objects can be anything you can select in your map, including path corners, triggers, AI, visportals and so on. But consider: the visibility of some of these may be adequately managed by Filters alone.
While an object can be assigned to multiple Layers, you can make it your policy to just assign each object to a single layer, if you wish.
Seeing Layers – the Layers Viewer
You can bring up the "Layers" viewer by either:
- the top menu’s View/Layers
- keyboard shortcut Ctrl+L
Once open, you’ll see the list of defined layers (only “Default” for a new project), where each row has the following items left to right:
- A button (with tooltip "Toggle layer visibility") that show one of 4 states:
- Blue with checkmark icon = this Layer is currently visible
- Blue with star icon = this Layer is currently visible, and "active", i.e., newly created (but not cloned) objects will be automatically assigned to it.
- Gray with no icon = this Layer is currently hidden
- Gray with star icon = this Layer is currently hidden, but will become the active Layer when "Show all" occurs.
- A slim color swatch. This is red for all Layers that the current selection(s) belong to; otherwise gray. Tooltip: "Indicates whether anything among the current selection is part of this layer".
- The name field, read-only. With tooltip: "Click to select all in layer, hold SHIFT to deselect, hold CTRL to set as active layer."
- A button with a pencil icon (tootip: "Rename this layer", to make the name field editable, except for "Default".
- A button with a red X icon (tooltip: "Delete this layer"), except for "Default". This just deletes the layer, not the objects. Objects that were only assigned to that deleted Layer will be reassigned to "Default".
At the bottom are 3 large buttons: "New" (with a plus sign), "Show all", and "Hide all".
Visibility of Objects in a Layer
Hiding an object by either a Filter or View’s Hide/Show will take priority over its visibility due to Layers. An object can be a member of multiple Layers. Assuming it’s not hidden by Filter or Hide/Show, then if any of its Layers are visible, it is too.
Selecting All Objects in a Layer
As just indicated, you can LMB on a Layer’s name field to select all its objects (or Shift+LMB to deselect). Alternatively, you can "Hide all" Layers, show the Layer of interest, then Edit/Invert selection (keyboard shortcut "I").
Thinking about Naming
Before you start creating Layers, think a little about what naming convention you want to use. In the Layer viewer, the Layers will always be shown in alphabetical order, and that may be a consideration. Don’t obsess about this; you can always evolve names later. It is seldom useful to have the word "Layer" as part of a name.
Creating a Layer
There are two ways to do this:
- In the Layers viewer, hit "New"
- In a map orthogonal view, RMB and "Create Layer…". (Any map object selected before doing this makes no difference.)
Either will bring up a dialog box to enter the Layer name. Subsequently, in the Layers viewer, the new row will appear in alphabetical order.
Managing Layer Assignments of Existing Objects
You can perform actions here with or without the Layers viewer open. With one or more map objects selected, in the orthogonal view, use RMB. There are 3 menu items
- "Add to Layer >". Adds the object(s) to a specified layer, without affecting any of its other Layer assignments. So, if an object is already in "Default" and you assign it "Ground Floor", it will then be in both Layers.
- "Move to Layer >". Adds the object(s) to a specified layer, and removes any of its assignments to other Layers (except for the one newly specified). So caution: any objects that previously were in multiple Layers are now not… if this is not what you want, take further action.
- "Remove from Layer >". Removes the object(s) from a specified layer, without affecting any of its other Layer assignments.
For each of these, further mouse navigation will show the current layer names in a sub-menu. Choose one with LMB.
Auto-Assigning New Objects using the Active Layer
When a new map object is created by copying (aka cloning) another object (e.g., with keyboard Space), it automatically gets the source object’s Layer assignment(s).
If instead, a map object is created afresh, it is assigned to the current "active" (i.e., starred) Layer, which is usually "Default", but not always. As discussed next, you can manipulate the star, to speed up assignment of multiple new objects to a particular layer.
Managing the Active (Starred) Layer
In the Layers viewer, usually, the "Default" layer has the star, so that newly created map objects (except when copied) are auto-assigned to that layer. You can move the star to a different layer. Quickest way:
Ctrl+LMB on the name field you want to use for auto-assignment. The left button becomes starred. Another easy way is by hiding all Layers except the one you want active:
- Press “Hide all”. Then all the layer row left buttons will be grayed out. All will be iconless, except "Default" will be starred.
- Hit the leftmost button in the row you want to use for auto-assignment. This Layer becomes visible, and its button will turn blue + starred.
- If you wish, make other rows individually visible, or hit “Show all”. The row starred in (2) remains starred.
Choice of Active Layer is somewhat temporary, in that, if you hide it (either individually or by using "Hide all"), the star always reverts back to "Default". However, the setting will persist across closing and opening the Layers viewer.
Custom DR Scripting of Layers
If you need special functionality, DR offers Python scripting, and in particular for Layers exposes a GlobalLayerManager (including LayerVisitor) API with about 2 dozen function calls. See the DarkRadiant Script Reference.
