Merge pull request #179 from Maaack/update-docs

Update docs

README.md

@@ -153,6 +153,7 @@ These instructions assume starting with just the contents of `addons/`. This wil
 
 ### More Documentation
 
+[Main Menu Setup](/addons/maaacks_game_template/docs/MainMenuSetup.md)  
 [Game Scene Setup](/addons/maaacks_game_template/docs/GameSceneSetup.md)  
 
 ## Links

addons/maaacks_game_template/README.md

@@ -153,6 +153,7 @@ These instructions assume starting with just the contents of `addons/`. This wil
 
 ### More Documentation
 
+[Main Menu Setup](/addons/maaacks_game_template/docs/MainMenuSetup.md)  
 [Game Scene Setup](/addons/maaacks_game_template/docs/GameSceneSetup.md)  
 
 ## Links

addons/maaacks_game_template/docs/ExistingProject.md

@@ -3,15 +3,7 @@
 These instructions assume starting with just the contents of `addons/`. This will be the case when installing the *plugin* version in the Godot Asset Library.
 
 
-1.  Update the project’s main scene (if skipped during plugin install).
-
-
-    1.  Go to `Project > Project Settings… > General > Application > Run`.
-    2.  Update `Main Scene` to `opening_with_logo.tscn`, or skip openings and go straight to `main_menu_with_animations.tscn`. (These are the default scenes used, but other options are available.)
-    3.  Close the window.
-
-
-2.  Update the project’s name in the main menu.
+1.  Update the project’s name in the main menu.
 
 
     1.  Open `main_menu_with_animations.tscn`.
@@ -22,7 +14,7 @@ These instructions assume starting with just the contents of `addons/`. This wil
     6.  Save the scene.
 
 
-3.  Link the main menu to the game scene.
+2.  Link the main menu to the game scene.
 
 
     1.  Open `main_menu_with_animations.tscn`.
@@ -31,7 +23,7 @@ These instructions assume starting with just the contents of `addons/`. This wil
     4.  Save the scene.
 
 
-4.  Add background music and sound effects to the UI.
+3.  Add background music and sound effects to the UI.
 
     1.  Add `Music` and `SFX` to the project's default audio busses.
 
@@ -46,8 +38,9 @@ These instructions assume starting with just the contents of `addons/`. This wil
         2.  Open `main_menu_with_animations.tscn`.
         3.  Select the `BackgroundMusicPlayer` node.
         4.  Assign the music asset to the `stream` property.
-        5.  Save the scene.
-        6.  Optionally, repeat steps 3-5 for background music nodes in:
+        5.  Make sure that the `bus` property is set to `Music`.
+        6.  Save the scene.
+        7.  Optionally, repeat steps 3-5 for background music nodes in:
             1.  `opening_with_logo.tscn`
             2.  `game_ui.tscn`
             3.  `end_credits.tscn`
@@ -73,7 +66,7 @@ These instructions assume starting with just the contents of `addons/`. This wil
             4.  Save the scene.  
 
 
-5.  Add readable names for input actions to the controls menu.
+4.  Add readable names for input actions to the controls menu.
 
 
     1.  Open `input_options_menu.tscn` (or `master_options_menu_with_tabs.tscn`, which contains an instance of the scene).
@@ -82,7 +75,7 @@ These instructions assume starting with just the contents of `addons/`. This wil
     4.  Save the scene.  
 
 
-6.  Add / remove configurable settings to / from menus.
+5.  Add / remove configurable settings to / from menus.
 
 
     1.  Open `mini_options_menu.tscn` or `[audio|visual|input|game]_options_menu.tscn` scenes to edit their options.
@@ -105,7 +98,7 @@ These instructions assume starting with just the contents of `addons/`. This wil
         3.  `config.cfg` should be in the top directory of the project.
 
 
-7.  Update the game credits / attribution.
+6.  Update the game credits / attribution.
 
 
     1.  Update the example `ATTRIBUTION.md` with the project's credits.
@@ -114,4 +107,7 @@ These instructions assume starting with just the contents of `addons/`. This wil
     4.  Save the scene.
 
 
-8.  Continue by [Setting Up a Game Scene](/addons/maaacks_game_template/docs/GameSceneSetup.md).  
+7.  Continue with:
+
+    1.  [Setting up the Main Menu.](/addons/maaacks_game_template/docs/MainMenuSetup.md)  
+    2.  [Setting up a Game Scene.](/addons/maaacks_game_template/docs/GameSceneSetup.md)  

addons/maaacks_game_template/docs/GameSceneSetup.md

@@ -10,23 +10,21 @@ The `pause_menu_controller.gd` script may be attached to a node in the scene tre
 This should be enough to capture when the `ui-cancel` input action is pressed in-game. On keyboards, this is commonly the `Esc` key.
 
 ## Level Loading
-Some level loading scripts are provided with the examples. They load levels in order from a list, or dynamically by file paths. They must called by a signal from the level or game UI.
+Some level loading scripts are provided with the examples. They load levels in order from a list, or dynamically by file paths. It is called from a `LevelListManager`.
 
 ```
-func _on_level_won():
-	$LevelLoader.advance_and_load_level()
+func _load_next_level():
+	level_list_loader.advance_and_load_level()
 ```
 
 A `LevelLoader` must be provided with a `level_container` in the scene. Levels will get added to and removed from this node. The example uses the `SubViewport`, but any leaf node (ie. node without children) in the scene should work.
 
-An additional loading screen in the scene can show progress of loading levels, but it needs to be toggled by signals from the `LevelLoader`.
+An additional loading screen in the scene can show progress of loading levels, and is toggled by the `LevelListManager`.
 
 ```
 func _on_level_loader_level_load_started():
-	$LoadingScreen.reset()
-
-func _on_level_loader_level_loaded():
-	$LoadingScreen.close()
+	if level_loading_screen:
+		level_loading_screen.reset()
 ```
 
 Level Loading is not required if the entire game takes place in one scene.  
@@ -58,13 +56,24 @@ If the game involves moving a player character, then the inputs for movements co
 If the game involves sending commands to multiple units, then those inputs probably should be read by a `game_ui.gd` script, that then propagates those calls further down the chain.  
 
 ## Win & Lose Screens
-The example includes win and lose screens. These can be triggered by events in the levels, or by running out of levels to load.
+The example includes win and lose screens. These are triggered by the `LevelListManager` when a level is won or lost.
 
 ```
-@export var win_scene : PackedScene
-
-func _on_level_loader_levels_finished():
-	InGameMenuController.open_menu(win_scene, get_viewport())
+func _load_level_complete_screen_or_next_level():
+	if level_won_scene:
+		var instance = level_won_scene.instantiate()
+		get_tree().current_scene.add_child(instance)
+		...
+	else:
+		_load_next_level()
 ```
+Winning on the last level results in loading a win screen or ending for the game.
 
-These are not appropriate for every game, but are available if needed. They'll need to be linked to direct back to the main menu, and the winning screen can be linked to direct forward to `end_credits.tscn`.
+```
+func _on_level_won():
+	if level_list_loader.is_on_last_level():
+		_load_win_screen_or_ending()
+	else:
+		_load_level_complete_screen_or_next_level()
+```
+ The `LevelListManager` will need to be linked to direct back to the main menu and forward to `end_credits.tscn`.

addons/maaacks_game_template/docs/MainMenuSetup.md

@@ -0,0 +1,28 @@
+# Main Menu Setup
+
+These are instructions for further editing the menus. Basic instructions are available in the [README](/addons/maaacks_game_template/README.md#usage).
+
+## Inheritance
+
+Most example scenes in the template inherit from scenes in `addons`. This is useful for developing of the plugin, but often less useful for those using it.  When editing the example scenes, any nodes inherited from a parent scene are highlighted in yellow in the scene tree. Inherited nodes cannot be edited like native nodes. Therefore, it is recommended to first right-click on the root node, and select `Clear Inheritance`. You'll get a warning that this cannot be undone, but it's okay. You probably won't need to undo it, and if you do, there are solutions.
+
+## Visual Placement
+
+The positions and anchor presets of the UI elements can be adjusted to match most designs with ease. Buttons can be centered, right or left justfied, or arranged horizontally. Most visual UI elements are contained within `MarginContainer` and `Control` nodes that allow for fine-tuning of placement.
+
+## Scene Structure
+Some designs may require rearranging the nodes in the scene tree. This is easier once the inheritance to the parent scene is cleared. However, if editing `main_menu_with_animations.tscn`, keep in mind that there are animations, and moving elements outside of the animated containers may have undesired effects.
+
+## 3D Background 
+When adding a 3D background to the menu, it is recommended to use a `SubViewportContainer` in place of or right above the `BackgroundTextureRect`. Then add a `SubViewport` to it, and finally the 3D world node to that. This structure gives fine-tune control of scaling, allows for layering 3D views when they have transparency, and makes it easy to add a texture shader to the whole background.
+
+## Theming
+It is recommended to create a theme resource file and set it as the custom theme in the project settings. Any changes made to the theme file will then apply automatically to the whole project.
+
+The main UI elements that are used throughout the project that require theming for customization are:
+- Button
+- Label
+- PanelContainer
+- ProgressBar
+- TabContainer
+- Tree

addons/maaacks_game_template/docs/NewProject.md

@@ -40,8 +40,9 @@ These instructions assume starting with the entire contents of the project folde
         2.  Open `main_menu_with_animations.tscn`.
         3.  Select the `BackgroundMusicPlayer` node.
         4.  Assign the music asset to the `stream` property.
-        5.  Save the scene.  
-        6.  Optionally, repeat steps 3-5 for background music nodes in:
+        5.  Make sure that the `bus` property is set to `Music`.
+        6.  Save the scene.
+        7.  Optionally, repeat steps 3-5 for background music nodes in:
             1.  `opening_with_logo.tscn`
             2.  `game_ui.tscn`
             3.  `end_credits.tscn`
@@ -115,4 +116,7 @@ These instructions assume starting with the entire contents of the project folde
 8.  Optionally, if using Git for version control, update `.gitignore` to include `addons/`.  
 
 
-9.  Continue by [Setting Up a Game Scene](/addons/maaacks_game_template/docs/GameSceneSetup.md).  
+9.  Continue with:
+
+    1.  [Setting up the Main Menu](/addons/maaacks_game_template/docs/MainMenuSetup.md).  
+    2.  [Setting up a Game Scene](/addons/maaacks_game_template/docs/GameSceneSetup.md).