Add new file

docs/launcher/README.md

@@ -0,0 +1,47 @@
+# Boulevard Combattant Launcher
+
+## What is the launcher about?
+
+In order to allow for the end-user to properly input its preferred parameters, we needed a user interface to edit the game.set JSON configuration file (which is then parsed by the game engine to configure itself). Therefore, a launcher window providing basic configuration toggles and boxes was implemented.
+
+![Screenshot](launcher_screenshot.png)
+
+## Functionality
+
+Through this window, the end-user can set the resolution, whether or not to display the game fullscreen or windowed, how many rounds to play and whether or not to display the hitboxes in-game.
+
+Also implemented is the ability to select characters for each player and another arena. **However, this game having both a single character and a single arena, this part of the user interface has been obscured.**
+
+## Behaviour
+
+When starting the program, the launcher window pops, prompting you to enter your preferred settings. Clicking on play will hide the launcher and start a new thread containing the game engine itself. Upon thread completion (ie: the match has ended, or the player quit the game), the window will reappear.
+
+## How does it work?
+
+The launcher code is entirely comprised within the `launcher` package. There are two classes: `launcher.Launcher` and `launcher.Settings`.
+
+### launcher.Launcher
+
+This class is an extension of the `javafx.application.Application` class. As such, it operates within its own JavaFX thread, allowing it to manipulate JavaFX artifacts at will using the `@FXML` annotation tag.
+
+Any JavaFX `Application` class instance must have a `start(Stage primaryStage)` method. This method is automatically called when an instance is created. `start(...)` proceeds to load the `launcher.fxml` resource file contained in the `launcher` package. This FXML file defines a class arborescence describing a JavaFX scene to be displayed. Once loaded, this class arborescence is filled with relevant additional information, such as default values parsed by `launcher.Settings`, and item lists for `javafx.scene.control.ChoiceBox<>` instances. Then finally, the window is given attributes (title, icon, etc) and displayed via the window manager of the operating system.
+
+`launcher.Launcher` also contains additional methods to be launched through user input:
+
+* runGame(): transcribes the user inputed data to a format usable by `launcher.Settings`, asks the `launcher.Settings` instance linked to the launcher to write the game.set JSON file, hides the window and creates a new thread containing an instance of the `gameplay.match.match` class. Upon thread completion, the window is shown again.
+
+* fillArraySettings(): transcribes the user inputed data to a format usable by `launcher.Settings`.
+
+* hideWindow(): hides the launcher window.
+
+* showWindow(): shows the launcher window again.
+
+* quit(): calls `System.exit(0);`.
+
+* website(): opens the gitlab page of the project in the user's default web browser on click.
+
+* chp(): part of the obscured character select pane. Changes the character image according to the user selected character.
+
+### launcher.Settings
+
+This class is specifically made to bridge between the launcher itself, and the resulting game.set JSON configuration file. `launcher.Settings` parses game.set using `com.googlecode.json-simple`, a JSON parser for Java, upon instanciation. It also provides a `write(...)` method to write the user inputed settings to file.