Exports

Loyalty System Complete API Documentation

The Loyalty System provides a set of functions to manage player loyalty cards and points. These functions are exported from the 'Loyalty' resource and can be used in other resources within your QBCore-based server.

Table of Contents

  1. HasCard

  2. GetPoints

  3. AddPoints

  4. RemovePoints

  5. General Notes

Functions

HasCard

Checks if a player has a loyalty card.

Parameters:

  • playerId (number): The server ID of the player.

Returns:

  • boolean: true if the player has a loyalty card, false otherwise.

Usage:

local hasCard = exports['Loyalty']:HasCard(playerId)
if hasCard then
    print("Player has a loyalty card")
else
    print("Player does not have a loyalty card")
end

GetPoints

Retrieves the current points balance for a player.

Parameters:

  • playerId (number): The server ID of the player.

Returns:

  • number: The current points balance of the player. Returns 0 if the player doesn't have a loyalty card.

Usage:

local points = exports['Loyalty']:GetPoints(playerId)
print("Player has " .. points .. " loyalty points")

AddPoints

Adds points to a player's loyalty card based on a dollar amount.

Parameters:

  • playerId (number): The server ID of the player.

  • amount (number): The dollar amount to convert to points.

  • reason (string, optional): A description of why points are being added. Defaults to "Purchase" if not provided.

Returns:

  • boolean: true if points were successfully added, false if the operation failed.

  • string: A message describing the result of the operation.

  • number: The actual number of points added after conversion.

Usage:

local success, message, pointsAdded = exports['Loyalty']:AddPoints(playerId, 50, "Large purchase reward")
if success then
    print(message)  -- "Points added successfully."
    print("Added " .. pointsAdded .. " points")
else
    print(message)  -- Could be "Player not found." or "Invalid amount. Please provide a valid number."
end

Notes:

  • This function converts the dollar amount to points using Config.PointsEach1Dollar.

  • The converted amount is rounded down to the nearest integer.

  • Points addition is logged in the loyalty_card_logs table.

  • After successful point addition, a notification is sent to the player using the "lb-phone" resource.

  • If the player is not found or the amount is invalid, the function will return false with an appropriate error message.

RemovePoints

Removes points from a player's loyalty card.

Parameters:

  • playerId (number): The server ID of the player.

  • pointsToRemove (number): The amount of points to remove.

  • customMessage (string, optional): A custom message for the reason of point removal. If not provided, defaults to "Points removed".

Returns:

  • boolean: true if points were successfully removed, false if the operation failed.

  • string: A message describing the result of the operation.

Usage:

local success, message = exports['Loyalty']:RemovePoints(playerId, 50, "Reward redemption")
if success then
    print(message)  -- "Points removed successfully."
else
    print(message)  -- Could be "Player not found." or "Not enough points available."
end

Notes:

  • This function checks if the player has enough points before removing them. If not, the operation will fail.

  • Point removal is logged in the loyalty_card_logs table with a negative value for points_added.

  • After successful point removal, a notification is sent to the player using the "lb-phone" resource.

General Notes

  1. Server-Side Usage: All these functions should be called server-side.

  2. Resource Dependency: Ensure that the 'Loyalty' resource is started before calling these functions.

  3. Database Interactions:

    • The system uses a loyalty_cards table to store player card information.

    • A loyalty_card_logs table is used to log all point transactions.

  4. Player Verification: All functions first verify if the player exists using QBCore's GetPlayer function.

  5. Notifications: The system uses the "lb-phone" resource to send notifications to players after successful point operations.

  6. Configuration:

    • The AddPoints function uses a configuration value Config.PointsEach1Dollar to convert dollar amounts to points. Ensure this configuration is properly set in your resource.

  7. Error Handling:

    • Functions return false with an error message if operations fail (e.g., player not found, insufficient points).

    • Always check the return values to handle success and failure cases appropriately in your scripts.

  8. Loyalty Card Requirement:

    • GetPoints will return 0 if a player doesn't have a loyalty card.

    • AddPoints and RemovePoints will fail if the player doesn't have a loyalty card.

    • Use HasCard to check for card existence before performing operations if you need to handle card/no-card situations differently.

  9. Asynchronous Operations:

    • Database operations are performed asynchronously to prevent blocking the main thread.

    • The AddPoints and RemovePoints functions use MySQL transactions to ensure data integrity.

  10. Rounding: When adding points, the dollar amount is converted to points and rounded down to the nearest integer.

  11. Logging: All point additions and removals are logged in the loyalty_card_logs table for auditing purposes.

PreviousTiersNextCustom Money Handling

Last updated