Mod command trees: command.set-tree and set-suggestions, typed parse, colouring and completion from one tree (API 19)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-30 15:43:11 +03:00
committed by airdef
parent 94dc8eda1a
commit 4cb83fcc9b
15 changed files with 1598 additions and 5 deletions
+52
View File
@@ -183,10 +183,62 @@ Access: capability `command`.
Capability `command`: vanilla commands run as the player, with the player's permissions, after the hook call returns (8 per call). A mod's own commands are not run this way.
### variant `value-kind`
What one word of a command line takes (AirDef fork, level 19).
| Case | Payload | |
| --- | --- | --- |
| `word` | `list<string>` | One word, anything up to the next space. The words given are only what the chat box suggests; any word is accepted. |
| `integer` | `tuple<option<s32>, option<s32>>` | A whole number, within the bounds given (either may be none). |
| `number` | `tuple<option<f64>, option<f64>>` | A number with or without decimals, within the bounds given. |
| `choice` | `list<string>` | One of these words and no other. |
| `names` | `string` | One word, suggested from the list `set-suggestions` last gave under this name; any word is accepted, so a list that is out of date refuses nothing. |
| `block-pos` | | Three coordinates: whole numbers, each one also `~` or `~n`. |
### record `tree-option`
One `key=value` option, or a bare flag (`noaudio`) when `value` is none.
| Field | Type | |
| --- | --- | --- |
| `key` | `string` | |
| `value` | `option<value-kind>` | |
### record `tree-options`
The words that follow, in any order, to the end of the line.
| Field | Type | |
| --- | --- | --- |
| `entries` | `list<tree-option>` | The options and flags that may appear, each at most once. |
| `free` | `option<list<string>>` | Words that are no option are free words (a name): none refuses them, some accepts them and suggests the words given. |
### variant `node-kind`
| Case | Payload | |
| --- | --- | --- |
| `value` | `value-kind` | One word, as `value-kind` says. |
| `text` | | The rest of the line, spaces included: only a last node. |
| `options` | `tree-options` | |
### record `tree-node`
A node of a command's tree. Nodes are listed flat; a node's children come after it in the list (a tree, never a loop).
| Field | Type | |
| --- | --- | --- |
| `name` | `string` | A literal's word, or an argument's name (the chat box's hint shows it as `<name>`). |
| `kind` | `option<node-kind>` | None: a literal that must be typed as it is. |
| `children` | `list<u32>` | The nodes that may follow, by their place in the list. A word no literal child is, goes to the argument children, in order. |
| `runs` | `bool` | The line may end here (a branch with optional words after it runs without them). |
| Function | Signature | What it does |
| --- | --- | --- |
| `run` | `func(line: string)` | `line` without its slash; its feedback goes to the chat as if typed. |
| `run-quiet` | `func(lines: list<string>)` | `lines` (each without its slash, at most 256 a call) as `run` does, but with nothing in the chat: no feedback and no failure. In single player and on Horizon's servers, each runs exactly as the player typing it would (the same rights), in order, 64 a tick, and the server logs one line a batch; one that carries a chat message (`say`, `msg`) is refused. On any other server they go as chat commands, and there their feedback shows: a mod running many should say so. |
| `set-tree` | `func(name: string, nodes: list<tree-node>) -> result<_, string>` | Describes the arguments of a command `name` the mod registered (AirDef fork, level 19), replacing the free text it takes otherwise: the chat box colours the line, shows the error and the next word before Enter, and completes it with Tab; a line that does not parse never reaches the mod's `command` hook (the player gets the error). A line that parses reaches it as it was typed. `nodes[0]` is the node right after the command's name (its literal children are the subcommands; `runs` says whether the bare command runs). At most 512 nodes, 256 words in a list, 64 characters in a word, no loops, no two children of a node with one name. Errs, and changes nothing, on a tree that breaks these rules; a tree for a name the mod did not register in `init` is ignored. Calling again replaces the tree. |
| `set-suggestions` | `func(topic: string, values: list<string>)` | Sets the words a `names` node suggests under `topic` (at most 256 of 64 characters, kept as given, the rest dropped). Call it again whenever the words change (a saved scenario, a deleted one): the chat box follows. |
## `ui`