freezy · freezy · Sep 15, 2022 · Aug 14, 2022 · Aug 21, 2022 · Aug 23, 2022
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,8 @@
 Built with Unity 2021.3.0
 
 ### Added
+- Documentation for score reels.
+- Score Motor Component ([#435](https://github.com/freezy/VisualPinball.Engine/pull/435), [Documentation](https://docs.visualpinball.org/creators-guide/manual/mechanisms/score-motors.html)).
 - Scale support for rubbers.
 - Slingarm coil arms can now be any game objects, not just primitives ([#432](https://github.com/freezy/VisualPinball.Engine/pull/432)).
 - Gate Lifter Component ([#418](https://github.com/freezy/VisualPinball.Engine/pull/418), [Documentation](https://docs.visualpinball.org/creators-guide/manual/mechanisms/lifting-gates.html)).

diff --git a/VisualPinball.Unity/Assets/Editor/Icons/large_colored/display_event.png b/VisualPinball.Unity/Assets/Editor/Icons/large_colored/display_event.png
diff --git a/VisualPinball.Unity/Assets/Editor/Icons/large_colored/display_event.png.meta b/VisualPinball.Unity/Assets/Editor/Icons/large_colored/display_event.png.meta
diff --git a/VisualPinball.Unity/Documentation~/creators-guide/manual/displays.md b/VisualPinball.Unity/Documentation~/creators-guide/manual/displays.md
@@ -1,5 +1,6 @@
 ---
-gui: displays
+uid: displays
+title: Displays
 description: How VPE handles dot matrix and segment displays.
 ---
 # Displays
@@ -24,12 +25,10 @@ For example, in [MPF](xref:mpf_index) you name your displays yourself in the mac
 
 <img src="display-add-component.png" width="243" alt="Add display component" class="img-responsive pull-right" style="margin-left: 15px"/>
 
-VPE provides two display components, one for segment displays and one for DMDs. Both components create the underlying geometry and apply a shader that renders the content of the display. In order to create one, make an empty game object in your scene and add the desired component under *Visual Pinball -> Display*.
+VPE provides three display components, a [score reel](xref:score-reels), a segment display and a DMD. Both the segment display and the DMD component create the underlying geometry and apply a shader that renders the content of the display. In order to create one, make an empty game object in your scene and add the desired component under *Visual Pinball -> Display*.
 
 You can also create the game object with a component already assigned by right-clicking in the hierarchy and choosing *Visual Pinball -> Dot Matrix Display*. This will place the display into your scene right behind your playfield.
 
-Since score reels come with additional geometry and textures, VPE provides them as prefabs through the asset library.
-
 <img src="display-dmd-inspector.png" width="354" alt="DMD Inspector" class="img-responsive pull-right" style="margin-left: 15px"/>
 
 Selecting the game object will let you customize it in the inspector, and assign the ID that links it to the gamelogic engine.

diff --git a/....Unity/Documentation~/creators-guide/manual/mechanisms/score-motor-gottlieb.png b/....Unity/Documentation~/creators-guide/manual/mechanisms/score-motor-gottlieb.png
diff --git a/...Unity/Documentation~/creators-guide/manual/mechanisms/score-motor-inspector.png b/...Unity/Documentation~/creators-guide/manual/mechanisms/score-motor-inspector.png
diff --git a/...ll.Unity/Documentation~/creators-guide/manual/mechanisms/score-motor-schema.jpg b/...ll.Unity/Documentation~/creators-guide/manual/mechanisms/score-motor-schema.jpg
diff --git a/...ity/Documentation~/creators-guide/manual/mechanisms/score-motor-score-event.png b/...ity/Documentation~/creators-guide/manual/mechanisms/score-motor-score-event.png
diff --git a/.../Documentation~/creators-guide/manual/mechanisms/score-motor-score-variable.png b/.../Documentation~/creators-guide/manual/mechanisms/score-motor-score-variable.png
diff --git a/.../Documentation~/creators-guide/manual/mechanisms/score-motor-switch-manager.png b/.../Documentation~/creators-guide/manual/mechanisms/score-motor-switch-manager.png
diff --git a/...Documentation~/creators-guide/manual/mechanisms/score-motor-uvs-reset-score.png b/...Documentation~/creators-guide/manual/mechanisms/score-motor-uvs-reset-score.png
diff --git a/...Documentation~/creators-guide/manual/mechanisms/score-motor-uvs-score-event.png b/...Documentation~/creators-guide/manual/mechanisms/score-motor-uvs-score-event.png
diff --git a/...umentation~/creators-guide/manual/mechanisms/score-motor-uvs-update-display.png b/...umentation~/creators-guide/manual/mechanisms/score-motor-uvs-update-display.png
diff --git a/...ocumentation~/creators-guide/manual/mechanisms/score-motor-uvs-update-score.png b/...ocumentation~/creators-guide/manual/mechanisms/score-motor-uvs-update-score.png
diff --git a/...alPinball.Unity/Documentation~/creators-guide/manual/mechanisms/score-motors.md b/...alPinball.Unity/Documentation~/creators-guide/manual/mechanisms/score-motors.md
@@ -0,0 +1,97 @@
+---
+uid: score-motors
+title: Score Motors
+description: Simulate EM reel timing during gameplay
+---
+
+# Score Motors
+
+Score motors are used in electro-mechanical games to add points to a player's score. They consist of multiple cams that are stacked on top of each other. Each cam has different patterns around the edges, and switches sit at different positions in order to open or close at specific times when the motor runs and thus the cams rotate.
+
+![Photo and schema of a score motor](score-motor-schema.jpg)
+<small>*A typical score motor, found in Gottlieb and early Bally machines.*</small>
+
+The score motor assembly sits typically at the bottom of the cabinet. The produced switch sequences are used when the game needs to do several things in a specific order. Although its main purpose is triggering the score reel relays, it is often used to drive other mechanisms as well.
+
+## Scoring in an EM
+
+There are two different modes of operation:
+
+1. The player scores **single points**, e.g. one, ten, hundred, and so on. In this case, a pulse is directly sent to the coil driving the corresponding score wheel, which increases its position by one.
+2. The player scores **multiple points**, like five, twenty, or 300. In this case, the score motor starts and the appropriate numbers of coil pulses are triggered by the switches around cams. For example, if a player scores fifty points, the score motor runs and enables the ten point relay to pulse five times. With each pulse of the ten point relay, the 10's score reel coil fires, which advances the score reel one position. 
+
+Another property of a score motor is that it has no state, i.e. it doesn't know the actual score. This means that while the motor is running and the player scores *multiple* points, they are ignored. For *single* points, it depends on the machine, some allow single-point scoring while the motor is running, some don't.
+
+> [!NOTE]
+> For an in-depth look at score motors, check out the fantastic article [Animated Score Motor circuits from EM Pinball Machines](https://www.funwithpinball.com/learn/animated-score-motor-circuits) at [Fun With Pinball](https://www.funwithpinball.com/).
+
+## Player Experience
+
+The way the scoring works results in a very particular timing of when exactly the score reels move during the game. Since in most games, chimes and bells are fired when the reel position changes, the player not only sees, but also hears these patterns. This means that accurate timing is essential for an authentic gaming experience.
+
+# Setup
+
+VPE provides a component that accurately simulates the behavior described above. It handles score resets and add points, all while performing accurate timing that can be specified by the table author.
+
+To setup a score motor, select any game object, click on *Add Component* in the inspector and select *Visual Pinball -> Mechs -> Score Motor*.
+
+Next, configure the score motor. The inspector shows the following options:
+
+<img src="score-motor-inspector.png" width="363" class="img-responsive pull-right" style="margin-left: 15px">
+
+- **Steps** defines how many steps the score motor pulses for one turn.
+- **Duration** defines the length of time it takes the score motor to completely cycle.
+- **Block Scoring** defines if single point scoring is blocked **while the score motor is running**. As mentioned before, multiple point scores are always blocked while the score motor is running.
+- **Increase by #** defines the behavior of the score motor for all of its the possible outputs. This gives the table author control over the timing and execution of `Wait` (pause) or `Increase` (add points) actions. The example in the screenshot shows a motor where when the player scores 30 points, it pulses on the first three actions of the score motor.
+
+> [!NOTE]
+> The minimum amount of `Steps` for a score motor is `5`. `Increase by 5` will not be shown under `Reel timing by increase` if `Steps` is set to 5, as all actions would be `Increase`.  
+
+<img src="score-motor-gottlieb.png" width="335" class="img-responsive pull-right" style="margin-left: 15px">
+
+By default, the score motor is configured to:
+
+- 6 Steps
+- 769 ms total run time
+
+Next, associate the score motor with the [score reel display](xref:score-reels) by selecting it in [its inspector](xref:score-reels#score-reel-display).
+
+# Usage
+
+Score motors are primarily used in EMs, so we'll focus on how to use them in [Visual Scripting](xref:uvs_index). Programming a game with a score motor is a bit more complicated than with traditional displays for one reason: Scores might get blocked due to the motor being active, so you cannot solely rely on a score variable being updated.
+
+To make this less cumbersome, we've added an [On Display Changed](xref:uvs_node_reference#on-display-changed) node that emits the actual value of the display when it has been updated (after potentially blocking scores).
+
+Give you've already set up your [score reel display](xref:score-reels), the recommended approach is the following:
+
+1. Add an *Add Score* [event](xref:uvs_setup#events) in the Visual Scripting GLE's inspector.
+   <img src="score-motor-score-event.png" width="357">
+2. Add a *Score* [player variable](xref:uvs_variables#setup) in the same inspector.
+   <img src="score-motor-score-variable.png" width="357">
+3. In your graph, whenever you do scoring, use a [Trigger Pinball Event](xref:uvs_node_reference#trigger-pinball-event) node and set the *Add Score* event to be emitted.
+   ![Score Event](score-motor-uvs-score-event.png)
+4. In your graph, at a centralized location, create an [On Pinball Event](xref:uvs_node_reference#on-pinball-event) node, select the *Add Score* event, and link it to an [Update Display](xref:uvs_node_reference#update-display) node.
+   ![Update Display](score-motor-uvs-update-display.png)
+5. Just beneath, add an [On Display Changed](xref:uvs_node_reference#on-display-changed) node, select your score reel, and link the node to [Set Player Variable](xref:uvs_node_reference#set-variable) node, with *Score* to be updated.
+   ![Update Score](score-motor-uvs-update-score.png)
+6. Use the [Clear Display](xref:uvs_node_reference#clear-display) node when the game starts, in order to reset the score reels to zero.
+   ![Reset Score](score-motor-uvs-reset-score.png)
+
+This setup allows you to:
+
+- Easily add scores in your game logic by triggering an *Add Score* event.
+- Subscribe to the *Score* variable in order to trigger score-dependent game logic, while taking into consideration eventually blocked scores by the motor.
+
+> [!WARNING]
+> If you're working on an original EM game, make sure to only emit scores that a score motor can actually handle. For example,  it's impossible to score anything higher than five points (or 50, 500, ...) at once. It's also impossible to score a combination of multiple points at once, like 150.
+
+Finally, you might want to hook up other events to the score motor's behavior. For example, in Gottlieb's Volley, some lamps are toggled off while the motor is running. In order to achieve that, the score motor component exposes two switches:
+
+1. The **Motor Running** switch is activated when the motors starts and deactivated when it stops.
+2. The **Motor Step Switch** pulses on each step.
+
+In order to hook into those switches, you'll have to create them in the GLE inspector and link them to the corresponding switches in the [Switch Manager](xref:switch_manager).
+
+<img src="score-motor-switch-manager.png" width="1044" class="img-responsive">
+
+Then, in your graphs, add your logic behind the corresponding [On Switch Changed](xref:uvs_node_reference#on-switch-changed) node(s).
diff --git a/...ocumentation~/creators-guide/manual/mechanisms/score-reel-display-inspector.png b/...ocumentation~/creators-guide/manual/mechanisms/score-reel-display-inspector.png
diff --git a/....Unity/Documentation~/creators-guide/manual/mechanisms/score-reel-inspector.png b/....Unity/Documentation~/creators-guide/manual/mechanisms/score-reel-inspector.png
diff --git a/...nity/Documentation~/creators-guide/manual/mechanisms/score-reel-uvs-display.png b/...nity/Documentation~/creators-guide/manual/mechanisms/score-reel-uvs-display.png
diff --git a/....Unity/Documentation~/creators-guide/manual/mechanisms/score-reels-geometry.jpg b/....Unity/Documentation~/creators-guide/manual/mechanisms/score-reels-geometry.jpg
diff --git a/...all.Unity/Documentation~/creators-guide/manual/mechanisms/score-reels-scene.png b/...all.Unity/Documentation~/creators-guide/manual/mechanisms/score-reels-scene.png
diff --git a/...alPinball.Unity/Documentation~/creators-guide/manual/mechanisms/score-reels.jpg b/...alPinball.Unity/Documentation~/creators-guide/manual/mechanisms/score-reels.jpg
diff --git a/VisualPinball.Unity/Documentation~/creators-guide/manual/mechanisms/score-reels.md b/VisualPinball.Unity/Documentation~/creators-guide/manual/mechanisms/score-reels.md
@@ -0,0 +1,77 @@
+---
+uid: score-reels
+title: Score Reels
+description: How to use EM-style reels to display the score.
+---
+
+# Score Reel Displays
+
+<img src="score-reels.jpg" width="350" alt="Score Reels a of a Gottlieb Volley" class="img-responsive pull-right" style="margin-left: 15px"/>
+
+In electro-mechanical games, score reels are very common for displaying the player score. Typically, four to six units are mounted behind the backglass. Each reel is driven by a coil that advances the reel by one position when pulsed. The coils are driven by the playfield elements in the game, often indirectly through a score motor for multi-point scoring.
+
+VPE includes components that simulate the [score motor](xref:score-motors) and render the score reel animation. This page is about the score reel, which presents itself to the [GLE](xref:gamelogic_engine) as a [display](xref:displays) that takes in the "numerical" frame format (i.e. numbers only). The score motor is an optional component that provides accurate timing when animating the reels.
+
+## Setup
+
+Typically you would drop the desired score reel variant from the asset library into your scene. But you can also set it up manually:
+
+A score reel display consists of two separate components.
+
+1. The *Score Reel Display* component, which represents the logical display that takes in a number and then sets the reels to display that number.
+2. The *Score Reel* component, which represents one single reel and handles the animation.
+
+### Model
+
+The best geometry for a score reel is a simple, open cylinder. Make sure the local origin is in the middle, and that it rotates around the Z-axis.
+
+![Score reel geometry](score-reels-geometry.jpg)
+
+The texture should contain the numbers 0-9, each taking up 36°. The order (and thus the direction of rotation) depends on the game, so both are valid, and can be configured later.
+
+### Scene
+
+In your scene, drop in your reel model and add the *Score Reel* component (not the *Score Reel Display* component) to the game object. You can find it under *Visual Pinball -> Display*. Since you'll need the same reel for each position, the best approach is to create a [prefab](https://docs.unity3d.com/Manual/Prefabs.html) for the reel and instance it for each position. Then, parent them under a game object that acts as your display. To this object, add the *Score Reel* component (also under *Visual Pinball -> Display*).
+
+![Score reel scene](score-reels-scene.png)
+
+### Components
+
+#### Score Reel
+
+<img src="score-reel-inspector.png" width="362" alt="Score Reel Inspector" class="img-responsive pull-right" style="margin-left: 15px"/>
+
+The *Score Reel* component is quick to set up. There is only one option, which is the *rotation direction*. What the score reel component gets from the display component is "turn to position X", where X is between 0 and 9, and the component's job is to animate the reel to that position.
+
+Internally, it also takes in the rotation speed, and how long it rests at the final position before it can advance to the next position. However, those parameters are not exposed in the inspector but retrieved from the display component described in the next section.
+
+#### Score Reel Display
+
+<img src="score-reel-display-inspector.png" width="362" alt="Score Reel Display Inspector" class="img-responsive pull-right" style="margin-left: 15px"/>
+
+This is the component on the parent game object that receives score numbers from the game and tells the individual reels to which position they need to turn to. 
+
+- **ID** defines the display ID. Remember that displays are [connected at runtime](xref:displays#setup), so this is the identifier that the GLE uses to send data to it.
+- **Speed** defines how quickly the reels should rotate.
+- **Wait** indicates the time the reels stand still before they can go to the next position.
+- Under **Reel Objects** you define your reels (they are not automatically retrieved from the children). The order is from largest to smallest, i.e. from left to right.
+- The **Score Motor** is an optional reference to a [score motor component](xref:score-motors).
+
+
+## Usage
+
+### Gamelogic Engine
+
+<img src="score-reel-uvs-display.png" width="362" alt="Score Reel Display Inspector" class="img-responsive pull-right" style="margin-left: 15px"/>
+
+Score reels are primarily used in EMs, so they are typically driven by [Visual Scripting](xref:uvs_index). As with every display, the first step is to define the display in the GLE component.
+
+Add a new display under *Displays* and set the same ID as you did in the display component. The *Width* and *Height* properties are ignored, since they are managed by the display component (contrarily to the other displays, where the size is given by the GLE).
+
+Next, add *Numeric* under *Supported Formats*.
+
+### Visual Scripting
+
+In Visual Scripting, use the [Update Display](xref:uvs_node_reference#update-display) node to set a new score. It's up to you whether to use a separate [event](xref:uvs_setup#events) or to subscribe to a [player variable](xref:uvs_variables) directly.
+
+If you're using a score motor, read how to set it up correctly [here](xref:score-motors#usage).
diff --git a/VisualPinball.Unity/Documentation~/creators-guide/toc.yml b/VisualPinball.Unity/Documentation~/creators-guide/toc.yml
@@ -96,6 +96,10 @@
         href: manual/mechanisms/drop-target-banks.md
       - name: Rotators
         href: manual/mechanisms/rotators.md
+      - name: Score Reels
+        href: manual/mechanisms/score-reels.md
+      - name: Score Motors
+        href: manual/mechanisms/score-motors.md
       - name: Collision Switches
         href: manual/mechanisms/collision-switches.md
       - name: Lifting Gates

diff --git a/...Pinball.Unity/Documentation~/plugins/visual-scripting/clear-display-example.png b/...Pinball.Unity/Documentation~/plugins/visual-scripting/clear-display-example.png
diff --git a/...nball.Unity/Documentation~/plugins/visual-scripting/display-changed-example.png b/...nball.Unity/Documentation~/plugins/visual-scripting/display-changed-example.png
diff --git a/VisualPinball.Unity/Documentation~/plugins/visual-scripting/node-reference.md b/VisualPinball.Unity/Documentation~/plugins/visual-scripting/node-reference.md
@@ -267,6 +267,12 @@ Creating original *graphical* content for displays is not yet supported by VPE.
 
 Even if we have nothing that creates the graphical content, we've defined the APIs used to pass the data around. This allows us to already have a working system that supports number and text data.
 
+### Clear Display
+
+This node clears a [display defined in the GLE](xref:uvs_setup#displays).
+
+![Clear Display](clear-display-example.png)
+
 ### Update Display
 
 This node takes in some data and sends it to one of the [displays defined in the GLE](xref:uvs_setup#displays). VPE supports segment displays and score reels, so the data can be numeric (score reels and segment displays) or alphanumeric (segment displays).
@@ -275,4 +281,10 @@ This example shows how the display is updated for a simple one player EM machine
 
 ![Update Display](update-display-example.png)
 
-The score reel animation is handled by the component driving the reel. It's also on component level where you can define the speed and delays of the score reel animation.
+The score reel animation is handled by the component driving the reel. It's also on component level where you can define the speed and delays of the score reel animation and associate a [score motor](xref:score-motors).
+
+### On Display Changed
+
+This event is triggered when a [display defined in the GLE](xref:uvs_setup#displays) is updated by *Clear Display* or *Update Display*. It is useful for EM machines that use a [score motor](xref:score-motors) and need to capture the score in a player variable.
+
+![On Display Changed](display-changed-example.png)
diff --git a/...inball.Unity/Documentation~/plugins/visual-scripting/update-display-example.png b/...inball.Unity/Documentation~/plugins/visual-scripting/update-display-example.png