Hotkey Config File Format

The config file is a plain text file that you edit on your computer and select in the add-on preferences file picker.

Defining Modes

A mode is defined by writing the name of the mode with an optional configuration.

:: default : config -> border_color=#0f0, border_width=10

A mode named default is required and it's the mode Superkey starts in. With the above declaration the Blender UI will show a 10-pixel wide green border when starting Superkey.

Colors can be in 3- or 6-digit hex RGB format (#fff or #ffffff), or one in the supported set of named colors: red, orange, yellow, green, blue, indigo, and violet. Red is the default color if no color is set. It's a good idea to give each mode a unique color to tell them apart.

The border width is 10 pixels by default if not defined, with a minimum of 8 and a max of 50.

You can define as many modes as you want. The name is only important to help you remember what the mode is for; the name will never be seen in the Blender UI.

Defining Hotkeys

After you've defined a mode you can start giving it hotkeys.

Each hotkey definition exists on one line and has:

• the name of one or more modes

• a key or key combination, and

• a command.

Let's see an example:

default < c : eval -> bpy.ops.mesh.primitive_cube_add()
sculpt  < c : eval -> bpy.ops.wm.tool_set_by_id(name="builtin_brush.Crease")

# Subdivide, but don't exit Superkey afterward.
default @ < s : eval -> bpy.ops.mesh.subdivide()

# Switch the current space to the Image Editor in both default and sculpt mode.
default, sculpt < shift - i : switch_space -> IMAGE_EDITOR

# Snap cursor to selected.
default < ctrl + shift - s : eval -> bpy.ops.view3d.snap_cursor_to_selected()

This hotkey creates a Cube when the key c is tapped while Superkey is in its default mode. In sculpt mode, the same key will choose the Crease brush.

You can think of the < character as an arrow that's saying, "insert the following hotkey into this mode." What follows is the key combination, in this case simply c, followed by a colon (:) which signals the command to execute. In this case the command is eval, which runs the Python code that follows the -> symbol.

The @ symbol means that Superkey will continue accepting keypresses after the command completes. In this example, you can subdivide more than once by pressing the s key multiple times, then hit the Escape key to exit Superkey.

You can discover which Python code to use by following the guide Getting Hotkey Commands.

Bind a hotkey to multiple modes by joining mode names with a comma.

Use the ctrl, shift, alt, and os keys as modifiers to make key combinations. Note that modifier keys are joined with +, while the last key is joined with -. The os key is the Command key on Mac, Windows key on Windows, and Super key on Linux.

Valid Hotkey Commands

The valid hotkey commands are eval, viewport_shading, switch_space, and cancel, and there's a special command for switching the active mode.

eval

The eval command will run whatever python code you give it, but it's best to keep it limited to Blender's built-in operators. Find out more about these operators in Getting Hotkey Commands.

# Toggle X-ray in the 3D Viewport.
default < x : eval -> bpy.ops.view3d.toggle_xray()

# Set the selected object's origin to its geometry.
default < o : eval -> bpy.ops.object.origin_set(type='ORIGIN_GEOMETRY')

# Set an object's parent, like using ctrl-p and clicking "Object".
object < p : eval -> bpy.ops.object.parent_set(type='OBJECT', keep_transform=False)

exec (v1.1.0+)

The exec command is like eval, but it's only used when you have a Python string that assigns a value by using the = symbol. Find out more about this in Changing Tool Settings.

# Set Dynamic Topology Refine Method to "Subdivide Edges".
default < a : exec -> bpy.context.tool_settings.sculpt.detail_refine_method = 'SUBDIVIDE'

# Set Dynamic Topology Refine Method to "Collapse Edges".
default < s : exec -> bpy.context.tool_settings.sculpt.detail_refine_method = 'COLLAPSE'

# Set Dynamic Topology Refine Method to "Subdivide Collapse".
default < d : exec -> bpy.context.tool_settings.sculpt.detail_refine_method = 'SUBDIVIDE_COLLAPSE'

viewport_shading

Switch the Viewport Shading in the 3D Viewport. The context changes after switching, so use of @ to keep Superkey running is best avoided.

default < h : viewport_shading -> WIREFRAME
default < j : viewport_shading -> SOLID
default < k : viewport_shading -> MATERIAL
default < l : viewport_shading -> RENDERED

switch_space

Switch space changes the displayed UI. For example, changing the 3D Viewport into the Image Editor.

# Show the 3D Viewport.
default < 3 : switch_space -> VIEW_3D

# Show the Image Editor.
default < i : switch_space -> IMAGE_EDITOR

The supported spaces are:

• VIEW_3D

• IMAGE_EDITOR

• NODE_EDITOR

• SEQUENCE_EDITOR

• CLIP_EDITOR

• DOPESHEET_EDITOR

• GRAPH_EDITOR

• NLA_EDITOR

• TEXT_EDITOR

• CONSOLE

• INFO

• OUTLINER

• PROPERTIES

• FILE_BROWSER

• SPREADSHEET

• PREFERENCES

cancel

This command quits Superkey. While the Escape key is always bound to this, it may come in handy to bind it to other keys.

# Quit Superkey with Command + Return on Mac,
#                    Windows + Enter on Windows, and
#                    Super + Enter on Linux.
# Bound to both default and sculpt modes.
default, sculpt < os - return : cancel

Switching Modes

Switching modes has a different format. Instead of a colon, use a semicolon. There is no -> input syntax for this command.

# First define a mode.
:: sculpt : config -> border_color=blue

# Bind `s` key in default mode to switch to sculpt mode.
default < s ; sculpt