IS:KeyMapper

From Lavish Software Wiki
Revision as of 19:48, 1 January 2009 by Lax (talk | contribs)
Jump to navigation Jump to search

What is KeyMapper?

KeyMapper is an open source key mapper solution for Inner Space

Features

  • Generates Inner Space "keypress" binds from XML configuration
  • Allows different keys to different target windows with ease
  • Makes it easy to create highly-customizable round-robin binds
  • Supports FTL (focusless, targetless, leaderless) setups, used for World of Warcraft
  • Supports any number of key maps, which can be activated or deactivated at will

Compatibility with Repeater

When using KeyMapper in conjunction with Repeater, you should prevent repeating of the keys you are setting up KeyMapper hotkeys for. This can be done using a blacklist (containing the key) or whitelist (not containing the key), or by simply disabling Repeater -- after all, with KeyMapper, you probably don't need Repeater passing keys.

Installing KeyMapper

  1. Download the latest version: keymapper-20090101.zip
  2. Extract to the Scripts folder of your Inner Space installation

Launching KeyMapper

Per Inner Space session you want to be able to use KeyMapper from
run keymapper

Configuring KeyMapper

KeyMapper will interpret XML files in a particular format.

When launched, KeyMapper will automatically import configuration from KeyMapper.XML, so to make it easy on yourself, always start by creating a KeyMapper.XML. You can have any number of KeyMapper configuration files, which you can import at any time using the KeyMapper command. Any number of configuration files can be loaded at any given time. After KeyMapper automatically imports KeyMapper.XML, it will then automatically load (activate) a key map from it called "Main". If that key map doesn't exist, it of course will not do anything. You can load key maps at any time using the KeyMapper command. Any number of key maps can be active at any given time.

For example, your KeyMapper.XML might have key maps for several different multi-boxing teams, in addition to the Main key map. The Main key map can be automatically loaded for all of the teams, and then it's a matter of loading the specific team's key map to make it complete. The Main key map would contain only the things that should be used for all of the teams, such as a key to make the team auto-follow, and so on.

Configuration XML file format

Step 1: Base configuration file

Let's start at the beginning. Here is a valid starting point for your KeyMapper XML file. It doesn't define any key maps, and it doesn't define any FTL modifiers. 

<?xml version='1.0' encoding='UTF-8'?>
<InnerSpaceSettings>
	<Set Name="Key maps">
	</Set>
</InnerSpaceSettings>

Step 2: FTL Modifiers (optional)

Here is the same example, with "standard" FTL Modifier configuration. 

<?xml version='1.0' encoding='UTF-8'?>
<InnerSpaceSettings>
	<Set Name="FTL Modifiers">
		<Setting Name="1">ctrl+shift</Setting>
		<Setting Name="2">ctrl+alt</Setting>
		<Setting Name="3">alt+shift</Setting>
		<Setting Name="4">ctrl+alt+shift</Setting>
		<Setting Name="5">ctrl</Setting>
	</Set>
	<Set Name="Key maps">
	</Set>
</InnerSpaceSettings>

The Set tag must have the Name attribute set to "FTL Modifiers" in order to apply the FTL Modifiers. The Settings inside must be Named 1, 2, and so on in order to match the session with the modifier. 1 means the first session, 2 means the second session, and so on. The following keys can be used as FTL Modifiers:

  • CTRL
  • SHIFT
  • ALT
  • RIGHT CTRL
  • RIGHT SHIFT
  • RIGHT ALT

As in the example, use + to string the modifiers together.

When set, FTL Modifiers will be automatically applied to all of the key maps that get loaded AFTER the FTL Modifiers are set, if and only if those key maps have "Use FTL Modifiers" enabled. Certain KeyMapper functionality is reduced when using FTL modifiers, as follows. FTL Modifiers may not be fully compatible with the Hold option. When sending to ALL, the FTL Modifier will be applied to ALL, including the local session. It is, of course, possible to set up FTL modifiers per bind, instead of using this setting.

To enable FTL Modifiers for a given Key Map, add the following Setting to the Key Map: 

<Setting Name="Use FTL Modifiers">1</Setting>


Step 3: Adding key maps

Here is the format for key maps. 

<?xml version='1.0' encoding='UTF-8'?>
<InnerSpaceSettings>
	<Set Name="Key maps">
		<Set Name="main">
		</Set>
	</Set>
</InnerSpaceSettings>

The innermost Set in the above XML is Named "main". This defines the "main" key map. Any number of Sets can be created inside Key maps, with different names. For example: 

<?xml version='1.0' encoding='UTF-8'?>
<InnerSpaceSettings>
	<Set Name="Key maps">
		<Set Name="main">
		</Set>
		<Set Name="shaman">
		</Set>
		<Set Name="tauren">
		</Set>
	</Set>
</InnerSpaceSettings>

As explained previously, to enable FTL Modifiers for a given Key Map, add the following Setting to the Key Map: 

<Setting Name="Use FTL Modifiers">1</Setting>

Example: 

<?xml version='1.0' encoding='UTF-8'?>
<InnerSpaceSettings>
	<Set Name="Key maps">
		<Set Name="main">
                     <Setting Name="Use FTL Modifiers">1</Setting>
		</Set>
		<Set Name="shaman">
		</Set>
		<Set Name="tauren">
		</Set>
	</Set>
</InnerSpaceSettings>


Step 4: Adding a key mapping

Here is a sample with a simple mapping. 

<?xml version='1.0' encoding='UTF-8'?>
<InnerSpaceSettings>
	<Set Name="Key maps">
		<Set Name="main">
			<Set Name="Other Jump">
				<Setting Name="Hotkey">ctrl+space</setting>
				<Setting Name="all other">space</setting>
			</Set>
		</Set>
	</Set>
</InnerSpaceSettings>

Within the "Main" key map Set, we have a new Set called "Other Jump". Any number of mappings can be placed inside the key map set, with different names. Inside, it has two Settings. One is called Hotkey, with a value of ctrl+space. A Setting called Hotkey is required for any mapping we create. This means that when we hit ctrl+space, the mapping is going to do what we tell it to. That's done by our other Setting. Any Setting that doesn't match a reserved name (currently including only Hotkey and Hold, which we will get to soon) is going to be considered a target to send a key to. Any number of targets can be added by creating an additional Setting. Here, the target is "all other", with the value of space. So, when we hit ctrl+space, "all other" will hit space. If FTL Modifiers are set, the correct modifier will automatically be applied.

Valid targets include:

  • self: The active session. When pressing the mapped key, nothing is pressed locally unless a target includes it! This is one of those.
  • all: ALL sessions, including the active session. This may include sessions on other PCs, if they are connected with Uplink Networking (which is disabled by default)
  • all other: ALL OTHER sessions, meaning ALL except the active session.
  • 1 through #: Session 1, session 2, etc can be referenced by simply giving the number, e.g. 1, 2, 3, etc.
  • is1 through is#: Alternative method to refer to session 1, session 2, etc (note: not valid in FTL Modifiers, just these targets!), e.g. is1, is2, is3, etc.

Here is a sample mapping passing different keys to different targets (this would go inside a mapping Set) 

<Setting Name="1">6</Setting>
<Setting Name="2">alt+6</Setting>
<Setting Name="3">alt+0</Setting>
<Setting Name="4">-</Setting>
<Setting Name="5">alt+=</Setting>
Step 4.5: Causing the keys to be held while holding the mapped key

To enable holding the keys while the mapped key is held down, add a Setting called Hold with the value 1 as follows: 

<Setting Name="Hold">1</Setting>

Example: 

<?xml version='1.0' encoding='UTF-8'?>
<InnerSpaceSettings>
	<Set Name="Key maps">
		<Set Name="movement">
			<Set Name="forward">
				<Setting Name="Hold">1</Setting>
				<Setting Name="Hotkey">ctrl+w</Setting>
				<Setting Name="all">w</Setting>
			</Set>
		</Set>
	</Set>
</InnerSpaceSettings>

Step 5: Round robin

Here is the sample from Step 4, with a Shaman key map set, and a round robin earth shock mapping: 

<?xml version='1.0' encoding='UTF-8'?>
<InnerSpaceSettings>
	<Set Name="Key maps">
		<Set Name="main">
			<Set Name="Other Jump">
				<Setting Name="Hotkey">ctrl+space</setting>
				<Setting Name="all other">space</setting>
			</Set>
		</Set>
		<Set Name="shaman">
			<Set Name="earth shock">
				<Setting Name="Hotkey">G12</Setting>
				<Set Name="step 1">
					<Setting Name="1">alt+5</Setting>
				</Set>
				<Set Name="step 2">
					<Setting Name="2">alt+5</Setting>
				</Set>
				<Set Name="step 3">
					<Setting Name="3">alt+5</Setting>
				</Set>
				<Set Name="step 4">
					<Setting Name="4">alt+5</Setting>
				</Set>
				<Set Name="step 5">
					<Setting Name="5">alt+5</Setting>
				</Set>
			</Set>
		</Set> 
	</Set>
</InnerSpaceSettings>

The shaman key map set would be loaded using the KeyMapper command, e.g.: 

keymapper -loadmap shaman

In this example, the Hotkey for Earth Shock is G12 -- one of the keys on a G15/G11 keyboard. Then we have more Sets, named step 1, step 2, step 3, and so on, inside our mapping. The names of these sets do not matter -- they are named step 1 through step 5 for ease of understanding. They are always going to be used in order from top to bottom, regardless of the name. In this example, each press of G12 is going to send alt+5 to a different target. The first press will send to the first character, second to the second, and so on. After the final step is executed, it will wrap back to the first step. Each Set may contain any number of target-press Settings in the same format as before.

Here is a more complex round-robin example: 

			<Set Name="utility totems">
				<Setting Name="Hotkey">G9</Setting>
				<Set Name="step 1">
					<Setting Name="1">6</Setting>
					<Setting Name="2">alt+6</Setting>
					<Setting Name="3">alt+0</Setting>
					<Setting Name="4">-</Setting>
					<Setting Name="5">alt+=</Setting>
				</Set>
				<Set Name="step 2">
					<Setting Name="2">6</Setting>
					<Setting Name="3">alt+6</Setting>
					<Setting Name="4">alt+0</Setting>
					<Setting Name="1">-</Setting>
					<Setting Name="5">alt+=</Setting>
				</Set>
				<Set Name="step 3">
					<Setting Name="3">6</Setting>
					<Setting Name="4">alt+6</Setting>
					<Setting Name="5">alt+0</Setting>
					<Setting Name="1">-</Setting>
					<Setting Name="2">alt+=</Setting>
				</Set>
				<Set Name="step 4">
					<Setting Name="4">6</Setting>
					<Setting Name="5">alt+6</Setting>
					<Setting Name="1">alt+0</Setting>
					<Setting Name="2">-</Setting>
					<Setting Name="3">alt+=</Setting>
				</Set>
				<Set Name="step 5">
					<Setting Name="5">6</Setting>
					<Setting Name="1">alt+6</Setting>
					<Setting Name="2">alt+0</Setting>
					<Setting Name="3">-</Setting>
					<Setting Name="4">alt+=</Setting>
				</Set>
			</Set>

A fuller example

<?xml version='1.0' encoding='UTF-8'?>
<InnerSpaceSettings>
	<Set Name="Key maps">
		<Set Name="main">
			<Set Name="Other Jump">
				<Setting Name="Hotkey">ctrl+space</setting>
				<Setting Name="all other">space</setting>
			</Set>
		</Set>
		<Set Name="shaman">
			<Set Name="earth shock">
				<Setting Name="Hotkey">G12</Setting>
				<Set Name="step 1">
					<Setting Name="1">alt+5</Setting>
				</Set>
				<Set Name="step 2">
					<Setting Name="2">alt+5</Setting>
				</Set>
				<Set Name="step 3">
					<Setting Name="3">alt+5</Setting>
				</Set>
				<Set Name="step 4">
					<Setting Name="4">alt+5</Setting>
				</Set>
				<Set Name="step 5">
					<Setting Name="5">alt+5</Setting>
				</Set>
			</Set>
			<Set Name="frost shock">
				<Setting Name="Hotkey">G10</Setting>
				<Set Name="step 1">
					<Setting Name="1">5</Setting>
				</Set>
				<Set Name="step 2">
					<Setting Name="2">5</Setting>
				</Set>
				<Set Name="step 3">
					<Setting Name="3">5</Setting>
				</Set>
				<Set Name="step 4">
					<Setting Name="4">5</Setting>
				</Set>
				<Set Name="step 5">
					<Setting Name="5">5</Setting>
				</Set>
			</Set>
			<Set Name="thunderstorm">
				<Setting Name="Hotkey">G6</Setting>
				<Set Name="step 1">
					<Setting Name="2">t</Setting>
				</Set>
				<Set Name="step 2">
					<Setting Name="3">t</Setting>
				</Set>
				<Set Name="step 3">
					<Setting Name="4">t</Setting>
				</Set>
				<Set Name="step 4">
					<Setting Name="5">t</Setting>
				</Set>
			</Set>
			<Set Name="utility totems">
				<Setting Name="Hotkey">G9</Setting>
				<Set Name="step 1">
					<Setting Name="1">6</Setting>
					<Setting Name="2">alt+6</Setting>
					<Setting Name="3">alt+0</Setting>
					<Setting Name="4">-</Setting>
					<Setting Name="5">alt+=</Setting>
				</Set>
				<Set Name="step 2">
					<Setting Name="2">6</Setting>
					<Setting Name="3">alt+6</Setting>
					<Setting Name="4">alt+0</Setting>
					<Setting Name="1">-</Setting>
					<Setting Name="5">alt+=</Setting>
				</Set>
				<Set Name="step 3">
					<Setting Name="3">6</Setting>
					<Setting Name="4">alt+6</Setting>
					<Setting Name="5">alt+0</Setting>
					<Setting Name="1">-</Setting>
					<Setting Name="2">alt+=</Setting>
				</Set>
				<Set Name="step 4">
					<Setting Name="4">6</Setting>
					<Setting Name="5">alt+6</Setting>
					<Setting Name="1">alt+0</Setting>
					<Setting Name="2">-</Setting>
					<Setting Name="3">alt+=</Setting>
				</Set>
				<Set Name="step 5">
					<Setting Name="5">6</Setting>
					<Setting Name="1">alt+6</Setting>
					<Setting Name="2">alt+0</Setting>
					<Setting Name="3">-</Setting>
					<Setting Name="4">alt+=</Setting>
				</Set>

			</Set>
			<Set Name="dps bolt">
				<Setting Name="Hotkey">G18</Setting>
				<Setting Name="shm_dps">2</Setting>
			</Set>
			<Set Name="all bolt">
				<Setting Name="Hotkey">G18</Setting>
				<Setting Name="all">2</Setting>
			</Set>
		</Set>
		<Set Name="tauren">
			<Set Name="stomp">
				<Setting Name="Hotkey">G15</Setting>
				<Set Name="step 1">
					<Setting Name="1">8</Setting>
				</Set>
				<Set Name="step 2">
					<Setting Name="2">8</Setting>
				</Set>
				<Set Name="step 3">
					<Setting Name="3">8</Setting>
				</Set>
				<Set Name="step 4">
					<Setting Name="4">8</Setting>
				</Set>
				<Set Name="step 5">
					<Setting Name="5">8</Setting>
				</Set>
			</Set>
		</Set>
	</Set>
</InnerSpaceSettings>


Commands

KeyMapper

The keymapper command provided by KeyMapper is the intended method for interacting with or configuring KeyMapper while it is loaded. It accepts any number of the following parameters in any order (but will be applied left to right):

  • -ftlmods <combo>: Sets modifiers to be used for FTL (focusless targetless leaderless) setups
  • -noftlmods: Removes FTL modifiers
  • -import <filename>: Imports a KeyMapper XML configuration file, merging with the already-loaded configuration (useful for having multiple configuration files). After import, individual keymaps may then be activated with -loadmap. Importing does not automatically activate or update any already activated keymaps.
  • -loadmap <name>: Loads (activates) a keymap by name, from the current configuration. Any number of keymaps can be loaded.
  • -unloadmap <name>: Unloads a keymap by name

Release history

Retrieved from "https://www.lavishsoft.com/wiki/index.php?title=IS:KeyMapper&oldid=6923"