commands.module
This package holds more than this page lists. See all of its files in its world.
README.md
editorCommands
The command registry — the single place an editor action is declared.
One declaration is rendered by four surfaces: the menu bar, DataView
context menus, the command palette, and the keymap. EditorRegistry's
addMenuItem is a thin wrapper over declare, so every menu action is
a command.
A command is { id, title, category, menu?, order?, keys?, icon?, enabledWhen?, run }. title and category are text or i18n.text
values, read in the editor's language each time a surface builds. A
command declared with menu = "add" is an entry of the top bar's Add
menu (and of the Hierarchy's create menu), and one with menu = "help"
an entry of its Help menu; a world or a panel adds entries to either by
declaring a command there. ctx passed to enabledWhen/run is the selection service's
context() augmented by the caller: { scope, refs, primary, view?, item? }.
Exports
M.declare(cmd) -> boolean— register/replace by id (duplicate replaces).M.get(id) -> Command?M.list() -> { Command }— sorted by (category, title).M.inMenu(menu) -> { Command }— the commands a top-bar menu lists, sorted by (order, id).M.remove(id) -> booleanM.isEnabled(id, ctx) -> boolean— true when no predicate, else its result.M.run(id, ctx) -> boolean— runs only when enabled; returns whether it ran.M.conflicts() -> { { keys, ids } }— keys claimed by more than one command.M.commandForKey(keys) -> id?— the last declarer wins a contested key.
Usage
local Commands = require("@builtin::modules.api.editor.commands")
Commands.declare({
id = "asset.delete", title = "Delete Asset", category = "Assets",
keys = "Delete",
enabledWhen = function(ctx) return #ctx.refs > 0 end,
run = function(ctx) ... end,
})
Notes
- State lives in a fixed
_Gslot, seeded pre-seal by the boot chain; it survives hot-reload and edit↔play flips. Mutations after boot write into the nestedbyId/keyClaimstables only. - A duplicate id replaces the prior declaration and rebinds its key.
- Conflicts are surfaced (
conflicts()), never silently dropped; the last declarer wins the live binding viacommandForKey.