promo-code

English | Русский

Library for SA-MP (Pawn) that allows creating, managing, and activating categorized promo codes with flexible reward logic and multi-language support.

Note: The library supports both English and Russian languages. Use #define PC_INTERFACE_LANGUAGE 1 for Russian.

Reference

• Installation
• Example
• Functions
• Callbacks
• Definition

Dependencies

• MySQL R41-4
• mdialog
• Pawn.Regex

Installation

Include in your code and begin using the library:

#include <promo-code>

Example

Click to expand the list

public OnGameModeInit() {

	//Add a handle to interact with the promo code after connecting to your database
	SetPromoCodeHandle(MySQL:handle);


    //Adding promo code categories
    CreatePromoCodeCategory("Skill TEC9");

    //You can add a value restriction.
    CreatePromoCodeCategory("Money", .minValue = 100, .maxValue = 100_000);
    return 1;
}


//After logging into the player's account, add their ID to interact with the promo code 
SetPromoCodeAccountID(playerid, accountId);


//Creating a promo code
CMD:create(playerid) {
	ShowPromoCodeCreationDialog(playerid);
	return 1;
}


//Editing a promo code
CMD:list(playerid) {
	ShowPromoCodeListDialog(playerid);
	return 1;
}


//Activating a promo code
CMD:activate(playerid, params[]) {

    if(!strlen(params)) {
		SendClientMessage(playerid, -1, "Use: /activate [name]");
		return 0;
	}

	if(!ActivatePromoCode(playerid, params)) {
		SendClientMessage(playerid, 0xc8c8c8AA, "Incorrect text format");
		return 0;
	}

	return 1;
}


//Checking the promo code
forward OnPlayerPromoCodeActivated(playerid, const name[], response);
public OnPlayerPromoCodeActivated(playerid, const name[], response) {
	
	if(response == PC_STATUS_INVALID) {
		SendClientMessage(playerid, 0xc8c8c8AA, "Promo code not found");
		return 0;
	}

	else if(response == PC_STATUS_LIMIT_REACHED) {
		SendClientMessage(playerid, 0xc8c8c8AA, "The promo code was activated as many times as possible");
		return 0;
	}

	else if(response == PC_STATUS_EXPIRED) {
		SendClientMessage(playerid, 0xc8c8c8AA, "Promo code expired");
		return 0;
	}

	else if(response == PC_STATUS_ALREADY_USED) {
		SendClientMessage(playerid, 0xc8c8c8AA, "You have already activated this promo code.");
		return 0;
	}


	//Personal check for a specific promo code
	if(IsPromoCodeMatch(name, "my promo code") && GetPlayerScore(playerid) >= 5) {
		SendClientMessage(playerid, 0xc8c8c8AA, "Promo code is only available until level 5");
		return 0; //To prevent activation, use 0
	}


	static const text[] = "You have successfully activated the promo code %s";
	new string[sizeof(text) + PC_NAME_LENGTH];
	
	format(string, sizeof(string), text, name);
	SendClientMessage(playerid, -1, string);
    return 1;
}


//Giving out promo code prizes
forward OnPlayerPromoCodeRewarded(playerid, const name[], const category[], value);
public OnPlayerPromoCodeRewarded(playerid, const name[], const category[], value) {

	printf("Rewarde --->>> | playerid: %d | name: %s | category: %s | value: %d", 
    	playerid,
		name, 
		category, 
		value);

	//Checking which category was issued
	if(IsPromoCodeCategoryMatch(category, "Skill TEC9")) {

        SetPlayerSkillLevel(playerid, 32, value);
		SendClientMessage(playerid, -1, "You have received the m4 skill");
    }

    if(IsPromoCodeCategoryMatch(category, "Money")) {

        GivePlayerMoney(playerid, value);
		SendClientMessage(playerid, -1, "You received the money");
    }
	
	return 1;
}

Functions

Click to expand the list

SetPromoCodeHandle(MySQL:handle)

Connects to a MySQL server and database.

• MySQL:handle - The connection handle

SetPromoCodeAccountID(playerid, accountId)

Set the player's account ID

• playerid - The ID of the player
• accountId - The account ID of the player
• NOTE: Required for promo code activation by the player.

CreatePromoCodeCategory(const name[], minValue = -1, maxValue = -1)

Add a category for the promo code

• name[] - Category name
• minValue - Minimum value restriction
• maxValue - Maximum value restriction
• NOTE: minValue, maxValue - Used when selecting a category in the creation dialog

ActivatePromoCode(playerid, const name[])

Activate a promo code

• playerid - The ID of the player
• name[] - Promo code name
• Returns 0 if the text format was incorrect

ShowPromoCodeCreationDialog(playerid)

Show the promo code creation dialog

• playerid - The ID of the player

ShowPromoCodeListDialog(playerid)

Show the list dialog of created promo codes

• playerid - The ID of the player

IsPromoCodeMatch(const name1[], const name2[])

Compare one text with another (similar to strcmp)

• name1[] - Name text 1
• name2[] - Name text 2

IsPromoCodeCategoryMatch(const name1[], const name2[])

Compare one text with another (similar to strcmp)

• name1[] - Category name 1
• name2[] - Category name 2

Callbacks

Click to expand the list

public OnPlayerPromoCodeActivated(playerid, const name[], response)

Called when a promo code is activated

• playerid - The ID of the player
• name[] - Promo code name
• response - Response value
• NOTE: To prevent activation, use return 0;

public OnPlayerPromoCodeRewarded(playerid, const name[], const category[], value)

Called after promo code activation and used for giving rewards

• playerid - The ID of the player
• name[] - Promo code name
• category - Promo code category
• value - Specified category value
• NOTE: Called multiple times per single activation by a player

public OnPlayerPromoCodeCreated(playerid, const name[], remainingUses, expirationDate)

Called after a promo code is created

• playerid - The ID of the player
• name[] - Promo code name
• remainingUses - Number of activations Value -1 is for infinite activations
• expirationDate - Promo code expiration date Uses gettime() data. Value 0 is used for no expiration date

public OnPlayerPromoCodeDeleted(playerid, const name[])

Called after a promo code is deleted

• playerid - The ID of the player
• name[] - Promo code name

Definition

Click to expand the list

Response value from OnPlayerPromoCodeActivated

Definition	ID	Description
PC_STATUS_INVALID	0	Code not found
PC_STATUS_ACTIVATED	1	Success
PC_STATUS_LIMIT_REACHED	2	Activations ended
PC_STATUS_EXPIRED	3	Expired
PC_STATUS_ALREADY_USED	4	Already activated by a player

#define PC_INTERFACE_LANGUAGE 0 // 0 - English | 1 - Russian 
#define PC_NAME_LENGTH 32
#define PC_CATEGORY_NAME_LENGTH 32
#define PC_REGEX_NAME "^[\\s0-9ёЁа-яА-Яa-zA-Z!@#$^&*()_+-=]{3,32}$"

#define PC_MAX_CATEGORIES 100
#define PC_MAX_CATEGORIES_PER_CODE 40
#define PC_MAX_LIST_ROWS 20 // max dialog list lines

#define PC_RED_COLOR 0xf44747AA
#define PC_WHITE_COLOR_TAG "{FFFFFF}"
#define PC_GREY_COLOR_TAG "{c8c8c8}"
#define PC_YELLOW_COLOR_TAG "{F5D742}"
#define PC_GREEN_COLOR_TAG "{8fce00}"
#define PC_RED_COLOR_TAG "{f44747}"