Keys and controls

Client scripts can react to keys, offer rebindable actions in the game's settings, and temporarily take away the player's controls.

Binding a key

// client
const { Key } = kcds.ui;

Key.bind('f', () => kcds.core.Events.toServer('openDoor'));
Key.bind('shift', 'both', (key, edge) => console.log(`${key} ${edge}`)); // edge is 'down' or 'up'
Key.unbind('f');

Key.getLabel(key) gives the text printed on that key for the player's keyboard, and Key.isDown(key) says whether it is held.

Binds fire only in a world, with the game window active and with no chat or web view taking typed text. While one of your NativeUI screens has focus, binds pause and keys go to that screen.

Key names

Keys are named by their position on a US keyboard, whatever layout the player uses.

Controller buttons

Any connected Xbox-style controller works too, using the game's button names:

Actions the player can rebind

Key.bind always uses the key you name. To let the player choose, add an action with kcds.ui.Keybinds. It appears in the game's Settings > Key bindings, and the player changes it like any other action. The game prevents it from sharing a key with a game action or another resource's action.

// client
const { Keybinds } = kcds.ui;
const { Events } = kcds.core;

Keybinds.addCategory('roleplay', 'Roleplay');
Keybinds.add('emote_menu', {
  label: 'Emote menu',
  category: 'roleplay',
  key: 'f6',
  controller: 'xi_dpad_up',
});
Keybinds.add('radio', { label: 'Talk on the radio', key: 'numpad1' });

Keybinds.on('emote_menu', () => Events.toServer('emotes:open'));
Keybinds.on('radio', 'both', (id, edge) => {
  Events.toServer('radio:talk', edge === 'down');
});

The game's own categories are general (the default), movement, combat, chat, qam, gui, photomode and other.

Handlers follow whatever key the player picks. To display the current key in a hint, use Keybinds.get(id):

// client
const menu = kcds.ui.Keybinds.get('emote_menu');
// { id: 'emote_menu', label: 'Emote menu', category: 'roleplay', key: 'f6', keys: ['f6'],
//   controller: 'xi_dpad_up', defaultKey: 'f6', defaultController: 'xi_dpad_up' }

Where choices are stored

Choices are saved on the player's computer separately for each server, and return when they rejoin. Other servers' resources cannot read or change them. They stay out of the game's profile, so the game played without KCDS is not affected.

Controller buttons and changes from a script

The settings screen lists only keyboard and mouse keys. A controller button is the default you give it, or what your script sets, perhaps from your own settings page:

// client
const { Keybinds } = kcds.ui;

Keybinds.set('radio', { key: 'f7', controller: 'xi_y' }); // saved like a choice on the screen
Keybinds.set('emote_menu', { controller: null }); // no controller button
Keybinds.reset('radio'); // back to the defaults

Removing actions

A stopping resource's actions leave the screen, and Keybinds.remove(id) removes one while it runs. The screen also offers the mouse wheel and keys KCDS does not poll. Choosing one means the action never fires.

Taking away controls

// client
const { Controls } = kcds.ui;

Controls.disable(); // no moving, fighting or using things
Controls.showCursor();
// ... your menu is open ...
Controls.hideCursor();
Controls.enable();

Each resource's hold is counted, so controls stay off while any resource holds them. A stopping resource gives back what it held.

Blocking one action

You can block a single game action, on whatever key the player uses for it. The key still reaches Key.bind, which lets a resource take over a game key:

// client
const { Controls, Key } = kcds.ui;

Controls.blockAction('jump'); // space no longer jumps
Key.bind('space', () => kcds.core.Events.toServer('ring:bell'));

// Later:
Controls.unblockAction('jump');

The names are the game's player actions, such as jump, use, opponent_lock, attack_primary_mouse, block, toggle_crouch and sprint.

Reference: Key, Keybinds, Controls.