Rework installation guides for 0.80

docs/gmc/installation.md

@@ -4,43 +4,13 @@ title: Installing GMC
 
 # Setup and Installation
 
-!!! note "GMC is in Early Access"
-
-    These instructions are for the early-access version of Godot MC, and require a few extra manual steps than the typical installation. You will need a functioning MPF 0.57+ project and a little patience :)
-
 !!! warning "Please use a repository"
 
-    Because GMC is in early access, you will likely be the first to encounter a scenario or request a feature. Having your project in a repository means that GMC developers can clone and run your game to quickly identify and fix issues, understand your goals, and validate requested features against your code. This is the fastest and smoothest way to make GMC better!
-
-## Create a Virtual Environment for MPF 0.80
-
-To support the new features and integrations of GMC, there is a new version of MPF in development. The first step, like with any MPF project, is to [create a virtual environment](../install/virtual-environments.md) that will keep this version of MPF and its dependencies separate from any other projects on your machine.
-
-Follow the instructions linked above and create a new virtual environment in Python 3.8-3.11. For convenience, you may want to name the environment "mpf080" or "mpfgmc". Once you've created the environment, activate it and proceed to the next step.
-
-## Download MPF 0.80 and MPF-GMC
-
-Because the GMC is not yet released, pre-built binaries are not available and must instead be run locally. You will need two Git repositories: one for MPF 0.80, and one for GMC. It's recommended to create a special folder on your computer for your Git repositories—in this example we'll create a folder called "git" in our home directory.
-
-First, clone the main MPF repository to your computer and then check out the 0.80 development branch.
-
-``` console
-  (mpf080) ~/git $> git clone https://github.com/missionpinball/mpf.git
-  (mpf080) ~/git $> cd mpf
-  (mpf080) ~/git/mpf $> git checkout 0.80.x
-```
-
-With the MPF source code on your machine, you can then use pip to install MPF. Unlike a normal pip installation, the `-e` flag instructs pip to run MPF directly from the source code rather than using a pre-compiled version. The period after the `-e` tells pip to install the package found in the current folder.
-
-``` console
-  (mpf080) ~/git/mpf $> pip install -e .
-```
+    Because GMC is brand new, you will likely be the first to encounter a scenario or request a feature. Having your project in a repository means that GMC developers can clone and run your game to quickly identify and fix issues, understand your goals, and validate requested features against your code. This is the fastest and smoothest way to make GMC better!
 
-After MPF is installed, return back up to your main git folder and clone the GMC repository.
+## Install MPF 0.80
 
-``` console
-  (mpf080) ~/git $> git clone https://github.com/missionpinball/mpf-gmc.git
-```
+Before you get working with GMC, you need to install MPF 0.80 by following the [MPF Installation Guide](../install/index.md).
 
 ## Download Godot 4
 
@@ -50,42 +20,46 @@ After Godot is installed, open the editor and create a New Project. Select your
 
 For most pinball games, *Mobile* rendering is the recommended balance between performance and featureset. If you plan to do advanced 3D graphics and complex rendering, choose *Forward+*. If you want to optimize your game to run on very low-powered hardware with limited rendering features, choose *Compatibility*. Note that you can change this setting at any time, so don't stress about it :)
 
+Finally, in your game project folder create a new folder called *addons*.
+
 !!! note "Root project vs GMC subfolder"
 
     Some users prefer to create a distinct "gmc" subfolder in their MPF machine folder, and save their Godot project there. This keeps the Godot Editor *FileSystem* tree cleaner because it's not filled with MPF config files, and can make it easier to navigate and maintain each piece independently.
 
     Note that Godot only has access to files in its project folder and below. If you choose to make a "gmc" subfolder for your Godot project, all slides, sounds, and widgets will need to be in those respective subfolders in the gmc folder (e.g. */gmc/slides/*), NOT in the MPF mode subfolders (e.g. */modes/attract/slides/*).
 
-## Setup Godot Editor
+## Install the GMC Plugin
 
-The Godot Editor includes some default configuration options that may cause headaches for users, so the following tweaks are recommended:
+### Simplest Installation: Godot Asset Library (Coming Soon!)
 
-### Indentation Setup
+The Godot editor features a built-in library of plugins that you can download and install with a single click. Unfortunately this library is managed manually by volunteers, and updating plugins can take weeks. Because GMC is changing and improving rapidly every day, it is not yet available on the Godot Asset Library.
 
-The GMC code is written with space-based indentation, but Godot not only defaults to tabs but defaults to auto-convert files. You are free to use tabs if that's your preference, but at least disabling the auto-convert will spare you grief.
+Until then, you will need to manually place the GMC plugin into your project addons folder using the Standard or Expert Installation steps.
 
-From the *Editor* menu select *Editor Settings > Text Editor > Behavior*.
+### Standard Installation: Download & Copy
 
-  *  In the *Indent* section change `Tabs` to `Spaces`.
-  *  In the *Files* section **disable** the `Convert Indent on Save` option.
+You can download the GMC plugin from the MPF-GMC repository on GitHub. Visit https://github.com/missionpinball/mpf-gmc and click on the green **Code** button to show the Code dropdown, and select *Download ZIP* to download the plugin.
 
-![image](images/editor-settings-indentation.png)
+![image](./images/gmc-download-zip.png)
 
-### Other Good Things
+Extract the downloaded ZIP file and go to the *addons* folder, where you'll see a folder named *mpf-gmc*. Copy this folder into the *addons* folder in your Godot project folder.
 
-Also in the *Editor Settings > Text Editor > Behavior* menu:
+!!! note "Manual Updates Required"
 
-  *  In the *Files* section, **enable** the `Trim Trailing Whitespace on Save` option, because it's just good practice.
-  *  If you use an external text editor like VS Code or Atom, in the *Files* section **enable** the option `Auto Reload Scripts on External Change`.
+    When downloading and copying GMC in this way, you will need to manually update the GMC to get new features and bugfixes. Just follow the above instructions again and overwrite the *addons/mpf-gmc* folder to get the newest version.
 
+### Expert Installation: Local Repository (MPF-GMC)
 
-## Place the GMC Plugin to your Project Folder
+For complete control, you can clone the MPF-GMC repository to your computer and run it directly. First, open a terminal window to the directory where you keep your Git repositories, and then clone:
 
-When GMC is officially released, it will be available to download and install with a single click from the Godot Asset Library. Until then, you will need to manually place the main folder of the GMC repository (which you cloned in a previous step) into your project addons folder.
+``` console
 
-In your game project folder, create a new folder called *addons*.
+    git clone https://github.com/missionpinball/mpf-gmc
+```
+
+You now have a copy of the MPF-GMC source code on your machine, and you need to share it with your Godot project. To update GMC, go to the repository folder in your terminal and type `git fetch` and `git pull`.
 
-### Option 1: Symbolic Links (Mac & Linux)
+#### Option 1: Symbolic Links (Mac & Linux)
 
 A symbolic link is a way to mirror one file or folder in a second location, which makes it easy to keep data synchronized. With a symbolic link from the GMC repository to your project folder, your project will always have the latest changes whenever you pull from the GMC repository.
 
@@ -106,25 +80,19 @@ When successful, you should see a new *mpf-gmc* folder in the *addons* folder yo
   lrwxr-xr-x    41 Apr  8 19:09 mpf-gmc -> /Users/tommy/git/mpf-gmc/addons/mpf-gmc
 ```
 
-### Option 2: Copy the MPF-GMC Folder (Windows)
+#### Option 2: Copy the MPF-GMC Folder (Windows)
 
 Windows does not support symbolic links in the same way, so you must manually copy the *mpf-gmc* folder from the GMC repository */addons* folder to your project *addons* folder. You'll know it's in the right place if your project root (in this example, "pinballgame") has the file path `/pinballgame/addons/mpf-gmc/plugin.cfg`.
 
 The downside of copying the folder is that you will need to manually re-copy the folder each time you download a new update to the GMC.
 
 
-## Keeping MPF 0.80 and MPF-GMC Up-To-Date
-MPF 0.80 and MPF-GMC are likely to change drastically during this period, including new features, fixes, and other changes. In order to ensure that you are experiencing the latest features, please ensure that you periodically run the following commands to get the changes to both projects. Once they are pulled into your local copy, you will immediately have access to the new features in building your game.
-
-To update MPF 0.80 run the following commands, which will show the changes or if your branch is still up to date.
+## Keeping MPF-GMC Up-To-Date
+MPF-GMC is in active development and changes frequently, including new features, fixes, and other changes. In order to ensure that you are experiencing the latest and greatest, please ensure that you periodically run the following commands to get the changes to both projects. Once they are pulled into your local copy, you will immediately have access to the new features in building your game.
 
-``` console
-  (mpf080) ~/git $> cd mpf
-  (mpf080) ~/git/mpf $> git fetch
-  (mpf080) ~/git/mpf $> git pull
-```
+If you downloaded MPF-GMC as a ZIP file from GitHub, follow those steps again and replace the old *addons/mpf-gmc* folder with the newly downloaded one.
 
-To update MPF-GMC run the following commands, which will show the changes or if your branch is still up to date.
+If you cloned the MPF-GMC repository, you need to fetch and pull:
 
 ``` console
   (mpf080) ~/git $> cd mpf-gmc
@@ -144,11 +112,11 @@ Because of how Godot processes and caches plugins and autoloads, sometimes pulli
 
     In these rare cases, exit the editor and from the Project List, remove your project from the list of saved projects. Then in your project folder delete the *.godot* folder and re-import your project.godot file into the Project List.
 
-## Install the GMC Plugin
+## Activate the GMC Plugin
 
 !!! note "There will be errors"
 
-    During this step, at various points some pieces will be setup before others and Godot will present errors. It is safe to ignore them, we will restart Godot after this step and everything will be in order.
+    During this step, at various points some pieces will be setup before others and Godot will present errors about files not found or scripts unable to be parsed. It is safe to ignore these errors for now: we will restart Godot after this step and everything will be in order.
 
 In the Godot Editor, open the *Project > Project Settings* menu and select the *Plugins* tab. You should see an option there for **Godot MC**, check the checkbox to enable the plugin.
 

docs/install/0.57.md

@@ -2,11 +2,11 @@
 title: Notes for upgrading to MPF 0.57
 ---
 
-# MPF 0.57 changes (current "dev" branch)
+# MPF 0.57 changes (current release)
 
 *Last updated October 14, 2023*
 
-The dev branch of MPF is now v0.57. (Technically `0.57.0.dev20` as of this writing, though the dev version number changes frequently.)
+The latest official release of MPF is v0.57.1, which has substantial changes from 0.56. If you are upgrading a 0.56 project, this page will provide guidance on how to do that.
 
 ## Big changes in 0.57
 

docs/install/index.md

@@ -4,21 +4,108 @@ title: Downloading & Installing MPF (2023 Version)
 
 # Installing MPF
 
-The current stable version of MPF is `0.57.x`.
 
-MPF should work with following platforms:
+The current stable version of MPF is `0.57.1`, and the upcoming release is `0.80.0`.
+
+!!! note "New MPF Coming Soon!"
+
+    The next major release of MPF will be 0.80 and is coming soon! This exciting advancement offers a brand-new media controller based on the powerful Godot game engine. If you are just getting started with MPF, consider giving 0.80 a try!
+
+MPF works with following platforms:
 
 * Windows 10 / Windows 11 (64-bit only)
 * macOS 10.14+, up through macOS 14 Sonoma (Intel & Apple Silicon)
 * Linux (64-bit, lots of distros including Debian and Ubuntu)
 * Raspberry Pi
 
-MPF 0.57 works with Python 3.8 - 3.11. It is untested on 3.12, so your mileage may vary.
+MPF works with Python 3.8 - 3.11. It runs on 3.12 but has not been extensively tested, so your mileage may vary.
+
+## Simplest Installation: Precompiled Binary (MPF 0.80)
+
+As of MPF 0.80 we are providing precompiled binaries for new users to get up and running as easily as possible. You can see all the latest binaries at the [MPF Precompiled Binaries](https://github.com/missionpinball/prepackaged-mpf-binaries/tree/main/latest) repository, but here are some links:
+
+  *  [**Mac OSX, Apple Silicon**, MPF 0.80.0.dev1 Python 3.12.3](https://github.com/missionpinball/prepackaged-mpf-binaries/raw/main/latest/mpf-0.80.0.dev1_cpython-3.12.3_darwin_arm64)
+
+  * [**Mac OSX, Intel x86**, MPF 0.80.0.dev1, Python 3.12.3](https://github.com/missionpinball/prepackaged-mpf-binaries/raw/main/latest/mpf-0.80.0.dev1_cpython-3.12.3_darwin_x86_64)
+
+  * [**Linux, x86_64**, MPF 0.80.0.dev1, Python 3.9.12](https://github.com/missionpinball/prepackaged-mpf-binaries/raw/main/latest/mpf-0.80.0.dev1_cpython-3.9.2_linux_x86_64)
+
+***Advantages of Simplest Installation:***
+
+  * Fastest way to get MPF running on a computer
+  * No installation or dependencies necessary
+  * Always has compatible Python and package versions
+
+***Disadvantages of Simplest Installation:***
+
+  * Startup times are slower than a Standard Installation
+  * Not (yet) available for all platforms
+  * No option to customize MPF or use bleeding-edge features
+
+!!! note "No, it's not actually pre-\"compiled\""
+
+    MPF is written in Python, which is an interpreted language, and therefore cannot be truly "compiled" into a binary. The provided binaries are special applications that bundle a copy of Python, the MPF framework modules, and all dependency packages into a single file.
+
+    The point is, you can download a single file and run it and have a working copy of MPF!
+
+## Standard Installation: Pip Install (MPF 0.80)
 
 Regardless of your platform or Python version, a [virtual environment](virtual-environments.md) is
-strongly recommended when working with MPF.
+strongly recommended when working with MPF unless you are using a precompiled binary.
+
+After creating your Python 3.8-3.12 virtual environment and activating it, install MPF 0.80.
+
+``` console
+
+    pip install mpf --pre
+```
+
+Now when inside your virtual environment, you can run MPF simply by typing `mpf` while in your machine folder. To update MPF, type `pip install --upgrade mpf`.
+
+***Advantages of Standard Installation:***
+
+  * Fast startup times (compared to precompiled binaries)
+  * Easy upgrading of MPF, including pre-release versions
+  * Smallest size on disk
+
+***Disadvantages of Standard Installation:***
+
+  * Requires a local Python 3.8+ installation
+  * Requires setting up a virtual environment
+  * Mistakes can pollute Pip environments and cause dependency conflicts
+  * No option to customize MPF or use bleeding-edge features
+
+## Expert Installation: Local Repository (MPF 0.80)
+
+For complete control, you can clone the MPF repository to your computer and run it directly from the source code.
+
+After creating your Python 3.8+ [virtual environment](virtual-environments.md), go to the folder where you wish to clone the MPF repository and type:
+
+``` console
+
+    git clone https://github.com/missionpinball/mpf
+    pip install -e mpf
+```
+
+Now when inside your virtual environment, you can run MPF simply by typing `mpf` while in your machine folder. Typing `pip list` will reveal that the MPF module is being run directly from the repo folder on your computer. To update MPF, navigate inside the MPF repo folder and type `git fetch` and `git pull`.
+
+
+***Advantages of Expert Installation:***
+
+  * Fast startup times (compared to precompiled binaries)
+  * Access to any version of MPF, including feature branches and forks
+  * Edit the MPF source code and see the effects immediately
+
+***Disadvantages of Expert Installation:***
+
+  * Requires a local Python 3.8+ installation
+  * Requires setting up a virtual environment
+  * Requires knowledge of Git mechanics
+  * Updates require a manual fetch and pull of the repository
+
+## Installing MPF 0.57 (Legacy MC)
 
-Here links to the installation guides for each platform:
+If you are installing MPF 0.57 to continue work on an existing MC-based project, here are links to the legacy installation guides for each platform:
 
 * [Mac](mac.md)
 * [Windows](windows.md)

docs/install/linux/index.md

@@ -4,6 +4,9 @@ title: Installing MPF on Linux
 
 # Installing MPF on Linux
 
+!!! warning "MPF 0.80 is Coming Soon"
+
+    This installation guide is for MPF 0.57 and the legacy MC, which is being replaced in the upcoming MPF 0.80 with the Godot MC. If you are just getting started with MPF, we recommend you [install MPF 0.80](../index.md) instead.
 
 ## May 2023 Update
 

docs/install/mac.md

@@ -6,6 +6,11 @@ title: Installing MPF on Mac
 
 *Last updated Mar 10, 2024*
 
+!!! warning "MPF 0.80 is Coming Soon"
+
+    This installation guide is for MPF 0.57 and the legacy MC, which is being replaced in the upcoming MPF 0.80 with the Godot MC. If you are just getting started with MPF, we recommend you [install MPF 0.80](index.md) instead.
+
+
 ## Install Python
 
 MPF 0.57 works on macOS running on both Intel and Apple Silicon (M1/M2

docs/install/windows.md

@@ -6,6 +6,11 @@ title: Installing MPF 0.56 on Windows
 
 This process walks through installing MPF 0.57 a Windows machine.
 
+
+!!! warning "MPF 0.80 is Coming Soon"
+
+    This installation guide is for MPF 0.57 and the legacy MC, which is being replaced in the upcoming MPF 0.80 with the Godot MC. If you are just getting started with MPF, we recommend you [install MPF 0.80](index.md) instead.
+
 Note that installing MPF is more complicated than a normal application.
 This is because MPF is a development tool you use to create your pinball
 software, not a finished app itself. So, like everything in pinball,