Skip to content

Latest commit

 

History

History
340 lines (235 loc) · 8.61 KB

profile-file.md

File metadata and controls

340 lines (235 loc) · 8.61 KB

SC-Controller profile file specification

Profile file contains json-encoded dictonary with specific keys. Missing keys are substituted with defaults, unknown keys are ignored. See Desktop.sccprofile for example.

Root dictonary has to contain following keys:

  • buttons - contains subkey for controller buttons. See buttons.
  • pad_left - sets action executed when finger is moved on left touchpad.
  • pad_right - ... when finger is moved on right touchpad.
  • stick - ... when stick angle is changed.
  • trigger_left - ... when left trigger value is changed.
  • trigger_right - ... when right trigger value is changed.
  • gyro - ... when gyroscope reading changes. Gyroscope in is activated only if this key is set to something else than NoAction
  • menus - stores menus saved in profile. See menus.
  • version - profile file version. Current version is 1. See If not pressent, 0 is assumed. If profile file version is lower than expected, automatic conversion may happen. This conversion is in-memory only, but changing and saving such profile in GUI will save converted data.

See actions.md file for list of possible actions.

Action definition

Action definition is dictionary containing action key and optional name key. Value assigned to action describes action to be executed.

action key can describe entire action, but for better readability, it is also possible to specify additional properties using additional keys.

For example,

{
  "trigger_left": {
    "action": "axis(Axes.ABS_Z)",
    "name": "Aim",
}}

assigns axis action with Axes.ABS_Z parameter to left trigger.

Additional keys in action definition

X and Y

Turns action into XYAction, allowing to specify different action for each pad or stick axis. If either of keys is specified, action key is ignored.

Example:

"stick" : {
  "X": { "action": "axis(Axes.ABS_RX)" },
  "Y": { "action": "raxis(Axes.ABS_RY)" }
},

is same as "stick" : { "action" : "XY(axis(Axes.ABS_RX), raxis(Axes.ABS_RY))" }

levels

Turns action into TriggerAction, allowing to specify lower and upper trigger levels among which is action executed.

Example:

"trigger_left": {
  "action": "button(BTN_LEFT)", 
  "levels": [127, 255]
},

Sets action that presses left mouse button, but only if trigger is roughly half-pressed.

dpad

Turns action into DPadAction, allowing to assign different action for each side of pad or stick alignment.

Example:

"dpad" : [
  { "action": "button(Keys.KEY_UP)" },
  { "action": "button(Keys.KEY_DOWN)" },
  { "action": "button(Keys.KEY_LEFT)" },
  { "action": "button(Keys.KEY_RIGHT)" }
],

ring

Defines outer and inner ring bindings. Expects keys with 'inner' and 'outer' actions and 'radius' as float value, but all keys are optional.

Example:

"pad_left": {
  "ring": {
    "inner": { "action": "XY(axis(Axes.ABS_X), raxis(Axes.ABS_Y))" },
    "outer": { "action": "XY(axis(Axes.ABS_RX), raxis(Axes.ABS_RY))" }, 
    "radius": 0.4
  }
},

defines inner ring binding controlling left stick and outer ring right stick of emulated gamepad.

tilt

Turns action into TiltAction, allowing to assign different action for tilting dpad. Works pretty-much as dpad on gyro.

Example:

"tilt" : [
  { "action": "button(Keys.KEY_UP)" },
  { "action": "button(Keys.KEY_DOWN)" },
  { "action": "button(Keys.KEY_LEFT)" },
  { "action": "button(Keys.KEY_RIGHT)" }
],

deadzone

Specifies deadzone. Allows for lower and upper subkeys defaulting to 0 and 32767 and mode subkey defaulting to 'CUT'. See see deadzone modifier for list of modes.

Example:

"trigger_left": {
	"mode" : "linear",
  "action": "axis(Axes.ABS_Z)",
  "deadzone": {
    "lower": 100,
    "upper": 200
}},

sensitivity

Specifies input sensitivity. Value is list with one or two values for sensitivity over X and Y axis (or one value for sensitivity of trigger.) Default sensitivity is 1.0

Example:

"stick" : {
  "action": "trackball()",
  "sensitivity": [2.0, 0.5]
},

doubles sensitivity over X and halves over Y axis.

rotate

Rotates input pad or stick input by given angle.

Example:

"stick" : {
  "action": "trackball()",
  "rotate": 15
},

feedback

Enables haptic feedback for action. Value is list with one to three values specifying feedback position ('LEFT', 'RIGHT' or 'BOTH'), amplitude and frequency.

Example:

"pad_left": {
  "action": "trackball()",
  "feedback": ["LEFT", 512.0, 5.0]
},

specifies feedback with amplitude of 512 (default vlaue) and frequency of 5 generated by left motor.

smooth

Enables input smoothing (see smooth modifier)

Example:

"pad_left": {
  "action": "trackball()",
  "smooth": [ 8, 0.7, 2.0 ]
},

enables smoothing with buffer of 8 and modifier set to 0.7.

osd

If set to True, enables OSD for action.

Example:

"X": {
  "action": "button(Keys.BTN_EAST)", 
  "osd": true
},

enables OSD feedback for X button.

click

If set to True, enables 'click' modifier, making action executed only when pad or stick is pressed.

Example:

"pad_left": {
  "action": "mouse()",
  "click": True
},

ball

If set to value, enables trackball mode. Value is list with zero to two values specifying friction and mass of virtual 'spinning ball'. See ball modifier for more info.

Example:

"pad_left": {
  "action": "mouse()",
  "ball": [ 10.0 ]
},

circular

Designed to controls scroll wheel by scrolling finger around pad, but can be used with any axis.

Example:

"pad_left": {
  "action": "mouse(Rels.REL_WHEEL)",
  "circular": true
},

circularabs

Works as to circular, but instead of counting with finger movements, translates exact position on dpad to axis value.

Example:

"pad_left": {
  "action": "circularabs(Rels.REL_WHEEL)",
  "circular": true
},

modes

Defines mode shifting (see mode modifier).

Value is dict with physical key names (A, B, X, Y...) as keys and actions for each mode as values. Action on same level as mode is used as default action.

Example:

"modes": {
  "A": { "action": "mouse()" },
  "B": { "action": "XY( axis(Axes.ABS_X), raxis(Axes.ABS_Y) )" }
},

defines pad or stick that controls mouse while button A is pressed and left virtual stick while button B is pressed.

gestures

Enables gesture cognition on pad (see gestures modifier).

Value is dict with encoded gestures (see description in actions.md) and actions for each gesture as values.

Example:

"gestures": {
  "UD": { "action": "button(Key.R)" }
},

enables gesture recognition with single gesture activated when user does short stroke up followed by short stroke down.

doubleclick

Defines action that is executed when user double-clicks with button. Optional time key can be used on same level as doubleclick to modify double-click time.

Example:

"buttons": {
  "A": {
    "action": "button(KEY_X)",
    "doubleclick": { "action": "button(KEY_Z)" },
	"time": 5
  }
}

defines button that emulates pressing X key when pressed normally and pressing Z key when doubleclicked.

hold

Defines action that is executed when user holds button for short time. Optional time key can be used on same level as hold to modify double-click time.

Example:

"buttons": {
  "A": {
    "action": "button(KEY_X)",
    "hold": { "action": "button(KEY_Z)" },
	"time": 5
  }
}

defines button that emulates pressing X key when pressed normally and pressing Z key when held for 5 seconds.

Buttons

buttons is dictionary with keys for each gamepad button. Possible keys are:

  • X, Y, A and B for colored buttons
  • C for Steam button in center
  • SELECT and START for small "( < )" and "( > )" buttons
  • LB and RB for left and right bumper
  • LPAD, RPAD and STICK for presing pads or stick.

All keys are optional. Value for each key is action definition

Example:

"buttons": {
  "A":    { "action": "button(Keys.BTN_WEST)",  }, 
  "B":    { "action": "osd('Hello world!')" }, 
  "BACK": { "action": "button(Keys.KEY_LEFTCTRL) and button(Keys.KEY_A)" }, 
}

Menus

menus is dictionary with menus stored along with profile. Keys are IDs of menus; Menu ID can contain any characters but dots (".") and slashes ("/").

Value for each key is same as root list in menu file