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.

Properties

  • trx.console.is_open (boolean). Whether the console is open. Assigning opens or closes it, as the key the player bound to it does.

Enums

  • trx.console.Result

    How a console command went. What a command's trx.console.register.spec.run gives back.

    • trx.console.Result.OK
      It worked.
    • trx.console.Result.FAILURE
      It ran and could not do what was asked.
    • trx.console.Result.UNAVAILABLE
      It cannot run here - no level is loaded, or the game is in a menu.
    • trx.console.Result.BAD_INVOCATION
      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.

    Assigning trx.ui.clipboard does the same thing.

    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.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:

    • line (string). The line to remember.
  • 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.