Lua Conventions

luascriptingbackend

Conventions for writing clean, maintainable Lua code covering module patterns, table usage, error handling, coroutines, and common patterns for game scripting and embedded environments.

Целевые файлы

Файл	Формат
.cursorrules	plaintext
CLAUDE.md	markdown

Содержимое

# Lua Conventions ## Module Pattern - Use the module-return pattern for every file. Return a table of public functions; do not pollute globals. ```lua local M = {} function M.greet(name) return "Hello, " .. name end return M ``` - Require modules at the top of each file, assigned to local variables: `local json = require("json")`. - Use `local` for all module-level variables and functions that are not part of the public API. - Never use global variables in library code. Use `_G` only for framework-level bootstrapping with explicit documentation. ## Naming Conventions - Variables and functions: `snake_case`. - Constants: `SCREAMING_SNAKE_CASE` (stored as module-level locals or in a constants table). - Classes/objects (tables used as classes): `PascalCase`. - Private functions (internal, not returned): prefix with `_`: `local function _compute_hash() end`. - Module names in `require` calls use dots for path separators: `require("myapp.utils.string")`. ## Tables - Use tables as arrays with integer keys starting at 1 (Lua convention). Never mix array-style and hash-style in the same table. - Prefer table constructors over sequential `table.insert` for known-size tables. - Use `#` to get array length only for sequences (no holes). For sparse tables, track length manually. - Reuse tables in hot paths to reduce GC pressure — reset fields instead of creating new tables. ## OOP Pattern - Implement classes with metatables: ```lua local Animal = {} Animal.__index = Animal function Animal.new(name) return setmetatable({ name = name }, Animal) end function Animal:speak() return self.name .. " speaks" end ``` - Use `:` syntax for methods that receive `self`. Use `.` syntax for class-level functions that do not. - Implement single inheritance by setting `setmetatable(Child, { __index = Parent })`. - Document `__index`, `__newindex`, `__tostring`, and other metamethods with comments. ## Error Handling - Use `pcall(f, ...)` or `xpcall(f, handler, ...)` to call functions that may raise errors. - Return multiple values for success/error pattern: `return nil, "error message"` on failure; `return result` on success. - Check the error pattern consistently: `local result, err = doThing(); if not result then ... end`. - Use `error(message, 2)` (level 2) to report errors at the call site, not the error function site. - Never use `assert` for error handling in production — use explicit error returns for recoverable errors. ## String Handling - Use `string.format` for string interpolation: `string.format("Hello, %s! You are %d.", name, age)`. - For repeated string concatenation in a loop, use `table.concat(parts, separator)` — not `..` in a loop. - Use `string.gmatch` for iterating over pattern matches; `string.gsub` for replacements. - Anchor patterns when possible for performance: `^` and `$` reduce backtracking. ## Coroutines - Use coroutines for cooperative multitasking and producer-consumer patterns. - Always check coroutine status before resuming: `if coroutine.status(co) ~= "dead" then`. - Use `coroutine.wrap` for simple iterator coroutines. Use `coroutine.create` + `coroutine.resume` when you need error handling. - Document coroutine yields with a comment explaining what is expected to be sent on resume. ## Performance - Cache frequently called global functions in locals at the top of hot functions: `local pairs = pairs`. - Avoid `table.unpack` in tight loops — it has overhead. - Prefer numeric `for` loops over generic `for` loops when iterating sequential tables. - Use LuaJIT-compatible patterns when targeting LuaJIT — avoid `debug` library calls and excessive metatable use in hot paths. ## Anti-Patterns - Do not use `loadstring` / `load` to execute dynamic code — it is a security risk in sandboxed environments. - Do not rely on `__index` metamethods for required fields — be explicit. - Do not ignore returned error values — always check the second return value for nil-error pairs. - Do not use `table.remove(t, 1)` in a loop — it is O(n). Reverse iterate or use a queue library.

CLI

npx mindaxis apply lua-rules --target cursor --scope project

Используется в паках

Не используется ни в одном паке

← Правила