djairoh/notSpore
1
0
Fork 0
Code Issues 2 Pull Requests Packages Projects Releases Wiki Activity

imported main menu scene addon

Browse Source
This commit is contained in:
Djairo Hougee
2026-05-10 15:48:56 +02:00
parent 86d9f75161
commit 71c2850a34
458 changed files with 14881 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
evolve-die-repeat/addons/maaacks_game_template/docs/AddingCustomOptions.md Normal file
View File

@@ -0,0 +1,49 @@
# Adding Custom Options
> [!WARNING]
> This page is being deprecated in favor of [Options Menus Setup](/addons/maaacks_game_template/docs/OptionsMenusSetup.md).
This page covers adding new buttons, sliders, or editable text fields to the options menus that automatically persist between sessions.
## To the Menu
Custom options can be added to a menu without any code.
1. Add an `option_control.tscn` node as a child to a container in a scene.
1. `slider_option_control.tscn` or `toggle_option_control.tscn` can be used if those types match requirements. In that case, skip step 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.
## To the Game
For options to have any effect outside of the menus, they will need to be referenced by their `key` and `section` from the `PlayerConfig` class.
```
PlayerConfig.get_config(key, section)
```
For example, here is how to get the player's desired input sensitivity for controlling a player camera.
```
var mouse_sensitivity : float = PlayerConfig.get_config(AppSettings.INPUT_SECTION, "MouseSensitivity", 1.0)
var joypad_sensitivity : float = PlayerConfig.get_config(AppSettings.INPUT_SECTION, "JoypadSensitivity", 1.0)
```
## Validation
Validate the values being stored in your local `player_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. Open `player_config.cfg` (should be in the top directory of the project).
4. Find the section by the section name in brackets, and the key name followed by an equals.
For example, here is how the player's desired input sensitivity could appear in the config file.
```
[InputSettings]
MouseSensitivity=1.05
JoypadSensitivity=0.95
```
> [!NOTE]
> Some settings may not appear until they have been customized.

29
evolve-die-repeat/addons/maaacks_game_template/docs/AddingUISFX.md Normal file
View File

@@ -0,0 +1,29 @@
# Adding UI Sound Effects
This page covers adding sound effects to common UI elements like buttons and sliders.
1. Verify the `Music` and `SFX` audio busses.
1. Open the Audio bus editor.
2. Confirm that `Music` and `SFX` audio busses are available.
1. If the last bus is `New Bus`, try restarting the editor and checking again.
3. If the audio bus doesn't exist, add it and save the project.
1. Add UI sound effects:
1. By scene.
1. Open `main_menu_with_animations.tscn` and `pause_menu.tscn`.
2. In the Scene Tree, select the `UISoundController` node.
3. In the Inspector, add audio streams to the various UI node events.
4. Save the scenes.
2. Project-wide.
1. Open `project_ui_sound_controller.tscn`.
2. In the Scene Tree, select the `UISoundController` node.
3. In the Inspector, add audio streams to the various UI node events.
4. Save the scene.

30
evolve-die-repeat/addons/maaacks_game_template/docs/AutomaticUpdating.md Normal file
View File

@@ -0,0 +1,30 @@
# Automatic Updating
This plugin automatically checks GitHub for new releases. When a new release is available, the option to update will appear in the `Project > Tools` menu.
## Starting an Update
> [!IMPORTANT]
> Save the state of the project, and close all open scenes and scripts.
Select the option from `Project > Tools > Update Maaack's Game Template to v...`.
A window will pop-up, confirming the choice to update to the latest release. Select `OK`.
Another window will show progress through downloading, saving, and extracting.
This effectively deletes the current `addons/maaacks_game_template/` folder and replaces it with a new one. Nothing outside of `addons/` should be affected.
After, a window should appear confirming a successful update.
## Disabling Automatic Checking
You can disable the automatic update checks by going into the Project Settings, and enabling the `maaacks_game_template/disable_update_check` setting. You can then close the window.
## Issues
If the option to update does not appear, try restarting the editor, or re-enabling the plugin.
Updating adds the examples folder into the `addons/maaacks_game_template/` folder, if it had been deleted previously.
Files already copied from the examples folder will not be affected by an update. However, a mismatch of versions may cause issues, too. If there are no major customizations to the copied files, it is recommended to delete them and recopy from `Project > Tools > Run Maaack's Game Template Setup...`.

68
evolve-die-repeat/addons/maaacks_game_template/docs/BasicSetup.md Normal file
View File

@@ -0,0 +1,68 @@
# Basic Setup
These instructions cover the basics for setting up the template.
## Setup Wizard
The _Setup Wizard_ shows the user's progress through the setup process.
### Open
Open the _Setup Wizard_ by navigating to `Project > Tools > Run Maaack's Game Template Setup...`.
![Setup Wizard Location](/addons/maaacks_game_template/media/setup-wizard-location.png)
### Check & Complete
A typical full installation will have the following steps completed:
- Using Latest Version
- Copy Example Files
- Delete Example Files
- Update Autoload Paths
- Set Main Scene
![Setup Wizard Window](/addons/maaacks_game_template/media/setup-wizard-window.png)
Depending on how the template was installed, or if any issues occurred, some of these may need to be run from the wizard to be completed.
The remaining steps are optional customizations.
## Scene Paths
The flow of scenes in the template is (by default):
```
Opening -> Main Menu -> Game Scene -> Ending Scene
```
To change the _Main Menu_, _Game Scene_, or _Ending Scene_:
1. Open `app_config.tscn`.
2. Select the `AppConfig` node.
3. Update `Main Menu Scene Path` to the desired path (`main_menu_with_animations.tscn` by default).
4. Update `Game Scene Path` to the path of the project's game scene (`game_ui.tscn` by default).
5. Update the optional `Ending Scene Path` to the desired scene (`end_credits.tscn` by default).
6. Save the scene.
To change the _Opening_:
1. Navigate to `Project > Project Settings…`
2. In the _Project Settings_ window, go to the `General` tab.
3. In the settings list, navigate to `Application > Run`.
4. Update `Main Scene` to the desired path.
## Next Steps
### Recommended
1. [Main Menu Setup](/addons/maaacks_game_template/docs/MainMenuSetup.md)
2. [Options Menu Setup](/addons/maaacks_game_template/docs/OptionsMenuSetup.md)
3. [Game Scene Setup](/addons/maaacks_game_template/docs/GameSceneSetup.md)
4. [Updating Credits](/addons/maaacks_game_template/docs/UpdatingCredits.md)
5. [Blending Music](/addons/maaacks_game_template/docs/BlendingMusic.md)
6. [Adding UI Sound Effects](/addons/maaacks_game_template/docs/AddingUISFX.md)
### Extra
1. [Adding Icons to the Input Options](/addons/maaacks_game_template/docs/InputIconMapping.md)
2. [Supporting Joypad Inputs](/addons/maaacks_game_template/docs/JoypadInputs.md)
3. [Loading scenes asynchronously](/addons/maaacks_game_template/docs/LoadingScenes.md)
4. [Utilizing Game Saving](/addons/maaacks_game_template/docs/GameSaving.md)
5. [Uploading to itch.io](/addons/maaacks_game_template/docs/UploadingToItchIo.md)

42
evolve-die-repeat/addons/maaacks_game_template/docs/BlendingMusic.md Normal file
View File

@@ -0,0 +1,42 @@
# Blending Music Between Scenes
This page covers the `ProjectMusicController`, which is used to blend music in between scenes, that would otherwise abruptly stop the music when they get unloaded.
## Setup
1. Verify the `Music` audio bus.
1. Open the Audio bus editor.
2. Confirm that `Music` audio bus is available.
1. If the last bus is `New Bus`, try restarting the editor and checking again.
3. If the audio bus doesn't exist, add it and save the project.
2. Verify the `ProjectMusicController` autoload.
1. Open the Project Settings.
2. Open the `Globals` tab.
3. Confirm that the `ProjectMusicController` is listed as an autoload.
3. Setup music blending between scenes.
1. Open up the `project_music_controller.tscn` scene.
2. Inspect the root node of the scene tree (`ProjectMusicController`).
3. Confirm that the `audio_bus` is set to `Music`.
4. Expand the `Blending` variable group.
5. Set a `fade_out_duration` or `fade_in_duration`, in seconds.
4. Add background music to your scenes.
1. Import the music asset into the project.
2. Add a `BackgroundMusicPlayer`.
3. Assign the music asset to the `stream` property.
4. Make sure that the `bus` property is set to `Music` and `autoplay` is `true`.
5. Save the scene.
## Internal Details
When a background music player is about to exit the scene tree, it gets reparented to the autoload node. This allows it to continue playing until the next scene is ready and a new background music player is detected. If the audio stream players share the same stream, then the controller will seek the next player to the same position on the stream, before removing the previous one. If a different stream is detected and a fade out duration is set, then the previous player will blend into the next one, by having its volume lowered to zero over the fade out duration.
The autload adds the "BlendMusic" audio bus is added at runtime. If a fade in duration is set, then the temporary bus is used to combine the increasing volume of the player with any other animations local to the scene.
The autoload will work with any `AudioStreamPlayer` with `bus` set to `Music` and `autoplay` set to `true`. These are detected up as they enter the scene tree. To dynamically add an `AudioStreamPlayer` to the background music, call `ProjectMusicController.play_stream(background_music_player)`.

304
evolve-die-repeat/addons/maaacks_game_template/docs/BuildAndPublish.md Normal file
View File

@@ -0,0 +1,304 @@
## How to Build and Publish my game using Github CICD?
**GitHub** is a platform that hosts your project’s source code online, making it easy to collaborate, track changes, and share your game with players, testers, or colleagues.
**CI/CD** (Continuous Integration and Continuous Deployment) refers to automating the process of building, testing, and publishing your game whenever you make updates. The idea is to speed up your game's release process so you can push updates frequently, to fix bugs quicker or add more game content.
Using GitHub Actions, you can set up **workflows that automatically compile your Godot project** and **upload it to platforms** like itch.io whenever you tag a new release. This saves time, reduces manual errors, and helps keep your build and release process smooth and repeatable.
**How does it work?** Once everything is set up, publish a new version of your game by creating a new **Github Release**. This will trigger the Github Action, that will build your game in the cloud and publish it to itch.io with a nice version tag.
> Note: You can set up all of this and still keep your game as a _Draft_ on itch.io. This is great for playtesting!
## Prerequisites
Before following this guide, make sure you have the following in place:
- **GitHub Account & Repository:** Your Godot project should be pushed to a GitHub repository. If you haven’t yet, create one and upload your project files.
- **Itch.io Account:** You’ll need an itch.io account to publish your game. Create one at itch.io if you don’t have it yet.
## Setup your game build
### 1. Setup exports for your game in Godot
First, open your game in Godot. Go to Project > Export... and make sure to add the following exports:
- `Web`
- `Linux`
- `macOS`
- `Windows Desktop`
![Godot export](../media/build-and-publish/godot_export.png)
Then, run the export for one platform manually **at least once.** This will create a `export_presets.cfg` file at the root of your project.
The `build-and-publish.yml` will **trigger** the build configs in `export_presets.cfg` **by name**. So make sure that your exports names are the same as in the list above. You can change the names or add more build configs with small edits to `build-and-publish.yml`.
#### Additional Git setup
Some version of Godot will add `export_presets.cfg` to `.gitignore` automatically. You'll want to remove that, so that git checks in your export configuration file with the rest of your code.
#### Additional MacOS setup
##### MacOS Bundle name
For MacOS, you have a field called "Bundle name" with default value `com.game.maaack-template`. Change this to be your game name.
##### MacOS Notarization
By default, your built game on MacOS will be flagged as dangerous. Players will need to allow its execution by going into _System Settings > Privacy & Security_, allow the app execution, and restart the game.
To avoid this, you need to notarize your game, i.e. tell Apple who you are and what is your binary.
For that, you'll need first to create an Apple developer account (99USD/year). Then, you'll need to adapt the Export configuration of MacOS [using this guide](https://docs.godotengine.org/en/latest/tutorials/export/exporting_for_macos.html#if-you-have-an-apple-developer-id-certificate-and-exporting-from-linux-or-windows) to add **rcodesign** notarization and your Apple tokens.
### 2. Create `GODOT_VERSION` and `EXPORT_NAME` variables
Go to your Github repository Settings > Secrets and Variables > Actions. Then, select the **Variables** tab.
Create two **Repository Variables**: `GODOT_VERSION` and `EXPORT_NAME`.
> [!NOTE]
> Repository variables will be available for this Github repository only, [but you can do more complex stuff if required](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables).
> Using variables is great, because repo admins can still see these values in Github and edit them.
Change the `EXPORT_NAME` to fit the name of your game. This will be the name of the file your players download.
By default, the workflow file is made for Godot 4.6, but you can set `GODOT_VERSION` to the version of Godot for your project. This will be used for loading container images and export templates. This workflow file uses [godot-ci](https://github.com/abarichello/godot-ci?tab=readme-ov-file) to build your game, so make sure the Godot version you're referring to is [available on Docker.](https://hub.docker.com/r/barichello/godot-ci/tags)
### 3. Copy the `build-and-publish.yml` file
Copy the file `addons/maaacks_game_template/extras/scripts/build-and-publish.yml` into the `.github/workflows` folder at the root of your github repository.
Then, push the file to github on your main branch. The workflow file will be detected by github as a Github Action.
### 4. (Optional) Edit the export platforms
The workflow file is made in two parts:
1. First, it builds your game
2. Then, it pushes the builds to itch.io
By default, the workflow file tries to build configs named `Web`, `Linux`, `macOS` and `Windows Desktop`, and will fail if one of the configs is not available.
#### Deleting a platform
If you **don't want** to export to one platform, **delete** the build jobs and the publish steps in the `build-and-publish.yml`.
For example, if you don't want to export for macOS, delete this part which builds the artifact:
```yml
export-mac:
name: macOS Export
runs-on: ubuntu-24.04
container:
image: barichello/godot-ci:${{ vars.GODOT_VERSION }}
steps:
- name: Checkout
uses: actions/checkout@v4
with:
lfs: true
- name: Setup
run: |
mkdir -v -p ~/.local/share/godot/export_templates/
mkdir -v -p ~/.config/
mv /root/.config/godot ~/.config/godot || true
mv /root/.local/share/godot/export_templates/${GODOT_VERSION}.stable ~/.local/share/godot/export_templates/${GODOT_VERSION}.stable || true
- name: Mac Build
run: |
mkdir -v -p build/mac
EXPORT_DIR="$(readlink -f build)"
cd $PROJECT_PATH
godot --headless --verbose --export-release "macOS" "$EXPORT_DIR/mac/${EXPORT_NAME}-mac.zip"
- name: Upload to GitHub Release (if this run is a release)
if: ${{ github.event_name == 'release' }}
uses: svenstaro/upload-release-action@v2
with:
file: build/mac/${{ env.EXPORT_NAME }}-mac.zip
- name: Upload Artifact
uses: actions/upload-artifact@v4
with:
name: mac
path: build/mac
```
Remove the job ID (ie. `export-mac`) from the needs of the `publish-builds` job:
```yml
publish-builds:
name: Publish Builds
needs: [export-web, export-windows, export-linux, export-mac]
```
And remove this part, which publishes it to itch.io:
```yml
- name: Upload to Itch.io - macOS
run: |
./butler push builds/mac ${{ env.ITCH_USERNAME }}/${{ env.ITCH_GAME }}:mac --userversion "${{ steps.version.outputs.version }}"
```
#### Adding a platform
If you want to export to a **new** platform, **copy paste** the build job and add a new step to itch.io publication.
In the build job, change:
1. the name of the **export config** that you created in Godot.
2. the paths in which the build artifact is created.
For example:
```yml
- name: NEW_PLATFORM Build
run: |
mkdir -v -p build/NEW_PLATFORM
EXPORT_DIR="$(readlink -f build)"
cd $PROJECT_PATH
godot --headless --verbose --export-release "BUILD_CONFIG_NAME" "$EXPORT_DIR/NEW_PLATFORM/$EXPORT_NAME.zip"
```
In the itch.io publication step, make sure to change the path and the tag.
```yml
- name: Upload to Itch.io - NEW_PLATFORM_TAG
run: |
./butler push builds/NEW_PLATFORM ${{ env.ITCH_USERNAME }}/${{ env.ITCH_GAME }}:NEW_PLATFORM_TAG --userversion "${{ steps.version.outputs.version }}"
```
## Setup Itch.io publication
### 1. Create a new project on itch.io
1. Go to [itch.io](https://itch.io/), click on the top right and **Upload a New Project**.
2. Fill in the game name and any information you want, but don't upload any file.
3. If you plan to have a **Web build**, select the **Kind of project** to be **HTML** instead of **Downloadable**.
4. Save the project as a **Draft** (you can change this to public later, once you tested that everything works).
### 2. Create `ITCH_USERNAME` and `ITCH_GAME` variables
To find your itch.io username and the name of your game, look at the url of your project: `https://your-username.itch.io/your-game`. The username is the first part of the URL, and the game name is in the last part.
Then, go to your Github repository Settings > Secrets and Variables > Actions. Then, select the **Variables** tab.
Create two **Repository Variables**: `ITCH_USERNAME` and `ITCH_GAME`.
You should have something like this (with your real username and your real game name instead, and any other repository variables):
![github variables](../media/build-and-publish/github-variables.png)
### 3. Create a `BUTLER_API_KEY` Github secret
1. Install [butler.](https://itch.io/docs/butler/installing.html) This is the official CLI tool for itch.io
2. Unzip and make sure the bin is executable
```bash
chmod +x butler
```
3. Run
```bash
butler login
```
This should open your browser. Login and allow butler to access your account.
![Authorize butler](../media/build-and-publish/authorize_butler.png)
In the terminal, the login flow will conclude with something like this:
```
Authenticated successfully! Saving key in /Users/username/Library/Application Support/itch/butler_creds...
```
**Note:** if you're already logged in into butler but forgot the path to credentials, use `butler login -h` to show the default location of `butler_creds`.
4. Get your butler API key by reading the content of this file. Beware of spaces in the filepath! This will show you a 40 characters string which is your butler API key.
```bash
cat "/Users/username/Library/Application Support/itch/butler_creds"
```
> **Warning:** your butler API key is sensitive and secret. **Do not** share it with anyone, **do not** commit it to your repository, and **do not** add it directly to the workflow file.
5. [Create a new Github secret](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets) for your Github repository. Go into Settings > Secrets and Variables > Actions and select the **Secrets** tab.
Create a new **Repository Secret** with name `BUTLER_API_KEY` (this secret will be available only in this repository). Inside, paste the 40 characters string of the previous step.
![github secrets](../media/build-and-publish/github-secrets.png)
> It's important to use Github Secrets here because their values are encrypted and hidden from everyone, even repo admins. This ensures privacy and security.
## How to publish the game?
Congrats, you're ready to create a new Github Release and automatically publish updates!
When you’re ready to publish a new version of your game, create a **GitHub release** tied to a version tag on the `main` branch. Using releases helps track updates, distribute builds, and communicate changes to players or testers.
A new release will trigger the `build-and-publish.yml` workflow, which will **build your game** in the cloud and **publish it** to itch.io (if everything is setup).
1. Ensure all desired changes are merged into the `main` branch. This is the version that'll get built and published.
2. On Github, go to **Release**, then **draft a new release** ([here is a step by step guide](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release)). Create a new tag on you `main` branch using [semantic versioning](https://semver.org/). As a best practice, also prefix it with `v` in Github.
- `x.0.0` — Major Release. Large updates or milestones (e.g., new game systems, overhauled visuals, major gameplay changes). Example: `v1.0.0` for the full launch.
- `x.y.0` — Minor Update. New content or features that expand gameplay but remain backward-compatible. Example: `v1.1.0` for new levels or mechanics.
- `x.y.z` — Patch / Hotfix. Small updates, bug fixes, performance improvements, or balancing tweaks. Example: `v1.1.3` for fixing a crash or visual glitch.
3. Publish the release. This will trigger the CICD in Github Actions. Monitor its execution and check for errors in the **Actions** tab on Github.
## Troubleshooting: Enable the HTML / Playable version of your game on itch
It may happen that you don't see the HTML version of your game as playable, but just as a file.
![no html](../media/build-and-publish/itch_html_missing.png)
What you need to do is edit your itch project to change the **Kind of project** to be **HTML** instead of **Downloadable**.
![kind of project](../media/build-and-publish/itch_kind_of_project.png)
Then, edit the `html5` channel and toggle **This file will be played in the browser**.
![html5 setting](../media/build-and-publish/itch_html_setting.png)
Going back to your project page, you should now see the HTML version of your game playable in the browser on itch.io page.
![Playable game](../media/build-and-publish/itch_playable.png)
## Next steps
Once your CI/CD pipeline is running smoothly, take it a step further:
- **Pre-Release Testing:** Add a test stage in your workflow to validate your project before publishing (for example, by running Godot unit tests or verifying builds).
- **Multi-Platform Deployment:** Add Android and iOS build, or remove the builds you don't use.
- **Other Distribution Platforms:** Adapt the CI/CD pipeline to push releases to other platforms like Steam, Google Play, App Store, Epic Games Store...
- **Add notarization for MacOS:** That's a best practice for a smoother experience.
## Sources
- **GitHub Documentation**
- [Creating a Release on GitHub](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release)
- [Using GitHub Secrets in Workflows](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)
- **Semantic Versioning**
- [Semantic Versioning 2.0.0](https://semver.org/)
- **Godot CI / Docker**
- [abarichello/godot-ci (GitHub)](https://github.com/abarichello/godot-ci?tab=readme-ov-file)
- [barichello/godot-ci Docker Hub Tags](https://hub.docker.com/r/barichello/godot-ci/tags)
- **Godot Engine Documentation**
- [Exporting for macOS (with Apple Developer ID)](https://docs.godotengine.org/en/latest/tutorials/export/exporting_for_macos.html#if-you-have-an-apple-developer-id-certificate-and-exporting-from-linux-or-windows)
- **itch.io Resources**
- [itch.io Main Website](https://itch.io/)
- [Butler CLI Installation Guide](https://itch.io/docs/butler/installing.html)

72
evolve-die-repeat/addons/maaacks_game_template/docs/Exhibiting.md Normal file
View File

@@ -0,0 +1,72 @@
# Exhibiting Games
This page covers general best practices for exhibiting your game at conventions like PAX, Gamescom, etc. You generally don't want people to just close your game and do potentially malicious stuff on the computer, especially if it is your personal computer.
## General Best Practices
- Create a separate non-admin account on your computer and use that to run the game.
- Disable the Alt-Tab shortcut in your operating system.
- Windows: Install PowerToys and use its Keyboard Manager to disable it.
## In Godot
- Create a custom [feature tag](https://docs.godotengine.org/en/stable/tutorials/export/feature_tags.html#custom-features) for an exhibition build.
- Create a autoload script that blocks quitting, sets the window mode to exclusive fullscreen, and sets the mouse mode to confined.
- Create custom actions for quitting the game.
- These can be a combination of letters that are unlikely to be pressed by a player during the game.
- Scripting an input timer can avoid an accidental press by a player from quitting the game.
- These should be kept hidden from the player.
- Create a exhibition build by adding the corresponding feature tag to a build preset.
### In the Game Template
- Hide the custom quit action(s) by setting `show_all_actions` to `false` for the `InputActionsList` and `InputActionsTree` nodes.
Update: Input Options Menu
- Disable quitting with the `ui_cancel` action using the feature tag.
Update:
- Main Menu
- End Credits
- Hide all quit buttons using the feature tag.
Update:
- Main Menu
- Pause Menu
- Overlaid Menu
- Game Won Menu
- Level Lost Menu
- Disable the fullscreen toggle.
Update: Video Options Menu
### Example
Autoload Script:
```swift
extends Node
var sum: float
func _ready() -> void:
if not OS.has_feature("exhibition"):
queue_free()
return
get_tree().set_auto_accept_quit(false)
get_window().mode = Window.MODE_EXCLUSIVE_FULLSCREEN
get_window().always_on_top = true
Input.mouse_mode = Input.MOUSE_MODE_CONFINED
func _process(delta: float) -> void:
if (Input.is_action_pressed("exh_quit_one") and Input.is_action_pressed("exh_quit_two")):
sum += delta
if sum >= 3:
get_tree().quit()
else:
sum = 0
```
Disable a quit button by checking for the additional feature flag.
Example from `end_credits.gd`:
```swift
if OS.has_feature("web") or OS.has_feature("exhibition"):
%ExitButton.hide()
```
An example implementation is available at [git.rostige-pipe.de](https://git.rostige-pipe.de/JaN0h4ck/fetziges-raetsel-spiel/commit/c65efc79e4460e88fecb8b8e81ce1edcfbbf9617#diff-32a77ee954ef131428f29b9ca647142bfaca06bf).

57
evolve-die-repeat/addons/maaacks_game_template/docs/ExistingProject.md Normal file
View File

@@ -0,0 +1,57 @@
# Existing Project
> [!WARNING]
> This page is being deprecated in favor of [Basic Setup](/addons/maaacks_game_template/docs/BasicSetup.md).
These instructions assume starting with just the contents of `addons/` and going through the installer to copy the examples content into your project. This will be the case when installing the *plugin* version in the Godot Asset Library.
To revisit any part of the initial setup, find the `Setup Wizard` at `Project > Tools > Run Maaack's Game Template Setup...`. Example files can be re-copied from the `Setup Wizard`, assuming they have not been deleted.
1. Update the project’s name in the main menu.
1. Open `main_menu_with_animations.tscn`.
2. Select the `TitleLabel` node.
3. The `Text` should match the project's name (in the project's settings).
1. If `Text` is customized, set `Auto Update` to false.
4. Select the `SubtitleLabelNode` node and customize the `Text` as desired.
5. Save the scene.
2. Link the main menu to a custom game scene (skip if using the example 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 / 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, refer to [Adding Custom Options.](/addons/maaacks_game_template/docs/AddingCustomOptions.md)
4. Update the game credits / attribution.
1. Update the example `ATTRIBUTION.md` with the project's credits.
2. Open `credits_label.tscn`.
3. Check the `CreditsLabel` has updated with the text.
4. Optionally, disable `Auto Update` and customize the text.
5. Save the scene (even if it shows no changes).
5. 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)
3. [Loading scenes asynchronously.](/addons/maaacks_game_template/docs/LoadingScenes.md)
4. [Adding icons to the Input Options.](/addons/maaacks_game_template/docs/InputIconMapping.md)
5. [Blending Music.](/addons/maaacks_game_template/docs/BlendingMusic.md)
6. [Adding UI Sound Effects.](/addons/maaacks_game_template/docs/AddingUISFX.md)
7. [Adding Custom Options.](/addons/maaacks_game_template/docs/AddingCustomOptions.md)
8. [Utilizing Game Saving.](/addons/maaacks_game_template/docs/GameSaving.md)

44
evolve-die-repeat/addons/maaacks_game_template/docs/GameSaving.md Normal file
View File

@@ -0,0 +1,44 @@
# 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 expected to be changed directly. 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.
## Internal Details
Many features provided in the example rely on the `GameStateExample` or `LevelStateExample` to work properly.
The main menu will check the current state to see if a game is in progress and show a `Continue` button. It can also optionally show a `Level Select` button if the player is at least on the 2nd level.
The `LevelManager` in the game UI scene (using `level_and_state_manager.gd`) checks the current state for the level it should load at each stage.
Lastly, the optional level select menu checks the state to determine which levels to display as options to the player.
Data is saved as a resource file in the player's local user directory.

103
evolve-die-repeat/addons/maaacks_game_template/docs/GameSceneSetup.md Normal file
View File

@@ -0,0 +1,103 @@
# 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_layer.tscn` (or `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.
The `LevelManager` manages the progress through levels. It works with a level loader and can open menus when players win or lose. With a child `SceneLister`, it manages progression linearly. Otherwise, it will rely on the levels themselves providing the path to the next level. It can either be assigned a starting level path (for open world progression) or start from the first level in a scene lister (for linear level progression).
The specific `level_and_state_manager.gd` in the scene inherits from `LevelManager` in order to sync progress with the player's `GameState`, as well.
A `LevelLoader` loads levels, attaches them to a container, and manages a loading screen. It must be provided with a `level_container` in the scene. The example uses the `SubViewport`, but any leaf node (ie. node without children) in the scene should work. An optional `level_loading_screen` in the scene can be attached to show progress of loading levels.
### Linear Level Progress
With linear progression, the path in the `starting_level_path` setting can be removed. Levels can be added to the `SceneLister` by either selecting a directory to automatically find scenes, or populating the files array manually.
If using the level select scene, then the `SceneLister` there will also need to be updated to match.
By default, the manager will open the first level from the `SceneLister`. It'll then set the checkpoint to the next level in the list when the current level is won. When winning the last level, it'll load the window for the game being won.
### Non-Linear Level Progress
Alternatively, with open world progression, the reference in the `scene_lister` setting can be removed. Instead, the path to the next level is expected to be provided by the current level. The example levels demonstrate this with the `next_level_path` setting.
By default, the manager will open `starting_level_path`. It'll then set the checkpoint to the next level sent in the `level_won` or `level_changed` signal from the current level. If no level path is provided, it'll load the window for the game being won.
### 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:
* LevelLoader
* LevelManager
* LevelLoadingScreen
The single level scene can then be added directly to the `SubViewport`, another container, or the root node.
To manage the win and lose screens and transitioning to other scenes, add a `Node` and attach the `win_lose_manager.gd` script. Inspect the node to attach the win / lose screens and paths. The `game_won()` or `game_lost()` will then need to be called when gameplay conditions are met.
## 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 `LevelManager` 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 is_on_last_level():
_load_win_screen_or_ending()
else:
_load_level_won_screen_or_next_level()
```
The `LevelManager` will need to be linked to direct back to the main menu and optionally forward to an end credits.

71
evolve-die-repeat/addons/maaacks_game_template/docs/GamesMade.md Normal file
View File

@@ -0,0 +1,71 @@
# 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
| HeartFix Express | Baking Godium | Rent Seek Kill |
| :-------:| :-------: | :-------: |
| ![HeartFix Express](/addons/maaacks_game_template/media/thumbnail-game-heartfix-express.png) | ![Baking Godium](/addons/maaacks_game_template/media/thumbnail-game-baking-godium.png) | ![Rent-Seek-Kill](/addons/maaacks_game_template/media/thumbnail-game-rent-seek-kill.png) |
| [Find on Steam](https://store.steampowered.com/app/3983290/HeartFix_Express_Demo/) | [Play on itch.io](https://maaack.itch.io/baking-godium) | [Play on itch.io](https://xandruher.itch.io/rent-seek-kill) |
## All Shared
### 2026
https://store.steampowered.com/app/3983290/HeartFix_Express_Demo/
https://store.steampowered.com/app/4029840/Zero_Warning_Burnt_Out/
https://maaack.itch.io/scout-quest
https://chippper.itch.io/hand-me-that
### 2025
https://sevadusk.itch.io/liferoot
https://maaack.itch.io/baking-godium
https://baconeggsrl.itch.io/umbra-city
https://store.steampowered.com/app/3911550/Warp_Marked_Demo/
https://maaack.itch.io/kobo-expansion
https://keur-collectif.itch.io/heartfix-express-demo
https://spacecheese.itch.io/cia
https://acul4321.itch.io/bleep
https://redspine.itch.io/gmtk-game-jam-2025
https://zunarii.itch.io/loopinball
https://dragonruler1000.itch.io/beep
https://store.steampowered.com/app/3751730/Loan_Shark/
https://parallaxrat.itch.io/no-mans-land
https://baconeggsrl.itch.io/sprouts-journey
https://maaack.itch.io/indys-expedition-2
https://maaack.itch.io/absurd-herd
https://maaack.itch.io/dungeon-fantasy-fashion-show
https://plexsoup.itch.io/factoriohno
https://maaack.itch.io/furnace-in-the-archive
https://schinken.itch.io/low-ink
### 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
### 2022
https://maaack.itch.io/rit-dot-wav
https://maaack.itch.io/supercritical-a-post-apocalyptic-bonsai

16
evolve-die-repeat/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 an autoload scene. It calls `app_settings.gd` to load all the configuration settings from the config file (if it exists) through `player_config.gd`.
- `scene_loader.tscn` is an autoload scene. 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 `player_config.gd` to keep settings persistent between runs.
- `credits_label.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_layer.tscn` (or `pause_menu.tscn`) when triggering `ui-cancel`.
- `pause_menu_layer.tscn` is a type of `OverlaidMenu` with a parent `CanvasLayer` and 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 `LevelLoader` node to load levels into a container, and `LevelManager` to manage level progress and show menus in case of a win or loss.

165
evolve-die-repeat/addons/maaacks_game_template/docs/InputIconMapping.md Normal file
View File

@@ -0,0 +1,165 @@
# 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
> [!IMPORTANT]
> Save the state of the project, and close all open scenes and scripts.
With the project open, select `Project > Tools > Run Maaack's Game Template Setup...`.
In the `Setup Wizard` window next to "Add Input Prompt Icons", click `Run`.
In the next window, select a style and then wait for the icons to download, extract, and setup.
If the icons have already been installed before, you will be presented with the option to skip re-downloading.
> [!WARNING]
> This may crash the editor.
> In that event, check if the process completed, and try running the setup again.
### 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
evolve-die-repeat/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.

64
evolve-die-repeat/addons/maaacks_game_template/docs/LoadingScenes.md Normal file
View File

@@ -0,0 +1,64 @@
# Loading Scenes
These are instructions for using the `SceneLoader` autoload to load resources asynchronously. This is especially useful for large scenes, but can be used throughout a project. The plugin comes with an example loading screen as well.
## Foreground Loading
By default, calling `SceneLoader.load_scene(path_to_scene)` will unload the current scene and replace it with a loading screen, until the next scene is fully loaded. At that point, the loading screen will be removed and replaced with the next scene.
It is intended to replace calls to `get_tree().change_scene_to_file(path_to_scene)` that open large scenes and may cause a stutter. It can also replace calls to `get_tree().change_scene_to_packed(loaded_packed_scene)`, that may require large scenes to already be loaded into memory.
## Background Loading
Calling `SceneLoader.load_scene(path_to_scene, true)` will load the scene in the background (hence the `in_background` argument being set to `true`).
There are a number of ways to then show the scene when it is ready, or even switch to foreground loading in case it is not.
### Signal When Loaded
A scene can be loaded as soon as it is ready, by listening for the `scene_loaded` signal from the `SceneLoader`.
An example of this is in `level_loader.gd` of [Maaack's Game Template](https://github.com/Maaack/Godot-Game-Template/blob/main/addons/maaacks_game_template/extras/scripts/level_loader.gd), which loads scenes in the background and displays a loading screen, but doesn't change the whole scene when the next one is ready. Instead, it loads the next level into a container.
Below is an example of reacting to `SceneLoader` signals to open the loaded scene in an optional `container` node, or switch to it entirely.
```
SceneLoader.load_scene(path_to_scene, true)
await SceneLoader.scene_loaded
if container:
# Has a container, so will open the loaded scene in it
var resource = SceneLoader.get_resource()
var instance = resource.instantiate()
container.add_child(instance)
else:
# Has no container, so will switch to the loaded scene
SceneLoader.change_scene_to_resource()
```
### On User Input or a Timed Event
A scene could load the next scene based on a timer, or when the player indicates that they are ready.
An example is in `opening.gd` of [Maaack's Game Template](https://github.com/Maaack/Godot-Game-Template/blob/main/addons/maaacks_game_template/base/nodes/opening/opening.gd), which starts loading the main menu immediately, and switches to it when its animations finish. Player's input can speed them up the animations, so by the end, if the next scene is not ready, a loading screen can be shown instead.
Below is an example of starting the load of the next scene.
```
func _ready() -> void:
# Immediately starting to load the next scene in the background
SceneLoader.load_scene(path_to_scene, true)
```
Below is an example of reacting to the player's input to either show the next scene or a loading screen.
```
func _unhandled_input(event : InputEvent) -> void:
var status = SceneLoader.get_status()
if status != ResourceLoader.THREAD_LOAD_LOADED:
# Resource is not loaded, so show the loading screen
SceneLoader.change_scene_to_loading_screen()
else:
# Resource is loaded, so switch to the loaded scene
SceneLoader.change_scene_to_resource()
```

53
evolve-die-repeat/addons/maaacks_game_template/docs/MainMenuSetup.md Normal file
View File

@@ -0,0 +1,53 @@
# Main Menu Setup
These are instructions for editing the main menu.
## Selecting a Menu
The main menu by default is `main_menu_with_animations.tscn`. The path to the main menu is set in the `AppConfig` autoload. Open the `app_config.tscn` scene, inspect the root note, and edit the `Main Menu Scene Path` to the desired scene.
Alternatively, the path to the main menu can be set directly in the following scenes:
- `opening.tscn`
- `pause_menu_layer.tscn`
- `game_ui.tscn` (`level_manager.gd`)
- `end_credits.tscn`
> [!IMPORTANT]
> Animations from 4.6 are not fully backwards compatible.
> When running, `main_menu_with_animations.tscn` will show a gray screen for Godot versions < 4.6.
> It is recommended to use the latest version of Godot, or use `main_menu.tscn` instead of `main_menu_with_animations.tscn`.
## Clear Inheritance
Most example scenes in the template inherit from scenes in `addons`. Nodes inherited from a parent scene are highlighted in yellow (by default) 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. The inheritance is useful when developing the plugin itself, but much less so for a game.
## Title and Subtitle
The title will automatically update from the project's name. If a custom title is desired, select the `TitleLabel` node, set `Auto Update` to false, and set `Text` to the custom title. The `SubTitleLabel` can be customized with the `Text` field as well, or hidden entirely.
## 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
If adding a 3D background to the menu, a 3D world node in the scene tree should normally display behind the control nodes. Using a `SubViewport` with the 3D world node attached to that adds a degree of control over scaling. Adding that into a `SubViewportContainer` provides even more fine-tune control of layering 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

35
evolve-die-repeat/addons/maaacks_game_template/docs/MovingFiles.md Normal file
View File

@@ -0,0 +1,35 @@
# Moving Files
This page covers some tips for rearranging files to an individual developer's preference.
> [!WARNING]
> Backup your project before attempting to rearrange files.
> You assume any risk.
## Move Files in the Editor
Use the editor to move files around, as this makes sure that `.uid` files get moved with `.gd` files, external resource references will get updated in `.tscn` files, and paths in project settings get updated.
UIDs do help with moving files outside of the editor, but not all scenes will have UIDs set if they've just recently been copied from the examples.
## Update File Paths
The flow of scenes in the template by default goes `Opening -> Main Menu -> Game Scene -> Ending Scene`.
The `Opening` is referenced in the project settings, and will get automatically update if moved in the editor.
The rest have their default paths stored in the `AppConfig` autoload. These do not get automatically updated, so the developer must update these paths if they change.
Alternatively, the developer can specify paths in the scenes that reference the other scenes by path. These include:
* `opening.tscn`
* `main_menu.tscn`
* `main_menu_with_animations.tscn`
* `pause_menu_layer.tscn`
* `game_ui.tscn` (`level_manager.gd`)
* `end_credits.tscn`
Any file paths in these scenes left blank will default to the values in `AppConfig`.
## Internal Details
File paths, stored as strings, do not get automatically updated by the editor when their target moves. Paths are used when asynchronous loading of scenes (ie. using `SceneLoader`) is preferred, primarily for memory management.

66
evolve-die-repeat/addons/maaacks_game_template/docs/NewProject.md Normal file
View File

@@ -0,0 +1,66 @@
# New Projects
> [!WARNING]
> This page is being deprecated in favor of [Basic Setup](/addons/maaacks_game_template/docs/BasicSetup.md).
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 accessible from the Project Manager window.
1. Finish setup.
1. Delete duplicate example files.
1. Go to `Project > Tools > Run Maaack's Game Template Setup...`.
2. In the `Setup Wizard` window next to "Delete Example Files", click `Run`.
3. In the next window, select `Yes` to continue with removing the example files.
2. Update autoload file paths.
1. Go to `Project > Tools > Run Maaack's Game Template Setup...`.
2. In the `Setup Wizard` window next to "Update Autoload Paths", click `Run`.
3. Set a default theme.
1. Go to `Project > Tools > Run Maaack's Game Template Setup...`.
2. In the `Setup Wizard` window next to "Set the Default Theme", click `Run`.
3. In the next window, select the desired theme from the preview and select `Yes` to set it as the project's default theme.
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. Select the `TitleLabel` node.
6. The `Text` should match the project's name.
1. If `Text` is customized, set `Auto Update` to false.
7. Select the `SubtitleLabelNode` node and customize the `Text` as desired.
8. Save the scene.
3. 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, refer to [Adding Custom Options.](/addons/maaacks_game_template/docs/AddingCustomOptions.md)
4. Update the game credits / attribution.
1. Update the example `ATTRIBUTION.md` with the project's credits.
2. Open `credits_label.tscn`.
3. Check the `CreditsLabel` has updated with the text.
4. Optionally, disable `Auto Update` and customize the text.
5. Save the scene (even if it shows no changes).
5. 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)
3. [Loading scenes asynchronously.](/addons/maaacks_game_template/docs/LoadingScenes.md)
4. [Adding icons to the Input Options.](/addons/maaacks_game_template/docs/InputIconMapping.md)
5. [Blending Music.](/addons/maaacks_game_template/docs/BlendingMusic.md)
6. [Adding UI Sound Effects.](/addons/maaacks_game_template/docs/AddingUISFX.md)
7. [Adding Custom Options.](/addons/maaacks_game_template/docs/AddingCustomOptions.md)
8. [Utilizing Game Saving.](/addons/maaacks_game_template/docs/GameSaving.md)

65
evolve-die-repeat/addons/maaacks_game_template/docs/OptionsMenuSetup.md Normal file
View File

@@ -0,0 +1,65 @@
# Options Menu Setup
These instructions cover customizing the options menus.
User choices persist in a user config file, and are loaded when the app opens.
## Removing Options
By default, more options are provided than are generally needed. It is recommended to hide or remove the extras.
1. Open `master_options_menu_with_tabs.tscn`.
2. Delete nodes of option scenes that do not apply to the game.
1. `Controls` is usually useful for supporting input remapping.
2. `Inputs` can be removed unless supporting a 3D camera.
3. `Audio` is usually useful.
4. `Video` is usually useful.
5. `Game` can be removed unless supporting persistant game state.
3. Open `mini_options_menu.tscn` or `[audio|visual|input|game]_options_menu.tscn` scenes to edit their options.
4. If an individual option is not desired, it can be hidden or removed entirely (sometimes with some additional work).
## Adding Options
New buttons, sliders, or editable text fields can be added that automatically persist user choices between sessions.
### To the Menu
Custom options can be added to a menu without any code.
1. Add an `option_control.tscn` node as a child to a container in a scene.
1. `slider_option_control.tscn` or `toggle_option_control.tscn` can be used if those types match requirements. In that case, skip step 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.
### To the Game
For options to have any effect outside of the menus, they will need to be referenced by their `key` and `section` from the `PlayerConfig` class.
```
PlayerConfig.get_config(key, section)
```
For example, here is how to get the player's desired input sensitivity for controlling a player camera.
```
var mouse_sensitivity : float = PlayerConfig.get_config(AppSettings.INPUT_SECTION, "MouseSensitivity", 1.0)
var joypad_sensitivity : float = PlayerConfig.get_config(AppSettings.INPUT_SECTION, "JoypadSensitivity", 1.0)
```
### Validation
Validate the values being stored in your local `player_config.cfg` file.
1. Navigate to `Project > Open User Data Folder`.
2. Open `player_config.cfg`.
3. Find the section by the section name in brackets, and the key name followed by an equals.
For example, here is how the player's desired input sensitivity could appear in the config file.
```
[InputSettings]
MouseSensitivity=1.05
JoypadSensitivity=0.95
```
> [!NOTE]
> Some settings may not appear until they have been customized.

25
evolve-die-repeat/addons/maaacks_game_template/docs/PluginSuite.md Normal file
View File

@@ -0,0 +1,25 @@
# Plugin Suite
![Plugins Suite](../media/maaacks-plugin-suite-256x256.gif)
Maaack's Game Templates are a culmination of a suite of plugins, that can be downloaded individually, if desired.
## Hierarchy
- Game Template ( [Github](https://github.com/Maaack/Godot-Game-Template) | [Asset Library](https://godotengine.org/asset-library/asset/2709) )
- Menus Template ( [Github](https://github.com/Maaack/Godot-Menus-Template) | [Asset Library](https://godotengine.org/asset-library/asset/2899) )
- Options Menus ( [Github](https://github.com/Maaack/Godot-Options-Menus) | [Asset Library](https://godotengine.org/asset-library/asset/3058) )
- Input Remapping ( [Github](https://github.com/Maaack/Godot-Input-Remapping) | [Asset Library](https://godotengine.org/asset-library/asset/4051) )
- Scene Loader ( [Github](https://github.com/Maaack/Godot-Scene-Loader) | [Asset Library](https://godotengine.org/asset-library/asset/2896) )
- Credits Scene ( [Github](https://github.com/Maaack/Godot-Credits-Scene) | [Asset Library](https://godotengine.org/asset-library/asset/2932) )
- UI Sound Controller ( [Github](https://github.com/Maaack/Godot-UI-Sound-Controller) | [Asset Library](https://godotengine.org/asset-library/asset/2897) )
- Music Controller ( [Github](https://github.com/Maaack/Godot-Music-Controller) | [Asset Library](https://godotengine.org/asset-library/asset/2898) )
- Minimal Game Template ( [Github](https://github.com/Maaack/Godot-Minimal-Game-Template) | [Asset Library](https://godotengine.org/asset-library/asset/4657) )
- Options Menus ( [Github](https://github.com/Maaack/Godot-Options-Menus) | [Asset Library](https://godotengine.org/asset-library/asset/3058) )
- Input Remapping ( [Github](https://github.com/Maaack/Godot-Input-Remapping) | [Asset Library](https://godotengine.org/asset-library/asset/4051) )
## Overview
[![All Plugins Video](https://img.youtube.com/vi/3yzaUSaROhw/hqdefault.jpg)](https://youtu.be/3yzaUSaROhw)

86
evolve-die-repeat/addons/maaacks_game_template/docs/Screenshots.md Normal file
View File

@@ -0,0 +1,86 @@
# Screenshots
1280x720 and 640x360 resolutions are shown, and resolutions up to 4k are supported.
## 1280 X 720
![Main Menu](/addons/maaacks_game_template/media/screenshot-7-main-menu-1.png)
![Input List](/addons/maaacks_game_template/media/screenshot-7-input-remapping-1.png)
![Input List - Icons Filled](/addons/maaacks_game_template/media/screenshot-7-input-remapping-2.png)
![Input Tree - Icons Filled](/addons/maaacks_game_template/media/screenshot-7-input-remapping-3.png)
![Input List - Icons Outlined](/addons/maaacks_game_template/media/screenshot-7-input-remapping-4.png)
![Input Tree - Icons Outlined](/addons/maaacks_game_template/media/screenshot-7-input-remapping-5.png)
![Audio Options](/addons/maaacks_game_template/media/screenshot-7-audio-options-1.png)
![Video Options](/addons/maaacks_game_template/media/screenshot-7-video-options-1.png)
![Credits](/addons/maaacks_game_template/media/screenshot-7-credits-1.png)
![Credits](/addons/maaacks_game_template/media/screenshot-7-credits-2.png)
![Level Tutorial](/addons/maaacks_game_template/media/screenshot-7-tutorial-1.png)
![Level](/addons/maaacks_game_template/media/screenshot-7-level-1.png)
![Level](/addons/maaacks_game_template/media/screenshot-7-level-2.png)
![Level Won](/addons/maaacks_game_template/media/screenshot-7-level-won-1.png)
![Level Lost](/addons/maaacks_game_template/media/screenshot-7-level-lost-1.png)
![Game Won](/addons/maaacks_game_template/media/screenshot-7-game-won-1.png)
![End Credits](/addons/maaacks_game_template/media/screenshot-7-end-credits-1.png)
![End Credits](/addons/maaacks_game_template/media/screenshot-7-end-credits-3.png)
![End Credits](/addons/maaacks_game_template/media/screenshot-7-end-credits-4.png)
![Loading Screen - Loading](/addons/maaacks_game_template/media/screenshot-7-loading-screen-1.png)
![Loading Screen - Still Loading](/addons/maaacks_game_template/media/screenshot-7-loading-screen-3.png)
![Loading Screen - Stalled](/addons/maaacks_game_template/media/screenshot-7-loading-screen-4.png)
![Loading Screen - Complete](/addons/maaacks_game_template/media/screenshot-7-loading-screen-5.png)
## 640 x 360
Screenshots organized by included themes.
### 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)

32
evolve-die-repeat/addons/maaacks_game_template/docs/UpdatingCredits.md Normal file
View File

@@ -0,0 +1,32 @@
# Updating Credits
These instructions cover updating the credits / attribution, both in the repo and application.
Credits are parsed automatically from the `ATTRIBUTION.md` file included with the template.
## Steps
1. Open `ATTRIBUTION.md` in a text or markdown editor.
2. Update the file with the project's credits. Refer to [Format Examples](#format-examples).
3. Save the changes and close the file.
4. Open `credits_label.tscn`.
5. Check the `CreditsLabel` has updated with the text.
1. Optionally, disable `Auto Update` and customize the text.
6. Save the scene (even if it shows no changes).
### Alternative
Optionally, `*.md` can be included for export in the _Export_ window's `Resources` tab, and steps 4-6 can be skipped, as `credits_label.tscn` will continue to update from `ATTRIBUTION.md` when exported.
## Format Examples
### Collaborators
> ### Role
> Contributor name
> [Contributor name w/ link]()
### Tools or Sourced Assets
> ### [Asset Type]
> #### Tool Name/Asset Name/Use Case
> Author: [Name]()
> Source: [Domain : webpage.html]()
> License: [License]()

40
evolve-die-repeat/addons/maaacks_game_template/docs/UploadingToItchIo.md Normal file
View File

@@ -0,0 +1,40 @@
# 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.
## Automating export and publication
You can use Github Actions to automate these steps. Look into the `.git/workflows` folder [and this guide](./BuildAndPublish.md).

14
evolve-die-repeat/addons/maaacks_game_template/docs/Videos.md Normal file
View File

@@ -0,0 +1,14 @@
# Videos
## Tutorials
[![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)
[![1.0 Release Video](https://img.youtube.com/vi/DE_6kqvT_yc/hqdefault.jpg)](https://youtu.be/DE_6kqvT_yc)
[![All Plugins Video](https://img.youtube.com/vi/3yzaUSaROhw/hqdefault.jpg)](https://youtu.be/3yzaUSaROhw)
[![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)
## Events
[![Lessons from 25+ Game Jams with Godot](https://img.youtube.com/vi/nUOAzSNmz1A/hqdefault.jpg)](https://youtu.be/nUOAzSNmz1A)