!HowToPrint
(For high level concepts about how to use Lua to write scripted tasks, please see VR-Forces User's Guide.)
This section of the Lua API documentation does not describe a module of code; its purpose is to collect the information on print-related functions in other modules into one place.
Basic Printing
The VR-Forces Lua interface supports printing through a set of new print functions that send output to the entity console, i.e. the entity information panel on the GUI. There are five functions corresponding to the five notification levels that can be set for an entity:- printError()
- printWarn()
- printInfo()
- printVerbose()
- printDebug()
The standard Lua print function has been redefined to execute printInfo. To access the original Lua print function, you must call luaPrint. luaPrint outputs to the simulation console, not the entity console.
When entities are created, their notification level is set to Warn, so unless their notification level is changed, only printError and printWarn output will show up in their console.
Examples:
printWarn("Hello World")
printDebug("There are ", 5, " notification levels.")
printInfo(string.format("This script is ticking at time %.3f", myTime)) These print functions append a newline character to the output, so it is not necessary to add a newline ("\n") to the output string. Printing Translatable Output
If you wish to have printed text translated to the local language being used in the GUI, then you must send the output to a TranslatableStream object. To create a TranslatableStream, you must use the vrf:trUtf8() function, which converts a string into a TranslatableStream. If the string has parameter substitution characters in it (e.g. "%1"), then the arg function can be called on the TranslatableStream to incorporate argument values. See the TranslatableStream module documentation.The TranslatableStream is printed using the same five functions above. Note that these print functions can either take one TranslatableStream argument, or a comma-separated list of arguments.
Examples:
printWarn(vrf:trUtf8("This string could be translated."))
local altitude = this:getLocation3D():getAlt()
printWarn(vrf:trUtf8("This aircraft is at %1 meters altitude."):arg(altitude))
Usage to Avoid
The VR-Forces string translation mechanism (see VR-Forces User's Guide, section 2.5) builds a list of strings to translate by searching the code for literal strings in a trUtf8 function. The translation tool will not find strings generated from variables or functions. Therefore the following examples, while they will print the English text as written, will not support the translation mechanism:myString = "Hello world"
printWarn(vrf:trUtf8(myString))
printWarn(vrf:trUtf8(string.format("Time in milliseconds: %.3f", myTime)))
printWarn(vrf:trUtf8("Translated text, and %1"):arg("untranslated text"))
Other Print Functions
There are print functions defined in the vrf and TranslatableStream classes. These functions should generally not be used in order to avoid confusion in your Lua code about syntax and argument types.Vrf
The five print functions above are also defined in the vrf module. These versions of the functions take a single argument which is a string. To display multiple arguments, the arguments must be converted to strings and contatenated into one string before calling the print function. These print functions do not append a newline character, so one must be appended to separate output lines, and to flush the output buffer.Example:
vrf:printInfo("This ship has " .. tostring(2) .. " missile launchers.\n")
vrf:printDebug(string.format("Ticked at time %.3f\n", myTime))
TranslatableStream
The five print function are also defined in the TranslatableStream module. Here the functions take no arguments, but print the stream.Example:
myOutStream = vrf:trUtf8("Warning: %1 missiles left."):arg(myNumMissiles)
myOutStream:printWarn()