Common User Interface Recommendations
IMPORTANT: Please do not edit this page before discussing your suggestion in the Talk page.
Gaming platforms generally have a set of common rules prepared by the vendor to give to a consistent user experience with the games. Since GPH will probably not publish similar recommendations, and already games are using at best inconsistent key mapping, and at worse completely unexpected controls the user has to 'discover'.
In order to give a good user experience to the gamers and high-quality games, please follow the guidelines on this page when developing an application or a game. This is especially important for the game or application is only available in one (foreign) language.
For emulated games, obviously, these rules might not apply, as they are probably following their own rules already. The emulator itself should try to follow these recommendations when appropriate.
When the word must is used, the recommendation is mandatory to be GP2X-CUI compliant.
When the word should is used, the recommendation is optional, but the application should not implement a features that violates the spirit of the recommendation and confuse the user with an unexpected usage of a familiar feature. Example: Stick click & L should NOT be used as shortcut for a action other than 'save'; if a 'save' shortcut is not available, Stick click & L must do nothing.
When the word may is used, the recommendation is optional, and the application doesn't have to follow the spirit of the rule in any way. Such recommendations are listed for 'best practice' purposes.
Use of standard keys and key combinations
The application must use the following keys and key combinations as listed below. A key combination is the click of several keys simultaneously.
- Standard keys in a menu type of screen:
- Start should be used as a shortcut for the default menu item (might not be the selected one)
- Stick directions must be used to change the highlighted menu item
- Stick click should be used to select the highlighted menu item
- A or B must be used to select the highlighted menu item (both must be implemented: if the user presses either, the menu item is selected)
- X must be used to cancel and go back to the previous menu
- L and R should be used to select the previous and next menu item, or the previous and next menu page or screen
- Standard keys in a game:
- Start must be used to start and pause the application; when paused, the application should display an application menu
- Either A or B should be used for the primary action. A and B actions don't need to be the same, but if either A or B don't have a specific action, both A and B should be used for the primary action.
- X should be used for the secondary action
- Select should be used to open an in-game menu, such as an inventory
- L and R may be used for actions related with 'left' and 'right' concepts and orientation in general
- Key combinations:
- Stick click in combination with one or several other keys should be used for system actions only, not for game actions
- Stick click & Start must be used to exit the application
- Stick click & Select should be used to toggle TV-out on and off
- Stick click & L should be used as shortcut for the 'save' menu action
- Stick click & one of A, B, X, Y may be used as shortcuts for menu actions
- Start & Select should be used to access an application configuration screen, an about screen or a debug screen
- Volume + & Volume - should be used to mute the sound
- Stick click & R is reserved for future recommendation and should not be used
The application must provide a way to exit to the GP2X menu. This must be done at least by the exit key combination. The application should also provide an 'exit' menu entry if it has a menu.
The application must be entirely contained in one directory (a.k.a. the application directory): the main executable and any additional resources (which can be in sub-directories) must assume they are all located inside the same directory. The name and location of the application directory can be changed by the user and the application must not make any assumption on its path.
If the application relies on shared external resources, such as libraries or skins, it is obviously not necessary to include those in the application directory, as long as those external resources have a public API the application can use.
Note: If the application is composed only of one executable and is not going to write files on the SD card, it is not necessary to put it alone in a directory: it can be located at the top of the SD card, in a directory with other one-file applications, or anywhere in the filesystem, but the application must still not make any assumption on its path.
Saving on the card
The application may save files on the SD card. Internal states, screenshots and the like must be saved in the application's directory. Then the application must call sync() to flush the write buffers to the SD cards. If possible, the application should group the write operations in batches and sync as seldom as possible.
If the application plays sounds or music, the application must provide volume control using the Volume + and Volume - keys. The application must at least allow the user to turn the sound off when the Volume - key is pressed, and turn the sound on when the Volume + key is pressed.
The application should provide a more fine grained volume control: 10 volume steps of volume is generally considered a good number. In this case, the application should also use mute key combination to turn the sound on and off.
Alternatively, Volume control buttons may be used as action buttons in vertically oriented games such as MAME games (Donkey Kong, Pac-Man etc.).
Optional Recommendations and Best Practices
Let the user know the game is GP2X-CUI compliant
If you follow all the CUI recommendations, you should use the GP2X-CUI logos in you application: use the small logo at the bottom of the start menu screen. Additionally, you should use the large or the small logo at the bottom of the splash screen, in the help/about screen and/or equivalent.
Small logo: This file is public domain --Titousensei 01:08, 2 December 2005 (GMT)
Large logo: TODO
TODO: can somebody propose better logos in the Talk page? The smallest size I could draw letters in is 31x9.
The application should print its version on the splash screen, on the help/about screen or equivalent.
The application may provide a way to localize the text messages it displays without recompilation, by either loading the messages from an external plain text file (encoded as ASCII/UTF-8), or by using external images.
Forgiving error handling
Any non-critical feature failing to initialize itself may display a warning message but should allow the user to proceed anyway. For example, if the sound cannot be initialized, or if the SD card cannot be written on for savings, the application may display a descriptive warning in the splash screen or in the about screen, and let the user play anyway.
Whenever possible, the application should turn off all the unnecessary devices and reduce the cpu frequency to the minimum value for which the application can run smoothly.
TODO: give code examples on how to do that programmatically.