= DarkRadiant User Guide
:toc: left
:toclevels: 3
:imagesdir: img
:icons:
:iconsdir: img

== Introduction

DarkRadiant is a level editor for Doom 3 and The Dark Mod, developed by The Dark
Mod team. It may also be used for editing levels for similar *id Software* games
such as Quake 4.

This User Guide describes the features and functionality of DarkRadiant, however
it is not intended as a guide to mapping techniques. Level design is a complex
topic, and is covered by various other learning resources, some of which are
listed below.

http://wiki.thedarkmod.com/index.php?title=Main_Page[The Dark Mod Wiki]:: The
starting point for most Dark Mod documentation and tutorials, including
gameplay, configuration and editing.

https://modwiki.xnet.fi[ModWiki]:: Online wiki covering editing topics for
vanilla Doom 3 and similar engines.

http://forums.thedarkmod.com[The Dark Mod forums]:: Online community for
discussion of the Dark Mod, including various ad-hoc mapping tutorial threads
posted by individual users.

=== Editing workflow

image::DarkRadiantWorkflow.png[align="center"]

The level editing process starts off with basic assets: models, textures,
sounds, entity definitions, skins, animations and so on. Many of these assets
will be packaged with a particular game installation, but a level designer may
also choose to create custom assets for a specific mission. These assets are
installed into a directory tree which is accessible both by DarkRadiant (for
editing) and the game engine itself (for playing the mission).

Once assets have been arranged in DarkRadiant according to the wishes of the
level designer, a `.map` file is saved to disk. This is a text file in a format
understood by the game engine, and includes both level geometry and references
to the assets used in the map. Since the `.map` file is simply text, and does
not actually embed the binary asset data, it tends to be fairly small.

The game engine includes functionality to _compile_ the `.map` file into a
`.proc` file containing low-level vertex geometry derived from the brushes and
patches within the `.map` file. The game engine can then render the mission in
realtime, making use of the same assets that were accessed by DarkRadiant during
editing.

DarkRadiant also maintains its own separate file containing various editing
information, such as object layers used within a map. This `.darkradiant` file
is never used by the game engine, and is non-critical -- a `.map` file with no
accompanying `.darkradiant` file can still be edited with DarkRadiant, although
certain DarkRadiant-specific state may be lost.

=== What's in a MAP?

There are three main types of object contained within a `.map` file: entities,
brushes and patches.

*Entities* are the top-level objects in a map -- essentially, a map file is just a
 list of entities. Every entity has an *entity class* which determines the type
 of entity it is: static mesh, AI, sound emitter, particle emitter, light etc.
 Entities also store a list of string key/value pairs, known as *spawnargs* or
 *properties*. Some entities also contain brushes and patches as children.

*Brushes* are convex solids used to define basic map geometry: walls, floors,
 ceilings, steps and other medium to large items. Brushes are often rectangular
 in shape, although a brush can actually have any number of faces provided that
 it is convex (it is impossible to have a brush in an L or a U shape, for
 example). Brushes are not smooth-shaded by the game engine, which generally
 makes them unsuitable for representing curved surfaces.

*Patches* are smooth one-sided surfaces used to represent curved objects such as
 vaulted ceilings, pillars or cave interiors. A patch is defined by a number of
 Bezier control points, and offers control over the level of detail used when
 subdividing the patch into triangles for rendering: more triangles will produce
 a smoother surface but may lower rendering performance.

Brushes and patches together are also referred to as *primitives* (since they
define the basic geometry of the map), and are typically described as such in
situations where the distinction between brush and patch is not important.

The entities, brushes and patches in a map are arranged in a hierarchy: not
every entity has children, but every primitive must have an entity as a parent.
Each map therefore starts with a single default entity called the *worldspawn*,
which acts as the parent for new brushes and patches created in DarkRadiant.

== Initial configuration

[[GameSetup]]
=== Choosing a game type

When running DarkRadiant for the first time, the *Game Setup* dialog will be
shown. This is where you configure the path to the game installation from which
DarkRadiant will load assets, such as textures, models and entity definitions.

image::GameSetupDialog.png[align="center"]

The *Game Setup* dialog contains the following options:

*Game Type*:: DarkRadiant ships with support for several different game engines,
 each of which is contained within a `.game` file. For editing Dark Mod
 missions, the default choice of `The Dark Mod 2.0 (Standalone)` is the one to
 use, but it is also possible to edit stock Doom 3 or Quake 4 missions.

*DarkMod Path* / *Engine Path*:: This is the path to the game installation on
 the system. The label text will change depending on whether the selected game
 is `The Dark Mod` or another engine.

*Mission*:: Optional path to a subdirectory containing assets specific to a
 particular mission which is being worked on. For game types other than `The
 Dark Mod`, this will be displayed as *Mod (fs_game)*, and should be set to the
 path of a subdirectory containing a particular game mod, if one is being used.

*Mod Base (fs_game_base)*:: This field only appears for non-DarkMod game types.
 It allows a two-level mod structure, where the *Mod Base* can point to a major
 game mod, possibly downloaded from elsewhere, while *Mod* can be set to point
 to an entirely local "sub-mod" which contains local changes and overrides.
 Before the release of Dark Mod standalone, this field would have been set to
 `darkmod` while the *Mod* field would have been set to the local mission,
 however this is no longer necessary when `The Dark Mod 2.0 (Standalone)` is
 being used.

Once the game paths are set up, click the *Save* button to proceed to the main
DarkRadiant interface.

NOTE: It is possible to *Cancel* the *Game Setup* dialog and proceed to the main
window without configuring a game installation, in which case DarkRadiant will
show a warning and ask if you wish to proceed. If you do, DarkRadiant will run
but there will be no available textures, models, entities or other game assets.

=== Interface layout

DarkRadiant uses a flexible layout system based on dockable windows which can be moved into
various positions around the edges of the main window, or floated as separate top-level
windows. The arrangement and sizes of these windows are saved into settings and persisted
between sessions.

Each window has a small title bar at the top showing the window's name. Dragging this title
bar will allow the docked window to be floated or docked into a different position depending
on the drag destination. When the window is dragged near a possible dock position, a shaded
rectangle will appear indicating where the window will be docked.

There is a central 2D view which cannot be undocked or replaced, although it can be made
arbitrarily small by expanding docked widgets towards the center. Likewise, the camera view
and properties panels cannot be removed, although they can be resized and moved into
different dock positions.

You can create _additional_ 2D and camera views using the *View -> New XY view* and *View ->
New Camera view* menu items. These additional views can be floated or docked like the main
windows, and can also be removed by clicking the *X* button at the top right of the title
bar. All 2D views store their orientation (XY/YZ/XZ) into settings, which makes it possible
to set up a traditional 3D modelling interface with three orthographic views and a camera
view, if desired.

[[ColourSchemes]]
=== Colour schemes

DarkRadiant defaults to a black-on-white colour scheme in the 2D windows, but ships with
four other colour schemes, which can be chosen with the *View -> Colours...* dialog. If you
prefer a dark theme, the `Black & Green` scheme might be suitable, whereas the
`Maya/Max/Lightwave Emulation` and `Super Mal` themes provide a more neutral, low-contrast
look.

Colour schemes only affect what is rendered in the 2D and 3D views by DarkRadiant itself.
The appearance of the user interface is determined by the *wxWidgets* toolkit based on the
system-wide widget theme, and can only be changed via system settings or other applications
(such as `gnome-tweaks` on Linux).

[align="center",cols="^.<a,^.<a,^.<a",grid="none"]
|===
|image:DarkRadiantDefaultTheme.png[] +
*DarkRadiant Default*
|image:BlackGreenTheme.png[] +
*Black and Green*
|image:Q3RadiantTheme.png[] +
*QE3Radiant Original*
|image:SuperMalTheme.png[] +
*Super Mal*
|image:MayaEmulationTheme.png[] +
*Maya/Max/Lightwave Emulation*
|
|===

Each of the colour schemes can be edited using the colour selector buttons in
the *Colours* dialog, and it is also possible to copy one of the default schemes
into a custom scheme with a new name.

NOTE: The game installation may specify the colour of certain entity types, in
which case it will not be possible to change the colour of these entities via
the *Colours* dialog.

== Basic editing

=== Navigating the 2D view

The game world is a three-dimensional vector space with a central origin,
rendered in the 2D editing window as a grid. The unit of measurement is an
arbitrary game unit which does not directly correspond to any real-world
measurement system -- in The Dark Mod, a typical human stands around 80 - 90
game units high, making a game unit about 2 cm.

Each 2D window shows which axes it is representing with an icon in the top-left
corner, as well as an identical icon at the `<0,0,0>` origin position, if
visible within the view.

.Components of the 2D view
image::2DViewMarkedUp.png[align="center"]

The 2D view also shows the current position of the camera (used for rendering
the separate 3D camera view window), and its view direction.

The following commands are available within the 2D view:

[cols="1h,3"]
|===
|Right drag|Scroll the view horizontally or vertically
|Mouse wheel|Zoom the view
|Shift + Right drag|Zoom the view (alternative binding)
|Ctrl + Middle click|Move the camera directly to the clicked position
|Middle click|Rotate the camera to look directly at the clicked point
|Ctrl + TAB|Change view axis (XY, XZ, YZ)
|Ctrl + Shift + TAB|Center 2D view on current camera position
|===

=== Adjusting the grid

The grid shown in the 2D view is used to snap the position and size of brushes
and patches, as well as the centerpoints of entities. The size of the grid can
be configured, in powers of 2, from 0.125 up to 256, using the *1-9* keys on the
main keyboard (not the numeric keypad), or the equivalent options in the *Grid*
menu.

The *0* key on the main keyboard can be used to toggle the display of the grid.
Note that objects will still be snapped to the grid even if the grid is not
visible; this is purely a visual toggle.

IMPORTANT: Level geometry built from brushes and patches should _always_ be
snapped to the grid to avoid problems such as rendering glitches and map leaks.
Static meshes and animated AI can be positioned more freely, however grid
snapping is a useful tool for ensuring that models are appropriately aligned
with the level geometry.

==== Customising the grid appearance

The appearance of the grid can be customised using the options in the *Grid* tab of the *Edit
-> Preferences* dialog. Separate styles can be chosen for major and minor grid lines.

[align="center",cols="^.<a,^.<a,^.<a",grid="none"]
|===
|image:GridStyleLines.png[] +
*Lines*
|image:GridStyleDottedLines.png[] +
*Dotted Lines*
|image:GridStyleMoreDottedLines.png[] +
*More Dotted Lines*
|image:GridStyleSquares.png[] +
*Squares*
|image:GridStyleDots.png[] +
*Dots*
|image:GridStyleBigDots.png[] +
*Big Dots*
|===

=== Adding a background image

The 2D view is capable of showing a background image, which may be useful to show image
references, or sketched 2D maps to guide the placement of level geometry.

To show a background image, choose *View -> Background image...* which will show the
background image configuration dialog.

*Use background image*:: Master toggle to show or hide the background image.

*Image file*:: Click on the widget to show a file chooser which allows you to find and
*select the background image to show.

*Opacity*:: Drag the slider to control the opacity of the image, from fully transparent
*(invisible) to fully opaque.

*Scale*:: Adjusts the size of the image.

*Horiz. offset*:: Adjusts the position of the image from left to right.

*Vert. offset*:: Adjusts the position of the image from top to bottom.

*Keep aspect*:: If checked, the image will always be displayed at its native aspect ratio.
If unchecked, the image will have the same aspect ratio as the containing 2D view.

*Zoom with viewport*:: If checked, the image will change size as the 2D view is zoomed in or
out. If unchecked, the image will always have the same size regardless of the 2D window
zoom.

*Pan with viewport*:: If checked, the image will be anchored in 2D space, and will stay in
the same position relative to the world as the 2D view is panned. If unchecked, the image
will always have the same position relative to the window, and the world geometry will pan
around it.

[[Using3DCameraView]]
=== Using the 3D camera view

The 3D camera view provides an approximate rendering of the map in three
dimensions, in several different render modes: wireframe, flat shaded, textured,
and fully lit by in-game light sources. While the 2D view is the main interface
for creating and aligning level geometry, the 3D view is a vital tool for tasks
such as texturing, or configuring light parameters.

IMPORTANT: The fully lit rendering mode in DarkRadiant is not identical to what
the game engine will ultimately render. Certain advanced rendering features such
as reflections and fog lights are not currently supported.

The 3D camera view provides its own toolbar which can be used to configure
various display settings.

[cols="^1h,3h,10"]
|===
3+^h|Render modes
|image:wireframeMode16.png[align="center",width=24]|Render in wireframe mode|
Render objects as wire meshes.
|image:solidMode16.png[align="center",width=24]|Render in flat-shaded mode|
Render objects as coloured solids, without textures or lighting.
|image:textureMode16.png[align="center",width=24]|Render in fullbright textured mode|
Render objects as preview textures, with no lighting or material effects such as
transparency.
|image:lightingMode.png[align="center",width=24]|Render in lighting preview mode|
Render all available lighting and texture effects.
|image:lightingModeWithShadows.png[align="center",width=24]|Toggle shadow rendering|
Enable the rendering of shadows when in lighting preview mode.
3+^h|Animation rendering
|image:StartPlayback.png[align="center",width=24]|Start render time|
Begin rendering animated effects.
|image:StopPlayback.png[align="center",width=24]|Stop render time|
Stop rendering animated effects.
3+^h|Far clip options
|image:toggleFarClip.png[align="center",width=24]|Toggle far clip|
Enable or disable the far clip plane.

The far clip plane is a performance optimisation which avoids rendering geometry
more than a certain distance away from the camera.
|image:farClipIn.png[align="center",width=24]|Clip plane in|
Move the far clip plane closer to the camera.
|image:farClipOut.png[align="center",width=24]|Clip plane out|
Move the far clip plane further away from the camera.
|===

The 3D view always renders the scene from a particular camera position, which is
shown in the 2D view as a blue diamond. This camera position can be set directly
from the 2D view with *Ctrl + Middle click*, and the camera view direction can
be set with *Middle click*. There are also various options within the 3D view
itself to adjust the camera position.

[cols="1h,3"]
|===
|Right click|Enter or leave free camera mode. In this mode, moving the mouse
around updates the camera view direction in real-time, and moving the mouse
around while holding *Ctrl* causes the camera to move up/down/left/right
according to the camera motion.
2+^h|Default mode (not free camera)
|Left/Right arrow|Pan the camera left or right
|Up/Down arrow|Move the camera forwards or backwards on the horizontal plane,
without changing its height on the Z axis.
2+^h|Free camera mode
|Left/Right arrow|Move ("truck") camera left or right, leaving view direction
the same.
|Up/Down arrow|Move ("dolly") the camera forwards or backwards along its view
axis

|===

=== Manipulating objects

Every object in a map can be selected and moved within the 2D view. Some objects
-- including brushes, patches and lights -- can also be resized.

For more advanced ways to select objects, see
<<BrushBasedSelection,brush-based selection>>.

[cols="1h,3"]
|===
|Shift + Left click|Select or deselect the object at the clicked position. Any
  existing selected objects will remain selected. If the clicked position
  overlaps more than one object, the closest one (according to the current 2D
  view axis) will be affected.
|Alt + Shift + Left click|Select the object at the clicked position, and
  deselect any existing selected objects. If the clicked position overlaps more
  than one object, each click will cycle through the overlapping objects.
|Shift + Left drag|Draw a selection rectangle, which will select any objects
 contained (fully or partially) within it.
|ESC|Deselect all objects
|Left drag (_inside_ object)|Move the selected object(s)
|Left drag (_outside_ object)|Resize the selected object(s) (if available)
|Space|Duplicate the selected object(s)
|Backspace|Delete the selected object(s)
|===

TIP: Like other editors in the Radiant family, DarkRadiant offers a rather
unusual system for resizing objects. Rather than clicking exactly on the edge,
or on a dedicated resizing handle, you can click and drag anywhere outside an
edge to move that edge inwards or outwards. Dragging outside a corner allows you
to move two edges at once.

==== Flipping and rotating

DarkRadiant provides six buttons to quickly flip or rotate objects (in 90 degree
increments) around each of the three world axes. These are available on the
left-hand vertical toolbar.

[cols="^1h,10"]
|===
|image:brush_flipx.png[align="center",width=24]|Flip along the X axis
|image:brush_rotatex.png[align="center",width=24]|Rotate around the X axis
|image:brush_flipy.png[align="center",width=24]|Flip along the Y axis
|image:brush_rotatey.png[align="center",width=24]|Rotate around the Y axis
|image:brush_flipz.png[align="center",width=24]|Flip along the Z axis
|image:brush_rotatez.png[align="center",width=24]|Rotate around the Z axis
|===

[[ManipulatorModes]]
==== Manipulator modes

For more precise control over object motion, there are three manipulator modes
which can be selected with buttons on the left-hand vertical toolbar.

[cols="^1h,3h,10"]
|===
|image:select_mousetranslate.png[align="center",width=24]|Translate mode|
A manipulator widget with axis-aligned arrows will be displayed at the selected
object's center. Click and drag one of the arrows to move the object along that
axis, or drag inside the manipulator box to move the object in two dimensions.
This mode may be useful for moving brushes around without accidentally resizing
them.
|image:select_mouserotate.png[align="center",width=24]|Rotate mode|
A widget with three axis-aligned rings will be displayed at the selected
object's center. Drag a ring to rotate the object by any arbitrary amount around
that ring's axis.
|image:select_mouseresize.png[align="center",width=24]|Resize mode|
This is the default Radiant drag mode (hence the "QE" icon referring to the
original QERadiant) which allows you to move objects by dragging inside them and
resize by dragging outside the boundary edges.
|===

=== Working with brushes

Brushes are the basic building blocks of all maps. Typically they are used for
coarse-grained level geometry such as walls, ceiling and floors. Brushes also
have a vital role in sealing a map from the void: even a map built entirely from
patches and static meshes must still be surrounded by brushes in order to avoid
leaking.

.Additive versus subtractive geometry
****
If you are used to mapping for the legacy Thief games using Dromed or T3Edit,
the system used by DarkRadiant may seem somewhat back-to-front. In previous
games, the world starts out as an infinite solid, in which you "carve out" rooms
using subtractive brushes. In DarkRadiant, the world starts out as an infinite
void, and all brushes are solid. The space in which the mission happens must be
fully enclosed by solid brushes, otherwise the map will "leak" and fail to
compile.

The need to deal with map leaks may at first seem like a burden, however the
exclusive use of solid brushes frees the engine from needing to worry about
"brush ordering", and allows an important performance optimisation: by "flood
filling" the map interior, the map compiler can efficiently discard geometry
that never needs to be rendered.
****

[[CreatingABrush]]
==== Creating a brush

To create a simple rectangular brush, ensure that nothing is selected (*ESC*),
then *Left drag* in the 2D view. A new brush will be created and sized according
to the dragged area, with its dimensions snapped to the current grid level. To
adjust the third dimension of the brush (perpendicular to the view direction),
used *Ctrl + TAB* to switch the 2D view axis, and *Left drag* outside the brush
boundary to adjust the size.

TIP: Whenever you drag to create a new brush, the third dimension will match the
size of the _most recently selected_ brush. This makes it easy to draw a series
of brushes with the same height, such as when you need to create a series of
floors or walls in succession. To match the height of an existing brush, simply
select (*Shift + Left click*) and deselect it (*ESC*) before drawing the new
brush.

[[BrushShapes]]
==== More complex brush shapes

Although each brush starts out as a six-sided cuboid, it doesn't have to stay
that way. DarkRadiant offers several options for creating multi-sided brushes in
more complex shapes. To create one of these shapes, first define a regular
cuboid brush covering the volume you want the new shape to occupy, then choose
the appropriate option from the *Brush* menu:

[%autowidth]
|===
|image:6Prism.png[]|
*Prism*

An n-sided approximation of a cylinder, with the axis of the cylinder
 aligned with the current 2D view.

|image:6Cone.png[]|
*Cone*

A tapered n-sided cone, which always points upwards regardless of the
2D view axis.

|image:6Sphere.png[]|
*Sphere*

A rotationally symmetric n-sided approximation of a sphere, with the
axis of rotation pointing upwards.
|===

While these shapes can be useful for certain architectural modelling, remember
that brushes are always flat-shaded and are not generally a good substitute for
spheres or cones created with patches or static meshes.

[[CreatingARoom]]
==== Creating a room

Although it is not too difficult to create a hollow room by creating floor,
ceiling and wall brushes manually, this is a common enough operation that
DarkRadiant provides a couple of shortcuts. These options can be found on the
vertical toolbar at the far left of the main window.

[cols="1,4"]
|===
|image:CreateRoomBrush.png[width=320]|
image:CreateRoom.png[width=36] *Create Room*

Create a room whose interior size matches the size of the currently-selected
brush. The wall thickness will be equal to the current grid size.

|image:HollowBrush.png[width=320]|
image:Hollow.png[width=36] *Hollow*

Hollow out the selected brush, leaving the exterior dimensions the same. The
wall thickness will be equal to the current grid size, but the wall brushes will
overlap at the corners, rather than just touching each other as with *Create
Room*.

This is legacy tool from GtkRadiant, and generally inferior to *Create Room*.
The overlapping wall brushes make it more difficult to precisely align interior
textures, since part of the inner face is obscured (and therefore removed during
map compilation). However, there may be occasional situations in which *Hollow*
is useful, so it is retained in DarkRadiant.
|===

The room creation tools do not require the initial brush to be rectangular --
you can quite happily *Create Room* with a triangular or trapezoidal brush, or a
brush with sloping sides. However, with a more complex brush shape, the
complexity of the resulting wall geometry increases considerably, so attempting
to hollow out a 7-sided sphere is probably ill-advised.

[[SplittingBrushes]]
==== Splitting brushes

Sometimes it is necessary to divide a brush into two or more pieces, perhaps to
create a doorway or other opening. The *Clipper* tool, accessed with the *X*
key, is used for this purpose.

.Splitting a brush into two parts
image::ClipTool3D.png[align="center"]

. Select the brush to be split (the Clipper can be activated with nothing
selected, but it will not do anything useful).
. Press *X* to activate the Clipper, or click on the respective icon on the
left-hand editing toolbar.
. Click in the 2D window at two different positions, to define the plane along
which the brush will be split. The proposed split plane will be highlighted in
blue; feel free to change 2D view axis with *Ctrl + TAB* or use the 3D camera view
to better visualise the split plane.
. Once the split plane is defined, press *Shift + Enter* to execute the split and
keep _both_ halves of the brush; press *Enter* to execute the split and keep
only one half. The part of the brush that is kept with *Enter* depends on the
order in which you define the clip points: the points (marked *0* and *1*) will
appear _clockwise_ on the brush edge according to the current 2D view. If in
doubt, just use *Shift + Enter* to keep both parts, and delete the unwanted one
afterwards.
. Repeat the process to perform additional splits on the selected brush, or
disable the Clipper with the *X* key. The Clipper is a toggled tool and will
remain active until disabled.

NOTE: It is possible to create _three_ split points before executing the split,
which will define a split plane in three dimensions. Defining a three-point
split plane which is actually useful, however, may be challenging.

==== Reshaping brush edges

All brush edges can be moved independently, which gives you the ability to
quickly create shapes like triangles or trapeziums. This functionality is
accessed via the *Select Edges* tool on the upper toolbar, or with the *E* key.

.Creating a trapezium using edge editing
image::EdgeEditing.png[align="center"]

. Select a brush.
. Activate *Select Edges* with the toolbar button or *E* key. DarkRadiant will
place a green control point at the center of each brush edge.
. In either the 2D or the 3D view, click and drag on a control point to move its
edge. The control point will turn blue and move along with the cursor. In the 2D
view, dragging corners is generally easiest, since the resulting shape change
can more easily be seen.
. To reduce the number of brush sides, such as changing a rectangle into a
triangle, simply drag one corner directly on top of another. The two edges will
be merged.

[[BrushBasedSelection]]
==== Brush-based selection

As well as using brushes to define map geometry, you can also use them to select
objects. There are three commands on the top toolbar which convert the selected
brush(es) into a temporary selection volume:

[cols="^1h,3h,10"]
|===
|image:SelectCompleteTall.png[align="center",width=24]|Select complete tall|
Select all objects that are _completely_ contained within the two-dimensional
outline of the selected brush(es) in the current 2D view window, ignoring their
position on the third axis (perpendicular to the screen).
|image:SelectInside.png[align="center",width=24]|Select inside|
Select all objects that are _completely_ contained within the selected brush
volume(s) in all three dimensions.
|image:SelectTouching.png[align="center",width=24]|Select touching|
Select all objects that are touching the selected brushes. Unlike the previous
two commands, this one does not remove the selected brushes, since it is
designed to allow you to quickly select objects that are adjacent to real map
geometry.
|===

=== Working with patches

Patches are smooth-shaded Bezier surfaces that can be created and manipulated in
the editor (unlike models), and used to represent a variety of curved shapes
such as vaulted ceilings, arches or pillars. Patches are single-sided surfaces,
not solid like brushes, and cannot be used to seal a map from the void -- any
patch work on the boundary of a map will need solid brushes behind it to prevent
the map from leaking.

==== Creating a simple patch

A simple patch starts off as a flat rectangle, which can then be manipulated
with vertex editing to produce a curved surface, if desired.

To create a simple patch:

. Set the 2D view axes (*Ctrl + TAB*) to define the orientation of the patch.
The patch will be created facing directly towards the screen, so to create a
horizontal (ceiling or floor) patch, the 2D view should be in XY (Top)
orientation.
. <<CreatingABrush,Create a rectangular brush>> to define the width and height of
the patch in the current 2D view (the third dimension is not important, since
the patch will be infinitely thin once created).
. With the brush selected, choose *Create Simple Patch Mesh* from the *Patch*
menu.
. In the dialog, choose the number of control points to define the shape of the
patch along its width and height. A patch can have between 3 and 15 control
points in each dimension; there will always be a control point at the extreme
edge, and one in the middle. More control points allow more complex shapes but
also require more manual adjustment -- creating a simple arch is much easier
with just three control points.
. Click *OK* to create the patch.

.Simple patches with 3, 7 and 15 control points in both dimensions
image::SimplePatchesControlPoints.png[align="center"]

==== Manipulating control points

With a patch selected, press *V* to enter (or leave) vertex editing mode. This
will display all of the control vertices, and allow you to select and move them.

- *Left click* and drag a vertex to move just that one vertex.
- *Shift + Left click* to add a vertex to the current selection set. When
   several vertices are selected, dragging any one of the selected vertices will
   move all of them together.
- *Shift + Left drag* around several vertices to draw a selection rectangle that
   will toggle the selection state of all vertices inside it, selecting them if
   unselected and unselecting them if already selected.

.Making an arch by raising the central row of vertices in a simple patch
image::PatchVertexEditing.png[align="center"]

==== Adding or removing control points

Control points can be added or removed from a patch using the appropriate sub-menus in the *Patch*
menu.

[cols="1h,3"]
|===
|*Insert*|
Add rows or columns of control points without changing the dimensions of the patch — the control
points will become more densely packed.
|*Extend*|
Add rows or columns of control points while extending the patch dimensions. The existing control
points are left in the same position.
|*Delete*|
Remove rows or columns without changing the dimensions of the patch (the opposite of *Insert*). The
control points will become less densely packed.
|===

.Inserting (top), Extending (middle) and Deleting (bottom) control points in a patch
image::AddRemovePatchControlPoints.png[align="center"]

==== Thickening a patch

When created, every patch has zero thickness and can only be viewed from one side; however, a patch
can be made into an apparently solid object by creating additional patches automatically via the
*Thicken* command in the *Patch* menu.

.Thickening a patch (left) with side walls (center) and no side walls (right)
image::PatchThicken.png[align="center"]

The *Thicken* dialog presents several options:

[cols="1h,3"]
|===
|*Extrude along Vertex Normals*|
Thicken the patch by extruding the patch surface in the direction it is facing.
|*Extrude along X/Y/Z Axis*|
Thicken the patch by extruding the surface along the specified axis, ignoring the face normal
direction.
|*Thickness (units)*|
Distance in map units to extrude the patch by.
|*Create seams ("side walls")*|
If checked, the extruded patch will be made into a fully solid "object" with an interior volume
completely enclosed by patches. If unchecked, only the initial patch and its extruded copy will be
created, with the sides left open.
|===

TIP: Although a thickened patch appears as a solid object, it still consists of individual patches
which can be selected and manipulated individually. If you wish it to continue to behave as a
solid, you can <<Group,group>> the patches together.

==== More complex patch shapes

Just like with brushes, DarkRadiant offers several default patch shapes beyond
the flat simple patch. These can be created by choosing the corresponding option
in the *Patch* menu. There is no need to have a brush selected first in order to
create these shapes, however if a brush _is_ selected, it will be removed and
used to define the size of the patch shape.

[cols="1,3"]
|===
|image:PatchSphere.png[]|
*Sphere*

An approximation of a sphere (the quadratic Bezier patch implementation in Doom
3 and DarkRadiant does not permit the creation of a perfect sphere).

|image:PatchCylinder.png[]|
*Cylinder*

A hollow cylinder aligned with the direction of the 2D view.

|image:PatchCone.png[]|
*Cone*

A tapered cone pointing along the 2D view axis.

|image:PatchEndCap.png[]|
*End cap*

An arch or half-cylinder covering a 180 degree angle, aligned with the 2D view
axis. The peak of the arch will be at the top if created in front or side views,
making this useful for curved ceilings and the like.

|image:PatchBevel.png[]|
*Bevel*

Portion of an arch covering a 90 degree angle. This may be placed along room
edges to give a curved appearance.

|===

==== Controlling patch subdivision

Although patches are defined by Bezier curves, they are subdivided into flat
polygons for rendering. By default, the number of polygons to create is
determined dynamically by the game engine, based on the shape of the patch.
However, you can also use the *Patch Inspector* to explicitly set the level of
subdivision required, which can be useful when optimising a map by reducing
on-screen polygon counts.

.Default (automatic) subdivision, 2x2 subdivision, 3x3 subdivision, 3x10 subdivision
image::PatchSubdivision.png[align="center"]

To subdivide a patch:

. Select *Patch Inspector* in the *View* menu to make the inspector widget
visible.
. With the patch selected, enable the *Fixed Subdivisions* checkbox.
. Use the *Horizontal* and *Vertical* numeric spinboxes to set the number of
polygons to divide the patch into. The value can range from *1*, making the
patch completely flat regardless of control point positions, up to a maximum of
*32*. Each dimension can have a different subdivision level, if required.

=== Applying textures

When a brush or patch is created, it will be assigned a default texture. To
apply a new texture, you must first select the brush, face or patch to be
textured. There are two different selection commands:

[cols="1h,3"]
|===
|Shift + Left click|
Select an entire brush or patch. Any chosen texture will apply to all faces.
|Ctrl + Shift + Left click|
Select a single brush face for texturing. This command is only available in the
3D camera view
|===

Once you have selected the objects or faces to texture, you can use either the *Media*
or the *Textures* tab to perform the texturing operation.

[[MediaTab]]
==== The Media tab

The *Media* tab shows a tree view which contains all of the textures available
in the game installation. Selecting a texture in the tree will show a small
preview swatch, along with some metadata about the texture definition.

image::MediaTab.png[align="center"]

To apply a texture to the selected brush, simply *Double-click* on a texture
name in the tree. The tree view also offers a context menu with several options:

[cols="1h,3"]
|===
|Load in Textures view|
Load all textures contained within the selected folder, making them available on
the *Textures* tab. This option is not available when a single texture is
highlighted.
|Apply to selection|
Apply the highlighted texture to the current object. This is identical to the
*Double-click* operation, and is only available for single textures, not
folders.
|Show Shader Definition|
Show a syntax-highlighted text window containing the definition of the selected
texture.
|Selected/deselect elements using this shader|
Select or deselect objects in the map which the highlighted texture is
applied to. This can be used for organisational purposes, or to identify whether
a texture is used or not.
|Add to/Remove from favourites|
Add or remove the selected texture from the favourites list. The favourites list
provides easy access to a user-chosen group of textures, and can be accessed by
choosing the *Show Favourites* radio button at the top of the panel.
|===

[[TexturesTab]]
==== The Textures tab

The *Textures* tab provides a scrollable canvas containing preview swatches of
all the textures which are currently loaded in the current map.

image::TexturesTab.png[align="center"]

When DarkRadiant first starts up no textures are loaded and this panel is empty.
New textures can only be loaded via the *Media* tab (described in the
<<MediaTab,previous section>>), either by applying a texture directly to a
brush, or by using the *Load in Textures view* command to explicitly load an
entire folder of textures.

Once textures are loaded onto the *Textures* tab, you can apply them to a
selected object by *Left clicking* on them. By *Right clicking* on a texture you
can access a context menu with a single command *Seek in Media browser*, which
will highlight the clicked texture in the *Media* tab.

[[SurfaceInspector]]
==== Using the Surface Inspector

Once a texture is applied via the Media or Textures tabs, you will most likely
wish to adjust the alignment and scale of the texture on the brush or patch
face. DarkRadiant provides the *Surface Inspector* for this purpose, which can
be toggled with the *S* key or by choosing the option in the *View* menu.

image::SurfaceInspector.png[align="center"]

The Surface Inspector can be used to adjust textures on a single brush or patch
face, or several selected faces/brushes/patches at once. If more than one face
is selected and these faces have different values for text boxes in the dialog,
the text box will be greyed out, however it is still possible to use the buttons
to make changes which will be applied uniformly to all selected faces.

[cols="1h,3"]
|===
|Shader|This shows the full name of the texture applied to the selected
face(s). You can use the folder button to bring up a new dialog which allows you
to choose a new texture.
|Horiz/Vert Shift|These text boxes show the current texture shift (translation)
on the horizontal and vertical axes. The associated arrow buttons will increase
or decrease the texture shift by the current *Step* value.
|Horiz/Vert Scale|These show the current texture scale in the horizontal and
vertical directions. The arrow buttons will increase or decrease the scale by
the current *Step* value.
|Rotation|Shows the current texture rotation, in degrees. The arrow buttons will
rotate the texture clockwise or anticlockwise by the current *Step* value.
|Fit Texture|These controls allow you to fit an exact number of copies of the
texture across the face, so that the texture edges correspond to the face edges.

The numeric spin boxes control how many copies of the texture are tiled on each
axis. You can enter a value manually (including fractional values above or below
1.0) or use the spin buttons to quickly increase or decrease the number of
tiles. Using the spin buttons will apply the fit immediately, so you can quickly
preview the results in the camera view.

Toggle the image:preserveAspect.png[] button to *preserve aspect ratio* when
using the spin buttons to fit the texture on one axis. This automatically
adjusts the other axis so that the aspect ratio of the texture image is
preserved, ignoring the value in the other axis' spin box. This can be useful
for textures like wooden planks, where you might want an exact number of plank
_widths_ on a certain brush face but the number of _lengths_ is not important
(since the texture is seamless); in this case, avoiding aspect ratio distortion
is more useful than fitting an exact number of lengths.

|Align Texture|These buttons shift the texture so that the Top/Bottom/Left/Right
edge of the face are aligned with a texture boundary, but otherwise do not
modify the scaling of the texture (unlike the *Fit* operation).
|Flip Texture|Flips (mirrors) the texture along the horizontal or vertical axis.
|Natural|This button resets the texture to a default alignment and scale, based
the location and size of the face.
|Texture Lock|If this is enabled, the alignment of the texture will be preserved
relative to the face if the brush or patch is moved in 3D space. If disabled,
the texture itself will remain fixed in 3D space as the brush or patch moves,
resulting in the alignment changing.

Typically, if you have *Fit* a particular number of texture tiles across a face,
you will want to preserve alignment with *Texture Lock*. Conversely, if the
texture is applied to a much larger group of brushes with a common texture (that
needs to align across all of the brushes, regardless of how they are moved or
resized), you will want to disable *Texture Lock*.
|===

[[ShaderClipboard]]
==== Using the shader clipboard

While constructing a map it will frequently be necessary to apply the same
texture to several different surfaces such that they appear seamless in game. In
order to assist with this, DarkRadiant provides a *shader clipboard* which
allows shaders to be copied and pasted between primitives, and is independent of
the main clipboard used for copying and pasting other objects.

===== Copying a shader

There are two ways to copy a shader to the shader clipboard.

1. Select a _single face_ (not an entire brush) with *Ctrl + Shift + Left click*
 in the 3D view, then choose *Edit -> Copy shader*.
2. Directly *Middle click* the face in the 3D view (there is no need to select
it first).

In both cases, the *ShaderClipboard* section of the bottom status bar will
update to show the new value of the shader clipboard. If the *Media* or
*Textures* tab is visible, their contents will also update to view the selected
shader.

NOTE: Selecting a texture explicitly in the *Media* or *Textures* tabs will also
update the shader clipboard with the selected shader.

===== Pasting a shader

Once a shader is on the shader clipboard, it can be pasted onto another surface
in a number of ways:

1. Select the destination face with *Ctrl + Shift + Left click*, then choose
*Edit -> Paste shader* or *Edit -> Paste shader (natural)*.
2. Directly *Middle click* the destination face while holding down either *Ctrl*
(to paste the shader with projected coordinates) or *Shift* (to paste the shader
with natural coordinates).

.Natural or projected pasting
****
The difference between natural and projected coordinates is apparent when
pasting a shader onto a curved patch.

With *projected* coordinates (*Ctrl + Middle click*) the texture on the patch
will be aligned identically to the texture on the source face, which might
result in a stretched texture depending on the angle between the patch and the
source face.

With *natural* coordinates (*Shift + Middle click*) the texture will flow over
the curved surface in a more natural manner.

When pasting a shader onto a flat brush face, there may be little or no
difference between the two options.
****

=== Working with entities

If brushes are the bricks and mortar of a map (often literally), entities are
its fixtures and fittings. Every object in a map which "does something" other
than form part of the level geometry is an entity: lights, audio speakers,
particle emitters, static meshes, animated creatures or machinery. There are
also various functional entity types which provide vital metadata to the game
engine, such as determining where the player should start, or how creatures
should navigate between locations.

DarkRadiant provides certain common functionality to all entities, such as the
ability to edit properties using the *Entity* tab. Particular entity types are
sufficiently common, however, that they have their own dedicated creation and
editing tools.

*Light*:: Every map requires at least one light source in order to render
anything in game. A light occupies a rectangular volume, which can be created
and resized much like a brush, and has properties to determine its colour,
visible shape and falloff pattern in three dimensions. Lights can optionally
cast shadows, and can even be animated to flicker or flash.

*Model (func_static)*:: Model entities represent geometry that is not compiled
as part of the map itself. The model geometry can either be derived from brushes
and patches created inside DarkRadiant, or from an external model file in ASE or
LWO format. Model files are the primary mechanism for including fine detail in a
map which would be cumbersome to create with brushes and patches.

*Speaker*:: Essentially the audio equivalent of a light, a speaker entity
represents the point from which an in-game sound source will emanate. It has
properties to control its size and falloff, and optionally override certain
properties of the sound shader itself, such as volume.

*Player start (info_player_start)*:: This entity tells the game engine where to
place the player when a map is first loaded. A map without such an entity will
not be playable.

[[CreatingLights]]
==== Creating lights

To create a light, *Right click* in the 2D view and choose *Create light…*.
The position and size of the light volume depends on the current selection:

- If _nothing_ is selected, then a light volume will be created at the clicked
  position with a default size.
- If a _single brush_ is selected, the brush will be deleted and the light
  volume will match the size and position of the brush.
- If _several brushes_ are selected, then all selected brushes will be deleted
  and the light volume will be sized according to the bounding box of the
  brushes (i.e. the smallest box that would contain all of the brushes).

Unselected lights are shown in the 2D view as small boxes, while selected lights
also show the boundaries of the light volume.

.Light entity selected (left) and unselected (right)
image::LightSelectedAndUnselected.png[align="center"]

A selected light entity can be moved by dragging inside the small center box,
and it can be resized by dragging outside the edge of the light volume. Unlike
brushes, light volumes will by default resize symmetrically, so that the center
point does not move during the resize.

NOTE: Although light volumes can be resized like brushes, their shape can never
be changed; every light is an axis-aligned cuboid. This does not, however, mean
that they need to _look_ rectangular in game. See the <<LightInspector,next
section>> for details on how to change the falloff texture using the light
inspector.

There are a couple of options on the top toolbar which control the display and
behaviour of light volumes:

[cols="^1h,3h,10"]
|===
|image:view_show_lightradii.png[align="center",width=24]|Show all light volumes|
If enabled, light volume boundaries will be rendered in the 2D view for _all_
light entities, not just selected entities. The default behaviour is to show
only the center box for unselected light entities.
|image:dragresize_symm.png[align="center",width=24]|Drag-resize entities symmetrically|
If enabled (the default), light entities will be resized symmetrically, without
moving the center point. If disabled, lights will be resized like brushes:
dragging an edge will move only that edge, while the opposite edge remains
fixed.
|===

[[LightInspector]]
===== The light inspector

When initially created, a light is pure white in colour and has an unrealistic
rectangular illumination pattern matching its shape. You can change these
properties using the light inspector, which is accessed with the *L* key.

image::LightInspector.png[align="center"]

TIP: The light inspector can change the properties of a single light, or
multiple selected lights simultaneously.

*Light volume (omni vs projected)*:: The majority of lights in a map will be the
default, omnidirectional shape. An omni light is a simple cuboid which emits
light in all directions from its center to its edges.
+
A projected light is pyramid-shaped, and emits light from the tip of the pyramid
towards the base. Projected lights behave more like spotlights in real-life, and
can be used to highlight particular areas or project images of windows onto the
floor.

*Colour*:: Use the colour selector button to display a standard colour selection
dialog. As well as changing the hue, the light colour also governs the overall
brightness of the light. You can use the slider below the colour button to
adjust the brightness of the selected light(s) without changing the hue, with
realtime feedback displayed in the 3D camera view if lighting preview mode is
enabled.

*Texture*:: The falloff texture controls the shape of the lit area when rendered
in-game; the square texture chosen here will be mapped directly onto the
rectangular shape of the light volume. Light textures can be simple, such as the
generic circular gradient of `biground1`, or much more complex, including
multiple colours or animation.

*Options*:: There are a few light-propagation options which are mostly used to
 tweak performance. In particular, disabling shadows for any light which does
 not actually _need_ to cast shadows can give a significant boost to rendering
 speed.

[[CreatingModels]]
==== Creating models

Static models can be used to provide fine details in a map which would be
difficult or impossible to create in the editor with brushes or patches. Models
are created with an external 3D application such as Blender, Lightwave or Maya,
and saved into the game asset tree in LWO or ASE format.

To insert a model, ensure that nothing is selected, then *Right click* in the 2D
view and choose *Create model…*. DarkRadiant will show the model selector
dialog:

image::ModelSelector.png[align="center"]

In the top-left of the model selector window is a tree of all available models
in the game installation. Models may have different _skins_, which are variants
of the same model with different textures applied. If a model has skins
available, these will be listed as children of the model entry in the tree.

Choosing a model or one of its skins will show a preview render in the large
widget on the right-hand side. Various metadata such as the polygon count and
the applied textures are also shown in table at the lower left.

When you have chosen the desired model, click *OK* to insert it into the map.
The model will be inserted at the position where you originally right-clicked to
show the model chooser.

==== Creating a player start marker

The game requires a special entity (`info_player_start`) to mark the position at
which the player should enter the map. Without such an entity the map will be
unplayable.

To create this entity, ensure that nothing is selected then *Right click* in the
2D view and choose *Create player start here*. DarkRadiant will create the
player start entity at the clicked position.

Since it makes no sense to have more than one player start location, DarkRadiant
will not enable the *Create player start here* menu option if there is already
an `info_player_start` in the map. Instead, you may choose *Move player start
here* to move the existing entity to the clicked position.

==== Creating other entity types

Entity types without a dedicated item in the right-click menu are created using
the generic *Create entity…* option, which displays a dialog very similar to the
<<CreatingModels,model selector>>:

image::EntityClassSelector.png[align="center"]

Just like the model selector, the entity selector displays a tree of all
available entity types in the game installation, and a large preview widget
which shows an approximate rendering of the entity, if appropriate. Purely
functional entity types such as `info_location` or `info_player_start` do not
have any visible appearance and their render preview will be blank.

Some entity types have a short textual description giving information about
their usage; if present, this is displayed in the text box underneath the entity
class tree.

After selecting the desired entity type in the tree, click the *Add* button to
insert an instance of the entity into the map at the right-clicked location. If
the selected entity type requires a brush selection and no brush is selected, a
warning will be shown at this point.

[[EntityInspector]]
==== Editing entity properties

Every entity has a list of key/value pairs known as _properties_ or _spawnargs_.
These properties are displayed on the *Entity* tab of the editing panel.

image::EntityInspector.png[align="center"]

The entity panel lists all of the properties of the currently-selected entity,
showing each property's name, its current value, and an icon representing its
type (boolean, vector, text etc) if known. Selecting a property will populate
the two text boxes in the center of the widget with the property name and value,
allowing the value to be edited. If the selected property is of a known type,
the panel at the bottom will show a custom widget appropriate for editing the
particular property, e.g. three separate numeric spinboxes for a vector
property, a colour selector widget for a colour property, and so on.

*Changing a property value*:: To change the value of the selected property,
 simply enter the new value in the lower text box, then hit *Enter* or click the
 green tick button. If the property has a type-specific editing widget, you can
 also change its value using the controls in this widget.

*Adding a new property*:: There are two different ways to add a new property:
. Enter a new property name in the upper text box (which shows the selected
property name), and hit *Enter*. This does not rename the selected property, but
adds a new property with the edited name and the current value.
. *Right click* in the list of properties and choose *Add property* from the
context menu. This will display a new dialog listing all known properties along
with their descriptive text (if available). Selecting a property in this dialog
and choosing *OK* will add the property to the entity with a default value of
"-", which can then be edited in the entity panel itself.

*Deleting a property*:: To delete the selected property, *Right click* on the
 property in the list and choose *Delete property*.

The entity panel provides two options controlling its behaviour:

[cols="1h,3"]
|===
|Show inherited properties|If checked, all properties that apply to the
selected entity will be shown, including those which are inherited from the
entity type declaration in the game installation. If unchecked, only those
properties explicitly set on this particular entity (and stored in the map file)
will be shown.

You can change the value of an inherited property by selecting it and entering a
new value in the entity panel; this will create a new explicit property on the
entity which overrides the inherited default.
|Show help|Enables or disables the text widget at the bottom of the panel
which shows a brief explanation of certain properties. If a property has help
text available, the question mark icon will be shown in the *?* column.
|===

[[ReparentingPrimitives]]
=== Reparenting primitives

Whenever a new brush or patch is created, it will automatically be made a child
of the special *worldspawn* entity, which serves as the default entity
containing all of the primitives which define the world geometry. However,
*worldspawn* is not the only entity which can contain brushes and patches as
children.

When you create a model using the <<CreatingModels,model selector>>, DarkRadiant
will insert a type of entity called a *func_static* into the map to represent
the model geometry. A *func_static* can contain a model file loaded from disk in
LWO or ASE format, but it can also be used as a parent for one or more
primitives created within DarkRadiant. In either case, the behaviour of
*func_static* is the same: it represents a static mesh which is rendered in
game but is considered separate from the main world geometry, meaning that it
does not participate in map compilation, will not seal the map from leaks, and
will not cause intersecting brushes to be subdivided.

It is therefore often useful to make certain brushes and patches — typically
those which represent "fine detail" rather than entire walls, floors and the
like — into *func_static* entities to improve in-game performance and reduce the
chances for map compilation problems caused by excessively complex world
geometry.

The *func_static* entity class is not the only type of entity which can contain
primitives: there are several other *func_* entities which perform various
functions, for example *func_rotating* which allows geometry to rotate
continuously. DarkRadiant offers dedicated commands to convert to/from a
*func_static* since this is a very common operation, however the ability to
<<SelectChildPrimitives,select>>, <<AddRemoveChildPrimitives,add and remove>>
individual primitives behaves the same for all types of primitive-containing
entity.

==== Converting primitives into func_static

To convert one or more existing primitives into a *func_static* entity, simply
select all of the primitives, right-click in the 2D window, and choose *Convert
to func_static*.

[[SelectChildPrimitives]]
==== Manipulating individual child primitives

After converting a primitive, a number of changes are noticeable:

. The primitive may be drawn in a different colour.
. The primitive will no longer be resizeable by dragging its boundary with the
mouse.
. When the primitive is selected, the *Entity Inspector* will no longer show the
*worldspawn* entity, but a new entity with a different *classname* (e.g.
`func_static`). You can set spawnargs on this entity like any other (including
giving it a custom name).
. Selecting any contained primitive will cause a small X/Y/Z axis widget to be
drawn at the entity's origin position (which may be inside one of the
primitives, or outside all of them, depending on their layout).
. If there are multiple primitives contained within a single entity, selecting
any individual primitive will cause all of the entity's primitives to be
selected. This allows you to easily move the entire static object by simply
dragging any one of its primitives.

However, it is still possible to perform operations on a single primitive, for
example resizing a brush, by selecting it with the *TAB* key. Each press of
*TAB* will cause DarkRadiant to select a different primitive contained within
the entity, after which it will return to selecting the entire entity. With only
a single primitive selected, all of the normal operations are possible on that
primitive, for example deleting or resizing it.

The <<EntityInspector,entity inspector>> widget makes it clear whether you have
selected an entity or a primitive within that entity, using the text above the
list of entity properties. If an entire entity is selected, the text will appear
similar to `Entity&nbsp;1`, whereas with a primitive selected it will read
`Entity&nbsp;1,&nbsp;Primitive&nbsp;1`.

[[AddRemoveChildPrimitives]]
==== Adding or removing primitives

Once you have created a *func_static* or similar entity from a number of
primitives, you can add or remove primitives without needing to create a new
entity from scratch.

*Adding a primitive*:: Select the entity, then expand the selection (i.e. using
 *Shift + Left click*) to include one or more existing primitives to add to this
 entity. Then choose *Edit -> Reparent primitives*.

*Removing a primitive*:: Use the *TAB* key to select the individual primitive to
 remove (you must do this even if there is only one primitive in the entity),
 then choose *Edit -> Reparent primitives to worldspawn*. The removed primitive
 will still exist in the map but it will be a regular worldspawn brush or patch,
 not parented to any other entity.

*Unparenting all primitives*:: With the entity selected, simply right-click in
 the 2D view and choose *Revert to worldspawn* to turn all of the primitives
 back into worldspawn.

=== Compiling a map

DarkRadiant does not include functionality for compiling a map into the form
needed by the game engine; instead, you must use external tools or the map
compiler built into the game itself.

For Doom 3 and the Dark Mod, the following commands are used within the in-game
console (which can normally be accessed with the key immediately above `TAB`):

[horizontal]
`dmap&nbsp;<mymapname.map>`:: Compile the map called `mymapname.map`, which must be
located within the `maps` directory of the mod installation. If there are any
problems compiling the map (e.g. a leak), the error will be displayed in the
console output.
`map&nbsp;<mymapname.map>`:: Load the compiled map `mymapname.map` into the game
engine and start playing it immediately.

TIP: When compiling and testing maps, it may be helpful to set your game to
play in windowed mode, with a reduced resolution. This will allow both the game
and DarkRadiant to be visible on the screen as separate windows, which you can
easily switch between during the compile and test cycle.

==== Preventing leaks

A map "leak" occurs when the play area is not fully enclosed with a complete
shell of opaque brushes. If the map leaks, compilation will fail and the map
will not be playable.

In order to minimise the likelihood of a map leak, ensure that your map has all
of the following properties:

- The map interior is _completely_ sealed from the exterior void by brushes (not
  patches). It is much easier to achieve this by building up a map carefully,
  making good use of the grid snapping functionality, rather than haphazardly
  throwing brushes together and hoping to seal them later.
- All of the sealing brushes have an opaque texture. Skybox textures are
  considered opaque and are OK, however semi-transparent or perforated mesh
  textures are not.
- The origin point of _every_ entity in the map lies within the sealed map
  interior. It is OK if a large model extends outside of the map, provided that
  its origin point is on the inside.

WARNING: Do *not* be tempted to avoid leaks by enclosing your entire map in a
single huge box. This may seem to solve the problem (the map will indeed not
leak), but it completely negates the important performance optimisations that
the map compiler carries out when it "flood fills" the map interior.

[[PointFile]]
==== Locating leaks with a pointfile

No matter how hard you try to avoid leaks, occasionally they will happen. In
this case the *pointfile* functionality is helpful to identify the location of
the leak.

After the map compilation has failed with a leak, return to DarkRadiant and
choose *Pointfile* from the *File* menu. This will automatically load the point
file associated with the current map, which contains a series of points
identifying the path to the leak. This path will be rendered as a bright red
line in both the 2D and 3D views:

.A pointfile rendered in both 3D and 3D views
image::Pointfile.png[align="center"]

In this example we can clearly see that the map has leaked because the far wall
brush does not join up with the ceiling.

== Organising a map

Since a fully developed Dark Mod map is large and complex, DarkRadiant provides
several tools to make organising a large map easier. Objects can be grouped,
sorted into user-defined layers and filtered using various criteria, while the
prefab system allows large chunks of map to be reused or shared with other
mappers.

[[Group]]
=== Grouping objects

DarkRadiant allows a number of objects to be grouped together, so that they can
be selected and manipulated as a single unit.

To *create* a group:

. Select several objects.
. *Right-click* in the 2D window to show the context menu.
. Choose *Group Selection*.

Once the objects are in a group, selecting any object in the group will
automatically select all other objects in the same group.

To *remove* a group, select the group then choose *Ungroup Selection* from the
2D view context menu.

NOTE: Groups can be nested, by creating a group that includes one or more
existing groups. When you ungroup such a nested group, the original component
groups will be restored.

[[WorkingWithPrefabs]]
=== Working with prefabs

DarkRadiant allows a collection of objects to be saved to disk as a *prefab*,
which can then be imported into other maps. You can use prefabs to store
anything from a single small object to a vast section of map geometry complete
with lights and AI.

==== Exporting to a prefab

. Select the objects in the map that you wish to include in the prefab.
. From the *File* menu, choose *Save selected as prefab...*
. Use the file chooser dialog to choose a location and name for the prefab file.

TIP: Unlike actual `.map` files which must be accessible by the game engine,
prefabs are a DarkRadiant-only feature that have no significance to the engine.
You are therefore free to store prefab files wherever you wish, either inside or
outside the game installation directory.

[[ImportPrefab]]
==== Importing a prefab

Either right-click in the 2D window and choose *Insert prefab...*, or open the
*File* menu and choose *Import prefab...*. This will show the prefab browser.

image::PrefabChooser.png[align="center"]

Like the model selector, the prefab selector shows a tree of available prefabs
on the left, and a preview window on the right giving an idea of what the prefab
looks like. Using the radio buttons at the top of the window, you can choose
whether to browse prefabs contained within the game installation, or within a
custom directory of your choice.

The preview window functions much like the 3D view in the main application:
*right click* to enter or leave camera mode, which enables the following motion
commands:

[cols="1h,3"]
|===
|Mouse move|Change the camera view direction (pan or tilt)
|Mouse wheel|Zoom the camera
|Up/Down arrow|Move the camera forwards or backwards
|Left/Right arrow|Move the camera left or right
|===

When you have chosen the desired prefab, click *OK* to insert it into the map.
Before inserting the prefab, you can use the
*Create&nbsp;Group&nbsp;out&nbsp;of&nbsp;Prefab&nbsp;parts* checkbox to control
whether the prefab is automatically grouped as a single object, or inserted as
separate selectable objects.

=== Exporting models

DarkRadiant provides a limited ability to export scene geometry into a number of
3D model file formats: ASCII Scene Export (ASE), Lightwave (LWO) or
Wavefront OBJ. This functionality is provided to help with organising
frequently-used map elements — DarkRadiant is not intended to compete with
full-featured 3D modelling applications such as Blender or 3DS Max.

Exporting to a model is similar to exporting to a prefab, except that models can
only contain geometry (brushes or patches), not other map entities such as
lights or speakers. However, unlike prefabs, models can be edited with other 3D
software, and exporting map geometry as a model might provide a useful template
for creating map-specific static meshes in a more powerful modelling tool.

To export a model:

. Select the geometry to be exported. Note that DarkRadiant currently does not
complain if you select non-geometry such as lights, however these will not
appear in the resulting model file.
. Open the *File* menu and choose *Export selected as model...*
. In the *Output Format* dropdown, choose one of the supported model formats:
`ASCII Scene Export (.ase)`, `Lightwave Object File (.lwo)`, or `Wavefront OBJ
(.obj)`.
. Choose the path for the exported model file in the *File Path* entry box.
. Click *OK* to export the model.

=== Using layers

When a map contains a large number of objects, it may become difficult to work
with the 2D views as a result of the visual clutter. Organising the map into
several *layers* can help solve this problem. The visibility of each layer can
toggled independently, allowing you to focus on the objects you want to work
with.

Layers do not impose any requirements on the physical layout of objects: it is
possible to include objects spread all over a map into a single layer. For
example, you can have a layer for all enemies, another layer for all lights,
another layer for brushwork, and so on.

==== The Layers window

To show or hide the *Layers* window, choose `Layers` from the `Edit` menu. The
window lists all of the layers which exist in the current project, and allows
you to perform various operations on them.

image::LayersWindow.png[align="center"]

*Creating a layer*:: To create a new layer, click the `New` button at the bottom
 of the window. A popup will be shown asking for the name of the new layer. Once
 the layer is created, it will appear in the list.

*Deleting a layer*:: Click the red 'X' button to the right of a layer to
 delete it. Deleting a layer does *not* delete the objects in the layer, only
 the layer itself. Any objects in that layer will be moved to the default layer.

*Renaming a layer*:: Click the edit button to the right of a layer name to
 change the name. A popup will be shown asking for the new name.

*Selecting objects on a layer*:: Click on the name of a layer itself to select
 all objects on that layer.

*Toggling visibility*:: The button to the left of a layer name is used to toggle
 the visibility of objects on that layer. If objects are visible, a tick is
 shown in the button, otherwise it is empty.

*Changing the active layer*:: The visibility toggle button shows a star for the
 layer which is currently set as the active layer. To change the active layer,
 *Ctrl + Left click* on the layer you wish to set as the new active layer.

==== Moving objects into layers

An object can be placed in any number of layers. To see which layers a selected
object is in, look at the narrow coloured rectangle next to the layer name in
the *Layers* window. The rectangle will turn from grey to pink for each layer
that contains the selected object.

.A light in two layers: "Default" and "Lights"
image::LightInTwoLayers.png[align="center"]

All newly-created objects will be placed in the *Default* layer. You can move or
copy objects between layers using the options in the 2D view's context menu.

*Create layer...*:: Bring up the name entry dialog and create a new layer,
 exactly as if the *New* button in the *Layers* window had been clicked.

*Add to layer...*:: Copy the selected object into the chosen layer, without
 removing it from its existing layer(s).

*Move to layer...*:: Move the selected object into the chosen layer, removing it
 from all other layers.

*Remove from layer...*:: Remove the selected object from the chosen layer.

=== Filtering map elements

While the Layers feature allows maps to be organised into manual groupings of
objects, DarkRadiant also provides a mechanism for controlling the visibility of
items based on their characteristics. This is controlled via the *Filter*
menu.

==== Built-in filters

The *Filter* menu is populated with a number of built-in filter rules which are
expected to be useful to mappers. Each filter may be activated independently,
and each activated filter will be shown with a tick alongside its name. Filters
operate in a "subtractive" sense: if a filter is active, objects matched by that
filter will be hidden; the remaining visible objects will be those which are not
matched by any active filters.

TIP: Active filters are persisted into settings, and are therefore retained
between DarkRadiant sessions.

The built-in filters include:

[cols="1h,3"]
|===
|All entities|Hide all entities other than the worldspawn, leaving only brushes
 and patches visible.
|World geometry|The inverse of *All entities*. Hides brushes and patches while
 leaving entities visible.
|Brushes|Hide only brushes, leaving patches and entities visible.
|Patches|Hide only patches, leaving brushes and entities visible.
|Caulk|Hide any brush or patch which has the *caulk* texture applied to at least
 one surface.
|Collision surfaces|Hide the additional collision meshes which are embedded in
 certain models, while leaving the models themselves visible. This filter is
 especially useful because collision meshes often obscure parts of the model
 itself.
|===

Aside from the list of filters, the *Filter* menu contains three other options:

[cols="1h,3"]
|===
|Activate all filters|Activate every filter in the list. Very unlikely to be
 useful, because it will probably result in every object in the map becoming
 invisible.
|Deactivate all filters|Turn off all active filters. This one _is_ useful, since
 you may have manually activated a number of filters and want to turn them all
 off at once.
|Edit filters...|Display a dialog allowing you to create, edit and manage the
 list of available filters.
|===

==== Customising filters

In addition to the filters supplied with the mod distribution, DarkRadiant also
allows you to add your own custom filters to the list by choosing the *Edit
Filters...* menu option. This displays a dialog containing the list of all
available filters, including built-in ones. Use the *Add* and *Delete* buttons
to add or remove custom filters from the list, and the *Edit* button to enter a
new dialog which allows you to edit the rules of the selected filter.

Built-in filters cannot be removed or edited, but you can choose the *View*
button to open the filter editor in a read-only mode.

.The filter editor dialog
image::FilterEditor.png[align="center"]

Each filter consists of a number of *rules*, which are applied in the order
shown in the list box. Filters may contain only a single rule ("hide all speaker
entities"), or multiple rules ("hide all entities, then show only speaker
entities"). You can freely add, remove or reorder rules using the buttons to the
right of the rules list.

Each rule has the following components:

*Index*:: An integer representing the rule's position in the list, numbered from
 zero.

*Type*:: This controls what the rule is "looking for" when it tries to match
 objects to hide or show. Currently there are four rule types: *entityclass*
 which matches the classname of entities (e.g. "speaker"), *object* which
 matches either "brush" or "patch" and is used for controlling the visibility of
 map geometry, *texture* which matches the name of an applied texture, and
 *entitykeyvalue* which matches the value of a specific property on the entity.

*Entity Key*:: This column is only used for *entitykeyvalue* rules, in which
 case it contains the name of the property to match (while the _value_ to match
 will be contained in the *Match* column).

*Match*:: This contains the actual value to be matched by the rule. Its
 interpretation and allowed values will depend on the rule type. For *object*
 type rules the value must be "brush" or "patch", whereas with all other rule
 types the value may be any arbitrary string.

*Action*:: Choose whether this rule will result in matched objects being shown,
 or hidden. The filter system starts with everything being visible by default,
 so a filter which does not contain at least one *hide* rule will have no
 effect.

=== The entity list

As a map becomes larger and more complex, keeping track of its contents may
become more challenging. To assist with this, DarkRadiant provides an *Entity
List* which functions as an "outline" view of the map, listing all entities and
their child brushes and patches (if any).

The entity list can be accessed by choosing the *Entity List* option from the
*View* menu.

.The entity list, showing a number of entities in a small test map
image::EntityList.png[align="center"]

The tree structure shown in the entity list corresponds to the structure of the
map itself: a single "world" entity which acts as the parent of the brushes and
patches in the map, alongside a number of other entities that have been placed
by the mapper, some of which may contain their own child brushes or patches.

Clicking on an entity in the list will cause it to be selected in the map. If
the *Focus camera on selected entity* checkbox is enabled, the camera will
additionally be moved to view the clicked entity.

By enabling the *List visible nodes only* checkbox, you can limit the entity
list to show only entities which are not currently hidden via filters.

== Dark Mod features

The Dark Mod is a considerably more complex game than vanilla Doom 3, and its
maps therefore include certain settings and features that would be cumbersome to
configure manually by entering property values on entities. DarkRadiant
therefore provides a number of Dark Mod specific dialogs which are described in
this section.

NOTE: Most Dark Mod features are compiled as separate plugins, and may not be
built by default on certain platforms. If these features seem to be missing,
contact the distributor of your DarkRadiant binary package for advice, or
examine the build options if you are compiling DarkRadiant yourself from source
code.

=== The Difficulty editor

Most Dark Mod maps can be played on one of three possible difficulty settings,
typically named "Easy", "Medium" and "Difficult" (although these names can be
overridden). The precise effects of each of these difficulty settings are fully
under the control of the map author, and might include such effects as spawning
or despawning particular enemies, changing enemy health or patrol routes, or
modifying the details of objectives.

DarkRadiant provides a Difficulty editor dialog to facilitate one particular
class of difficulty-dependent modification: making global changes to entity
classes throughout the map. This could be used, for example, to change the
health of every instance of a particular enemy, or (as shown in the diagram)
removing a particular enemy type's ability to relight torches.

.The Difficulty editor, showing a modified property on a particular entity class
image::DifficultyEditor.png[align="center"]

The Difficulty editor shows the names of the available difficulty levels in a
dropdown widget, beneath which are the settings for the selected difficulty
level. The difficulty names are customisable on a per-map basis — normally these
will be the default values of "Easy", "Medium" and "Difficult", but if the
current map has customised difficulty names DarkRadiant will adjust the tab
names accordingly.

On the left is a tree view showing all of the property overrides for the current
difficulty level. Each top-level item is a particular entity class, which
contains all of the property changes that are made to this entity class in this
difficulty level. In this example, the `ai_builder_guard` entity has its
`canLightTorches` property set to 0 on the Easy difficulty setting, meaning that
all enemies of this particular type will not be able to relight torches.

*Adding a setting*:: To add a new property setting for the current difficulty
 level, click the *Add* button. The widgets on the right hand side will become
 available, allowing you to choose an entity class, a property ("Spawnarg") to
 change, and the change to make ("Argument"). You can choose a number of
 mathematical operations for the modification, including a simple value
 assignment, or an addition or multiplication. After specifying the values, make
 sure you click the *Save* button to commit the changes into the list view.

*Removing a setting*:: Select an item in the list view and click the *Delete*
 button to remove a particular setting. You can only remove individual
 assignments from the list; to remove all of the assignments for a particular
 entity class, you must select and delete each one individually.

*Editing the difficulty name*:: To edit the name of the current difficulty
 level, click the edit button to the right of the dropdown, and enter a new name
 in the text box. The modified name will be written into a property on the
 `worldspawn` entity and reflected both in game and in DarkRadiant.

TIP: For details of more advanced difficulty-dependent changes, such as
modifying the behaviour of a *single* entity (rather than an entire entity
class), consult the Dark Mod Wiki.

=== Game Connection

The Dark Mod includes functionality to dynamically interact with a DarkRadiant
session running on the same machine, allowing certain information (such as
camera position) to be synchronised both to and from the game, and for certain
entity property changes to be pushed to the running game without needing to
restart.

These features are accessed in DarkRadiant through the *Connection* menu and
buttons on the camera view toolbar.

==== Activating the connection

. In *The Dark Mod*, load the map which you are currently editing in DarkRadiant.
. Bring down the game console and enter the command
[listing]
com_automation 1
+
This should result in a status message indicating that the game is listening for
connections on a particular network port.
[listing]
Automation now listens on port 3879

The game process is now ready to exchange data with DarkRadiant.

==== Synchronising camera position

You can synchronise the DarkRadiant camera position and the game player position
in both directions: editor to game and game to editor. This feature is most
easily controlled with the buttons on the camera view toolbar, but it can also
be activated from the *Connection* menu.

[cols="^1h,3h,10"]
|===
|image:CameraSync.png[align="center",width=24]
|Game position follows DarkRadiant camera|
Any motion of the DarkRadiant camera will be transmitted in realtime to the
game, resulting in the player position moving (in *noclip* mode) to the same
position and view direction.

This is a toggled option which remains active until switched off.
|image:CameraSyncBack.png[align="center",width=24]
|Move camera to current game position|
Update the DarkRadiant camera to match the current player position and view
direction in game.

This is a single-shot command; there is no mechanism to continuously move the
DarkRadiant camera in response to player motion in game.
|===

== Command reference

=== File menu

*New map*:: Prompt to save and close the current map (if necessary), then start
 working on a new empty map.

*Open map...*:: Prompt to save and close the current map (if necessary), then
 display a file browser to choose and load an existing map file from disk.

*Import map...*:: Display a file browser to choose and load an existing map file
 from disk, merging the contents with the existing map

*Import prefab...*:: Display the <<ImportPrefab,prefab browser>> to choose and
 import a prefab from disk.

NOTE: Importing a map and importing a prefab are functionally identical
operations; the only difference is the user interface used for choosing what to
import. The prefab browser is designed to offer a user-friendly workflow for
browsing, previewing and importing from a library of frequently-used map
elements, while *Import map* may be more useful for merging two or more
partially-complete maps.

*Save*:: Save the current map to disk under its existing file name.

*Save as...*:: Display a file browser to choose a new name for the current map,
 then save to this new file name in future.

*Save copy as...*:: Display a file browser to choose a new filename to save this
 map into, without changing the current map name for future *Save* operations.

*Save selected as Map...*:: Choose a file name and save the currently-selected
 items into a new map file without changing the current map name. Equivalent to
 *Save copy as* but it only saves the selected items, not the entire map.

*Save selected as prefab...*:: Equivalent to *Save selected as Map* but it saves
 the selected items into a <<WorkingWithPrefabs,prefab>> (`*.pfb`) file in the
 standard prefab location.

*Save selected as Collision Model...*:: Allows a selected map object (typically
 a brush) to be set as the collision model for a particular ASE or LWO model.
 After choosing this option, DarkRadiant will display the model chooser dialog,
 allowing you to choose the particular model that the selected object should be
 associated with. The selected brush is then saved, and associated with the
 model so that subsequent insertions of the same model will use the new
 collision geometry.

*Reload Models/Selected Models/Skins/Scripts/Readable Guis/Materials/Defs/Particles*::
 Forces DarkRadiant to re-read the selected category of items from disk,
 refreshing its internal data structures. This is necessary if you have edited
 or re-exported some asset which DarkRadiant is using in the current map and you
 want to see the latest changes.

*Game/Project Setup...*:: Show the <<GameSetup,Game Setup>> dialog for
 configuring game-specific settings.

*Pointfile*:: Load and show the <<PointFile,pointfile>> for the current map, if
there is one. If more than pointfile is available, a dialog will be shown
allowing you to choose which pointfile to load. An error dialog will be
displayed if there is no current pointfile (which is usually the case if the
current map has not leaked during compilation). Choose this option a second time
to hide the rendered pointfile.

*Exit*:: Exit DarkRadiant, prompting to save the current map if necessary.

=== Edit menu

*Undo*:: Undo the most recent operation.

*Redo*:: Redo the most recently undone operation.

*Copy*:: Copy the selected item(s) to the clipboard.

*Paste*:: Paste the item(s) on the clipboard to their original world location.

NOTE: Objects copied to the clipboard are represented using the same text format
which can be found in `.map` files. This makes it possible to save clipboard
content into a file and load it later as an actual map fragment.

*Paste to camera*:: Paste the item(s) on the clipboard to the current camera
 location, ignoring their original world location.

*Duplicate*:: Make a copy of the currently selected item(s), slightly offset
 from their original position.

*Delete*:: Remove the currently selected item(s).

*Group selection*:: Combine the selected items into a <<Group,group>>.

*Ungroup selection*:: Split the selected group back into individual objects.

*Reparent primitives*:: Make all selected worldspawn brushes or patches into
 children of the selected func_static (or similar entity). Requires exactly one
 entity to be selected, along with at least one primitive which is currently a
 child of the worldspawn.

*Reparent primitives to worldspawn*:: Unparent the selected primitive from a
 func_static (or similar entity), making it a child of the worldspawn. Before
 using this command you must first select a single primitive with the *TAB* key
 (even if the entity only contains a single primitive), otherwise the whole
 entity will be selected and the command will silently fail.

TIP: To unparent *all* of an entity's primitives and convert them back into
worldspawn, just right-click in the 2D view and choose *Revert to worldspawn*.

*Merge selected entities*:: Convert two more more selected entities into a
single entity which contains all of the contained brushes and patches. Only
works for entities which can contain primitives (e.g. func_static).

*Copy shader*:: Copy the shader from the selected face to the
<<ShaderClipboard,shader clipboard>>.

*Paste shader*:: Paste the shader currently on the <<ShaderClipboard,shader
clipboard>> to all selected faces.

*Clear selection*:: De-select all selected objects.

*Invert selection*:: De-select all selected objects, and select all unselected
objects.

*Select complete tall*:: Convert the currently-selected brush into a selection
volume, selecting all objects which are completely contained within its outline
in the current 2D view (ignoring the third dimension). See
<<BrushBasedSelection,brush-based selection>>.

*Select inside*:: Convert the currently-selected brush into a selection volume,
selecting all objects which are completely contained within it in all three
dimensions. See <<BrushBasedSelection, brush-based selection>>.

*Select fully inside*:: Like *Select inside*, except that contained brushes
which touch the boundary of the selection brush will not be selected.

*Select children*:: Select primitives which are children of the
currently-selected entity. See <<ReparentingPrimitives,reparenting primitives>>.

*Select parent entities*:: Select the parent entity of the currently-selected
primitive. See <<ReparentingPrimitives,reparenting primitives>>.

=== View menu

*New XY view*:: Create a new dockable orthographic (2D) view.

*New Camera view*:: Create a new dockable 3D camera view.

*Colours...*:: Show a dialog for choosing and editing <<ColourSchemes,colour schemes>>.

=== Entity menu

*Connect selected entities*:: Set a `target` spawnarg on the first selected entity pointing to the
second selected entity.

*Bind selected entities*:: Set a `bind` spawnarg on the first selected entity pointing to the
*second selected entity.

*Entity class tree...*:: Show a tree of all available entity types in the current game, along with
all of their properties. Unlike the tree shown in the *Create Entity* dialog, this entity class
tree shows an inheritance-based hierarchy and does not include a 3D preview.

=== Brush menu

*Prism...*:: Create an angular prism (extruded polygon) from the selected brush. See
<<BrushShapes,brush shapes>>.

*Cone...*:: Create a cone or pyramid from the selected brush. See <<BrushShapes,brush shapes>>.

*Sphere...*:: Create an approximation of a sphere from the selected brush. See
<<BrushShapes,brush shapes>>.

*CSG -> Make Hollow*:: Create a hollow room from the selected brush. See
<<CreatingARoom,creating a room>>.

*CSG -> Make Room*:: Create a hollow room from the selected brush, without any overlapping walls.
See <<CreatingARoom,creating a room>>.

*Clipper -> Clip Selection*:: Split the selected brush along the defined clip plane, keeping one
half. See <<SplittingBrushes,splitting brushes>>.

*Clipper -> Split Selection*:: Split the selected brush along the defined clip plane, keeping both
halves. See <<SplittingBrushes,splitting brushes>>.

*Clipper -> Flip Clip Orientation*:: Change which half of the brush is retained after using the
*Clip Selection* command. Difficult to use in practice; instead just *Split Selection* and delete
the unwanted half manually. See <<SplittingBrushes,splitting brushes>>.

*Make Detail / Make Structural*:: These options only exist to support legacy games, and are not
used in the Dark Mod.

== Configuring DarkRadiant

DarkRadiant offers a large number of configurable options which can be used to
tailor its behaviour to your desired workflow. Most of these options can be
found either in the Preferences dialog or exposed directly as menu items.

=== The Preferences dialog

The Preferences dialog can be shown by choosing `Preferences...` from the `Edit`
menu. The dialog contains a number of pages containing groups of logically
related options.

==== Camera settings

The *Camera* page contains options relating to the movement and behaviour of the
3D camera.

*Movement Speed*:: Use this slider to control how many game units the camera
 moves forwards or backwards when you use the scroll wheel in the 3D view. It
 does not affect the speed of rotation or lateral dragging (e.g. with *Ctrl*) in
 free look mode, nor does it affect motion with the arrow keys.

*Rotation Speed*:: This controls the speed of angular rotation when dragging the
 mouse after entering free look mode with right-click. If you have a high DPI
 mouse and want to be able to direct the camera more precisely, reducing this
 setting may help.

*Freelook mode can be toggled*:: Disabling this checkbox makes the free look
 functionality behave more like typical MMO games, where you hold down the right
 mouse button and drag to move the camera around. Uncheck this option if you
 hate modal interfaces or find the default toggle behaviour confusing.

*Discrete movement (non-freelook mode)*:: If this is checked, moving the camera
 with the arrow keys in non-freelook mode will cause discrete jumps in position,
 rather than smooth motion.

*Enable far clip plane*:: You can completely disable the <<Using3DCameraView,far
clip plane>> by unchecking this option. This will avoid the need to manage the
position of the far clip plane, but may negatively impact rendering performance
in large or complex maps.
+
NOTE: Technically it is not actually possible to _disable_ the far clip plane,
since having a far clip plane is a requirement for 3D rendering to work
correctly. This command in fact sets the far clip plane to a very high value,
e.g. 32768. If your map is very large, it is conceivable that you will still see
some far clipping behaviour.

*Invert mouse vertical axis*:: Enable this option to flip the sense of the
 vertical camera motion when freelook mode is enabled, so that moving the mouse
 upwards tilts the camera downwards, and vice versa.

*Solid selection boxes*:: This option controls whether selected brushes are
 drawn with a dashed outline (option disabled) or a solid line (option enabled).
 It affects both the 2D and the 3D views.

*Show camera toolbar*:: Uncheck this to completely hide the toolbar at the top
 of the 3D camera window (which includes the render mode buttons and the far
 clip plane controls).

==== Orthoview settings

The *Orthoview* page contains options controlling the display and behaviour of
the 2D views.

*View chases mouse cursor during drags*:: If this is enabled, dragging an object
 off the edge of a 2D view will cause the 2D view to automatically scroll to
 keep the dragged object in view. If disabled, the dragged object will reach the
 edge and stop. You can control the speed of the scrolling with the *Maximum
 Chase Mouse Speed* slider.

*Update views on camera movement*:: This option controls whether the camera
 position indicator in the 2D views is automatically kept in sync with camera
 movements in the 3D window. If this option is disabled, the 2D view camera
 indicator may not move until you explicitly click on or interact with a 2D
 view.

*Show crosshairs*:: Enable this option to display full-window-sized crosshairs
 tracking the mouse cursor whenever it moves over a 2D window. This may assist
 with precise selection or object alignment.

*Show grid*:: Control the visibility of grid lines in the 2D views. This does
 not affect the snapping behaviour, just the visual rendering of the grid.

*Show size info*:: Control the visibility of the text overlays which show the
 dimensions of a selected object on the X, Y or Z axes. This option is also
 available in the `View -> Show` menu.

*Show entity angle arrow*:: Hide or show the small arrow which indicates the
 direction of an entity with an `angle` spawnarg, such as `info_player_start`.
 This affects both the 2D and 3D views.

*Show entity names*:: Enable this to show permanently-visible text names next to
 each entity in the map. This option is also available as `View -> Show -> Show
 names`.

*Show blocks*:: If enabled, the world space is divided into a horizontal grid of
 1024x1024 unit blocks (of infinite height) which are outlined in blue in the 2D
 views. Each block is assigned a pair of numbers representing its position from
 the centermost block, which is assigned `(0, 0)`. This might help with
 "blocking out" a map at the beginning of the design phase. This option is also
 available in the `View -> Show` menu.

*Show coordinates*:: Toggle the visibility of the coordinate rulers along the
 edges of the 2D window. Also available in the `View -> Show` menu.

*Show axes*:: Control the visibility of the axis widget displayed at the
 top-left of each 2D window and at the world origin. Also available in the `View
 -> Show` menu.

*Show window outline*:: Enable this to draw a rectangular outline around the
 edge of the 2D window. Depending on the platform and GUI theme this may be
 almost invisible, but might be useful to improve visibility in certain
 environments.

*Show workzone*:: The 'workzone' is an imaginary axis-aligned cuboid which
 encloses the set of currently-selected items (this is what defines the volume
 of a new light, when a <<CreatingLights,light is created>> from one or more
 existing brushes). Enabling this option causes the workzone to be outlined in
 red in the 2D views. Also available in the `View -> Show` menu.

*Translate manipulator always constrained to axis*:: This option affects the
 behaviour of the <<ManipulatorModes,translate manipulator>>. When the option is
 disabled, dragging a selected object in translation mode will behave as if the
 manipulator's *central square* is being dragged, and allow motion in two
 dimensions. If the option is enabled, dragging the selected object will behave
 as if the closest manipulator *arrow* is being dragged, and allow motion along
 only a single axis. Translation in two dimensions will always be possible by
 clicking on the manipulator's central square directly, regardless of the state
 of this option.

*Higher selection priority for entities*:: When using the mouse to click on and
 select an entity which is in front of, behind or inside a brush, this option
 controls whether DarkRadiant will prefer to select the entity (enabled) or the
 brush (disabled).

==== Multi Monitor settings

The Multi Monitor page contains a single setting, *Start DarkRadiant on
monitor*, which allows you to choose which monitor DarkRadiant will start on if
you have several available.

==== Autosave settings

*Enable Autosave*:: Controls whether the autosave feature is active or disabled.

*Autosave Interval*:: Use this slider to choose how often DarkRadiant will make
 an autosave. By default, autosaves are made every 5 minutes.

*Save Snapshots*:: If this option is enabled, DarkRadiant will make each
 autosave into a separate copy of the map file, allowing you to potentially
 revert changes which were made several autosaves ago. If this option is
 disabled, there will only ever be a single autosave file, which will protect
 against DarkRadiant or system crashes but not against long-term erroneous
 changes.

*Snapshot folder*:: This specifies the name of the folder used to store snapshot
 autosaves, if the *Save Snapshots* option is enabled.

*Max Snapshot size per map*:: This allows you to control the amount of disk
 space used for storing snapshots, by specifying a maximum number of megabytes
 that will be used for storing the snapshots for a single map. If the disk usage
 grows above this limit, DarkRadiant will start to delete old snapshots.

==== Clipper settings

*Clipper tool uses caulk texture*:: If this option is enabled, the
 <<SplittingBrushes,clipper tool>> will texture the newly-created clip face with
 the texture specified in the *Caulk shader name* text field. If the option is
 disabled, the new face will be given the same texture as the rest of the brush.

==== Grid settings

This page contains a couple of options relating to the appearance and default
behaviour of the grid.

*Default grid size*:: Use this combo box to choose the default grid size used in
 new projects (to change the grid size in the _current_ project, use the options
 in the *Grid* main menu).

*Major grid style*:: Choose the rendering style for the major grid lines.
 Available options are *Lines*, *Dotted Lines*, *More Dotted Lines*, *Crosses*,
 *Dots*, *Big Dots*, and *Squares*.

*Minor grid style*:: Choose the rendering style for the minor grid lines.
 Available options are the same as the *Major grid style* combo box.

==== Selection settings

*Ignore light volume bounds when calculating default rotation pivot location*::
 This option affects the behaviour of the <<ManipulatorModes,rotation tool>>
 when multiple objects are selected. DarkRadiant will place the rotation widget
 at the approximate "center of gravity" of the set of selected objects. If this
 option is enabled, any selected lights will be treated as point entities, with
 no volume in 3D space regardless of their actual light volumes. If this option
 is disabled, the entire light volume will be taken into account as if the light
 were a rectangular brush.

==== Undo settings

*Undo Queue Size*:: Use this spinbox to control the number of operations which
 are saved onto DarkRadiant's internal undo stack. Larger values provide a
 longer history of undoable operations, at the expense of requiring more memory.

==== Primitives settings

This page contains two options controlling the default behaviour of applied
textures. These values can be set on a per-object basis using the
<<SurfaceInspector,Surface Inspector>>.

*Default texture scale*:: Set a default scale factor for newly applied textures.

*Enable texture lock*:: Set the default value of the Texture Lock button. See
 the <<SurfaceInspector,Surface Inspector>> section for more details on this
 feature.

==== Texture Browser settings

These options control the behaviour of the <<TexturesTab,Textures tab>>.

*Uniform texture thumbnail size*:: Choose the size in pixels that will be used
 for texture thumbnails.

*Texture scrollbar*:: Hide or show the scrollbar in the textures tab. If the
 scrollbar is hidden, scrolling is only possible with the mouse wheel.

*Mousewheel increment*:: This option determines how much the window is scrolled
 when the mouse wheel is rotated.

*Max shadername length*:: Choose the maximum number of characters that may
 appear in each texture name. If a texture contains more characters than this,
 the texture name will be abbreviated with "..." in the middle.

==== Map files settings

*Number of most recently used files*:: Choose the number of map files to list in
 the recent map section at the bottom of the *File* menu.

*Open last map on startup*:: Enable this option to make DarkRadiant
 automatically load the most recently-used map every time it starts, rather than
 starting with an empty map.

== Features for game distributors

DarkRadiant is designed to work out of the box with a standard Doom 3 or Dark
Mod game installation, however it also offers a few features aimed at developers
of the game itself.

=== Controlling asset visibility

As the development of a game progresses, certain models or textures may become
obsolete or deprecated, either because they are no longer needed or because they
fall short of the quality standard that is expected of new assets. If these
models and textures have already been distributed, removing them from the game
installation may be problematic, as maps which depend on them will fail to load
correctly.

DarkRadiant offers a mechanism to deal with this by allowing certain assets to
be marked as "hidden". A hidden asset will no longer be presented for selection
by the user (e.g. on the Media tab or in the Model selector), but will continue
to function as normal when it appears in a loaded map.

==== Creating an assets.lst file

To change the visibility of assets, you need to create a file called
`assets.lst` which resides in the top-level `models` or `materials` directories
in the mod installation. This file may be inside a PK4 or in an extracted
directory tree.

The contents of `assets.lst` are a simple list of key/value pairs, assigning a
visibility value to each named asset. For example:

.assets.lst
----
darkmod/chairs/some_broken_chair.lwo=hidden
darkmod/tables/another_table.ase=hidden
----

Asset paths listed on the left-hand side are interpreted relative to the
directory containing `assets.lst` (which must be `models` or `materials`). The
visibility value on the right-hand side must be either `hidden` or `normal`; a
value of `normal` is equivalent to not listing the file at all, and results in
no change to its visibility.

NOTE: Only *files* may be listed in an `assets.lst`, not items in a virtual
hierarchy such as the material shader tree. When an MTR file is listed as hidden
in the `materials` directory, all shaders contained within it will be hidden in
DarkRadiant. This means that in order to hide specific shaders, you must move
these into one or more MTR files which are listed as hidden.
