Differences

This shows you the differences between two versions of the page.

--- evmapy [2022/04/08 12:10] – created atari
+++ evmapy [2022/04/14 06:38] (current) – header overhaul atari
@@ Line 1: / Line 1: @@
 ====== Evmapy ======
-<WRAP center round todo>
+[[https://github.com/kempniu/evmapy|Evmapy]] is a tool used by Batocera to map inputs from the controller to a virtual keyboard (although, its capable of quite a bit more than that). Refer to [[https://github.com/kempniu/evmapy/blob/master/README.rst|evmapy's readme]] for more information. This is primarily used to enable the use of the emulator's shortcuts if it does not natively support hotkey binding onto the controller's buttons (for example, [[emulators:dolphin|Dolphin]] does not use evmapy).
-Under construction.
-</WRAP>
-[[https://github.com/kempniu/evmapy|Evmapy]] is a tool used by Batocera to map inputs from the controller to a virtual keyboard (although, its capable of quite a bit more than that). You can refer to [[https://github.com/kempniu/evmapy/blob/master/README.rst|its readme]] for more information.
+===== Setting up the makefile =====
-===== Input triggers =====
+The emulator's "keys" file, if used, is located at ''package/batocera/<emulators or ports>/<emulator or port>/<system shortname>.<emulator>.keys''. This file must then be copied from ''%%$(BR2_EXTERNAL_BATOCERA_PATH)/package/batocera/<emulators or ports>/<emulator or port>/<system shortname>.<emulator>.keys%%'' to ''%%$(TARGET_DIR)/usr/share/evmapy%%'' in its makefile. For example, with Citra (the 3DS emulator):
-<WRAP center round todo>
+<code bash citra.mk>
-Todo
+define CITRA_EVMAP
-</WRAP>
+	# Create the directory if it doesn't already exist.
+	mkdir -p $(TARGET_DIR)/usr/share/evmapy
+	# Copy, while making all the parent folders, the keys file to the correct location.
+	cp -prn $(BR2_EXTERNAL_BATOCERA_PATH)/package/batocera/emulators/citra/3ds.citra.keys \
+		$(TARGET_DIR)/usr/share/evmapy
+endef
-===== Acceptable output events =====
+CITRA_POST_INSTALL_TARGET_HOOKS = CITRA_EVMAP
+</code>
+===== "Keys" file syntax =====
+Evmapy uses a simple syntax for its events, and indentation/spacing is not enforced (but it's still recommended for readability). First, everything must be inside of a curly bracket:
+<code>
+{
+</code>
+then the controller defined. In Batocera, defining this as ''"actions_player1"'' will automatically use whichever controller is currently assigned to player 1. Then, its triggers and actions are contained within a square bracket:
+<code>
+    "actions_player1": [
+</code>
+From there on, every trigger and action is contained inside of another curly bracket. For instance:
+<code>
+        {
+            "trigger": ["hotkey", "start"],
+            "type": "key",
+            "target": ["KEY_LEFTCTRL", "KEY_Q"],
+            "description": "Exit emulator"
+        },
+</code>
+and additional trigger and actions are separated by commas, like a list, until the last one is reached and the remaining brackets are closed off:
+<code>
+        {
+            "trigger": "r3",
+            "type": "key",
+            "target": "BTN_LEFT",
+            "description": "Mouse Click"
+        }
+    ]
+}
+</code>
+==== Input triggers ====
+Batocera uses ''es_input'''s generic terms to refer to its controller's inputs. Though not everything is intuitive, is a list of the human-readable inputs against the ''"trigger"'' code they use in the keys file:
+^ Input ^ Trigger name ^
+| ''[HOTKEY]'' | ''hotkey'' |
+| ''[START]'' | ''start'' |
+| ''[SELECT]'' | ''select'' |
+| {{:wiki:south.png?nolink&20|South button (B SNES)}} | ''b'' |
+| {{:wiki:east.png?nolink&20|East button (A SNES)}} | ''a'' |
+| {{:wiki:west.png?nolink&20|West button (Y SNES)}} | ''y'' |
+| {{:wiki:north.png?nolink&20|North button (X SNES)}} | ''x'' |
+| D-pad Down | ''down'' |
+| D-pad Right | ''right'' |
+| D-pad Up | ''up'' |
+| D-pad Left | ''left'' |
+| All left analog stick movement | ''joystick1'' |
+| All right analog stick movement | ''joystick2'' |
+| LS Down | ''joystick1down'' |
+| LS Right | ''joystick1right'' |
+| LS Up | ''joystick1up'' |
+| LS Left | ''joystick1left'' |
+| RS Down | ''joystick2down'' |
+| RS Right | ''joystick2right'' |
+| RS Up | ''joystick2up'' |
+| RS Left | ''joystick2left'' |
+| ''[L1]'' | ''pageup'' |
+| ''[R1]'' | ''pagedown'' |
+| ''[L2]'' | ''l2'' |
+| ''[R2]'' | ''r2'' |
+| ''[L3]'' (LS click-in) | ''l3'' |
+| ''[R3]'' (RS click-in) | ''r3'' |
+This is but the tip of the iceberg of triggers that evmapy can parse. Refer to [[https://github.com/kempniu/evmapy/blob/master/README.rst|its documentation]] for more details.
+==== Output events ====
+=== Keys ===
-==== Execute ====
+The bread and butter of events evmapy will be sending out. Type in the name of the key desired to be pressed. If multiple keys are needed, separate them with commas in a list.
-<WRAP center round todo>
+The most common modifier keys: ''KEY_LEFTCTRL'', ''KEY_LEFTSHIFT'', ''KEY_LEFTALT'', ''KEY_RIGHTSHIFT'', ''KEY_ENTER'', ''KEY_PAGEDOWN'', etc.
-Todo
-</WRAP>
-==== Target (keys) ====
+The most common exit shortcuts are ''[ "KEY_LEFTALT", "KEY_F4" ]'' and ''["KEY_LEFTCTRL", "KEY_Q"]''.
 Here's a sample of the ''/usr/include/linux/input-event-codes.h'' file from a standard installation of Solus. This should cover all the possible output events that can be handled by evmapy.
@@ Line 981: / Line 1060: @@
 <--
+=== Execute ===
+In case the emulator in question supports no keyboard shortcuts to perform actions, evmapy is capable of running commands directly. This should only be used as a last-resort, and typically only to kill the emulator.
+To execute a command instead of pressing a key, replace the type ''"key"'' with ''"exec"'', then type out the desired command enclosed in quotation marks as the target. For example, from the [[systems:sonicretro|Sonic Retro engines]] (which do not feature keyboard shortcuts):
+<code>
+	{
+            "trigger": ["hotkey", "start"],
+            "type": "exec",
+            "target": "killall -9 sonic2013; killall -9 soniccd"
+	}
+</code>