Merge remote-tracking branch 'remotes/orbweaver/master'

debian/changelog

@@ -1,3 +1,9 @@
+darkradiant (2.7.0) bionic; urgency=medium
+
+  * 2.7.0 release for Bionic.
+
+ -- Matthew Mott <orbweaver3d@gmail.com>  Tue, 14 Jan 2020 21:37:34 +0000
+
 darkradiant (2.6.0) bionic; urgency=medium
 
   * 2.6.0 release for Bionic.

debian/compat

@@ -1 +1 @@
-5
+9

debian/docs

@@ -1 +1 @@
-README
+README.md

debian/rules

@@ -20,6 +20,10 @@ ifeq (,$(findstring nostrip,$(DEB_BUILD_OPTIONS)))
     INSTALL_TARGET=install
 endif
 
+configure:
+	dh_testdir
+	./autogen.sh
+
 config.status: configure
 	dh_testdir
 	./configure --prefix=/usr --mandir=\$${prefix}/share/man --infodir=\$${prefix}/share/info --enable-darkmod-plugins

doc/manual.adoc

@@ -80,14 +80,18 @@ brushes and patches.
  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 brush and patch 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.
+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
@@ -985,6 +989,7 @@ 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_.
@@ -1037,6 +1042,72 @@ 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.
 |===
 
+=== 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.
+
+==== 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*.
+
+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 *classname* of `func_static`. You
+can set spawnargs on this entity like any other (including giving it a custom
+name).
+. Selecting any primitive contained by a *func_static* 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.
+
+==== Selecting individual child primitives
+
+As mentioned in the previous section, selecting any primitive which comprises
+part of a *func_static* will cause the entire entity and all of its child
+primitives to be selected together. 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`.
+
 === Compiling a map
 
 DarkRadiant does not include functionality for compiling a map into the form
@@ -1084,6 +1155,7 @@ 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
@@ -1110,6 +1182,7 @@ 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
@@ -1131,6 +1204,7 @@ 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*,
@@ -1181,6 +1255,32 @@ Before inserting the prefab, you can use the
 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
@@ -1371,6 +1471,68 @@ 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 consists of a tabbed widget, where each tab contains the
+settings which correspond to a particular difficulty level. The difficulty names
+are shown for the current map — 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.
+
+TIP: For details of more advanced difficulty-dependent changes, such as
+modifying the behaviour of a *single* entity (rather than an entire entity
+class), or changing the names of difficulty settings, consult the Dark Mod Wiki.
+
 == Command reference
 
 === File menu
@@ -1402,6 +1564,78 @@ partially-complete maps.
 *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. 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).
+
+*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*.
+
 == Configuring DarkRadiant
 
 DarkRadiant offers a large number of configurable options which can be used to