funkey/RetroFE
1
0
Fork 0
mirror of https://github.com/FunKey-Project/RetroFE.git synced 2025-12-13 18:28:52 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity
RetroFE/Documentation/Manual/Configuration.rst
Don Honerbrink d77756d1d4 Remove quotes from controls documentation
2015-01-30 20:36:36 +00:00

501 lines
24 KiB
ReStructuredText
Raw Blame History

.. _Configuration:
==================================
Configuration
==================================
RetroFE splits up configuration files to optimize flexability and portability. The configuration is broken up into the following categories:
=========================== ==================================================================================================================================================================
Configuration Role
=========================== ==================================================================================================================================================================
Main Settings Defines screen resolution, controls, etc.
Launchers Defines what executables to use for launching menu items (emulators, apps, etc.)
Collections Defines directories to scan for populating lists, media (image and video) paths, and additional information for an item (i.e controls, instructions, histrory)
Main Menu Defines the list of collections to pick from on the main page.
=========================== ==================================================================================================================================================================
Main Configurations
################################################
**/Settings.conf**
See below for a list of supported properties.
================================== ========================================================================================================
Property Description
================================== ========================================================================================================
horizontal Horizontal screen width (in pixels)
vertical Vertical screen width (in pixels)
fullscreen Display in fullscreen or windowed mode (yes/no)
layout Name of the default layout to use (unless overridden in the themes)
exitOnFirstPageBack Exit the frontend when the back button is pressed on the first page
attractModeTime Number of seconds while idleing to wait before entering attract mode (0 to disable)
showParenthesis Set to no if you want to hide parenthesis (and anything inside) for menu lists
showSquareBrackets Set to no if you want to hide braces (and anything inside) for menu lists
showVideo Set to no if you want to not load video (for slower systems)
videoLoop Number of times to loop video playback (enter 0 to continuously loop)
firstCollection Defines the first collection to load. If not specified, the "Main" collection will be used.
================================== ========================================================================================================
**/Controls.conf**
See below for a list of supported properties.
========================= ========================================================================================================
Property Description
========================= ========================================================================================================
previousItem The key to press to scroll to the previous item in a list
nextItem The key to press to scroll to the next item in a list
pageUp The key to press to scroll page up in a list
pageDown The key to press to scroll page down in a list
select The key to press to select (or launch) the selected list item
back The key to press to return to the previous menu
quit The key to press to quit the frontend
========================= ========================================================================================================
Basic example for Settings.conf (640x480 fullscreen):
.. code-block:: javascript
horizontal = 640
vertical = 480
fullscreen = yes
Basic example for Controls.conf:
.. code-block:: javascript
previousItem = Up
nextItem = Down
pageUp = Left
pageDown = Right
select = Space
back = Escape
quit = q
See :ref:`ControlKeycodes` for a list of valid key codes
.. _ConfigurationLaunchers:
Launchers
################################################
**/Launchers/<launcher>.conf**
*(where <launcher> is the name of the launcher)*
A launcher is a program (i.e. emulator, application, or game) which gets executed when a menu item is selected. Parameters can also be passed
into a launcher.
See below for a list of supported properties.
=========================== ==================================================================
Property Description
=========================== ==================================================================
executable Path of where the executable exists
arguments Arguments to pass when executing the launcher (i.e. ROM name)
=========================== ==================================================================
See below for a basic launcher for the Nestopia emulator (/Launchers/nestopia.conf)
.. code-block:: javascript
executable = D:/Emulators/Nestopia/nestopia.exe
arguments = "%ITEM_FILEPATH%"
%ITEM_FILEPATH% is a reserved variable name. See the variables table below for other variables that may be used.
Also note the quotes around "%ITEM_FILEPATH%" to help not confuse the executable from thinking that an item with spaces as multiple arguments.
Assuming that "Super Mario Bros" was the selected item, the frontend will attempt to execute:
.. code-block:: javascript
"D:/Emulators/Nestopia/nestopia.exe" "D:/ROMs/Nintendo/Super Mario Bros.nes".
You can also use relative paths (relative to the root folder of RetroFE)
.. code-block:: javascript
executable = ../Emulators/Nestopia/nestopia.exe
arguments = "%ITEM_FILEPATH%"
Variables
-----------
=========================== =========================== ===============================================
Variable Description Translated Example
=========================== =========================== ===============================================
%ITEM_FILEPATH% Full item path D:/ROMs/Nintendo/Super Mario Bros.nes
%ITEM_NAME% The item name Super Mario Bros
%ITEM_FILENAME% Filename without path Super Mario Bros.nes
%ITEM_DIRECTORY% Folder where file exists D:/ROMs/Nintendo
%ITEM_COLLECTION_NAME% Name of collection for item Nintendo Entertainment System
%RETROFE_PATH% Folder location of Frontend D:/Frontends/RetroFE
%RETROFE_EXEC_PATH% Location of RetroFE D:/Frontends/RetroFE/RetroFE.exe
=========================== =========================== ===============================================
More elaborate example:
.. code-block:: javascript
# Have fceux load a save state automatically for the ROM when started
executable = D:/Emulators/fceux/fceux.exe
arguments = "%ITEM_FILEPATH%" -loadstate "%ITEM_DIRECTORY%/%ITEM_NAME%.fcs"
.. _ConfigurationCollections:
Collections
################################################
**/Collections/<collection name>/**
A collection is a list of items to display on a menu. A collection can be built by scanning a list of files in a folder. Each collection configuration is broken up into three separate
configuration files (for portability).
================================== ==================================================================================================================
Configuration File Description
================================== ==================================================================================================================
Settings.conf Defines which launcher to use, item (ROM) folders, extensions, media paths, layout/theme, etc...
Include.txt List the filenames (without the extension) to show up in your list. If empty, all files will be shown in the list.
Exclude.txt List the filenames (without the extension) to hide from being shown up in your list
================================== ==================================================================================================================
General Settings
----------------------
**/Collections/<collection name>/Settings.conf**
================================== ================================================================================================================================
Property Description
================================== ================================================================================================================================
launcher Launcher to use when item is selected (will look up /Launchers/<launcher>.conf
layout The name of the layout to load for the collection (will read layout from Layouts/<layout>
path Location of where files to launch exist
extensions Adds only files with the given extension to a list (comma separated)
media.snap Snapshot image folder
media.title Title screen image folder
media.video Video folder
media.box Box artwork folder
================================== ================================================================================================================================
The following example will use the launcher configuration from "/Launchers/nestopia.conf" and will use the layout in "Layouts/Nintendo Entertainment System"
.. code-block:: javascript
launcher = nestopia
layout = Nintendo Entertainment System
path = D:/ROMs/Nintendo Entertainment System
extensions = nes,zip
media.snap = D:/Media/Nintendo Entertainment System/Snaps
media.title = D:/Media/Nintendo Entertainment System/Titles
media.video = D:/Media/Nintendo Entertainment System/Videos
media.box = D:/Media/Nintendo Entertainment System/Box
Showing and Hiding Collection Items
------------------------------------------
**/Collections/<collection name>/Include.txt** and **/Collections/<collection name>/Exclude.txt**
By default, RetroFE will show all items scanned in your folder path (assuming the extension matches). If an Include.txt file exists (and Include.txt is not empty), only the
items in that file will show up in the menu (assuming the file exists).
If an Exclude.xml file exists, the file will always be hidden from the list, regardless if the file item is specified in Include.txt.
All items listed in Include.txt and Exclude.txt are the name of the file (without the file extension).
Example Include.txt file:
.. code-block:: javascript
Super Mario Bros (USA)
Contra (USA)
Example Exclude.txt file:
.. code-block:: javascript
E.T. (USA)
Bayou Billy (USA)
Meta Database (scraping)
################################################
RetroFE has the ability to take information from various sources and and consolidate them into a database for collections to reference for additional details about a specific game item.
The database is populated by scanning for all files in /Meta/Hyperlist and /Meta/Mamelist.
HyperLists and mamelists are supported for scraping. The latest versions of RetroFE come pre-packaged with the Hyperlist files and/Meta/Hyperlist/<CollectionName>.xml and /Meta/Mamelist/<CollectionName.xml>.
If no cache.db file exists, the frontend will scrape those files and build the database for you automatically. To update the database, it is currently required that you manually delete cache.db.
.. _ConfigurationMenu:
Main Menu
################################################
**/Collections/Main/Menu.xml**
This file defines what menu items are displayed on the first page. See below for a basic example:
.. code-block:: xml
<menu>
<collection name="Nintendo Entertainment System" />
<collection name="Arcade" />
</menu>
Note that for each item specified, one with an identical name (case sensitive) must exist in your collections folder. For the example above, the collection configuration in
/Collections/Nintendo Entertainment System/ and /Collections/Arcade/ must exist.
.. _ControlKeycodes:
Valid Key Codes
################
These codes were taken from https://wiki.libsdl.org/SDL_Keycode
See below for a list of key codes that can be used for configuring the controls:
=================== ================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================
Code Notes
=================== ================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================
0
1
2
3
4
5
6
7
8
9
A
AC Back the Back key (application control keypad)
AC Bookmarks the Bookmarks key (application control keypad)
AC Forward the Forward key (application control keypad)
AC Home the Home key (application control keypad)
AC Refresh the Refresh key (application control keypad)
AC Search the Search key (application control keypad)
AC Stop the Stop key (application control keypad)
Again the Again key (Redo)
AltErase Erase-Eaze
'
Application the Application / Compose / Context Menu (Windows) key
AudioMute the Mute volume key
AudioNext the Next Track media key
AudioPlay the Play media key
AudioPrev the Previous Track media key
AudioStop the Stop media key)
B
\ Located at the lower left of the return key on ISO keyboards and at the right end of the QWERTY row on ANSI keyboards. Produces REVERSE SOLIDUS (backslash) and VERTICAL LINE in a US layout, REVERSE SOLIDUS and VERTICAL LINE in a UK Mac layout, NUMBER SIGN and TILDE in a UK Windows layout, DOLLAR SIGN and POUND SIGN in a Swiss German layout, NUMBER SIGN and APOSTROPHE in a German layout, GRAVE ACCENT and POUND SIGN in a French Mac layout, and ASTERISK and MICRO SIGN in a French Windows layout.
Backspace
BrightnessDown the Brightness Down key
BrightnessUp the Brightness Up key
C
Calculator the Calculator key
Cancel
CapsLock
Clear
Clear / Again
,
Computer the My Computer key
Copy
CrSel
CurrencySubUnit the Currency Subunit key
CurrencyUnit the Currency Unit key
Cut
D
DecimalSeparator the Decimal Separator key
Delete
DisplaySwitch display mirroring/dual display switch, video mode switch
Down the Down arrow key (navigation keypad)
E
Eject the Eject key)
End
=
Escape the Esc key)
Execute
ExSel
F
F1
F10
F11
F12
F13
F14
F15
F16
F17
F18
F19
F2
F20
F21
F22
F23
F24
F3
F4
F5
F6
F7
F8
F9
Find
G
` Located in the top left corner (on both ANSI and ISO keyboards). Produces GRAVE ACCENT and TILDE in a US Windows layout and in US and UK Mac layouts on ANSI keyboards, GRAVE ACCENT and NOT SIGN in a UK Windows layout, SECTION SIGN and PLUS-MINUS SIGN in US and UK Mac layouts on ISO keyboards, SECTION SIGN and DEGREE SIGN in a Swiss German layout (Mac: only on ISO keyboards), CIRCUMFLEX ACCENT and DEGREE SIGN in a German layout (Mac: only on ISO keyboards), SUPERSCRIPT TWO and TILDE in a French Windows layout, COMMERCIAL AT and NUMBER SIGN in a French Mac layout on ISO keyboards, and LESS-THAN SIGN and GREATER-THAN SIGN in a Swiss German, German, or French Mac layout on ANSI keyboards.
H
Help
Home
I
Insert insert on PC, help on some Mac keyboards (but does send code 73, not 117)
J
K
KBDIllumDown the Keyboard Illumination Down key
KBDIllumToggle the Keyboard Illumination Toggle key
KBDIllumUp the Keyboard Illumination Up key
Keypad 0 the 0 key (numeric keypad)
Keypad 00 the 00 key (numeric keypad)
Keypad 000 the 000 key (numeric keypad)
Keypad 1 the 1 key (numeric keypad)
Keypad 2 the 2 key (numeric keypad)
Keypad 3 the 3 key (numeric keypad)
Keypad 4 the 4 key (numeric keypad)
Keypad 5 the 5 key (numeric keypad)
Keypad 6 the 6 key (numeric keypad)
Keypad 7 the 7 key (numeric keypad)
Keypad 8 the 8 key (numeric keypad)
Keypad 9 the 9 key (numeric keypad)
Keypad A the A key (numeric keypad)
Keypad & the & key (numeric keypad)
Keypad @ the @ key (numeric keypad)
Keypad B the B key (numeric keypad)
Keypad Backspace the Backspace key (numeric keypad)
Keypad Binary the Binary key (numeric keypad)
Keypad C the C key (numeric keypad)
Keypad Clear the Clear key (numeric keypad)
Keypad ClearEntry the Clear Entry key (numeric keypad)
Keypad : the : key (numeric keypad)
Keypad , the Comma key (numeric keypad)
Keypad D the D key (numeric keypad)
Keypad && the && key (numeric keypad)
Keypad || the || key (numeric keypad)
Keypad Decimal the Decimal key (numeric keypad)
Keypad / the / key (numeric keypad)
Keypad E the E key (numeric keypad)
Keypad Enter the Enter key (numeric keypad)
Keypad = the = key (numeric keypad)
Keypad = (AS400) the Equals AS400 key (numeric keypad)
Keypad ! the ! key (numeric keypad)
Keypad F the F key (numeric keypad)
Keypad > the Greater key (numeric keypad)
Keypad # the # key (numeric keypad)
Keypad Hexadecimal the Hexadecimal key (numeric keypad)
Keypad { the Left Brace key (numeric keypad)
Keypad ( the Left Parenthesis key (numeric keypad)
Keypad < the Less key (numeric keypad)
Keypad MemAdd the Mem Add key (numeric keypad)
Keypad MemClear the Mem Clear key (numeric keypad)
Keypad MemDivide the Mem Divide key (numeric keypad)
Keypad MemMultiply the Mem Multiply key (numeric keypad)
Keypad MemRecall the Mem Recall key (numeric keypad)
Keypad MemStore the Mem Store key (numeric keypad)
Keypad MemSubtract the Mem Subtract key (numeric keypad)
Keypad - the - key (numeric keypad)
Keypad \* the \* key (numeric keypad)
Keypad Octal the Octal key (numeric keypad)
Keypad % the Percent key (numeric keypad)
Keypad . the . key (numeric keypad)
Keypad + the + key (numeric keypad)
Keypad +/- the +/- key (numeric keypad)
Keypad ^ the Power key (numeric keypad)
Keypad } the Right Brace key (numeric keypad)
Keypad ) the Right Parenthesis key (numeric keypad)
Keypad Space the Space key (numeric keypad)
Keypad Tab the Tab key (numeric keypad)
Keypad \| the \| key (numeric keypad)
Keypad XOR the XOR key (numeric keypad)
L
Left Alt alt, option
Left Ctrl
Left the Left arrow key (navigation keypad)
[
Left GUI windows, command (apple), meta
Left Shift
M
Mail the Mail/eMail key
MediaSelect the Media Select key
Menu
-
ModeSwitch I'm not sure if this is really not covered by any of the above, but since there's a special KMOD_MODE for it I'm adding it here
Mute
N
Numlock the Num Lock key (PC) / the Clear key (Mac)
O
Oper
Out
P
PageDown
PageUp
Paste
Pause the Pause / Break key
.
Power The USB document says this is a status flag, not a physical key - but some Mac keyboards do have a power key.
PrintScreen
Prior
Q
R
Right Alt alt gr, option
Right Ctrl
Return the Enter key (main keyboard)
Return
Right GUI windows, command (apple), meta
Right the Right arrow key (navigation keypad)
]
Right Shift
S
ScrollLock
Select
;
Separator
/
Sleep the Sleep key
Space the Space Bar key(s)
Stop
SysReq the SysReq key
T
Tab the Tab key
ThousandsSeparator the Thousands Separator key
U
Undo
Up the Up arrow key (navigation keypad)
V
VolumeDown
VolumeUp
W
WWW the WWW/World Wide Web key
X
Y
Z
# ISO USB keyboards actually use this code instead of 49 for the same key, but all OSes I've seen treat the two codes identically. So, as an implementor, unless your keyboard generates both of those codes and your OS treats them differently, you should generate SDL_SCANCODE_BACKSLASH instead of this code. As a user, you should not rely on this code because SDL will never generate it with most (all?) keyboards.
&
*
@
^
:
$
!
>
#
(
<
%
+
?
)
_
=================== ================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================================
Reference in New Issue View Git Blame Copy Permalink