Player Hotkeys & Settings

Scripts can now directly manipulate a player's customized settings and hotkeys. Because settings alter the player's core gameplay experience, changes should be made carefully and with explicit context.

Real-World Use Case: Auto-Binding Starter Gear

When players start a quest or receive important new tools (like a shovel or a bow), you can streamline their experience by assigning it directly to a hotkey and optimizing their interface.

The setsettings method uses the same strict backend validation to ensure only permitted configurations are applied.

/**
 * Grants a new item to the player, auto-binds it to their hotbar, 
 * and adjusts settings for optimal usability.
 * 
 * @param {object} player - The player instance
 */
function grantStarterGear(player) {
    // 1. Give the player the item without forcing it into their hands instantly
    // Using { noautoequip: true } stops it from overriding their current weapon
    player.additem('bow1', 1, { noautoequip: true });
    player.arrows += 50;

    // 2. Automatically bind the bow to hotkey slot 1 for convenience
    player.sethotkey(1, 'bow1');

    // 3. Optional: Optimize the player's view for ranged combat
    const currentSettings = player.getsettings();

    // If they have button zoom disabled, enable it to help them aim
    if (currentSettings.buttonzoom !== true) {
        player.setsettings({ buttonzoom: true });
    }

    // 4. Notify them of the change
    player.showmessage('Quest started! Bow bound to slot 1.');
}

Checking Saved Hotkeys

You can easily read a player's hotkeys using the hotkeys object.

/**
 * Checks if a player has their healing potion bound to any hotkey.
 */
function hasPotionBound(player) {
    const boundKeys = player.hotkeys;

    for (const slot in boundKeys) {
        if (boundKeys[slot].id === 'healthpotion') {
            return true;
        }
    }
    return false;
}