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.
trx.console.is_open (boolean). Whether the console is open.
Assigning opens or closes it, as the key the player bound to it does.How a console command went. What a command's trx.console.register.spec.run
gives back.
trx.console.Result.OKtrx.console.Result.FAILUREtrx.console.Result.UNAVAILABLEtrx.console.Result.BAD_INVOCATIONA registered console command, as the help command reads one.
Properties:
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:
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:
trx.console.log.warn(message)
Logs a warning.
Parameters:
trx.console.log.warning(message)
Logs a warning. An alias of warn.
Parameters:
trx.console.log.error(message)
Logs an error.
Parameters:
trx.console.log.debug(message)
Logs a debug message.
Parameters:
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:
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.
Assigning trx.ui.clipboard does the same thing.
Parameters:
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:
trx.console.history()
The lines the player has entered, oldest first.
The list is a copy, so changing it changes nothing. Use
trx.console.remember to add to it.
Returns: a list of string. The lines entered so far.
trx.console.remember(line)
Adds a line to what the player has entered.
The console does this for every line the player runs, so a script needs it only where it takes lines of its own.
Parameters:
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:
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.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:
Returns: trx.console.Command or nil. nil when nothing answers to the name.