Plugins

Plugins are named extension points that modules can expose, allowing other modules to hook into their logic without replacing the entire service.

Declaring Plugin Hooks

In your service, declare hooks at meaningful points:

-- server/services/InventoryService.lua
function InventoryService:addItem(playerId, item, count)
    -- Run beforeAddItem plugins
    local plugins = self._container:makeAll('inventory:beforeAddItem')
    for _, plugin in ipairs(plugins) do
        local allow = plugin({ playerId = playerId, item = item, count = count })
        if allow == false then
            return false  -- cancelled
        end
    end

    -- ... actual add logic

    -- Run afterAddItem plugins
    local afterPlugins = self._container:makeAll('inventory:afterAddItem')
    for _, plugin in ipairs(afterPlugins) do
        plugin({ playerId = playerId, item = item, count = count })
    end

    return true
end

Registering a Plugin

In your module's init(), bind to the plugin hook:

function M.init(container)
    -- Block illegal items for non-police
    container:bind('inventory:beforeAddItem', function(ctx)
        local illegal = { 'weapon_pistol', 'drug_cocaine' }
        for _, illegalItem in ipairs(illegal) do
            if ctx.item == illegalItem then
                local player = container:make('IPlayer')
                if not player:hasJob(ctx.playerId, 'police') then
                    return false
                end
            end
        end
        return true
    end)
end

Plugin Contract

Naming	module:hookName
beforeX hooks	Return false to cancel, anything else to allow
afterX hooks	Return value is ignored
transformX hooks	Return the modified value

Documenting Plugin Hooks

Document your hooks in docs/plugins.md so other module developers know what they can hook into.

See Also

• Concepts: Overrides →
• Container →