minimata/MovementTests
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

gd: added menu template

Browse Source
This commit is contained in:
Alexandre Serex
2025-06-10 18:46:20 +02:00
parent f9a6c42b14
commit c554e24b01
421 changed files with 12371 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
addons/maaacks_game_template/docs/ExistingProject.md Normal file
View File

@ -0,0 +1,116 @@
# Existing Project
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 name in the main menu.
1. Open `main_menu_with_animations.tscn`.
2. Select the `Title` node.
3. Update the `Text` to your project's title.
4. Select the `Subtitle` node.
5. Update the `Text` to a desired subtitle or empty.
6. Save the scene.
2. Link the main menu to the game scene.
1. Open `main_menu_with_animations.tscn`.
2. Select the `MainMenu` node.
3. Update `Game Scene Path` to the path of the project's game scene.
4. Save the scene.
3. Add background music and sound effects to the UI.
1. Add `Music` and `SFX` to the project's default audio busses.
1. Open the Audio bus editor.
2. Click the button "Add Bus" twice (x2).
3. Name the two new busses `Music` and `SFX`.
4. Save the project.
2. Add background music to the Main Menu.
1. Import the music asset into the project.
2. Open `main_menu_with_animations.tscn`.
3. Select the `BackgroundMusicPlayer` node.
4. Assign the music asset to the `stream` property.
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`
3. Add sound effects to UI elements.
1. By scene.
1. Open `main_menu_with_animations.tscn` and `pause_menu.tscn`.
2. Select the `UISoundController` node.
3. Add audio streams to the various UI node events.
4. Save the scenes.
2. Project-wide.
1. Open `project_ui_sound_controller.tscn`.
2. Select the `UISoundController` node.
3. Add audio streams to the various UI node events.
4. Save the scene.
4. Add readable names for input actions to the controls menu.
1. Open `input_options_menu.tscn`.
2. In the scene tree, select the `Controls` node.
3. In the node inspector, select the desired input remapping mode (defaults to `List`).
4. In the scene tree, select `InputActionsList` or `InputActionsTree`, depending on the choice of input remapping. The other node should be hidden.
5. In the node inspector, update the `Input Action Names` and corresponding `Readable Action Names` to show user-friendly names for the project's input actions.
6. Save the scene.
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.
2. If an option is not desired, it can always be hidden, or removed entirely (sometimes with some additional work).
3. If a new option is desired, it can be added without writing code.
1. Find the node that contains the existing list of options. Usually, it's a `VBoxContainer`.
2. Add an `option_control.tscn` node as a child to the container.
1. `slider_option_control.tscn` or `toggle_option_control.tscn` can be used if those types match requirements. In that case, skip step 5.3.6.
2. `list_option_control.tscn` and `vector_2_list_option_control.tscn` are also available, but more complicated. See the `ScreenResolution` example.
3. Select the `OptionControl` node just added, to edit it in the inspector.
4. Add an `Option Name`. This prefills the `Key` string.
5. Select an `Option Section`. This prefills the `Section` string.
6. Add any kind of `Button`, `Slider`, `LineEdit`, or `TextEdit` to the `OptionControl` node.
7. Save the scene.
4. For options to have an effect outside of the menu, it will need to be referenced by its `key` and `section` from `config.gd`.
1. `Config.get_config(section, key, default_value)`
5. Validate the values being stored in your local `config.cfg` file.
1. Refer to [Accessing Persistent User Data User](https://docs.godotengine.org/en/stable/tutorials/io/data_paths.html#accessing-persistent-user-data-user) to find Godot user data on your machine.
2. Find the directory that matches your project's name.
3. `config.cfg` should be in the top directory of the project.
6. Update the game credits / attribution.
1. Update the example `ATTRIBUTION.md` with the project's credits.
2. Open `credits.tscn`.
3. Check the `CreditsLabel` has updated with the text.
4. Save the scene.
7. Continue with:
1. [Setting up the Main Menu.](/addons/maaacks_game_template/docs/MainMenuSetup.md)
2. [Adding icons to the Input Options.](/addons/maaacks_game_template/docs/InputIconMapping.md)
3. [Setting up a Game Scene.](/addons/maaacks_game_template/docs/GameSceneSetup.md)
4. [Utilizing Game Saving](/addons/maaacks_game_template/docs/GameSaving.md)

32
addons/maaacks_game_template/docs/GameSaving.md Normal file
View File

@ -0,0 +1,32 @@
# Game Saving
> [!IMPORTANT]
> The save system doesn't follow the same conventions as other systems.
> It is subject to change.
> [!WARNING]
> The save system relies on resource files, which are vulnerable to having malicious scripts injected into them.
> Please discourage players from sharing their save files. Do not use this for cloud saving, either.
> A safer save system is planned.
The templates and plugin suite aim to keep most class definitions within the addon. These are not usually expected change. Unlike the other classes, the `GameState` and `LevelState` are defined for the developer to edit to their needs.
## Usage
The `GlobalState` static class keeps the state saved to a resource. The developer is responsible for making sure `GlobalState.save()` gets called when they want the state saved to the disk.
### Game State
The `GameState` class represents the state of a single playthrough of the game. It currently stores the current level, the max level reached, and the state of each level currently visited.
It is currently expected to be used as a singleton, too.
### Level State
The `LevelState` class represents the state of a single level in a playthrough of the game. It currently stores whether the tutorial has been read, and a color, if the player has set one in the example levels. It can be used to store the states of many other level specific features.
From within the `_ready()` method of a level scene, call `GameState.get_level_state(scene_file_path)` to get the last saved `LevelState`, or a new one, and then set the state of the level from that. When a state of the level changes that is intended to be preserved, save it into the level state, and call `GlobalState.save()`.
Examples are provided allowing the player to save the level background color, and keeping the tutorial message from popping up more than once per playthrough.

87
addons/maaacks_game_template/docs/GameSceneSetup.md Normal file
View File

@ -0,0 +1,87 @@
# Game Scene Setup
When setting up a game scene, it is useful to refer to the `game_scene/game_ui.tscn` included in the examples.
There are a few parts to setting up a basic game scene, as done in the `GameUI` example used in the template.
## Pausing
The `PauseMenuController` node can be added to the tree, or the `pause_menu_controller.gd` script may be attached to an empty `Node`. Selecting the node should then allow for setting the `pause_menu_packed` value in the inspector. Set it to the `pause_menu.tscn` scene and save.
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. Levels can be added to the `LevelListLoader` by either selecting a directory to automatically read scene files from, or populating the files array manually.
A `LevelListLoader` 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.
The level loader is called from a `LevelListManager` with `advance_and_load_level()`. An additional loading screen in the scene can show progress of loading levels, and is toggled by the `LevelListManager` with `reset()`.
### Games without levels
Level Loading is not required if the entire game takes place in one scene.
In that case, the following nodes can be safely removed:
* LevelListLoader
* LevelLoadingScreen
* LevelListManager
The single level scene can then be added directly to the `SubViewport` or the root node.
## Background Music
`BackgroundMusicPlayer`'s are `AudioStreamPlayer`'s with `autoplay` set to `true` and `audio_bus` set to "Music". These will automatically be recognized by the `ProjectMusicController` with the default settings, and allow for blending between tracks.
A `BackgroundMusicPlayer` can be added to the main game scene, but if using levels, the level scenes are typically a better place for them, as that allows for tracks to vary by level.
## SubViewports
The game example has the levels loaded into a `SubViewport` node, contained within a `SubViewportContainer`. This has a couple of advantages.
- Separates elements intended to appear inside the game world from those intended to appear on a layer above it.
- Allows setting a fixed resolution for the game, like pixel art games.
- Allows setting rendering settings, like anti-aliasing, on the `SubViewport`.
- Supports easily adding visual effects with shaders on the `SubViewportContainer`.
- Visual effects can be added to the game world without hurting the readability of the UI.
It has some disadvantages, as well.
- Locks the viewport resolution if any scaling is enabled, which is not ideal for 3D games.
- Requires enabling Audio Listeners to hear audio from the game world.
- Extra processing overhead for the viewport layer.
If a subviewport does not work well for the game, use any empty `Node` as the game world or level container, instead.
### Pixel Art Games
If working with a pixel art game, often the goal is that the number of art pixels on-screen is to remain the same regardless of screen resolution. As in, the art scales with the monitor, rather than bigger monitors showing more of a scene. This is done by setting the viewport size in the project settings, and setting the stretch mode to either `canvas_mode` or `viewport`.
If a higher resolution is desired for the menus and UI than the game, then the project viewport size should be set to a multiple of the desired game window size. Then set the stretch shrink in `SubViewportContainer` to the multiple of the resolution. For example, if the game is at `640x360`, then the project viewport size can be set to `1280x720`, and the stretch shrink set to `2` (`1280x720 / 2 = 640x360`). Finally, set the texture filter on the `SubViewportContainer` to `Nearest`.
### Mouse Interaction
If trying to detect `mouse_enter` and `mouse_exit` events on areas inside the game world, enable physics object picking on the `SubViewport`.
## Read Inputs
Generally, any game is going to require reading some inputs from the player. Where in the scene hierarchy the reading occurs is best answered with simplicity.
If the game involves moving a player character, then the inputs for movements could be read by a `player_character.gd` script overriding the `_process(delta)` or `_input(event)` methods.
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 are triggered by the `LevelListManager` when a level is won or lost.
```
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.
```
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`.

51
addons/maaacks_game_template/docs/GamesMade.md Normal file
View File

@ -0,0 +1,51 @@
# Games
This page features games using Maaack's Godot Game Template and/or plugins.
If you have a game you'd like to share, join the [Discord server](https://discord.gg/AyZrJh5AMp ) and post a link to your game in #showcase.
## Featured
| Spud Customs | Rent Seek Kill | A Darkness Like Gravity |
| :-------:| :-------: | :-------: |
![Spud Customs](/addons/maaacks_game_template/media/screenshot-game-spud-customs.png) | ![Rent-Seek-Kill](/addons/maaacks_game_template/media/screenshot-game-rent-seek-kill.png) | ![A Darkness Like Gravity](/addons/maaacks_game_template/media/screenshot-game-a-darkness-like-gravity.png) |
[Find on Steam](https://store.steampowered.com/app/3291880/Spud_Customs/) | [Play on itch.io](https://xandruher.itch.io/rent-seek-kill) | [Play on itch.io](https://maaack.itch.io/a-darkness-like-gravity) |
## All Shared
### 2025
https://schinken.itch.io/low-ink
https://maaack.itch.io/furnace-in-the-archive
https://plexsoup.itch.io/factoriohno
https://maaack.itch.io/dungeon-fantasy-fashion-show
https://maaack.itch.io/absurd-herd
https://maaack.itch.io/indys-expedition-2
https://baconeggsrl.itch.io/sprouts-journey
### 2024
https://store.steampowered.com/app/3291880/Spud_Customs/ (Source: https://github.com/Lost-Rabbit-Digital/SpudCustoms)
https://glockenberg.itch.io/icefire-temple
https://maaack.itch.io/backroom-labyrinths
https://maaack.itch.io/haunted-circuits
https://maaack.itch.io/talk-up-the-tower
https://marinaaaa.itch.io/meowntaineer
https://maaack.itch.io/a-darkness-like-gravity
https://maaack.itch.io/lore-of-the-wild-gwj-70
https://maaack.itch.io/infinite-horizon
https://elidef.itch.io/forge-ur-boss
https://maaack.itch.io/forgeomino
https://xandruher.itch.io/rent-seek-kill
https://maaack.itch.io/blind-escape-gwj-66-edition
https://justaguyjustaguy.itch.io/nannybot-overload
https://maaack.itch.io/the-last-host-boss-rush
https://kyveri.itch.io/riverking
### 2023
https://xandruher.itch.io/spectral-war
https://maaack.itch.io/the-cat-with-eight-gwj-63-edition
https://maaack.itch.io/harvest-hill-gwj-62-edition
https://shoddygames.itch.io/once-summoned
https://maaack.itch.io/the-last-host
https://maaack.itch.io/do-androids-dream-gwj-55-edition
https://maaack.itch.io/character-builder-gwj-53-edition
https://maaack.itch.io/rit-dot-wav
https://maaack.itch.io/supercritical-a-post-apocalyptic-bonsai

16
addons/maaacks_game_template/docs/HowPartsWork.md Normal file
View File

@ -0,0 +1,16 @@
# How Parts Work
This page features snippets of extra documentation on key pieces of the plugin. It was previously included in the README.
- `app_config.tscn` is set as the first autoload. It calls `app_settings.gd` to load all the configuration settings from the config file (if it exists) through `config.gd`.
- `scene_loader.tscn` is set as the second autoload. It can load scenes in the background or with a loading screen (`loading_screen.tscn` by default).
- `opening.tscn` is a simple scene for fading in/out a few images at the start of the game. It then loads the next scene (`main_menu.tscn`).
- `main_menu.tscn` is where a player can start the game, change settings, watch credits, or quit. It can link to the path of a game scene to play, and the packed scene of an options menu to use.
- `option_control.tscn` and its inherited scenes are used for most configurable options in the menus. They work with `config.gd` to keep settings persistent between runs.
- `credits.tscn` reads from `ATTRIBUTION.md` to automatically generate the content for it's scrolling text label.
- The `UISoundController` node automatically attaches sounds to buttons, tab bars, sliders, and line edits in the scene. `project_ui_sound_controller.tscn` is an autload used to apply UI sounds project-wide.
- `project_music_controller.tscn` is an autoload that keeps music playing between scenes. It detects music stream players as they are added to the scene tree, reparents them to itself, and blends the tracks.
- The `PauseMenuController` can be set to load `pause_menu.tscn` when triggering `ui-cancel`.
- `pause_menu.tscn` is a type of `OverlaidMenu` with the `pauses_game` flag set to true. It will store the previously focused UI element, and return focus to it when closed.
- `capture_focus.gd` is attached to container nodes throughout the UI. It focuses onto UI elements when they are shown, allowing for easier navigation without a mouse.
- `game_ui.tscn` is a demo game scene that displays recognized action inputs, and features the `PauseMenuController` node, the `LevelListLoader` node to load levels from a directory, and `LevelListManager` to manage level progress and show menus in case of a win or loss.

154
addons/maaacks_game_template/docs/InputIconMapping.md Normal file
View File

@ -0,0 +1,154 @@
# Input Icon Mapping
The `InputIconMapper` in `input_options_menu.tscn` is a generalized tool meant to be broadly compatible with freely licensed icon asset packs. Instructions on how to use it with a few of these packs are provided, with links to download them from their creator's page.
## Kenney Input Prompts
### Automatic
With the project open, select `Project > Tools > Install Input Icons for Maaack's Game Template`.
Select a style and then wait for the icons to download, extract, and setup.
### Manual
Available from [kenney.nl](https://kenney.nl/assets/input-prompts) and [itch.io](https://kenney-assets.itch.io/input-prompts).
This pack is organized by `Device/IconType`. The `IconTypes` for each device are just `Default`, `Vector`, or `Double`. These instructions will assume using `Default`. In the inspector of `InputIconMapper`, set the `directories` to include the subdirectories of the asset pack.
* `.../kenney_input-prompts/Keyboard & Mouse/Default`
* `.../kenney_input-prompts/Generic/Default`
* `.../kenney_input-prompts/Xbox Series/Default`
* `.../kenney_input-prompts/PlayStation Series/Default`
* `.../kenney_input-prompts/Nintendo Switch/Default`
* `.../kenney_input-prompts/Steam Deck/Default`
Set `filtered_strings` to:
* `keyboard`
* `color`
* `button`
* `arrow`
Set `replace_strings` with the key pairs:
* `"Capslock": "Caps Lock"`
* `"Generic Stick": "Generic Left Stick"`
* `"Guide": "Home"`
* `"Slash Back": "Back Slash"`
* `"Slash Forward": "Slash"`
* `"Stick L": "Left Stick"`
* `"Stick R": "Right Stick"`
* `"Trigger L 1": "Left Shoulder"`
* `"Trigger L 2": "Left Trigger"`
* `"Trigger R 1": "Right Shoulder"`
* `"Trigger R 2": "Right Trigger"`
#### Filled Icons
![Kenney Filled Icons](../media/screenshot-5-kenney-2.png)
Under the `FileLister` properties of the `InputIconMapper`, expand the `Constraints` and `Advanced Search` tabs. Set `ends_with=".png"` and `not_ends_with="outline.png"`.
Press `Refresh Files`.
If you want to use colored icons, in `prioritized_strings` add `color`. Otherwise set `filter="color"`.
Press `Match Icons to Inputs`.
Validate the results by inspecting the `matching_icons` dictionary.
#### Outlined Icons
![Kenney Outlined Icons](../media/screenshot-5-kenney-4.png)
Not all icons have outlined versions, so we will end up including the filled icons as fallback, and prioritizing outlined.
Under the `FileLister` properties of the `InputIconMapper`, expand the `Constraints` and `Advanced Search` export groups. Set `ends_with=".png"`.
Press `Refresh Files`.
Add to `filtered_strings`:
* `outline`
In `prioritized_strings` add `outline`. If you want to use colored icons, in `prioritized_strings` add `color`, too. Otherwise set `filter="color"`.
Press `Match Icons to Inputs`.
Validate the results by inspecting the `matching_icons` dictionary.
## Kenny Input Prompts Pixel 16x
Incompatible: File names not useable.
## Xelu 's Free Controller & Key Prompts
![Xelu's Icons](../media/screenshot-5-xelu-2.png)
Available from [thoseawesomeguys.com](https://thoseawesomeguys.com/prompts/).
This pack is organized by `Device`. In the inspector of `InputIconMapper`, set the `directories` to include the subdirectories of the asset pack. Assumes using the `Dark` icon set with the keyboard and mouse.
* `.../Xelu_Free_Controller&Key_Prompts/Keyboard & Mouse/Dark`
* `.../Xelu_Free_Controller&Key_Prompts/Xbox Series`
* `.../Xelu_Free_Controller&Key_Prompts/PS5`
* `.../Xelu_Free_Controller&Key_Prompts/Switch`
* `.../Xelu_Free_Controller&Key_Prompts/Steam Deck`
Under the `FileLister` properties of the `InputIconMapper`, expand the `Constraints` and `Advanced Search` tabs. Set `ends_with=".png"`.
Press `Refresh Files`.
Set `filtered_strings` to:
* `dark`
* `key`
Set `replace_strings` with the key pairs:
* `"Ps 5": "Playstation"`
* `"Xbox Series X": "Xbox"`
* `"Steam Deck": "Steamdeck"`
* `"L 1": "Left Shoulder"`
* `"R 1": "Right Shoulder"`
* `"L 2": "Left Trigger"`
* `"R 2": "Right Trigger"`
* `"Click": "Press"`
Set `add_stick_directions=true`.
Press `Match Icons to Inputs`.
Validate the results by inspecting the `matching_icons` dictionary.
Since `Generic` device icons are not available, set `initial_joypad_device` to either `Xbox`, `Playstation`, `Switch`, or `Steamdeck`.
## Free Icon Pack for Unity & Unreal – 1500+ Input Icons for Game UI
![Julio Cacko's Icons](../media/screenshot-5-juliocacko-2.png)
Available from [itch.io](https://juliocacko.itch.io/free-input-prompts).
This pack is organized by `Device/IconType`. In the inspector of `InputIconMapper`, set the `directories` to include the subdirectories of the asset pack. Assumes using the `Dark` icon set with the keyboard and mouse, and `Default` for the others.
* `.../Source/Keyboard_Mouse/Dark`
* `.../Source/P4Gamepad/Default`
* `.../Source/XGamepad/Default`
* `.../Source/SGamepad/Default`
Under the `FileLister` properties of the `InputIconMapper`, expand the `Constraints` and `Advanced Search` tabs. Set `ends_with=".png"`.
Press `Refresh Files`.
In `prioritized_strings`, add either `color` or `white`, depending on what icons you prefer.
Set `filtered_strings` to:
* `dark`
* `key`
* `t`
* `color`
* `white`
Set `replace_strings` with the key pairs:
* `"P 4": "Playstation"`
* `"X": "Xbox"`
* `"S": "Switch"`
* `"L": "Left Stick"`
* `"R": "Right Stick"`
* `"Left Stick 1": "Left Shoulder"`
* `"Right Stick 1": "Right Shoulder"`
* `"Left Stick 2": "Left Trigger"`
* `"Right Stick 2": "Right Trigger"`
Press `Match Icons to Inputs`.
Validate the results by inspecting the `matching_icons` dictionary.
Since `Generic` device icons are not available, set `initial_joypad_device` to either `Xbox`, `Playstation`, or `Switch`.

31
addons/maaacks_game_template/docs/JoypadInputs.md Normal file
View File

@ -0,0 +1,31 @@
# Joypad Inputs
This page covers topics related to working with joypads.
## Recognized Devices
- Xbox
- Playstation 4
- Playstation 5
### Unconfirmed
- Switch
- Steam Deck
## Added UI Inputs
There is a `override.cfg` in the project root directory that adds a few additional inputs to the project's built-in UI actions.
These additional inputs are for joypads and include the following:
- `UI Accept`: A Button (Xbox A / Sony X)
- `UI Cancel`: Back Button (Xbox Back / Sony Select)
- `UI Page Up`: Left Shoulder (Xbox LB / Sony L1)
- `UI Page Down`: Right Shoulder (Xbox RB / Sony R2)
However, for these to work in exported versions of the project, the inputs need to either be added manually to the project's built-in actions, or `override.cfg` will need to be included in the exports. The latter can be done by including the pattern (`*.cfg`) in **Filters to export non-resource files/folders** under the *Resources* tab of the *Export* window.
## Web Builds
Godot (or the template) currently does not support joypad device detection on the web. If icons are being used for input remapping, the joypad icons will *not* update automatically to match a new detected controller.

34
addons/maaacks_game_template/docs/MainMenuSetup.md Normal file
View File

@ -0,0 +1,34 @@
# 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.
## Level Select
A basic level select scene is available to add to the menu. In `main_menu_with_animations.tscn`, click the root `MainMenu` mode and set `Level Select Packed Scene` to `level_select_menu.tscn`. The button will appear on the main menu when the player has reached the second level.
Levels can be added to the menu by inspecting the `SceneLister` and either selecting a directory to automatically read scene files from, or populating the files array manually.
## Theming
It is recommended to have a custom theme for a project. Create a theme resource file or use one of the ones provided with the template 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

126
addons/maaacks_game_template/docs/NewProject.md Normal file
View File

@ -0,0 +1,126 @@
# New Projects
These instructions assume starting with the entire contents of the project folder. This will be the case when cloning the repo, or starting from the *template* version in the Godot Asset Library.
1. Finish setup and remove duplicate example files.
1. Go to `Project > Tools > Copy Maaack's Game Template Examples`.
2. Click `Cancel` in the first window asking to copy the examples. It's already done.
3. Select a theme in the next window if desired.
4. Go to `Project > Tools > Delete Maaack's Game Template Examples`.
5. Click `Yes` in the first window.
2. Update the project’s name.
1. Go to `Project > Project Settings… > General > Application > Config`.
2. Update `Name` to `"Game Name"`.
3. Close the window.
4. Open `main_menu_with_animations.tscn`.
5. The `Title` node should automatically update with the project's title. Customize the `Text` property if desired.
7. Select the `Subtitle` node and customize the `Text` property if desired.
9. Save the scene.
3. Add background music and sound effects to the UI.
1. Verify the `Music` and `SFX` audio busses.
1. Open the Audio bus editor.
2. Make sure there is a bus for `Music` and another for `SFX`.
3. Add the busses if they do not exist.
2. Add background music to the Main Menu.
1. Import the music asset into the project.
2. Open `main_menu_with_animations.tscn`.
3. Select the `BackgroundMusicPlayer` node.
4. Assign the music asset to the `stream` property.
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`
3. Add sound effects to UI elements.
1. By scene.
1. Open `main_menu_with_animations.tscn` and `pause_menu.tscn`.
2. Select the `UISoundController` node.
3. Add audio streams to the various UI node events.
4. Save the scenes.
2. Project-wide.
1. Open `project_ui_sound_controller.tscn`.
2. Select the `UISoundController` node.
3. Add audio streams to the various UI node events.
4. Save the scene.
4. Add readable names for input actions to the controls menu.
1. Open `input_options_menu.tscn`.
2. In the scene tree, select the `Controls` node.
3. In the node inspector, select the desired input remapping mode (defaults to `List`).
4. In the scene tree, select `InputActionsList` or `InputActionsTree`, depending on the choice of input remapping. The other node should be hidden.
5. In the node inspector, update the `Input Action Names` and corresponding `Readable Action Names` to show user-friendly names for the project's input actions.
6. Save the scene.
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.
2. If an option is not desired, it can always be hidden, or removed entirely (sometimes with some additional work).
3. If a new option is desired, it can be added without writing code.
1. Find the node that contains the existing list of options. Usually, it's a `VBoxContainer`.
2. Add an `option_control.tscn` node as a child to the container.
1. `slider_option_control.tscn` or `toggle_option_control.tscn` can be used if those types match requirements. In that case, skip step 5.3.6.
2. `list_option_control.tscn` and `vector_2_list_option_control.tscn` are also available, but more complicated. See the `ScreenResolution` example.
3. Select the `OptionControl` node just added, to edit it in the inspector.
4. Add an `Option Name`. This prefills the `Key` string.
5. Select an `Option Section`. This prefills the `Section` string.
6. Add any kind of `Button`, `Slider`, `LineEdit`, or `TextEdit` to the `OptionControl` node.
7. Save the scene.
4. For options to have an effect outside of the menu, it will need to be referenced by its `key` and `section` from `config.gd`.
1. `Config.get_config(section, key, default_value)`
5. Validate the values being stored in your local `config.cfg` file.
1. Refer to [Accessing Persistent User Data User](https://docs.godotengine.org/en/stable/tutorials/io/data_paths.html#accessing-persistent-user-data-user) to find Godot user data on your machine.
2. Find the directory that matches your project's name.
3. `config.cfg` should be in the top directory of the project.
6. Update the game credits / attribution.
1. Update the example `ATTRIBUTION.md` with the project's credits.
2. Open `credits.tscn`.
3. Check the `CreditsLabel` has updated with the text.
4. Save the scene.
7. Keep, update, or remove `res://LICENSE.txt`.
8. Optionally, if using Git for version control, update `.gitignore` to include `addons/`.
9. Continue with:
1. [Setting up the Main Menu.](/addons/maaacks_game_template/docs/MainMenuSetup.md)
2. [Adding icons to the Input Options.](/addons/maaacks_game_template/docs/InputIconMapping.md)
3. [Setting up a Game Scene.](/addons/maaacks_game_template/docs/GameSceneSetup.md)
4. [Utilizing Game Saving](/addons/maaacks_game_template/docs/GameSaving.md)

27
addons/maaacks_game_template/docs/PluginSuite.md Normal file
View File

@ -0,0 +1,27 @@
# Plugin Suite
![Plugins Suite](../media/maaacks-plugin-suite-256x256.gif)
Maaack's Game Template is a culmination of a suite of plugins, that can be downloaded individually, if desired.
## GitHub
- [Game Template](https://github.com/Maaack/Godot-Game-Template)
- [Menus Template](https://github.com/Maaack/Godot-Menus-Template)
- [Options Menus](https://github.com/Maaack/Godot-Options-Menus)
- [Input Remapping](https://github.com/Maaack/Godot-Input-Remapping)
- [Scene Loader](https://github.com/Maaack/Godot-Scene-Loader)
- [Credits Scene](https://github.com/Maaack/Godot-Credits-Scene)
- [UI Sound Controller](https://github.com/Maaack/Godot-UI-Sound-Controller)
- [Music Controller](https://github.com/Maaack/Godot-Music-Controller)
## Godot Asset Library
- [Game Template](https://godotengine.org/asset-library/asset/2709)
- [Menus Template](https://godotengine.org/asset-library/asset/2899)
- [Options Menus](https://godotengine.org/asset-library/asset/3058)
- [Input Remapping](https://godotengine.org/asset-library/asset/4051)
- [Scene Loader](https://godotengine.org/asset-library/asset/2896)
- [Credits Scene](https://godotengine.org/asset-library/asset/2932)
- [UI Sound Controller](https://godotengine.org/asset-library/asset/2897)
- [Music Controller](https://godotengine.org/asset-library/asset/2898)

57
addons/maaacks_game_template/docs/Screenshots.md Normal file
View File

@ -0,0 +1,57 @@
# Screenshots
Screenshots organized by included themes with a variety of the features shown.
The template is presented here in a 640x360 resolution, but up to 4k resolutions are supported.
## Default (No Theme)
![Main Menu - Default](/addons/maaacks_game_template/media/screenshot-6-main-menu-5.png)
![Input List - Default](/addons/maaacks_game_template/media/screenshot-6-input-list-3.png)
![Input List - Default](/addons/maaacks_game_template/media/screenshot-6-input-list-2.png)
![Input List - Default](/addons/maaacks_game_template/media/screenshot-6-input-list-1.png)
![Input Tree - Default](/addons/maaacks_game_template/media/screenshot-6-input-tree-4.png)
![Audio Options - Default](/addons/maaacks_game_template/media/screenshot-6-audio-options-6.png)
![Video Options - Default](/addons/maaacks_game_template/media/screenshot-6-video-options-6.png)
![Level Won - Default](/addons/maaacks_game_template/media/screenshot-6-level-won-3.png)
![Level Lost - Default](/addons/maaacks_game_template/media/screenshot-6-level-lost-3.png)
## Gravity
![Main Menu - Gravity](/addons/maaacks_game_template/media/screenshot-6-main-menu-1.png)
![Input List - Gravity](/addons/maaacks_game_template/media/screenshot-6-input-list-5.png)
![Input List - Gravity](/addons/maaacks_game_template/media/screenshot-6-input-list-4.png)
![Input Tree - Gravity](/addons/maaacks_game_template/media/screenshot-6-input-tree-1.png)
![Audio Options - Gravity](/addons/maaacks_game_template/media/screenshot-6-audio-options-1.png)
![Video Options - Gravity](/addons/maaacks_game_template/media/screenshot-6-video-options-1.png)
![Level State - Gravity](/addons/maaacks_game_template/media/screenshot-6-level-state-1.png)
![Pause Menu - Gravity](/addons/maaacks_game_template/media/screenshot-6-pause-menu-2.png)
![Level Won - Gravity](/addons/maaacks_game_template/media/screenshot-6-level-won-1.png)
![Level Lost - Gravity](/addons/maaacks_game_template/media/screenshot-6-level-lost-1.png)
## Lore
![Main Menu - Lore](/addons/maaacks_game_template/media/screenshot-6-main-menu-2.png)
![Input List - Lore](/addons/maaacks_game_template/media/screenshot-6-input-list-6.png)
![Input List - Lore](/addons/maaacks_game_template/media/screenshot-6-input-list-7.png)
![Input Tree - Lore](/addons/maaacks_game_template/media/screenshot-6-input-tree-2.png)
![Audio Options - Lore](/addons/maaacks_game_template/media/screenshot-6-audio-options-3.png)
![Video Options - Lore](/addons/maaacks_game_template/media/screenshot-6-video-options-3.png)
![Pause Menu - Lore](/addons/maaacks_game_template/media/screenshot-6-pause-menu-3.png)
## Steal This Theme
![Main Menu - Steal This Theme](/addons/maaacks_game_template/media/screenshot-6-main-menu-4.png)
![Input Tree - Steal This Theme](/addons/maaacks_game_template/media/screenshot-6-input-tree-5.png)
![Audio Options - Steal This Theme](/addons/maaacks_game_template/media/screenshot-6-audio-options-4.png)
![Video Options - Steal This Theme](/addons/maaacks_game_template/media/screenshot-6-video-options-5.png)
![Pause Menu - Steal This Theme](/addons/maaacks_game_template/media/screenshot-6-pause-menu-4.png)
![Level Won - Steal This Theme](/addons/maaacks_game_template/media/screenshot-6-level-won-2.png)
![Level Won - Steal This Theme](/addons/maaacks_game_template/media/screenshot-6-level-won-2.png)
![Loading Screen - Steal This Theme](/addons/maaacks_game_template/media/screenshot-6-loading-screen-1.png)
![Loading Screen - Steal This Theme](/addons/maaacks_game_template/media/screenshot-6-loading-screen-2.png)
![Loading Screen - Steal This Theme](/addons/maaacks_game_template/media/screenshot-6-loading-screen-3.png)
![Loading Screen - Steal This Theme](/addons/maaacks_game_template/media/screenshot-6-loading-screen-4.png)
## Tower
![Main Menu - Tower](/addons/maaacks_game_template/media/screenshot-6-main-menu-3.png)
![Input List - Tower](/addons/maaacks_game_template/media/screenshot-6-input-list-8.png)
![Input List - Tower](/addons/maaacks_game_template/media/screenshot-6-input-list-9.png)
![Input Tree - Tower](/addons/maaacks_game_template/media/screenshot-6-input-tree-3.png)
![Audio Options - Tower](/addons/maaacks_game_template/media/screenshot-6-audio-options-5.png)
![Video Options - Tower](/addons/maaacks_game_template/media/screenshot-6-video-options-4.png)

37
addons/maaacks_game_template/docs/UploadingToItchIo.md Normal file
View File

@ -0,0 +1,37 @@
# Uploading to itch.io
This is a guide on using *Butler* along with a *Butler Manager* helper script to rapidly upload and deploy your builds to itch.io. It's useful for game jams!
## Butler
*Butler* is a command-line tool provided by itch.io to upload content to project pages on itch.io.
Get it here: https://itchio.itch.io/butler
After installing it, run `butler login` and go through the login flow. You should only have to do this once.
*Butler* automatically compares builds and only uploads what has changed, so the first upload will take the longest, but every upload after should be faster.
## Exporting
It is recommended to create an `exports/` directory for your builds, add the directory to your `.gitignore` file (if applicable), and also add a `.gdignore` file to the directory to avoid having Godot add `*.import` files to it as well.
## Butler Manager
This script provided at `addons/maaacks_game_template/extras/scripts/butler_manager.sh` can be used to rapidly deploy 4 different builds to your project page. Make sure you can run `bash` shell scripts on your OS. Copy the script into your `exports/` directory and mark it as an executable, if required.
Run the script with `./butler_manager.sh`. On the first run, it will ask for the destination for uploads. This is a combination of the page owner and the project's URL.
The Butler Manager will look for directories named the following:
* HTML5
* Linux
* Windows
* MacOS
Matching directories will be uploaded by *Butler* to their corresponding channels on itch.io. They will then be processed by itch.io servers and eventually appear on the page (usually within 2 minutes).
The owner of the project page will also get a notification when the builds have finished processing.
You can re-run `./butler_manager.sh` right after an export from Godot to keep your builds synced.

6
addons/maaacks_game_template/docs/Videos.md Normal file
View File

@ -0,0 +1,6 @@
# Videos
[![Quick Intro Video](https://img.youtube.com/vi/U9CB3vKINVw/hqdefault.jpg)](https://youtu.be/U9CB3vKINVw)
[![Installation Video](https://img.youtube.com/vi/-QWJnZ8bVdk/hqdefault.jpg)](https://youtu.be/-QWJnZ8bVdk)
[![UI Theming (1) Video](https://img.youtube.com/vi/SBE4icfXYRA/hqdefault.jpg)](https://youtu.be/SBE4icfXYRA)
[![UI Theming (2) Video](https://img.youtube.com/vi/wCc2QUnaBKo/hqdefault.jpg)](https://youtu.be/wCc2QUnaBKo)