Merge branch 'main' of github.com:missionpinball/mpf-docs

docs/gmc/guides/spanning-multiple-monitors.md

@@ -0,0 +1,74 @@
+---
+title: Spanning Multiple Monitors
+---
+
+# Spanning Multiple Monitors
+
+GMC supports running multiple `MPFDisplay` parents across multiple monitors, with a little extra setup in Godot. This guide will help you setup your project to span across multiple screens so you can direct slides to a specific screen.
+
+!!! caution "Work in Progress"
+
+    Every operating system is different and we don't have the resources to test every scenerio on every system. If you are working with multiple screens, your help and feedback will be greatly appreciated to aid us in ironing out kinks and ensuring that this guide works for all cases!
+
+## Set your Project Settings
+
+Open the Project Settings menu and go to *Display > Window*, and in the upper left corner toggle on *Advanced Settings* to see additional configuration options.
+
+  * **Viewport Width / Height**: Set these to be the maximum bounding box to contain all of your displays.
+  * **Initial Position Type**: Absolute
+  * **Resizable**: Off
+  * **Borderless**: On
+  * **Window Width / Height Override**: The same as the viewport width and height
+  * **Embed Subwindows**: Off
+
+## Create a custom Window scene
+
+GMC uses a scene with an `MPFWindow` root node as the entry point for all displays and slides. There is a default *window.tscn* included in GMC that works for single-screen projects, but for a multi-screen project you'll need to create your own.
+
+In your project root */slides* folder create a new scene with `MPFWindow` as the root node and save the scene (probably as *window.tscn* but you may choose something else).
+
+The `MPFWindow` node will automatically size itself to the Viewport Width / Height defined in your Project Settings.
+
+Right-click on your new scene in the *FileSystem* window and select **Set as Main Scene**.
+
+## Create Main Display
+
+The first display will be run on the main screen, and doesn't require extra setup. In your scene tree add a new node of type `MPFDisplay` and give it a name (this name will be how it's targeted in MPF `slide_player`).
+
+In the *Inspector* panel set `is_default` to true and select an initial slide. For most use cases, the default GMC initial slide will work (*/addons/mpf-gmc/slides/startup.tscn*). Expand the *Layout > Transform* section and set the size to be the dimensions of the main monitor.
+
+## Create a Window Container
+
+The second display will run on a separate monitor, so Godot must be configured to generate a new application window on that monitor.
+
+Under your main Window root node, create a new node of type `Window` (just the default Godot `Window`, not the custom GMC `MPFWindow`).
+
+In the *Inspector* panel, set the following:
+
+  *  **Initial Position**: Absolute
+  *  **Size**: The dimensions of the screen
+  *  **Position**: The coordinates from the top-left of the main monitor
+
+Under the *Flags* dropdown, set the following:
+
+  * **Transient**: On
+  * **Unresizable**: On
+  * **Borderless**: On
+
+Now create a new `MPFDisplay` child node of this `Window`. Set the same Initial Slide as the other, and under *Layout > Transform > Size* set the dimensions of the second monitor. Give this node a name that you will reference in MPF to target it.
+
+In the Editor scene view, you should now see two copies of the MPF logo, one for each display.
+
+## Configure Slides in MPF
+
+In your MPF config files, you can now target a specific display using the name of the `MPFDisplay` nodes. Whichever node is tagged as default does not need a target, but you can provide one for clarity. If your main display node is named "primary" and your other node is named "mini-display" then you could setup your attract mode like this:
+
+``` yaml
+
+    slide_player:
+        mode_attract_started:
+            attract_main_slide:
+                target: primary
+            attract_mini_slide:
+                target: mini-display
+```

docs/gmc/reference/mpf-event-handler.md

@@ -0,0 +1,34 @@
+---
+title: MPFEventHandler
+summary: A GMC Node for handling MPF events directly in Godot
+---
+
+# MPFEventHandler
+
+`MPFEventHandler` is a Godot Node class provided by GMC that creates BCP event subscriptions to trigger behavior based on arbitrary MPF events.
+
+## Node Configuration
+
+An `MPFEventHandler` can be placed anywhere in your scene, but must be either the direct parent or direct child of the nodes that will handle the event callback.
+
+### event_name:
+
+Single value, type `String`
+
+The name of the MPF event that this handler will subscribe to. If no BCP trigger is established for this event, one will be created on instantiation and removed when the node is destroyed.
+
+### handler_direction:
+
+Single value, one of `Parent` or `Children`. Default `Parent`
+
+Controls whether the `MPFEventHandler` triggers behavior on its parent node or on its children nodes.
+
+If set to `Parent`, the `call_method` callable will be invoked on the direct parent of the `MPFEventHandler` node. If the parent does not have a callable by the specified name, a warning will be logged.
+
+If set to `Children`, the `call_method` callable will be invoked on every direct child of the `MPFEventHandler` node. If a child does not have a callable by the specified name, it will be logged.
+
+### call_method:
+
+Single value, type `String`
+
+The name of a Callable (function) on the parent or child nodes that will be called when the event triggers. The event arguments will be passed to the callable as a dictionary.

mkdocs.yml

@@ -622,8 +622,9 @@ nav:
       - MPFChildPool: gmc/reference/mpf-child-pool.md
       - MPFConditional: gmc/reference/mpf-conditional.md
       - MPFConditionalChildren: gmc/reference/mpf-conditional-children.md
-      - MPFLogger: gmc/reference/mpf-logger.md
       - MPFDisplay: gmc/reference/mpf-display.md
+      - MPFEventHandler: gmc/reference/mpf-event-handler.md
+      - MPFLogger: gmc/reference/mpf-logger.md
       - MPFSlide: gmc/reference/mpf-slide.md
       - MPFSoundAsset: gmc/reference/mpf-sound-asset.md
       - MPFVariable: gmc/reference/mpf-variable.md
@@ -639,6 +640,7 @@ nav:
       - Random Sound Pools: gmc/guides/random-sound-pools.md
       - Random Slide Children: gmc/guides/random-slide-children.md
       - Bonus Mode Slide: gmc/guides/bonus_mode.md
+      - Spanning Multiple Monitors: gmc/guides/spanning-multiple-monitors.md
       - Display Filter Effects: gmc/guides/window-filters.md
       - Advanced Custom Code: gmc/guides/advanced-custom-code.md