Actions and keys

import { Actions, KEY_NAMES, type ActionOptions } from "@sagl/server";

Things players do with a key, such as an engine switch, a seatbelt or a radio. The player picks the key. Every action shows in their pause menu under Settings → Controls, grouped under the server's name, with your default key. They can give it another key, or two, and SAGL keeps their choice for this server (in their sagl.ini).

SAGL's own keys are there too, and players can rebind them the same way:

Action	Default keys
Open the chat	T, F6
Type a command	/, keypad /
Left indicator, right indicator, hazard lights	, . ;
Debug panel	F8

A key does one thing at a time: binding it to an action takes it from any other action that had it.

The game's own controls are in the same tab: on foot, driving and the camera, with two keys and a mouse button each, as GTA's own controls menu had them (SAGL's pause menu replaces that menu). They follow the game's rules: one key can be both an on-foot control and a driving control, as F is for getting in and out. When a key is both one of the game's controls and one of these actions, the page says so. Both happen when it's pressed.

server.actions

register(id, options, handler?)

register(id: string, options: { label: string; key?: string }, handler?: (player: Player) => void): void

Defines an action, or changes one that's already defined. Every player gets it, including those who join later.

Parameter	Type	Description
id	string	1-32 of A-Z, 0-9, _ . : -. Players' own keys are kept by it.
options.label	string	What players see in Controls.
options.key	string	The default key: one of KEY_NAMES ("E", "F5", "Comma"...). Leave it out for no default key.
handler	(player) => void	Runs when a player presses the action's key.

Throws RangeError for a bad id or key name.

server.actions.register("engine", { label: "Engine on/off", key: "N" }, (player) => {
  const v = player.vehicle;
  if (v && player.seat === 0) v.engine = !v.engine;
});

remove(id), ids

remove takes an action away, from players' Controls too. ids lists the actions you've registered.

The playerAction event

server.on("playerAction", (player, id) => { ... });

A player pressed the key for one of your actions. This happens as well as the action's handler.

Key names

Key names follow where the key sits on a US keyboard. Players see what their own keyboard prints on that key: on a German keyboard, Semicolon shows as Ü. Every name is in KEY_NAMES:

• A-Z, 0-9, F1-F24
• Numpad0-Numpad9, NumpadMultiply, NumpadPlus, NumpadMinus, NumpadDecimal, NumpadDivide
• Space, Tab, Enter, Backspace, Insert, Delete, Home, End, PageUp, PageDown
• Up, Down, Left, Right, Shift, Ctrl, Alt, CapsLock
• Comma, Period, Semicolon, Slash, Minus, Equals, LeftBracket, RightBracket, Backslash, Quote, Backquote, IntlBackslash

Escape and Alt can't be bound.

When keys work

Keys work while the player is in the game world. They don't work while the chat, a dialog or a menu is taking typing.

The game still sees the key, so pick one that isn't one of the game's own controls (F, G, H, the movement keys and so on), or leave it to players to choose. SAGL's own actions are the exception: they keep the key to themselves. For example, opening the chat doesn't also type a T.

Client scripts

Client scripts have the same: sagl.actions. They can register actions of their own and listen for yours. They can also find out which key a player has for an action, to show a hint such as "Press N to start the engine".