Skip to content

What can a DynamicKey do

Jump to bottom
kmcnaught edited this page Jul 31, 2024 · 6 revisions

A <DynamicKey> defines a single eye-selectable key placed an interface, with one or more behaviours associated with it.

Here is a simple example of a DynamicKey, which has the label "A" and when you select it, it causes the (A) button on a gamepad to be pressed:

<DynamicKey>
     <Label>A</Label>
     <KeyPress>XBoxA</KeyPress>
</DynamicKey>

Key properties

You can define the following properties as XML elements inside the key

  • <Label> - the label that appears on the key
  • <Symbol> - the symbol that appears on the key (see Symbols for a list of available symbols)
  • <ShiftDownLabel> - an alternative label to show when Shift` is held down
  • <KeyGroup> - a key may have one or more KeyGroup elements to associate it with a KeyGroup named in the XML file - see Key groups for more information

A key also can have the following optional attributes:

  • Row - which row of the grid to be placed in (if not declared it will be positioned automatically)
  • Col - which column of the grid to be placed in (if not declared it will be positioned automatically)
  • Width - the width, in number of columns (defaults to 1)
  • Height - the height, in number of rows (defaults to 1)
  • Any of the attributes of a Key group may be declared here and will act as override values for this key.

For example, this key has lots of optional elements and attributes. It presses the keyboard key "p":

<DynamicKey Row="3" Col="4" Width="2" Height="1" ForegroundColor="green">
     <Label>p</Label>
     <ShiftDownLabel>P</ShiftDownLabel>
     <KeyPress>p</KeyPress>
     <KeyGroup>LetterKeys</KeyGroup>
</DynamicKey>

Multiple actions in one key

If you want more than one action to occur in a single key press, just add each element one after another. They will be performed in the order they appear in the DynamicKey declaration. For instance, this key presses (A) then (B) then (X) with 100ms delays between each press.

<DynamicKey>
     <Label>A</Label>
     <KeyPress>XBoxA</KeyPress>
     <Wait>100</Wait>
     <KeyPress>XBoxB</KeyPress>
     <Wait>100</Wait>
     <KeyPress>XBoxX</KeyPress>
</DynamicKey>

Key presses, in different ways

When you press a key on a physical keyboard or a gamepad with your finger or thumb, what actually happens is the key is pressed DOWN and then shortly afterwards the key is released UP. In many games, this natural short delay is necessary for the associated action to occur.

A KeyPress action as used in the above examples is the simplest way to perform a full keypress (DOWN and then UP). It includes a short default delay. This delay can be customised in OKGO's settings (right click -> Settings -> Controls).

You can also specify the duration for a specific key press using a Duration attribute, where the duration is specified in milliseconds:

<DynamicKey>
     <Label>A</Label>
     <KeyPress Duration="100">XBoxA</KeyPress>
</DynamicKey>

Sometimes you may need more control over a key press, for instance pressing a particular button/key for longer, or pressing more than one button at a time. In this case you can explicitly control the KeyDown and KeyUp events separately. Here is an example in which the (A) button is pressed for 500 milliseconds.

<DynamicKey>
     <Label>A</Label>
     <KeyDown>XBoxA</KeyDown>
     <Wait>500</Wait>
     <KeyUp>XBoxA</KeyUp>
</DynamicKey>

This key presses (A) and (B) together for 200 milliseconds

<DynamicKey>
     <Label>A</Label>
     <KeyDown>XBoxA</KeyDown>
     <KeyDown>XBoxB</KeyDown>
     <Wait>500</Wait>
     <KeyUp>XBoxB</KeyUp>
     <KeyUp>XBoxA</KeyUp>
</DynamicKey>

You may also want to lock down a key/button. For this you can use a KeyToggle. The first time you activate this key, it will hold the button down, and the next time it will release the button. While the button is held down, the key will appear "locked" to show you that it's still active.

<DynamicKey>
     <Label>A</Label>
     <KeyToggle>XBoxA</KeyToggle>
</DynamicKey>

What can you press?

A KeyDown, KeyUp, KeyPress or KeyToggle can be defined for any of the following "keys":

  • A button on a gamepad:
    • Face buttons: XboxA, XboxB, XboxX, XboxY, XboxStart, XboxBack, XboxGuide
    • D-pad: XboxUp, XboxDown, XboxLeft, XboxRight
    • Click down sticks: XboxLeftThumb , XboxRightThumb
    • Shoulder/bumper/triggers: XboxLeftShoulder , XboxRightShoulder , XBoxLeftTrigger , XBoxRightTrigger
  • A single-character key like w, a, s, d
  • A named function key like Space or F12. This can match:
    • the (case-sensitive) name of a builtin FunctionKey with associated VirtualKeyCode from this list: FunctionKeysExtensions.cs
    • the (case-insensitive) name of any keyboard from InputSimulator's VirtualKeyCodes, for instance <KeyUp>SNAPSHOT</KeyUp> or <KeyUp>Snapshot</KeyUp>. This excludes keycodes associated with mouse buttons, such as LBUTTON which do not seem to work.

Manually controlling thumb sticks with a Press

You can have finer control over joysticks by treating the "thumb stick" as a button, but with specified direction to press. For example:

  • <KeyPress>XboxLeftThumb</KeyPress> presses and release the left thumb stick in neutral
  • <KeyDown>XboxRightThumb</KeyDown> holds down the right thumb stick in neutral
  • <KeyDown>XboxLeftThumbLeft</KeyDown> holds the left joystick down to the left.
  • <KeyDown>XBoxLeftThumb | NorthEast | 0.25 </KeyDown><Wait>100</Wait><KeyUp>XBoxLeftThumb | NorthEast | 0.25 </KeyUp> presses the left joystick at 25% up and to the right, for 100 milliseconds, then releases.

[Note that currently <KeyPress Duration=... doesn't seem to respect the duration for a joystick "press" - this is a bug that will be fixed]

In general you can construct a request as follows:

// XBoxLeftThumbLeft
// XBoxRightThumbUp
// Any combination: XBox{Left/Right}Thumb{Left/Right/Up/Down/Forward/Back/Backward}
// Half versions: XBox{Left/Right}ThumbHalf{Left/Right/Up/Down/Forward/Back/Backward}
// 
// With stick, direction & amplitude separated with |:
// XBoxLeftThumb | NorthEast | 0.25
// XBoxRightThumb | South | 1.0
// XBoxRightThumb | Up | 1.0
// XBoxRightThumb | 10 | 1.0
// XBoxRightThumb | Down 
// XBoxRightThumb|Left
//  
// If no amplitude given, will default to 1.0
// Direction is word, compass direction or degrees clockwise from north (integer)
// Accepted words are: "northeast", "southeast", "southwest", "northwest", "up", "forward", "north", 
//                     "right", "east", "down", "backward", "back", "south", "left", "west"
// Whitespace and capitalisation is ignored
Clone this wiki locally