Lost Artefacts

Console module

Module for interacting with the developer console.

trx.console.log writes to the console overlay in-game, where trx.log writes only to the terminal and the log file.

Enums

trx.console.Result

How a console command went. What a command's trx.console.register.spec.run gives back.
- trx.console.Result.OK = 0
  It worked.
- trx.console.Result.FAILURE = 1
  It ran and could not do what was asked.
- trx.console.Result.UNAVAILABLE = 2
  It cannot run here - no level is loaded, or the game is in a menu.
- trx.console.Result.BAD_INVOCATION = 3
  The player typed it wrong.

Structures

trx.console.Command

A registered console command, as the help command reads one.

Properties:
- aliases: a list of string, optional. The other words that reach it, where it answers to more than one.
- help: string, optional. What the console shows for --help, where the command carries any.
- name: string. The word the player types.

Functions

trx.console.log(message)
Logs a line to the developer console. Calling the group itself logs at INFO. Takes any value: a table is pretty-printed, anything else coerced to a string.

Parameters:
- message (any). Any value; a table is pretty-printed.
Example:
```
trx.console.log({ hp = 1000, pos = { x = 1 } })
```
trx.console.log.generic(level, message)
Logs at a level chosen at runtime.

Parameters:
- level (trx.log.LogLevel).
- message (any). Any value; a table is pretty-printed.
trx.console.log.info(message)
Logs an informational message.

Parameters:
- message (any). Any value; a table is pretty-printed.
trx.console.log.warn(message)
Logs a warning.

Parameters:
- message (any). Any value; a table is pretty-printed.
trx.console.log.warning(message)
Logs a warning. An alias of warn.

Parameters:
- message (any). Any value; a table is pretty-printed.
trx.console.log.error(message)
Logs an error.

Parameters:
- message (any). Any value; a table is pretty-printed.
trx.console.log.debug(message)
Logs a debug message.

Parameters:
- message (any). Any value; a table is pretty-printed.
trx.console.eval(command, [opts])
Runs a developer console command. Raises if the command fails.

Output appears only in the terminal and the log file by default. Pass { verbose = true } to show it in the console, or { capture = true } to return the logged text.

Parameters:
- command (string). Command to run, as the player would type it.
- opts (table, optional). How to run it.
  
  Keys:
  - verbose (boolean, optional). Show the command's output.
  - capture (boolean, optional). Return the command's output.
Returns: string or nil. What the command logged, one line per message. nil unless opts.capture is true.

Example:
```
trx.console.eval("play 1", { verbose = true })
```
trx.console.copy(text)
Puts text in the system clipboard. Raises if the platform refuses it.

Parameters:
- text (string). What to put in the clipboard.
Example:
```
trx.console.copy(trx.game.TRX_VERSION)
```
trx.console.complete(line, caret)
Completes a console line with the same suggestions as the prompt. Use it when a Lua command wraps another console command.

Parameters:
- line (string). The line so far, without the key that opens the console.
- caret (integer). Where the caret sits, as a byte offset.
Returns:
- a list of string. The best match comes first.
- integer. Where the run they replace starts.
- integer. Where that run ends.
trx.console.register(spec)
Registers a console command written in Lua.

Every command has a trx.argparse parser. spec.args is an optional function that shapes it - it receives the parser and declares the arguments the command takes. A command that omits spec.args takes none, and reports so when handed one. The console completes the arguments from the parser, and answers -h/--help from it.

spec.run receives the parsed values, a table keyed by argument name. What it gives back is a trx.console.Result, and returning nothing means OK. It may return a message after that, which is logged to the console - as an error, for any result but OK. A line the parser rejects is reported with what it expected, without reaching spec.run.

The console completes arguments from the parser by default. spec.complete replaces that behavior, so a command that wraps trx.console.eval can answer from trx.console.complete.

A command lives for the whole run, so it can only be registered from a global script. A level script raises if it calls this: it runs again every time its level is loaded.

Parameters:
- spec (table). The command.
  
  Keys:
  - name (string). The word the player types.
  - help (string, optional). A game string key for the help text.
  - args (function, optional). Shapes the parser.
  - run (function). Called with the parsed arguments.
  - complete (function, optional). Completes arguments instead of the parser. Called with the text past the command word and the caret byte offset in it, and gives back what trx.argparse.Parser:complete does.
  - aliases (a list of string, optional). Other words that reach the same command. They dispatch but stay out of the command listing, and the help for the command shows them.
Example:
```
trx.console.register({
  name = "greet",
  aliases = { "hello", "hi" },
  args = function(parser)
    parser:positional("who", { help = "who to greet" })
  end,
  run = function(args)
    trx.console.log("hello " .. args.who)
  end,
})
```
trx.console.clear()
Clears the console.
trx.console.commands()
Every registered console command, in registration order. The help command is built on this.

Returns: a list of trx.console.Command.
trx.console.command(name)
The command a name reaches, by its own name or an alias, matched as the console matches when it dispatches.

Parameters:
- name (string). The word or alias to look up.
Returns: trx.console.Command or nil. nil when nothing answers to the name.