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 string as a developer console command. Raises if the command fails.

  Output is silenced by default and appears only in the terminal and the log file. Pass { verbose = true } to show it in the console as a command typed by the player would.

  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.

  Example:

  trx.console.eval("play 1", { verbose = true })
  

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

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