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.