Key binding and preset UI ​

It takes about 10 minutes to read this article

This article provides an overview of how to quickly set up control scenarios for your PC experience using key binding and mouse lock, and what features are included in the preset UI for new projects.

What is the key binding? ​

Key binding means that the developer can complete key binding on the basis of the mobile experience UI when making the experience, so as to efficiently and quickly set the PC experience Player's control scheme without redesigning a set of PC experience UI, and the Player's keyboard mouse operation in the experience will be mapped to the corresponding mobile experience UI;

A preset UI is a set of modifiable mobile preset UIs provided by the editor for new projects, and corresponding PC side key bindings.

Key Binding Menu within the UI Editor ​

• Double-click any UI file in the project content, and after clicking the Key Binding button in the UI editor toolbar, open the Key Binding menu, where developers can directly bind or overlay the mobile UI (including joysticks, camera sliders, buttons) to key mouse keys
• The button binding menu for each UI file automatically reads all four types of UI widgets within that UI file: joystick, camera slider, button, text button; only one UI widget can be bound per key mouse button, and the widget bound later overrides the widget bound earlier; but one UI widget can be bound to multiple keys

• For camera sliders, buttons, text buttons: Click/release/hold the bound mouse button to trigger click/release/hold the corresponding UI widget

• For joysticks: supports binding joysticks in four directions up and down and pressing/lifting only,

  • four directions: corresponding joystick input values (0,1), (0,-1), (-1,0) and (1,0) four effects
  • Press/Lift Only: Pressing the bound mouse button triggers a joystick press lift event, but the joystick's current value remains unchanged at (0,0)
  • Use Scene: To achieve aim by turning the camera while firing, joystick controls are recommended for the firing key in the shooting game; and if you need to provide control for the PC side, you can bind the firing joystick's only press/lift to the left mouse button, so that the Player can hold down the right mouse button and drag or directly drag the mouse (when the mouse is locked) to turn the camera to aim and use the left trigger joystick to complete firing

• Click the button in the menu to change bindings, click Reset button to redo to empty

Key Mouse Binding Related APIs ​

• In addition to key binding menus within the UI editor, developers can customize control schemes using scripts or override default key positions
• Note: As with the [Key Binding] menu logic within the UI editor, only one UI widget can be bound per key mouse button. The widget bound behind overrides the widget bound before; however, one UI widget can be bound to multiple buttons

Script Example:

const JumpBtn = this.uiWidgetBase.findChildByPath('Canvas/Button_Jump') as Button
const Joystick = this.uiWidgetBase.findChildByPath('Canvas/Joystick') as VirtualJoystickPanel

// button binding key
JumpBtn.addKey(Keys.Up)
// button unbundling key
JumpBtn.removeKey(Keys.Up)
// joystick binding button
Joystick.addKey(new JoystickBindKeyType(Keys.W,Keys.S,Keys.A,Keys.D))
// joystick change key
let keydata1=new JoystickBindKeyType(Keys.I,Keys.K,Keys.J,Keys.L) 
Joystick.addKey(keydata1)
// joystick unbundling key
Joystick.removeKey(new JoystickBindKeyType(Keys.I,Keys.K,Keys.J,Keys.L))

const JumpBtn = this.uiWidgetBase.findChildByPath('Canvas/Button_Jump') as Button
const Joystick = this.uiWidgetBase.findChildByPath('Canvas/Joystick') as VirtualJoystickPanel

// button binding key
JumpBtn.addKey(Keys.Up)
// button unbundling key
JumpBtn.removeKey(Keys.Up)
// joystick binding button
Joystick.addKey(new JoystickBindKeyType(Keys.W,Keys.S,Keys.A,Keys.D))
// joystick change key
let keydata1=new JoystickBindKeyType(Keys.I,Keys.K,Keys.J,Keys.L) 
Joystick.addKey(keydata1)
// joystick unbundling key
Joystick.removeKey(new JoystickBindKeyType(Keys.I,Keys.K,Keys.J,Keys.L))

• For the developer's different needs for the PC experience, such as wanting a camera slider/joystick to be clickable by the mouse, APIs are provided in the Virtual Joystick Panel and TouchPad classes to be mouse-controlled, and this property can also be checked within the editor in the Camera Slide/Joystick property panel
• Please note: Controlling UI by direct click/drag is a higher priority than controlling UI by key mouse binding, so if camera slider/joystick is set to be clickable by mouse and these two widgets generally occupy a larger ratio in the screen, it is easy to manipulate the camera or joystick and cannot trigger the key mouse binding UI

• See UI widgets - joystick and UI widgets - camera slide for use scenes for this feature

Script Example:

let touchpad=this.uiWidgetBase.findChildByPath('Canvas/UITouchPad_1') as TouchPad
let joystick=this.uiWidgetBase.findChildByPath('Canvas/UIVirtualJoystickPanel_1') as VirtualJoystickPanel
// Set joystick and camera slide area can be clicked by mouse
touchpad.controlByMouseEnable=true
joystick.controlByMouseEnable=true
// Gets whether joystick and camera slider can be clicked by mouse
let bool1 = touchpad.controlByMouseEnable
let bool2 = joystick.controlByMouseEnable

let touchpad=this.uiWidgetBase.findChildByPath('Canvas/UITouchPad_1') as TouchPad
let joystick=this.uiWidgetBase.findChildByPath('Canvas/UIVirtualJoystickPanel_1') as VirtualJoystickPanel
// Set joystick and camera slide area can be clicked by mouse
touchpad.controlByMouseEnable=true
joystick.controlByMouseEnable=true
// Gets whether joystick and camera slider can be clicked by mouse
let bool1 = touchpad.controlByMouseEnable
let bool2 = joystick.controlByMouseEnable

Preset UI control scheme for new projects ​

• Provides a preset UI file for new projects and binds a set of key mouse default keys as the default control scheme
• The preset UI file includes a joystick on the left, camera slider on the right, and two buttons on the bottom right (Jump/Attack)
• The preset UI script file includes logic to control the actions that can be achieved by clicking the jump button, clicking the attack button
• Please note: Although left and right mouse buttons can control the camera in a new project, the logic of the two is different. Left mouse button controls camera similar to mobile side controls camera by dragging finger in camera slide area, while right mouse button controls camera by binding to camera slide area in key binding menu. If you do not want right mouse button to control camera, you can unbind it in menu

PC side mouse lock function and API ​

• PC games allows mouse lock function, hide mouse in case of mouse lock, turn mouse to rotate lens and character orientation directly, this frees both left and right buttons for other character actions, such as achieving right-click aim + left-click shoot common in PC shooting games
• You can either use isLockMouse to directly control the player's current mouse lock state or use mouseLockOptionEnabled to control whether you want to allow the Player to switch mouse lock states with the shift key (equivalent to giving the value of isLockMouse to the Player to control)

Script Example:

// Set to not allow Players to switch mouse lock state using shift
InputUtil.mouseLockOptionEnabled=false
// Set to allow Players to toggle mouse lock state using shift
InputUtil.mouseLockOptionEnabled=true
// Set Player to mouse lock directly
InputUtil.isLockMouse=false
// Set Player end mouse lock status directly
InputUtil.isLockMouse=true

// Set to not allow Players to switch mouse lock state using shift
InputUtil.mouseLockOptionEnabled=false
// Set to allow Players to toggle mouse lock state using shift
InputUtil.mouseLockOptionEnabled=true
// Set Player to mouse lock directly
InputUtil.isLockMouse=false
// Set Player end mouse lock status directly
InputUtil.isLockMouse=true