Mixed-Media-Bundle-Launcher

What is it?

This Godot 3 project is an easy-to-edit jumping off point for making a launcher to make your game/file/whatever bundles look more professional. As the name implies it can launch pretty much anything you throw at it, all in one consistent looking animated package.

The MM Bundle Launcher configured to run windows games from Indiepocalypse Zine issue #1.

https://www.youtube.com/embed/PsbcywH_quk

The MM Bundle Launcher running the example project. See it for yourself by going to the projects itch.io page and downloading compiled & assembled example project .

https://www.youtube.com/embed/4GafFLNjFHc

What can it do?

It can:

launch exe files
open files using default app
run an emulator with the game already loaded and ready to play
open folders in file explorer
be used with a controller

At the moment it can't:

have multiple files per one cover on the carousel
have submenus
show files in a non carousel view
emulate non Gameboy consoles without prior modifications

Things listed above can be added or changed if you are ready to tweak the source code a bit.

Documentation and Instructions

[TOC]

This documentation accurately describes the project as it was on 4th of May 2021.

If you are planning to contribute to the project please document the features you add here.

If you believe the tutorial below to be not good and believe you can improve on it - please do so by submitting a pull request on the git repo.

Set up the environment

Skip this section if you have experience working with Godot and have the latest version + export templates already installed. If not - follow the steps below.

Download the latest stable release of Godot Engine(33.8MB). Get the standard version, NOT Mono.
Download the source files for this project(1.5MB) and if you feel like it - the example(80.3MB).
Run Godot, on the right hand side click Scan and select the src folder you downloaded. If everything went right you should see a new project appear.
Open the Launcher project. It should load into Launcher.tscn by default. This is how it should look if everything went right (except your interface will be dark gray/blue).
Look at the top-left side of the screen. Under Editor > Manage Export Templatesand download the export templates for the current version (this might take a while)

Extra info if you are new to Godot:

Click on a node in the Scene hierarchy window on the left side, then look at the Inspector window on the right side to see and change its parameters.
To preview how the project will look click on the play button in the top-right (above Inspector).
You can drag and drop files from the FileSystem window on the bottom-right into the scene as well as into relevant fields in the Inspector window.

If everything went right you should be all set up now!

Exporting the launcher

To test if it is able to launch the files that you specified and prepare the launcher for release and distribution you will need to export it. To do it, in the top right go to Project > Export.... Select the preset that is already there and click Export Project. It should be done in a second or two.

Adding your games to the launcher

Structure

In Launcher.tscn the Carousel node of is a parent to many instances of Game.tscn.

Each Instance represents one game cover on the carousel. The Script Variables of each of these nodes(found in the Inspector on the right) contain the information you will need to tweak to replace the examples with your own stuff.

The names of the nodes do not do anything and can be whatever.

The order in which they are shown in the scene hierarchy is important and determine where they will be on the carousel.

Variables

For each cover you want to be presented in the launcher you will need to fill out the information displayed to the user.

Write the name of the game in Game Name
Write the name of the author in Author Name, the launcher will then display "by [author name you wrote]"
Add the images you want to use as covers to the project folder.
Drag and drop the image file you want to be the cover from File System window into the Cover field.
If the image is not upright and you want to change that select the appropriate option from the Rotate dropdown menu.
Select the appropriate Game Type from the dropdown, this will determine how the next variable is treated. More about what each game type means can be found below.
Input the path to the file you want to execute/open in the File To Run field. More info on how this data should be formatted can be found below.

Keep in mind that changing these variables will not cause any immediate change in what you see in the editor. You need to run the project to see how it will look.

Breakdown of what each variable will change and how it will look for the user.

Variable Name	What it do
Game Name	What is displayed in a large bold font over the cover when it is in front of the user
Author Name	Second line displayed above cover is "by `Author Name`"
Cover	Image used as game cover. Can be of any resolution and aspect ratio, the launcher will scale it to look reasonable. Most formats are supported, details can be found here.
Rotate	If using zine pages as covers - some of them can be intended to be read in landscape mode. This dropdown eliminates the need to open an image editor. Handy free tool to convert PDF pages to PNGs in bulk.
Game Type	Changes the third line displayed above the cover as well as the way the launcher treats the file provided in `File To Run`. How to change these will be described in detail later.
File To Run	Relative path from the compiled .exe of the launcher to the file you intend this cover to launch. Details below.

File Paths and how to use them

Paths to the app/file you want to open/run can be relative or absolute. I recommend using relative paths if you intend to share the launcher with other people as it is not relying on the user unpacking the bundle in a specific spot. Lets examine the relative paths from Launcher.exe in the provided example.

Folder structure of example

Launcher Example
┣━A folder
┃ ┣━Folder inside a folder
┃ ┃ ┣━yo-grl
┃ ┃ ┃ ┣━info.txt
┃ ┃ ┃ ┗━yo-grl.gb
┃ ┃ ┗━TEXTREME.exe
┃ ┗━example_video.mp4
┣━GB Emulator
┣━example pdf file.pdf
┗━Launcher.exe

What the launcher will do	`File To Run` variable	`Game Type` variable
open `example pdf file.pdf`	example pdf file.pdf	link/pdf/html/other file
open `example_video.mp4`	A folder\\example_video.mp4	link/pdf/html/other file
run `TEXTREME.exe`	A folder\\Folder inside a folder\\TEXTREME.exe	windows exe
run `yo-grl.gb` in a Gameboy emulator	A folder\\Folder inside a folder\\yo-grl\\yo-grl.gb	gameboy rom
open `Folder insdie a folder` in file explorer	A folder\\Folder inside a folder	link/pdf/html/other file
open `itch.io` in browser	https://itch.io	link/pdf/html/other file

Keep in mind that to test if your launcher is able to launch the things you want it to it first has to be exported and placed in the folder where the files it will launch/folders containing those files are located (Done through Project > Export in the top right).

Making your launcher sexy

If you got this far you probably already have a functioning launcher but it still doesn't fit the theme of your bundle or your personal style. Not to worry, the appearance shouldn't be hard to change!

Fonts

Make sure to drop the fonts you want to use into the project folder in .otf or .ttf format.

Game title

Open Game.tscn, find the TextInfo > GameName node. In the inspector scroll down until you see the Custom Fonts tab. Inside you will find a font resource, click on it. You should now see this. Drag and drop your new font into Font Data and change other variables until you are satisfied. You can change the color of the letters in the Custom Colors tab below.

Author and file type

In Game.tscn edit the parameters of the TextInfo > ExtraInfo node.

Control instructions

In Launcher.tscn edit the parameters of the Controls node.

Other Visuals

Background

In Launcher.tscn edit the children of Background. You can use sprites or a tiled TextureRect node. Simple effects can be applied to it using ColorRect nodes/other images with CanvasItemMaterial set to different mixing modes. If you already know how to use Godot I'm sure you can come up with some fun shaders or animations to put there.

IMPORTANT DETAIL Project is currently configured in a way where the users with any monitor size and aspect ratio will see the same amount of the scene vertically. If the user has a 4:3 aspect ratio they will not see the sides of what is in the thin blue border. If they have an ultra wide monitor they will see beyond the thin blue border. Because of this please make sure to add a bit of padding around what the camera would normally see.

Quit Launcher Pop-Up

In Launcher.tscn edit the children of Exit Popup. Everything inside of that node is purely decorative and can be changed however you want.

Tint on game cover

In Launcher.tscn edit the parameters of Carousel. The covers are tinted the colour of Far Tint * Unselected Tint when they are on the furthest point of the carousel from user. They are tinted the colour of Unselected Tint when they are on the closest point of the carousel. They are not tinted at all when they are selected (located in the front of carousel and in the middle of your screen). Tint can be removed by setting tint colours to white.

Sounds

Background music

In Launcher.tscn change the Straem parameter in the Music node to a .ogg file of your choice.

Moving the carousel

In Launcher.tscn change the Stream parameter in the Move node to a .wav file of your choice.

Open/Close exit popup

In Launcher.tscn change the Stream parameters in the PopupSound and PopupClose nodes to a .wav file of your choice.

Launching a game

In Game.tscn change the Stream parameter in the Success node to a .wav file of your choice.

Nothing to launch

In Game.tscn change the Stream parameter in the Failure node to a .wav file of your choice.

Select game

In Game.tscn change the Stream parameter in the Select node to a .wav file of your choice.

Advanced Fuckery

Inner workings

Game Type	What it does
no file	does nothing and plays a disappointed sound
windows exe	Asks OS to run the given file with no arguments OS.execute(file_to_run, [], false)
link/pdf/html/other file	Sends a URI to open to the OS OS.shell_open(file_to_run)
gameboy rom	Asks OS to run the emulator with the provided ROM as an argument OS.execute("GB Emulator\bgb.exe", ["-rom", file_to_run], false)

current implementation of console emulation is not good, this will be fixed in the nearest future.

Emulating other consoles

Find an emulator for your console of choice that:

You can legally package with your bundles
Can be run from console with game file to emulate as an argument

Open Game.gd, edit line with game_type export var.

export (int, "no file", "windows exe", "link/pdf/html/other file", "gameboy rom", "new console to emulate") var game_type

edit the match game_type: in func _ready():

match game_type:
		0:
			# no exe
			$TextInfo/ExtraInfo.text += "no compatible file available"
			pass
		1:
			# exe
			$TextInfo/ExtraInfo.text += "a Windows executable"
			pass
		2:
			# pdf/html
			$TextInfo/ExtraInfo.text += "opens a file"
			pass
		3:
			# gb rom
			$TextInfo/ExtraInfo.text += "GameBoy ROM that runs in emulator"
			pass
		4:
			# new console to emulate
			$TextInfo/ExtraInfo.text += "Game emulated in my new console"

edit the match game_type: in func play():

	match game_type:
		0:
			# nothing to run
			$Failure.play()
			pass
		1:
			# exe
			OS.execute(file_to_run, [], false)
			$Success.play()
			pass
		2:
			# pdf/html/other file
			OS.shell_open(file_to_run)
			$Success.play()
			pass
		3:
			# gb rom
			OS.execute("GB Emulator\\bgb.exe", ["-rom", file_to_run], false)
			$Success.play()
			pass
		4:
			# new console to emulate
			OS.execute("relative path to new emulator", 
					[arguments to run file_to_run as array of strings], false)
			$Success.play()

cis-ash/MM-Bundle-Launcher