Getting started

Write your first Luna Lua script, load it, and learn which libraries and sandbox rules apply.

Quick start#

Luna scripts are plain .lua files. Your first script takes a minute:

  1. Create hello.lua in C:\luna\scripts (or press New in the Lua tab).
  2. Paste the example below and save.
  3. Open the Lua tab, select the script and press Load (tick "Load on start" to load it at injection).
  4. print output and errors appear in the console sub tab of the Lua tab and under the editor.
print("Hello from Luna!")

events.present_queue:add(function()
    render.text(10, 10, "Hello World!", Color(255, 255, 255))
end)
Every name is resolved without caring about case or underscores: events.present_queue, events.presentQueue and events.PresentQueue are the same thing, so are get_abs_origin and GetAbsOrigin.

Runtime#

PropertyValue
EngineLuaJIT 2.1 with the JIT compiler (Lua 5.1 syntax, goto supported). The FFI is off by default, see the FFI section.
Librariesbase, string, table, math, bit, jit, plus reduced io, os and package (see Sandbox below). ffi and debug only exist when Allow Lua FFI is on. table.unpack and bit32 exist for 5.2 style code.
IsolationEvery script runs in its own Lua state; scripts cannot break each other.
Time limitA callback that runs longer than 300 ms is stopped (3 s while the script loads). Code compiled by the JIT that loops forever without calling a function cannot be interrupted, so keep loops bounded.
AccessScripts run in a restricted sandbox: no processes, no raw file handles, no native modules, no bytecode. Files go through file.*, memory through memory.*. Even so, only run scripts you trust.

Sandbox#

RemovedUse instead
os.execute, os.remove, os.rename, os.exit, os.getenv, os.tmpname, os.setlocaleos.time, os.date, os.clock still work. For files use file.*; for time use utils.get_unix_time().
io.open, io.lines, io.input, io.output, io.popenfile.read, file.write, file.append, file.list (relative paths point to scripts\data).
loadfile, dofile, package.loadlib, native (.dll) modules in requirerequire("name") loads scripts\lib\name.lua. load and loadstring still compile source text.
Bytecode (string.dump, loading precompiled chunks)Ship readable source.
ffi, debug and jit.* internals, also through requireTurn on Allow Lua FFI (unsafe) in the Settings tab if a script really needs them.
LuaJIT has no |, &, ~ or >> operators. Use bit.band, bit.bor, bit.bxor, bit.bnot, bit.lshift, bit.rshift. For button masks above 32 bits use luna.band, luna.bor and luna.bclear.

Loading and lifecycle#

TopicDetails
FolderC:\luna\scripts\*.lua. Modules for require("name") go in scripts\lib. Relative paths of file functions point to scripts\data.
Entry pointThe script runs top to bottom when it loads. Register callbacks to hook into the game.
Modulesrequire("name") loads scripts\lib\name.lua. Only Lua source is loaded: native modules and bytecode are blocked.
Lua tabSub tabs scripts (list, New, Delete, Save, Run, Check, Open folder, Load / Unload, Refresh, editor with live syntax check and auto save), elements (controls created by scripts) and console.
Auto-loadScripts with "Load on start" ticked load at injection (scripts\autoload.txt).
UnloadUnload button, deleting the file, or luna.unload() from the script. events.shutdown callbacks and a global __shutdown() run first.
ErrorsAn error at load time or inside any callback prints the message and a traceback in the console, shows a toast and unloads the script.
Saved valuesValues of the controls a script created are saved in scripts\<name>.values and restored on the next load.