Agentic Lua Class

Lua Class Pattern

Basic class structure:

--- @class Animal
local Animal = {}
Animal.__index = Animal

function Animal:new()
    self = setmetatable({}, self)
    return self
end

function Animal:move()
    print("Animal moves")
end

Key points:

• Set __index to self for inheritance
• Use setmetatable to create instances
• Return the instance from constructor

Method definition syntax:

• function Class:method() - Instance method, receives self implicitly

  • Called as: instance:method() or instance.method(instance)
  • Use for methods that need access to instance state

• function Class.method() - Module function, static, does NOT receive self

  • Called as: Class.method() or instance.method() (both work, but no self)
  • Use for utility functions, constructors, or static helpers

Inheritance Pattern

Class setup (module-level):

local Parent = {}
Parent.__index = Parent

--- @class Child : Parent
local Child = setmetatable({}, { __index = Parent })
Child.__index = Child

Constructor with parent initialization:

function Parent:new(name)
    local instance = {
        name = name,
        parent_state = {}
    }
    return setmetatable(instance, self)
end

function Child:new(name, extra)
    -- Call parent constructor with Parent class
    local instance = Parent.new(Parent, name)

    -- Add child-specific state
    instance.child_state = extra

    -- Re-metatable to child class for proper inheritance chain
    return setmetatable(instance, Child)
end

Critical rules:

• Always pass parent class explicitly: Parent.new(Parent, ...) not Parent.new(self, ...)
• Re-assign metatable to child class after parent initialization
• Inheritance chain: instance → Child → Parent

Calling parent methods:

function Child:move()
    Parent.move(self)  -- Explicit parent method call
    print("Child-specific movement")
end

Class Design Guidelines: creating and modifying

• Minimize class properties - Only include properties that:

  • Are accessed by external code (other modules/classes)
  • Are part of the public API
  • Need to be accessed by subclasses

• Use visibility prefixes for encapsulation - Control what external code can access:

  Visibility levels (configured in .luarc.json):

  • _*: Private - Hidden from external consumers (applies to class methods/fields ONLY)
  • __*: Protected - Visible to subclasses
  • No prefix: Public - Visible everywhere

  IMPORTANT: Module-level local functions and variables do NOT need _ prefix:

  • ✅ local function helper() - correct (already private by local scope)
  • ❌ local function _helper() - incorrect (redundant _ prefix)
  • ✅ local config = {} - correct
  • ❌ local _config = {} - incorrect (redundant _ prefix)
  • ✅ function MyClass:_private_method() - correct (class method needs _)
  • ✅ @field _private_field - correct (class field needs _)

  -- ❌ Bad: Unnecessary public exposure of `counter` property, not used externally
  --- @class MyClass
  --- @field counter number
  local MyClass = {}
  MyClass.__index = MyClass
  
  function MyClass:new()
      return setmetatable({ counter = 0 }, self)
  end
  
  -- ✅ Good: Proper visibility control
  --- @class MyClass
  local MyClass = {}
  MyClass.__index = MyClass
  
  function MyClass:new()
      return setmetatable({
        -- Counter is internal state, not exposed publicly
        _counter = 0
      }, self)
  end
  
  --- @protected
  function MyClass:__protected_method()
      self._counter = self._counter + 1
  end
  
  --- Module-level helper functions (no underscore prefix needed)
  local function format_value(val)
      return tostring(val)
  end
  
  --- @class Child : MyClass
  function Child:use_parent_state()
      self:__protected_method()
  end

  Note: The @private annotation is NOT necessary for private class methods

  • LuaLS infers privacy from the _ prefix automatically
  • Only use @protected for protected methods (__*, luals limitation)

• Document intent with LuaCATS - Use visibility annotations:

  --- @class MyClass
  --- @field public_field string Public API
  --- @field __protected_field table For subclasses
  --- @field _private_field number Internal only

• Regular cleanup - When adding new code, review class definitions and remove:

  • Unused properties
  • Properties that were needed during development but are no longer used
  • Properties that could be local variables instead

LuaCATS annotation syntax

Space after --- for descriptions and annotations. Do NOT write param/return descriptions unless requested. Group related annotations together.