Godot 4 Jam Template

Quick start template for game jams built on hatmix/godot-4-ci. See the plain template in action at https://hatmix.itch.io/godot-4-jam-template (try password gwj70).

Features:

• Github template repository vs. addon
• Web, Windows, Linux and macOS exports for maximum jam
• Premade basic UI for main menu, pause menu, credits, and settings
• Visualization of controls with built-in remapping
• Settings persisted across sesssions (where user:// filesystem is writable)
• Keyboard and controller support for all template UI, touchscreen via Godot's emulate mouse from touch setting
• UI transition animations with Simple GUI Transitions
• ATTRIBUTION.md for in-game credits (inspired by Maaack's approach)
• Addon management with gd-plug
• CI/CD for automatic Itch.io updates adapted from abarichello/godot-ci

Don't just settle for the first template you find! Compare the alternatives and decide which best fits your desired feature set, coding style, and approach to game development.

Alternatives:

• https://github.com/Maaack/Godot-Game-Template
• https://github.com/bitbrain/godot-gamejam
• https://github.com/nezvers/Godot-GameTemplate
• And many more...

Initial setup

After cloning or templating the repo, it's necessary to install plugins. Plugins are managed with gd-plug. To install plugins from the Godot editor use gd-plug-ui. Or, plugins can be installed with the command line.

godot.exe -s plug.gd install

Starting Godot twice after installing plugins this way should fix any errors on startup--once to build the import cache and a second time for plugins to load properly. Skip saving changes between restarts or plugins may need to be re-enabled. Run the project and verify everything is working correctly.

Main

Once plugins are installed and activated, open res://main.tscn and res://main.gd and create your game!

UI

Most of this template's work is done in the UI scenes under res://ui/.... The Simple GUI Transitions addon uses a "layout" concept for showing and hiding UI elements. A layout might be an entire screen or just a widget in the corner. The main UI scene includes the layouts for all of the template's menus, a skeleton in-game UI, and Maaack's ProjectUISoundController.

The intended approach is to keep all UI in res://ui/ui.tscn and instantiate it as a child of every other scene. This is just preference and it could be changed any number of ways. Simple GUI Transitions will discover its layouts wherever they are in the scene tree. It's also extremely flexible and much more could be done with its features.

The top-level UI is set PROCESS_MODE_ALWAYS with children inheriting the mode. The InGameMenuOverlay will appear when get_tree().paused == true. In games where pausing the tree should not hide the game area, either remove that node or have the PauseMenu show and hide the overaly.

Folder structure

Each UI layout is contained in its own directory under res://ui. The assets folder is for non-scene/non-code files used in the UI. The game folder and its scene are intended for the UI (HUD) shown in gameplay only and I recommend creating a res://game directory to hold other game files.

├───autoloads
├───tests
└───ui
    ├───assets
    │   ├───audio
    │   ├───fonts
    │   └───icons
    │       ├───input_devices
    │       └───notifications
    ├───controls
    ├───credits
    ├───game
    ├───main_menu
    ├───notifications
    ├───pause_menu
    └───settings

Settings and Controls

Actions not starting with "ui_" or "editor_" will be listed in the controls UI. If there are no actions defined, a default set of ui_ actions will be shown. The default set is just for testing and changes to those actions will not persist.

Settings are saved automatically in user://settings.cfg and control mappings in user://controls.tres. Saving and loading are handled by res://autoloads/settings.gd.

Tests

GUT is used for testing. The tests/ folder contains the (too little) test code. One benefit of too little test code is you lose very little if you want to use another framework, like gdUnit4.

CI/CD

Github actions are used to run the tests on every push to source control. The Github build environment is limited compared to the desktop Godot editor. Tests relying on the following features should use the skip_script variable to avoid tests failing under CI.

• DisplayServer
• Input (depends on DisplayServer)

On succesful test and export, and if configured, the CI action uses butler to deploy the game to itch.io. Setup these secrets in your Github repository to enable push:

• ITCHIO_USERNAME
• ITCHIO_GAME
• BUTLER_API_KEY