Merge pull request #596 from bosh/high_score_tags

add switch tag information for 0.80 high_score mode text_input binding support

Author: bosh

docs/config/instructions/tags.md

@@ -171,11 +171,18 @@ For the full reference of Ball Device tags, see [ball_devices:tags](../ball_devi
 
 ### Switch Tags
 
-Switches in particular have a wide variety of built-in behaviors provided by MPF. Features such as flipper cancel and automatic ball detection on playfields will automatically work if you include these tags. To see the full reference, visit [switches:tags](../switches.md#tags).
+Switches in particular have a wide variety of built-in behaviors provided by MPF.
+Features such as flipper cancel, automatic ball detection on playfields,
+and high_score text input selection will automatically work
+if you include the appropriate tags on your switch configurations.
+To see the full reference, visit [switches:tags](../switches.md#tags).
 
 ### Playfield Tags
 
-If your game has a single playfield, it should have the tag "default" set in its config. If your game has multiple playfields, one of them will need to be tagged as default - usually it will be the one that the plunger lane most frequently ejects to. See: [playfields:tags](../playfields.md#tags).
+If your game has a single playfield, it should have the tag "default" set in its config.
+If your game has multiple playfields, one of them will need to be tagged as default -
+usually it will be the one that the plunger lane most frequently ejects to.
+See: [playfields:tags](../playfields.md#tags).
 
 
 ## Using `*` for a catch all

docs/config/switches.md

@@ -269,6 +269,8 @@ consumed by something, e.g. `light_player` or if `debug:true` is defined
 for them. They will be posted regardless of the `debug` setting, it is
 only a question of visibility in the `mpf monitor`.
 
+#### Built-in Tags
+
 Special-purpose tags for switches include:
 
 * `playfield_active` - This tag should be used for all switches on the
@@ -285,15 +287,52 @@ Special-purpose tags for switches include:
     (Note that in MPF, the game start process is kicked off when this
     switch is released, not pressed, which allows the "time held down"
     to be sent to MPF to perform alternate game start actions.) See: [Start Button](../tutorial/9_start_button.md).
+    With MPF 0.80, the `start` tag is used by the high_score mode to select a letter or submit the name text.
 * `left_flipper` and `right_flipper` - MPF will provide automatic [flipper_cradle](../events/flipper_cradle.md)
     and [flipper_cancel](../events/flipper_cancel.md) events if your cabinet flipper buttons are tagged with
-    their respective flippers.
+    their respective flippers. With MPF 0.80, the built-in high_score mode and slide hook onto these two flipper tags
+    to control character selection and submission.
+
+#### Tags for optional built-in modes
+
+Some of the default modes included with MPF include switch tag hooks so that it is easy for you to incorporate features into your game.
+
+##### Tilt Mode
+
+MPF's default tilt mode supports both slam tilt and plumb-bob tilt detection, either or both tags may be used.
+See: [Tilt](../game_logic/tilt/index.md)
+
+* `tilt_warning` - This is added to a plumb-bob style tilt switch.
+* `slam_tilt` - This is added to a slam tilt type switch. 
+
+##### High Score Mode
+
+(*tag support new in MPF 0.80*)
+
+The built-in [high_score mode](../game_logic/high_scores/index.md) in MPF 0.80 and high_score slide in GMC allow players
+to select letters and submit their high score via use of an [MPFTextInput](../gmc/reference/mpf-text-input.md) in Godot.
+
+* `left_flipper` and `right_flipper` - These tags are reused by the high score text input to move
+    the highlighted item left or right
+* `start` - The start tag is reused by the high score mode to select the highlighted item
+
+##### Service Mode
+
+The Service Mode code included with MPF is intended for four-button service doors
+and has support for coin door detection and other features. The way this works is
+through a variety of tags, including the re-use of some existing tags.
+See: [Service Mode](../game_logic/service_mode.md)
+
 * `service_esc`, `service_down`, `service_up`, and `service_enter` - When using the builtin
     Service Mode, you will want to tag four different switches with these tags so the
-    operator can use the interface without keyboard or mouse access. See: [Service Mode](../game_logic/service_mode.md)
-* `service_door_open` - This is used for the coin door switch to manage the service mode. See: [Service Mode](../game_logic/service_mode.md)
-* `tilt_warning` - This is added to a plumb-bob style tilt switch. See: [Tilt](../game_logic/tilt/index.md)
-* `slam_tilt` - This is added to a slam tilt type switch. See: [Tilt](../game_logic/tilt/index.md)
+    operator can use the interface without keyboard or mouse access.
+* `service_door_open` or `service_door_closed` - Service mode will hook into
+    the open or closed detection behavior of your coin door switch if you include
+    one of these tags. Only one is necessary, but both are available depending on
+    whether your switch is normally open or normally closed.
+* `start`, `left_flipper`, and `right_flipper` - Service mode will reuse these three tags
+    that you likely already had defined for other machine features. (See section above.)
+
 
 ## Monitorable Properties
 

docs/gmc/reference/mpf-text-input.md

@@ -85,17 +85,22 @@ If no settings are provided, the `character_appearance` will be applied to the s
 
 ## Events and MPF Integration
 
-To control the on-screen keyboard from the pinball machine, an `event_player` must be setup that sends the event *"text_input"* with an appropriate `action` value (one of "left", "right", or "select").
+The MPFTextInput included in the default [high_score mode](../../game_logic/modes/high_score.md) has event controls already defined.
+These included event_player bindings use the standard flipper and start tags to control the input. If you are adding an MPFTextInput on your own
+to some other slide, or if you want to add more buttons to control the selected items on the high score slide,
+you will need to create a way to post *`text_input`* events with the appropriate `action` value.
+
+For example, to allow more switches to control the on-screen keyboard, you could define an `event_player` that sends the event *"text_input"* with one of the three supported `action` values ("left", "right", or "select").
 
 ``` yaml
 event_player:
-  s_flipper_left_active:
+  s_my_additional_left_control_active:
     text_input:
       action: left
-  s_flipper_right_active:
+  s_my_additional_right_control_active:
     text_input:
       action: right
-  s_start_button_active:
+  s_another_select_button_active:
     text_input:
       action: select
 ```