Merge pull request #57 from mpewsey/update-docs

Update docs impacted by refactor

Assets/Scripts/Runtime/LayoutTileMapBookSample.cs

@@ -48,7 +48,7 @@ private void Awake()
 
         private void OnSliderValueChanged(float value)
         {
-            Map.SetOnionMapColors(value, Gradient);
+            Map.SetOnionskinColors(value, Gradient);
             ZLabel.text = value.ToString("0.00");
         }
 

Docs/Doxyfile

@@ -874,9 +874,9 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../Packages/ManiaMap.Unity/Scripts \
-                         ../Scripts \
-                         ../README.md
+INPUT                  = ../Packages/ManiaMap.Unity/Scripts/Runtime \
+                         ../README.md \
+                         pages/layout-generation-instructions.md
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses

Docs/pages/layout-generation-instructions.md

@@ -0,0 +1,97 @@
+# Generating a Layout
+
+The following subsections outline how to procedurally generate an arrangement of rooms, called a `Layout`.
+
+## Step 1: Create Rooms and Room Templates
+
+The procedural generator creates layouts by pulling from user-defined room templates. To the generator, a room is a collection of cells in a grid, with information, such as the available door connections, assigned to them.
+
+### Creating a Room
+
+1. In the Unity scene heirarchy, right-click then select `Mania Map > Room`.
+2. In the inspector, specify the room's type, whether you intend to work with 2D or 3D physics.
+3. Specify the number of cell rows and columns, along with the cell size to create the bounding shape of the room.
+4. When the room node is selected, a toolbar will appear in the Godot main window (Circled in red in the screenshot below). The options on this toolbar may be used to edit the cell activities to further define the shape of the room. For instance, selecting the toggle edit mode button, then clicking or dragging over cells in the view will toggle the targeted cells on or off.
+5. Save the room as a prefab.
+
+In the below screenshot, the cells for an angle shaped room have been created, with the active cells shown in blue and inactive cells shown in red and crossed-out. The active cells are the regions where we intend to build our scene.
+
+![Screenshot 2024-06-14 182659](https://github.com/mpewsey/ManiaMap.Unity/assets/23442063/f4248cb5-54f0-4db3-8b66-955a54efe5b6)
+
+### Creating Doors
+
+Doors define the locations where two rooms can be connected. At least one door must be added to a room.
+
+1. Right-click on the room in the scene heirarchy and select `Mania Map > Door`. To save time, you may wish to save your doors as prefabs with any related components, such as sprites or collision. These prefabs can then be referenced in your room prefab.
+2. Position the door within the room and assign its direction and connection constraints.
+4. To auto assign the closest cell and direction to the door, make sure the applicable flags are selected in the inspector and click the `Auto Assign` button on the room toolbar. The assigned door direction will be based on its location relative to the center of its assigned cell.
+
+Additional room child nodes such as `CollectableSpotComponent`, `Feature`, and `RoomFlag` can also be added to the room if you wish them to be included.
+
+The below screenshot shows a square 3x3 room with doors around its entire perimeter. Each of the door direction (north, west, east, and south) use a different prefab since the tiles depicting the doors are different for each.
+
+![Screenshot 2024-06-14 184508](https://github.com/mpewsey/ManiaMap.Unity/assets/23442063/7cd8e3dc-7723-4d7d-bfbf-37eb6d1b210e)
+
+### Exporting Room Templates
+
+The procedural generator uses one or more `RoomTemplateResource` exported from a room to generate layouts.
+
+1. With at least one room saved as a prefab in your project, from the top toolbar, select `Mania Map > Batch Update Room Templates`.
+2. This operation will perform auto assignment on all room prefabs throughout the project and save `RoomTemplateResource` Scriptable Objects with the `.room_template.asset` extension to the prefab paths.
+
+## Step 2: Create Room Template Groups
+
+One or more `TemplateGroup` are used by the procedural generator to determine which rooms can be assigned to a given position in a layout.
+
+1. To create a template group, right-click in the Unity project explorer and select `Create > Mania Map > Template Group`.
+2. Click on the newly created template group and, in the inspector, assign a unique name to the group.
+3. Drag and drop one or more `RoomTemplateResource` into the rectangular region to add them to the group.
+
+> **Note:** Locking the inspector and searching `t:RoomTemplateResource` in the project explorer can make adding room templates to a group easier.
+
+## Step 3: Create a Layout Graph
+
+The procedural generator uses a `LayoutGraphResource` as a base for generating layouts. This allows you to design high level relationships between rooms while still making the resulting layout appear random.
+
+1. To create a layout graph, right-click in the Unity project explorer and select `Create > Mania Map > Layout Graph`.
+2. Double click on the created object to open the graph editor window.
+3. In the graph editor window, right click in an open area, then select `Create Node` to add a node to the graph. Each node will serve as a room location.
+4. To add edges, serving as connections between rooms, to the graph, right-click on the starting node and select `Add Edge`, then click on a second node to make the connection.
+5. Selecting nodes and/or edges will allow you to edit their properties in the inspector. Each node must have a `TemplateGroup` assigned; though it is optional of edges.
+
+![Screenshot 2024-06-14 191811](https://github.com/mpewsey/ManiaMap.Unity/assets/23442063/b3b44803-7173-4a48-af0b-05d034b6b2e7)
+
+## Step 4: Create a Generation Pipeline
+
+The `GenerationPipeline` takes various inputs and feeds them through a series of operational steps to generate one or more outputs. In the context of this package, the output is most notably a room `Layout`.
+
+1. To create a pipeline, right-click in the scene heirarchy and select `Mania Map > Generation Pipeline`. A pipeline with the default inputs and steps will be created.
+2. On the `Inputs` Game Object, add one or more `LayoutGraphResource` to the `LayoutGraphsInput` component.
+3. Optionally, add one or more `CollectableGroup` to the `CollectableGroupsInput` component.
+4. Create a script that references the `GenerationPipeline` you wish to run, and call the `Run`, `RunAsync`, or `RunAttemptsAsync` methods to generate a layout. For example:
+
+```ExampleGenerationPipelineRunner.cs
+using MPewsey.ManiaMap;
+using MPewsey.ManiaMapGodot.Generators;
+
+public class ExampleGenerationPipelineRunner : MonoBehaviour
+{
+    [SerializeField] public GenerationPipeline _pipeline;
+
+    public void RunPipeline()
+    {
+        var results = _pipeline.Run();
+        var layout = results.GetOutput<Layout>("Layout");
+
+        // At this point, you will probably want to do something with the layout...
+        //
+        // * You could save it to file using the JsonSerialization or XmlSerialization static classes.
+        // * You could use a RoomDatabase or RoomTemplateGroupDatabase to instantiate the rooms in the layout.
+        // * You could use it with the LayoutTileMap or LayoutTileMapBook components to generate maps.
+        //
+        // See the project samples for example implementations.
+    }
+}
+```
+
+> **Note:** Depending on your room templates and layout graph, it may not be possible to generate a layout for all (if any) random seeds. If you are encountering issues with successfully generating a layout, you may need to reconsider the constraints imposed on its generation. For example, you may need to add more doors to ensure that your rooms have a better chance of connecting. Even then, you may still encounter some isolated failures, in which case the generation pipeline `RunAttemptsAsync` method can help by automatically falling back to other seeds.

Packages/ManiaMap.Unity/Scripts/Editor/BatchUpdaterTool.cs

@@ -12,6 +12,9 @@ public class BatchUpdaterTool : ScriptableObject
     {
         [SerializeField]
         private string[] _searchPaths = new string[] { "Assets" };
+        /// <summary>
+        /// An array of project paths to search for room prefabs.
+        /// </summary>
         public string[] SearchPaths { get => _searchPaths; set => _searchPaths = value; }
 
         [MenuItem("Mania Map/Batch Update Room Templates", priority = 0)]
@@ -20,6 +23,10 @@ public static void RunBatchUpdateRoomTemplates()
             LoadSettings().BatchUpdateRoomTemplates();
         }
 
+        /// <summary>
+        /// Returns the batch updater tool at ManiaMap/BatchUpdaterTool within a Resources folder if it exists.
+        /// If it does not exist, returns a new default instance.
+        /// </summary>
         private static BatchUpdaterTool LoadSettings()
         {
             var settings = Resources.Load<BatchUpdaterTool>("ManiaMap/BatchUpdaterTool");
@@ -30,6 +37,9 @@ private static BatchUpdaterTool LoadSettings()
             return CreateInstance<BatchUpdaterTool>();
         }
 
+        /// <summary>
+        /// Performs batch update for all discovered rooms.
+        /// </summary>
         public void BatchUpdateRoomTemplates()
         {
             var count = 0;
@@ -45,6 +55,10 @@ public void BatchUpdateRoomTemplates()
             Debug.Log($"<color=#00FF00><b>Completed room template batch update on {count} rooms.</b></color>");
         }
 
+        /// <summary>
+        /// Performs auto assignment on the specified room.
+        /// </summary>
+        /// <param name="room">The room.</param>
         public static void AutoAssign(RoomComponent room)
         {
             var count = room.AutoAssign();
@@ -60,6 +74,12 @@ public static void AutoAssign(RoomComponent room)
             Debug.Log($"<color=#00FF00><b>Auto assigned {count} cell children.</b></color>");
         }
 
+        /// <summary>
+        /// Updates or creates the room template for the room at the specified GUID.
+        /// If the object at the GUID does not contain a RoomComponent at its root, skips it and returns false.
+        /// Returns true when successful.
+        /// </summary>
+        /// <param name="roomGuid">The room GUID.</param>
         private bool UpdateRoomTemplate(string roomGuid)
         {
             var roomPath = AssetDatabase.GUIDToAssetPath(roomGuid);

Packages/ManiaMap.Unity/Scripts/Editor/BatchUpdaterToolEditor.cs

@@ -4,14 +4,11 @@
 namespace MPewsey.ManiaMapUnity.Editor
 {
     /// <summary>
-    /// The TemplateSaveSettings editor.
+    /// The BatchUpdaterTool editor.
     /// </summary>
     [CustomEditor(typeof(BatchUpdaterTool))]
     public class BatchUpdaterToolEditor : UnityEditor.Editor
     {
-        /// <summary>
-        /// If a ManiaMap/BatchUpdaterTool resource does not already exist, creates it.
-        /// </summary>
         [MenuItem("Mania Map/Create Batch Updater Tool Settings", priority = 0)]
         public static void CreateBatchUpdaterToolSettings()
         {

Packages/ManiaMap.Unity/Scripts/Editor/CellChildEditor.cs

@@ -3,7 +3,7 @@
 namespace MPewsey.ManiaMapUnity.Editor
 {
     /// <summary>
-    /// The CollectableSpot editor.
+    /// The CellChild editor.
     /// </summary>
     [CanEditMultipleObjects]
     [CustomEditor(typeof(CellChild))]

Packages/ManiaMap.Unity/Scripts/Editor/CollectableGroupEditor.cs

@@ -17,9 +17,6 @@ public override void OnInspectorGUI()
             serializedObject.ApplyModifiedProperties();
         }
 
-        /// <summary>
-        /// Draws the drag and drop area and evaluates user input within the area.
-        /// </summary>
         private void DrawDragAndDropArea()
         {
             var rect = GUILayoutUtility.GetRect(0, 50, GUILayout.ExpandWidth(true));
@@ -42,9 +39,6 @@ private void DrawDragAndDropArea()
             }
         }
 
-        /// <summary>
-        /// Adds any dragged and dropped templates to the group.
-        /// </summary>
         private void AddDragAndDropTemplates()
         {
             var group = (CollectableGroup)serializedObject.targetObject;

Packages/ManiaMap.Unity/Scripts/Editor/CollectableGroupEntryDrawer.cs

@@ -4,19 +4,12 @@
 namespace MPewsey.ManiaMapUnity.Editor
 {
     /// <summary>
-    /// The CollectableGroupEntry custom property drawer.
+    /// The CollectableGroupEntry custom property drawer. The drawer is drawn without the typical dropdown.
     /// </summary>
     [CustomPropertyDrawer(typeof(CollectableGroupEntry))]
     public class CollectableGroupEntryDrawer : PropertyDrawer
     {
-        /// <summary>
-        /// The spacing between properties.
-        /// </summary>
         private const float Spacing = 2;
-
-        /// <summary>
-        /// The top and bottom padding.
-        /// </summary>
         private const float Padding = 4;
 
         public override void OnGUI(Rect position, SerializedProperty property, GUIContent label)

Packages/ManiaMap.Unity/Scripts/Editor/CollectableSpotComponentEditor.cs

@@ -10,9 +10,6 @@ namespace MPewsey.ManiaMapUnity.Editor
     [CustomEditor(typeof(CollectableSpotComponent))]
     public class CollectableSpotComponentEditor : CellChildEditor
     {
-        /// <summary>
-        /// Creates a new collectable spot Game Object.
-        /// </summary>
         [MenuItem("GameObject/Mania Map/Collectable Spot", priority = 20)]
         [MenuItem("Mania Map/Create Collectable Spot", priority = 100)]
         public static void CreateCollectableSpot()

Packages/ManiaMap.Unity/Scripts/Editor/DoorComponentEditor.cs

@@ -4,15 +4,12 @@
 namespace MPewsey.ManiaMapUnity.Editor
 {
     /// <summary>
-    /// The Door editor.
+    /// The DoorComponent editor.
     /// </summary>
     [CanEditMultipleObjects]
     [CustomEditor(typeof(DoorComponent))]
     public class DoorComponentEditor : CellChildEditor
     {
-        /// <summary>
-        /// Creates a new door Game Object.
-        /// </summary>
         [MenuItem("GameObject/Mania Map/Door", priority = 20)]
         [MenuItem("Mania Map/Create Door", priority = 100)]
         public static void CreateDoor()

Packages/ManiaMap.Unity/Scripts/Editor/FeatureEditor.cs

@@ -10,9 +10,6 @@ namespace MPewsey.ManiaMapUnity.Editor
     [CustomEditor(typeof(Feature))]
     public class FeatureEditor : CellChildEditor
     {
-        /// <summary>
-        /// Creates a new collectable spot Game Object.
-        /// </summary>
         [MenuItem("GameObject/Mania Map/Feature", priority = 20)]
         [MenuItem("Mania Map/Create Feature", priority = 100)]
         public static void CreateFeature()

Packages/ManiaMap.Unity/Scripts/Editor/FileUtility.cs

@@ -5,6 +5,9 @@
 
 namespace MPewsey.ManiaMapUnity.Editor
 {
+    /// <summary>
+    /// Contains methods for interacting with files within Unity.
+    /// </summary>
     public static class FileUtility
     {
         /// <summary>

Packages/ManiaMap.Unity/Scripts/Editor/Graphs/LayoutGraphEdgeEditor.cs

@@ -4,7 +4,7 @@
 namespace MPewsey.ManiaMapUnity.Graphs.Editor
 {
     /// <summary>
-    /// The LayoutEdge editor.
+    /// The LayoutGraphEdge editor.
     /// </summary>
     [CanEditMultipleObjects]
     [CustomEditor(typeof(LayoutGraphEdge))]

Packages/ManiaMap.Unity/Scripts/Editor/Graphs/LayoutGraphNodeEditor.cs

@@ -4,7 +4,7 @@
 namespace MPewsey.ManiaMapUnity.Graphs.Editor
 {
     /// <summary>
-    /// The LayoutNode editor.
+    /// The LayoutGraphNode editor.
     /// </summary>
     [CanEditMultipleObjects]
     [CustomEditor(typeof(LayoutGraphNode))]

Packages/ManiaMap.Unity/Scripts/Editor/Graphs/LayoutGraphResourceEditor.cs

@@ -7,14 +7,11 @@
 namespace MPewsey.ManiaMapUnity.Graphs.Editor
 {
     /// <summary>
-    /// The LayoutGraph custom inspector.
+    /// The LayoutGraphResource editor.
     /// </summary>
     [CustomEditor(typeof(LayoutGraphResource))]
     public class LayoutGraphResourceEditor : UnityEditor.Editor
     {
-        /// <summary>
-        /// Shows the layout graph editor window.
-        /// </summary>
         [UnityEditor.Callbacks.OnOpenAsset]
         public static bool OnOpenAsset(int instanceId, int line)
         {

Packages/ManiaMap.Unity/Scripts/Editor/Graphs/LayoutGraphWindow.cs

@@ -7,7 +7,7 @@
 namespace MPewsey.ManiaMapUnity.Graphs.Editor
 {
     /// <summary>
-    /// A window for viewing and editing a LayoutGraph.
+    /// A window for viewing and editing a LayoutGraphResource.
     /// </summary>
     public class LayoutGraphWindow : EditorWindow
     {

Packages/ManiaMap.Unity/Scripts/Editor/Graphs/LayoutGraphWindowEditor.cs

@@ -4,7 +4,7 @@
 namespace MPewsey.ManiaMapUnity.Graphs.Editor
 {
     /// <summary>
-    /// The LayoutGraph window editor.
+    /// The LayoutGraphWindow editor.
     /// </summary>
     public class LayoutGraphWindowEditor : UnityEditor.Editor
     {

Packages/ManiaMap.Unity/Scripts/Editor/ManiaMapSettingsEditor.cs

@@ -9,9 +9,6 @@ namespace MPewsey.ManiaMapUnity.Editor
     [CustomEditor(typeof(ManiaMapSettings))]
     public class ManiaMapSettingsEditor : UnityEditor.Editor
     {
-        /// <summary>
-        /// If a ManiaMap/ManiaMapSettings resource does not already exist, creates it.
-        /// </summary>
         [MenuItem("Mania Map/Create Mania Map Settings", priority = 100000)]
         public static void CreateManiaMapSettings()
         {

Packages/ManiaMap.Unity/Scripts/Editor/RoomComponentEditor.cs

@@ -4,15 +4,12 @@
 namespace MPewsey.ManiaMapUnity.Editor
 {
     /// <summary>
-    /// The Room editor.
+    /// The RoomComponent editor.
     /// </summary>
     [CanEditMultipleObjects]
     [CustomEditor(typeof(RoomComponent))]
     public class RoomComponentEditor : UnityEditor.Editor
     {
-        /// <summary>
-        /// Creates a Game Object with the Room component.
-        /// </summary>
         [MenuItem("GameObject/Mania Map/Room", priority = 20)]
         [MenuItem("Mania Map/Create Room", priority = 100)]
         public static void CreateRoomTemplate()

Packages/ManiaMap.Unity/Scripts/Editor/RoomComponentToolbar.cs

@@ -3,6 +3,9 @@
 
 namespace MPewsey.ManiaMapUnity.Editor
 {
+    /// <summary>
+    /// The toolbar for editing RoomComponent in the Unity scene view.
+    /// </summary>
     [InitializeOnLoad]
     public class RoomComponentToolbar : UnityEditor.Editor
     {

Packages/ManiaMap.Unity/Scripts/Editor/RoomFlagEditor.cs

@@ -4,15 +4,12 @@
 namespace MPewsey.ManiaMapUnity.Editor
 {
     /// <summary>
-    /// The Feature editor.
+    /// The RoomFlag editor.
     /// </summary>
     [CanEditMultipleObjects]
     [CustomEditor(typeof(RoomFlag))]
     public class RoomFlagEditor : CellChildEditor
     {
-        /// <summary>
-        /// Creates a new room flag Game Object.
-        /// </summary>
         [MenuItem("GameObject/Mania Map/Room Flag", priority = 20)]
         [MenuItem("Mania Map/Create Room Flag", priority = 100)]
         public static void CreateRoomFlag()