Hotkeys
Run a function when a key is pressed during play.
A hotkey runs your function when the player presses a key.
ui.Hotkey("F6", function()
ui.Notify("You pressed F6.", { kind = "good" })
end)Close the menu and press F6.
When a hotkey reacts
- A hotkey reacts during play, while the menu is closed.
- It does not react while the menu is open, so typing in a text box never triggers it.
- It goes away when your mod reloads.
init.luathen makes it again.
The game still sees the key too. Pick a key that the game does not use for something else.
To make a hotkey react while the menu is open as well, pass in_menu = true:
ui.Hotkey("F7", function()
ui.Notify("F7 works with the menu open or closed.")
end, { in_menu = true })| Option | What it does |
|---|---|
in_menu | true makes the hotkey react while the menu is open too. |
typing | true makes it react while a text box has the keyboard as well. Without it, a key that writes a letter is left to the box. |
hover | true makes it a key for the slot under the mouse. It only reacts while the mouse is over a slot of a Slots control. |
A key with Ctrl, Shift or Alt
Put Ctrl+, Shift+ or Alt+ before the key. The hotkey then reacts only while exactly those are held.
ui.Hotkey("Ctrl+Three", function()
ui.Notify("Ctrl and 3.")
end)
ui.Hotkey("Ctrl+Shift+K", function()
ui.Notify("Ctrl, Shift and K.")
end)A plain key gives way to the same key with Ctrl, Shift or Alt. If "Three" and "Ctrl+Three" are both hotkeys,
pressing 3 while Ctrl is held runs only the second.
Is a key held right now
ui.IsKeyDown(key) is true while the key is held. Use it in a loop that a hotkey started, to do something
for as long as the key stays down.
ui.Hotkey("F6", function()
local seconds = 0
while ui.IsKeyDown("F6") do
task.wait(0.1)
seconds = seconds + 0.1
end
ui.Notify(("You held F6 for %.1f seconds."):format(seconds))
end)- It takes the same key names as
ui.Hotkey. WithCtrl+,Shift+orAlt+it istrueonly while the key is down with exactly those held. - It does not look at whether the menu is open or a text box has the keyboard.
ui.IsTyping()tells you the second. - Every call asks the game. So call it in a loop that runs while something is held, not in every frame of the game.
Key names
A key is given by its name, as text.
| Keys | Names |
|---|---|
| Letters | "A" to "Z" |
| Digits on the top row | "Zero", "One", "Two", "Three", "Four", "Five", "Six", "Seven", "Eight", "Nine" |
| Function keys | "F1" to "F12" |
| Number pad | "NumPadZero" to "NumPadNine", "Multiply", "Add", "Subtract", "Decimal", "Divide" |
| Arrows | "Up", "Down", "Left", "Right" |
| Editing | "Insert", "Delete", "Home", "End", "PageUp", "PageDown", "BackSpace", "Enter", "Tab", "SpaceBar", "CapsLock" |
| Shift, Control and Alt | "LeftShift", "RightShift", "LeftControl", "RightControl", "LeftAlt", "RightAlt" |
| Punctuation | "Tilde", "Hyphen", "Equals", "LeftBracket", "RightBracket", "Backslash", "Semicolon", "Apostrophe", "Comma", "Period", "Slash" |
| Mouse | "MiddleMouseButton", "ThumbMouseButton", "ThumbMouseButton2" |
You rarely need to type these. A Keybind control lets the player press the key, and gives you its name.
Let the player choose the key
Give the key a name with ui.Bind. It works like ui.Hotkey, and Wax does the rest:
local ping = ui.Bind("Ping", "F6", function()
ui.Notify("Ping!", { kind = "good" })
end, { label = "Send a ping" })
print("Ping is on", ping:Get() or "no key")- The key is listed on your mod's card of the Mods page, under the label you gave. The player clicks it and presses a new key, or clears it.
- The player's choice is remembered and used the next time.
"F6"is only where it starts. - When another mod, or the Wax panel, acts on the same key, both still run. The card says which key clashes and with whom, and so does a line at the top of the Mods page, so the player can change one of them.
in_menu = truein the options lets it run while the menu is open as well.
| Function | What it does |
|---|---|
ui.Bind(name, key, callback, options) | A named key. name stays the same between versions of your mod. |
bind:Get() | The key it has now, or nil when the player left it without one. |
bind:Set(key) | Gives it another key, as the player does on the card. |
bind.Changed | A signal that fires with the new key. |
ui.Keys.Binds(owner) | The named keys of one mod, or of every mod. |
ui.Keys.Clashes(owner) | The keys more than one owner acts on, as lines of text. |
Name the key in mod.lua as well (keys = { "F6: Ping" }), and it is on the card while your mod is still switched
off. Mods has that.
Use ui.Bind for every key a player might want to change, and ui.Hotkey for the ones that are fixed.
Stop a hotkey
ui.Hotkey gives back the hotkey.
| Function | What it does |
|---|---|
hotkey:SetKey(key) | Changes the key it reacts to. |
hotkey.Disconnect() | Stops the hotkey. |
local hotkey = ui.Hotkey("F6", function()
ui.Notify("Ping!")
end)
local window = ui.Window({ title = "Hotkeys", width = 300, height = 140 })
window:Button("Switch the hotkey off", function()
hotkey.Disconnect()
ui.Notify("F6 does nothing now.")
end)A hotkey may wait
Your function runs as a task, so it may pause.
ui.Hotkey("F6", function()
ui.Notify("Three...", { seconds = 1 })
task.wait(1)
ui.Notify("Two...", { seconds = 1 })
task.wait(1)
ui.Notify("One...", { seconds = 1 })
end)The key of your windows
The key that shows and hides your mod's windows is not a hotkey of yours. Wax gives every mod that has a
window such a key, and the player can change it on the mod's card of the Mods page. To ask for a key,
pass key to your first window:
local window = ui.Window({ title = "Tools", key = "F6" })
window:Label("F6 shows and hides this window.")- If you make a hotkey on the key Wax gave your windows, Wax gives the windows another key and tells the player.
- If your hotkey and your windows have the same key because you asked for it, the press runs your hotkey and is not also taken as the key of the windows.
ui.Keys reads and sets these keys from code. See The menu.
Every function is listed in the ui reference.