Lua Scripting skill for Codex

Good Lua is written for a specific runtime: every variable is local unless it must be global, modules return a table, errors are raised with useful messages and caught at a deliberate boundary, and the code only uses features the host’s Lua version has.

First, identify the runtime

Host	Lua version	Consequences
Neovim	LuaJIT (5.1 semantics + some 5.2 extensions)	no //, no <const>/<close>, write local unpack = table.unpack or unpack, bit library for bitops, vim.* APIs
Standalone lua	usually 5.4	integers vs floats, //, <const> and <close> locals, table.unpack only
Embedded in an app or game	whatever the host links (often 5.1/LuaJIT or 5.4)	check the host docs; globals and require may be restricted
Roblox	Luau (typed dialect)	different stdlib and type syntax; not covered here
Redis EVAL	5.1	no globals, keys passed via KEYS/ARGV

Check with lua -v, nvim --version, or print(_VERSION, jit and jit.version). Read AGENTS.md, .luarc.json, .luacheckrc / selene.toml and stylua.toml if present.

Core idioms

-- mymod/init.lua (or mymod.lua)
local M = {}

local DEFAULTS = { retries = 3, timeout_ms = 2000 }

---@param opts? { retries?: integer, timeout_ms?: integer }
function M.setup(opts)
  M.config = vim and vim.tbl_deep_extend("force", DEFAULTS, opts or {})
    or setmetatable(opts or {}, { __index = DEFAULTS })
end

local function backoff(attempt)        -- private: local, not in M
  return math.min(2 ^ attempt * 100, 5000)
end

function M.fetch(url)
  for attempt = 1, M.config.retries do
    local ok, result = pcall(do_request, url, M.config.timeout_ms)
    if ok then return result end
    sleep_ms(backoff(attempt))
  end
  error(("fetch %s failed after %d attempts"):format(url, M.config.retries), 2)
end

return M

• local everything. A missing local creates a global that leaks across modules; luacheck and selene flag it.
• Modules return a table; never set globals from a module.
• Cache hot globals as locals in performance-sensitive files (local insert = table.insert).
• error(msg, 2) blames the caller’s line; raise tables (error({code = "E_TIMEOUT"})) when callers need to branch on the error.
• Use pcall/xpcall(fn, debug.traceback) at boundaries (event handlers, plugin entry points), not around every call.

Tables and metatables

local Stack = {}
Stack.__index = Stack

function Stack.new() return setmetatable({ n = 0 }, Stack) end
function Stack:push(v) self.n = self.n + 1; self[self.n] = v end
function Stack:pop()
  if self.n == 0 then return nil end
  local v = self[self.n]
  self[self.n] = nil
  self.n = self.n - 1
  return v
end

• Arrays are 1-based. #t is only defined for sequences without holes; track length yourself (n) when nil values are possible, or use select("#", ...) for varargs.
• ipairs stops at the first nil; pairs order is unspecified, so sort keys before producing output that must be deterministic.
• a.b vs a:b(): the colon passes self. Mixing them is the most common “attempt to index a nil value” source.
• Only nil and false are falsy. 0 and "" are true.
• x = x or default breaks when false is a legitimate value.
• String building in loops: collect into a table and table.concat, not repeated ...

Sandboxing untrusted scripts (5.2+)

local SAFE = { string = string, table = table, math = math, pairs = pairs,
               ipairs = ipairs, tostring = tostring, tonumber = tonumber, type = type }

local function run_untrusted(code)
  local env = setmetatable({}, { __index = SAFE })
  local chunk, err = load(code, "=user", "t", env)  -- "t": text only, no bytecode
  if not chunk then return nil, err end
  return pcall(chunk)
end

Never load untrusted bytecode (mode "b"), never expose os, io, load, require, debug, package or string.dump. Sandboxing does not bound CPU or memory; use debug.sethook instruction counts or host-side limits. On 5.1/LuaJIT use setfenv(chunk, env) instead of the env argument.

Embedding Lua in C

#include <lua.h>
#include <lauxlib.h>
#include <lualib.h>

static int l_log(lua_State *L) {
    const char *msg = luaL_checkstring(L, 1);   /* raises a Lua error on bad type */
    host_log(msg);
    return 0;                                   /* number of return values */
}

int run_script(const char *path) {
    lua_State *L = luaL_newstate();
    if (!L) return -1;
    luaL_openlibs(L);                           /* or open only the libs you allow */
    lua_register(L, "host_log", l_log);

    int rc = luaL_loadfile(L, path) || lua_pcall(L, 0, 0, 0);
    if (rc != LUA_OK) {
        fprintf(stderr, "lua: %s\n", lua_tostring(L, -1));
        lua_pop(L, 1);
    }
    lua_close(L);
    return rc;
}

• Every API call has a documented stack effect; check lua_gettop(L) before and after in debug builds.
• Call into Lua with lua_pcall, never lua_call, from host code: an error in lua_call longjmps out of your C stack and skips C++ destructors.
• Keep references to Lua values across calls with luaL_ref(L, LUA_REGISTRYINDEX) and release them with luaL_unref.
• A lua_State is not thread-safe; one state per thread or a lock around all access.
• Expose host objects as full userdata with a metatable (luaL_newmetatable, luaL_checkudata) and a __gc that frees the C resource.

Neovim configuration

-- ~/.config/nvim/init.lua
vim.g.mapleader = " "
vim.opt.number = true
vim.opt.expandtab = true
vim.opt.shiftwidth = 2

vim.keymap.set("n", "<leader>w", "<cmd>write<cr>", { desc = "Save file" })

local group = vim.api.nvim_create_augroup("user_format", { clear = true })
vim.api.nvim_create_autocmd("BufWritePre", {
  group = group,
  pattern = { "*.lua", "*.go" },
  callback = function(args) vim.lsp.buf.format({ bufnr = args.buf }) end,
})

-- Neovim 0.11+: built-in LSP config
vim.lsp.config("lua_ls", {
  settings = { Lua = { diagnostics = { globals = { "vim" } } } },
})
vim.lsp.enable({ "lua_ls", "gopls" })

• Always pass an augroup with clear = true, or re-sourcing the config duplicates autocmds.
• Use vim.keymap.set with desc (shows in which-key and :map), not nvim_set_keymap with string RHS.
• Long-running work: vim.system({...}, {}, on_exit) (0.10+) or vim.uv (was vim.loop); touch the UI from callbacks only inside vim.schedule.
• Plugin layout: lua/<name>/init.lua with M.setup(opts), and lazy-load via the plugin manager the user has (lazy.nvim specs with event, cmd, keys, opts). Check :checkhealth after changes.
• On older versions without vim.lsp.config, the user likely uses nvim-lspconfig; check nvim --version before rewriting their LSP setup.

Tooling and verification

stylua --check .                       # formatting (stylua.toml)
luacheck .                             # or: selene .  (globals, unused vars, shadowing)
lua-language-server --check .          # type annotations (---@param) if the repo uses LuaLS
busted                                 # tests, if spec/ exists
nvim --headless -c 'lua require("myplugin").setup()' -c 'qa!'   # smoke-test a plugin

• No new globals reported by luacheck/selene (configure vim as a read global for Neovim code).
• Tests or a headless smoke run pass on the target runtime version.
• Embedded code: run the host under ASan once to catch stack misuse in the C side.
• Report the runtime and version targeted.

Installing these tools (luarocks install luacheck busted, cargo install stylua) needs network access; ask first.