Skip to content

Lua Runtime

Jump to bottom
Daniel Flassig edited this page Jun 18, 2026 · 4 revisions

PYTHA uses a customized version of the Lua language / runtime. It is based on Lua 5.3.

Runtime and Sandbox

The following Lua 5.3 standard libraries are available in the runtime:

  • math
  • table
  • string
  • utf8
  • os (restricted functionality, see below)

The PYTHA lua runtime runs in a sandboxed environment to protect the user from rogue plugin code. Therefore, the following standard Lua features are not available and will result in error, when called

  • dofile
  • loadfile
  • print
  • os.execute
  • os.exit
  • os.getenv
  • os.remove
  • os.rename
  • os.setlocale
  • os.tmpname
  • No debug library

In addition, a PYTHA plugin runs with ample (but in principle limited) memory and instruction budget. A malicious plugin could still hog the user interface thread indefinitely, but the budget restriction is a line of defense against mundane programming errors.

Unit Notation

All coordinates and distances used by PYTHA (and the PYTHA Lua APIs) are given in terms of the working unit set by the user at runtime. Use pytha.get_length_unit for conversion.

As a semantic convenience, PYTHA's Lua syntax is extended to support unit suffixes for numbers, e.g. 3m or 18.5 cm (whitespace between the number and the unit symbol is optional).

Mixed-unit syntax is supported (e.g. 1m 30cm). If such an expression must be used in a multiplication, use brackets, or the operator precedence would be confusing (e.g. 3 * (1m 30cm)).

For users of imperial units (inch and feet), the unit may also be indicated by double-quotes 3" for inch or an apostrophe 1.2' for foot. Fraction notation is also supported: 1 3/8" or 3' 1/2"

Unit symbols are only special when used inside these expressions. They may otherwise be used as parameter or variable names without restriction, e.g. local m = 7.

A full list of supported units is: m, dm, cm, mm, ft, in, pt, yd

Additional Mathematical functions in global scope

These are provided by PYTHA in the Global Environment. See Math functions for their signatures. All three case variants (upper, lower, camel case) are defined initially.

ABS, Abs, abs, ACOS, Acos, acos, ASIN, Asin, asin, ATAN, Atan, atan, COS, Cos, cos, IFTHEN, IfThen, Ifthen, ifthen, PI, Pi, pi, PYTHAGORAS, Pythagoras, pythagoras, SIN, Sin, sin, SQRT, Sqrt, sqrt, TAN, Tan, tan

Recommended practice

  • Do not reuse the namespace names (pytha, pyui, ...) as local variables.
  • Global variables starting with py should not be used to avoid conflicts with future namespace names

Clone this wiki locally