Merge pull request #932 from dionoid/master

P2000T (M2000) - Introducing the new "On-Screen Key Selector" feature

docs/library/m2000.md

@@ -4,9 +4,9 @@
 
 ## Background
 
-The P2000T was Philips' first home computer, before they later switched to manufacturing MSX computers. The P2000T was a Z80-powered machine which launched in 1981 and was built like a tank. It featured an integrated keyboard, power supply, two cartridge slots and a very innovative and fast Mini-Cassette system (MDCR), which was fully automated and used mini tapes that could hold up to 42 kilobytes of data.
+The P2000T was Philips' first computer for the home market in the early '80s, before they later switched to manufacturing MSX computers. The P2000T was a Z80-powered machine, running at a clock speed of 2.5 MHz and was built like a tank. It featured an integrated keyboard, power supply, two cartridge slots and a very innovative and fast Mini-Cassette system (MDCR), which was fully automated and used mini tapes that could hold up to 42 kilobytes of data.
 
-The P2000T was reasonably popular among hobbyists and kids in elementary schools in The Netherlands, as Philips promoted the machine strongly in the science and education sectors. Because of the relatively high introductory price and the fact that its SAA5050 video chip only supported teletext display mode, the P2000T never became the success that Philips hoped for.
+The P2000T was reasonably popular among hobbyists and kids in elementary schools in The Netherlands, as Philips promoted the machine strongly in the science and education sectors. Because of the relatively high introductory price and the fact that its SAA5050 video chip only supported a 40 x 24 character teletext display mode, the P2000T never became the success that Philips hoped for.
 
 While the system's video and sound capabilities were rather limited, some developers still were able to create remarkably good games, like a Pac-Man clone named "Ghosthunt", a Phoenix clone named "Fraxxon", a Lady Bug clone named "Lazy Bug" and a Breakout clone named "Brick-Wall".
 
@@ -67,70 +67,133 @@ The M2000 core's library name is 'M2000'.
 
 - The M2000 core's core provided FPS is `50`
 - The M2000 core's core provided sample rate is `30000`
-- The M2000 core's base width is `640`
-- The M2000 core's base height is `480`
-- The M2000 core's max width is `640`
-- The M2000 core's max height is `480`
+- The M2000 core's base width is `240`
+- The M2000 core's base height is `240`
+- The M2000 core's max width is `240`
+- The M2000 core's max height is `240`
 - The M2000 core's core provided aspect ratio is `4/3`
 
 ## Usage
 
-Playing P2000T games using the M2000 core works best when the core is in **'Game Focus'** mode, which allows it to take precedence in inputs. The reason is that **every** P2000T game relies on keyboard input and even the buttons of the RetroPad controller are internally emulating actual key presses.
+When playing P2000T games using the M2000 core, you will notice that **every** P2000T game relies on keyboard input; usually the Space key to fire and the Arrow-keys to navigate, but also for simple J/N (= Yes/No) questions or when entering the number of players.
 
-The easiest way to automatically enable 'Game Focus' mode for the M2000 core is in **Settings > Input** where you set the option called **Auto Enable 'Game Focus' Mode** to `Detect`. Or correspondingly in retroarch.cfg set `input_auto_game_focus = "2"`. Be aware that the default hotkey for toggling the **Game Focus** mode is the **Scroll Lock** key, which might not be present on your keyboard. If that's the case, you'll need to remap it - for example to the **Tab** key.
+While the P2000T didn't have any joystick ports, there was a third-party company back in the '80s who was selling I/O cartridges to which you could connect up to 2 joysticks. These cartridges basically simulated actual key presses and that is exactly what the Joypad is doing in the M2000 core.
+
+Playing P2000T games using the M2000 core usually works best in one of these three ways:
+
+1. Using **Keyboard only**
+This basically means that you play the P2000T games like most people did back in the day. Do note that because of the positional key mapping, not all keys you type will display the character you expect. However, during game-play you probably won't ever notice this.
+This way of playing works best when the core is in **'Game Focus'** mode, which allows the core to take precedence in inputs. The easiest way to automatically enable 'Game Focus' mode for the M2000 core is in **Settings > Input** where you set the option called **Auto Enable 'Game Focus' Mode** to `Detect`. Or correspondingly in retroarch.cfg set `input_auto_game_focus = "2"`. Be aware that the default hotkey for toggling the **Game Focus** mode is the **Scroll Lock** key, which might not be present on your keyboard. If that's the case, you'll need to remap it - for example to the **Tab** key.
+
+2. Using both **Keyboard** and **Joypad**
+Use the **Keyboard** to answer the game's Yes/No questions and for things like entering the number of players or typing your name for the highscore list. Then switch to the **Joypad** during actual game play.
+This way of playing also works best when the core is in **'Game Focus'** mode.
+
+3. Using **Joypad only.**
+This requires the use of the On-Screen Key Selector to enter the number of players or to answer Y/N questions. See the description below on how to use the On-Screen Key Selector.
+For this way of playing the core doesn't have to be in **'Game Focus'** mode.
+
+### On-Screen Key Selector
+
+The On-Screen Key Selector lets you simulate key presses using your Joypad controller. This allows you to play almost all P2000T games without the need of an actual keyboard. Next to the regular Joypad mappings (i.e. Navigation keys +  Space to fire), most games will ask simple Yes/No questions or allow you to enter your name in a high score list.
+
+The On-Screen Key Selector is activated by holding your Joypad's Left Bumper/Trigger/Shoulder button. Then with the D-pad you can loop through the keys and with the A/B button you then enter the highligted key.
+
+In the screenshot below you can see the On-Screen Key Selector in the bottom of the screen, where the player is about the enter the 'N' key to skip showing the "spelregels" (game rules):
+
+![](../image/core/m2000/on-screen-key-selector.png)
 
 ## User 1 device types
 
 The M2000 core supports the following device type(s) in the controls menu, bolded device types are the default for the specified user(s):
 
-- **RetroKeyboard** - Keyboard. Keyboard inputs are always active.
-- RetroPad - Joypad. The buttons are internally mapped to actual key presses (see information below).
+- **RetroKeyboard** - Keyboard. The keyboard inputs are always active.
+- **RetroPad** - Joypad. The buttons are internally mapped to actual keyboard key presses (see information below).
 
 ## Joypad
 
-| RetroPad Inputs                             | P2000T    |
-|---------------------------------------------|-----------|
-| ![](../image/retropad/retro_a.png)          | Space     |
-| ![](../image/retropad/retro_b.png)          | Space     |
-| ![](../image/retropad/retro_start.png)      | < START > |
-| ![](../image/retropad/retro_select.png)     | < STOP >  |
-| ![](../image/retropad/retro_dpad_up.png)    | Up        |
-| ![](../image/retropad/retro_dpad_down.png)  | Down      |
-| ![](../image/retropad/retro_dpad_left.png)  | Left      |
-| ![](../image/retropad/retro_dpad_right.png) | Right     |
+| RetroPad Inputs                             | P2000T Keys            |
+|---------------------------------------------|------------------------|
+| ![](../image/retropad/retro_a.png)          | Space / Fire           |
+| ![](../image/retropad/retro_b.png)          | Space / Fire           |
+| ![](../image/retropad/retro_start.png)      | < START >              |
+| ![](../image/retropad/retro_select.png)     | < STOP >               |
+| ![](../image/retropad/retro_dpad_up.png)    | Up                     |
+| ![](../image/retropad/retro_dpad_down.png)  | Down                   |
+| ![](../image/retropad/retro_dpad_left.png)  | Left                   |
+| ![](../image/retropad/retro_dpad_right.png) | Right                  |
+| ![](../image/retropad/retro_l1.png)         | On-Screen Key Selector |
+| ![](../image/retropad/retro_l2.png)         | On-Screen Key Selector |
 
-### Joypad remapping for games that use alternative keys (e.g. Fraxxion)
+### Joypad remapping for games that use alternative keys
 
-Some P2000T games use alternative keys for navigation. An example is Fraxxion, which uses the **Left** and **Up** keys to move the spaceship horizontally, which was probably done for better control on the original P2000T keyboard. 
-To be able to use the D-pad for horizontal movement in the emulator, you should start Fraxxion, then open the menu and go to **Quick Menu > Controls > Port 1 Controls** and remap **D-Pad Right** to RetroPad **Up**. Now return to **Quick Menu > Controls**, click **Manage Remap Files** and select **Save Game Remap File** to save the remapping for Fraxxion only.
+Some P2000T games use alternative keys for navigation. An example is Fraxxon, which uses the **Left** and **Up** keys to move the spaceship horizontally, which was probably done for better playability on the original P2000T keyboard. 
+To be able to use the D-pad for horizontal movement in the emulator, you should start Fraxxon, then open the menu and go to **Quick Menu > Controls > Port 1 Controls** and remap **D-Pad Right** to RetroPad **Up**. Now return to **Quick Menu > Controls**, click **Manage Remap Files** and select **Save Game Remap File** to save the joypad remapping for Fraxxon only.
 
 ## Keyboard
 
-| RetroKeyboard Inputs         | P2000T Key                |
-|------------------------------|---------------------------|
-| Keyboard a .. z              | a .. z                    |
-| Keyboard 0 .. 9              | 0 .. 9                    |
-| Keyboard Backspace           | Backspace                 |
-| Keyboard Return              | Enter                     |
-| Keyboard Space               | Space                     |
-| Keyboard Double Quote "      | Double Quote "            |
-| Keyboard Slash /             | Slash /                   |
-| Keyboard Question ?          | Question ?                |
-| Keyboard Comma ,             | Comma ,                   |
-| Keyboard Minus -             | Minus -                   |
-| Keyboard Period .            | Period .                  |
-| Keyboard Underscore _        | Underscore _              |
-| Keyboard Backquote `         | < CODE >                  |
-| Keyboard Keypad 0 .. 9       | 0 .. 9                    |
-| Keyboard Keypad Period .     | Period .                  |
-| Keyboard Keypad Enter        | Enter                     |
-| Keyboard Up                  | Up                        |
-| Keyboard Down                | Down                      |
-| Keyboard Right               | Right                     |
-| Keyboard Left                | Left                      |
-| Keyboard F1                  | < START >                 |
-| Keyboard F2                  | < STOP >                  |
-| Keyboard F3                  | < ZOEK >                  |
+The M2000 core is using **positional** key mapping, which maps every key from a "real" keyboard to the key which has the same position on a P2000T keyboard. This makes the keyboard more comfortable to use in games that require the keys to be in the correct positions. And also this allows for pressing multiple keys simultaneously.
+
+Below you can see how the keys on the RetroKeyboard map to keys on the P2000T keyboard:
+
+| RetroKeyboard Inputs      | P2000T Keys          |
+|---------------------------|----------------------|
+| a .. z                    | a .. z               |
+| A .. Z                    | A .. Z               |
+| 0 .. 9                    | 0 .. 9               |
+| Shift + 1                 | Exclaim !            |
+| Shift + 2                 | Double Quote "       |
+| Shift + 3                 | Pound &              |
+| Shift + 4                 | Dollar $             |
+| Shift + 5                 | Percent %            |
+| Shift + 6                 | Ampersand &          |
+| Shift + 7                 | Quote '              |
+| Shift + 8                 | Left Parenthesis (   |
+| Shift + 9                 | Right Parenthesis )  |
+| Shift + 0                 | Equals =             |
+| Minus -                   | Minus -              |
+| Underscore _              | Dash —               |
+| Equals =                  | One Quarter ¼        |
+| Plus +                    | Three Quarters ¾     |
+| Left Bracket [            | At @                 |
+| Left Curly Brace {        | Arrow Up ↑           |
+| Right Bracket ]           | Arrow Right →        |
+| Right Curly Brace }       | Arrow Left ←         |
+| Backslash \               | Hash #               |
+| Pipe \|                   | Block █              |
+| Semicolon ;               | Semicolon ;          |
+| Colon :                   | Plus +               |
+| Quote '                   | Colon :              |
+| Double Quote "            | Asterisk *           |
+| Comma ,                   | Comma ,              |
+| Period .                  | Period .             |
+| Slash /                   | Slash /              |
+| Question ?                | Question ?           |
+| Delete                    | Less <               |
+| Shift + Delete            | Greater >            |
+| Backspace                 | Backspace            |
+| Return                    | Enter                |
+| Space                     | Space                |
+| Backquote `               | < CODE >             |
+| Tab                       | Tab                  |
+| Caps Lock                 | Shift Lock           |
+| Left Shift                | Left Shift           |
+| Right Shift               | Right Shift          |
+| Up                        | Up                   |
+| Down                      | Down                 |
+| Right                     | Right                |
+| Left                      | Left                 |
+| Keypad 0 .. 9             | 0 .. 9               |
+| Keypad Period .           | Double Zero 00       |
+| Keypad Enter              | Period .             |
+| Keypad Multiply *         | Clear Line           |
+| Shift + Keypad Multiply * | Clear Page           |
+| Shift + Keypad 1          | < ZOEK >             |
+| Shift + Keypad 3          | < START >            |
+| Shift + Keypad Enter      | < STOP >             |
+| F1                        | < START >            |
+| F2                        | < STOP >             |
+| F3                        | < ZOEK >             |
 
 ## External Links