🪝 Hooks System

Overview

The Hooks system is an event-driven architecture that allows other resources to register callback functions for specific events within the nolag_properties resource. This system enables seamless integration with other resources and provides extensibility for custom functionality.

API Reference

Registering Hooks

lua
Copy
local hookId = exports.nolag_properties:registerHook(event, callback)

Parameters:

• event (string): The name of the event to listen for
• callback (function): Function to execute when the event is triggered

Returns:

• hookId (integer): Unique identifier for the registered hook

Example:

lua
Copy
-- Register a hook for property purchases
local hookId = exports.nolag_properties:registerHook('buyProperty', function(data)
    print(('Player %s bought property %s'):format(data.source, data.propertyId))
    
    -- Return false to cancel the purchase
    if someCondition then
        return false
    end
    
    -- Return true or nothing to allow the event to continue
    return true
end)

Removing Hooks

lua
Copy
exports.nolag_properties:removeHooks(hookId)

Parameters:

• hookId (integer): The ID returned from registerHook

Example:

lua
Copy
exports.nolag_properties:removeHooks(hookId)

Event Cancellation

Hooks can prevent events from continuing by returning false. This is useful for:

• Adding custom validation logic
• Implementing permission systems
• Preventing actions based on custom conditions

lua
Copy
exports.nolag_properties:registerHook('buyProperty', function(data)
    -- Custom validation
    if not hasPermissionToBuy(data.source) then
        TriggerClientEvent('chat:addMessage', data.source, {
            args = {'System', 'You do not have permission to buy properties'}
        })
        return false -- Cancels the purchase
    end
    
    -- Allow the purchase to continue
    return true
end)

Best Practices

1. Keep Hooks Fast

Hooks should execute quickly to avoid performance issues. Avoid:

• Database queries in hooks (use async patterns)
• Heavy computations
• Long-running operations

2. Error Handling

Always implement proper error handling in your hooks:

lua
Copy
exports.nolag_properties:registerHook('buyProperty', function(data)
    local success, result = pcall(function()
        -- Your hook logic here
        return myCustomLogic(data)
    end)
    
    if not success then
        print('Hook error:', result)
        return true -- Don't cancel the event due to errors
    end
    
    return result
end)

3. Resource Cleanup

Hooks are automatically cleaned up when resources stop, but you can manually remove them:

lua
Copy
-- Store hook IDs for manual cleanup
local hookIds = {}

-- Register hooks
hookIds.buyProperty = exports.nolag_properties:registerHook('buyProperty', buyPropertyHandler)
hookIds.rentProperty = exports.nolag_properties:registerHook('rentProperty', rentPropertyHandler)

-- Manual cleanup when needed
AddEventHandler('onResourceStop', function(resourceName)
    if resourceName == GetCurrentResourceName() then
        for _, hookId in pairs(hookIds) do
            exports.nolag_properties:removeHooks(hookId)
        end
    end
end)

Usage Examples

Example 1: Logging System

lua
Copy
-- Log all property transactions
exports.nolag_properties:registerHook('buyProperty', function(data)
    local message = ('Property %s purchased by player %s'):format(data.propertyId, data.source)
    -- Send to your logging system
    TriggerEvent('mylogging:log', 'property', message)
    return true
end)

exports.nolag_properties:registerHook('rentProperty', function(data)
    local message = ('Property %s rented by player %s for %s days'):format(
        data.propertyId, 
        data.source, 
        data.rentDays
    )
    TriggerEvent('mylogging:log', 'property', message)
    return true
end)

Example 2: Permission System

lua
Copy
-- Custom permission system
local function hasPropertyPermission(source, action)
    -- Your permission logic here
    return exports['mypermissions']:hasPermission(source, 'property.' .. action)
end

exports.nolag_properties:registerHook('buyProperty', function(data)
    if not hasPropertyPermission(data.source, 'buy') then
        TriggerClientEvent('mynotifications:notify', data.source, 'No permission to buy properties', 'error')
        return false
    end
    return true
end)

Example 3: Economy Integration

lua
Copy
-- Custom economy integration
exports.nolag_properties:registerHook('buyProperty', function(data)
    -- Add bonus for VIP players
    if exports['myvip']:isVIP(data.source) then
        exports['myeconomy']:addMoney(data.source, 'bank', 10000, 'VIP property purchase bonus')
    end
    
    -- Update statistics
    exports['mystats']:incrementStat(data.source, 'properties_bought', 1)
    
    return true
end)

Troubleshooting

Common Issues

1. Hook not triggering
   • Verify the event name is spelled correctly
   • Check that the resource is started after nolag_properties
   • Ensure ox_lib dependency is met
2. Performance warnings
   • Review hook logic for expensive operations
   • Move heavy operations to async handlers
   • Consider caching frequently accessed data
3. Events getting cancelled unexpectedly
   • Check all registered hooks for the event
   • Verify return values (undefined/nil is treated as true)
   • Add logging to identify which hook is cancelling

Debug Tips

lua
Copy
-- Add logging to your hooks for debugging
exports.nolag_properties:registerHook('buyProperty', function(data)
    print('buyProperty hook triggered:', json.encode(data))
    
    local result = myCustomLogic(data)
    print('buyProperty hook result:', result)
    
    return result
end)