[nG Inverse]

Dynamic Player Account Data

About
This library is part of the San Andreas Multiplayer Framework (sampfw) and serves two purposes: 1) implement a seamless and customizable account system and 2) allow dynamic binding of data to the player account.

The dynamic account data manipulation is similar to that of Slice's user.inc The download link for that include is no longer valid, so this could serve as a replacement.

Install
Define any settings (see below) then include the files:

pawn Code:

#include <sampfw\extra\util>
#include <sampfw\account\account>

Note that util.inc must always be the first file included in the framework.

Settings
SAMPFW_REQUIRE_REGISTRATION
If defined, the user will be required to have a registered account (and be logged-in) to play

SAMPFW_PASSWORD_MIN
If defined, the user's password must be a minimum of this length (must use with SAMPFW_PASSWORD_MAX)

SAMPFW_PASSWORD_MAX
If defined, the user's password must be a maximum of this length (must use with SAMPFW_PASSWORD_MIN)

SAMPFW_USE_DIALOGS
This is a global sampfw control. If defined, sampfw will use dialogs where internally implemented; in this case, to handle the user's registration/login.

SAMPFW_USE_CMDS
This is a global sampfw control. If defined, sampfw will use commands where internally implemented; in this case, to handle the user's registration/login. Includes commands /register <password> and /login <password>

Functions

pawn Code:

bool: sampfw::IsPlayerLoggedIn(playerid)    
// Checks whether the player is currently logged-in to an account

pawn Code:

sampfw::AddAccountData(const name[BUD_MAX_COLUMN_NAME], BUD::e_COLUMN_TYPES: type, {Float, _}:...)
// Adds account data to dynamically save and load (Recommended to use in OnGameModeInit)
// See 'Dynamic Data Saving/Loading Example'

Callbacks

pawn Code:

public OnPlayerRegister(playerid)
// Called when a player registers an account

pawn Code:

public OnPlayerLogin(playerid)
// Called when a player logs in to their account

NOTE: When OnPlayerRegister is called, the players are automatically logged-in and OnPlayerLogin will NOT be called

Example

pawn Code:

// controls
#define SAMPFW_USE_DIALOGS
#define SAMPFW_USE_CMDS

// sampfw Utilities (Always include AFTER global settings and BEFORE other sampfw files)
#include <sampfw\extra\util>
 
// account.inc sampfw settings ----------------------------------------------------

#define SAMPFW_REQUIRE_REGISTRATION
#define SAMPFW_PASSWORD_MIN         4
#define SAMPFW_PASSWORD_MAX         16

#include <sampfw\account\account>

At this point, with the current configuration, you have a fully working registration system that includes:

• Dialogs for the player to register/login
• Commands /register <password> and /login <password>
• Players must be registered / logged-in to play
• Player's password must be between 4 and 16 characters long

Dynamic Data Saving/Loading Example
A neat feature of this library is to automatically have player data loaded from the database when logging in, saving to the database when disconnecting, and automatically loaded to variables for your manipulation while in-game.

Each data piece you want to save needs a separate variable to store. Then, it needs to be added to the list of data to save via sampfw::AddAccountData.

sampfw::AddAccountData is as followed

pawn Code:

stock sampfw::AddAccountData(const name[BUD_MAX_COLUMN_NAME], BUD::e_COLUMN_TYPES: type, {Float, _}:...)

const name[BUD_MAX_COLUMN_NAME]
The database column name to store the data under
BUD::e_COLUMN_TYPES: type
The "data-type" of the data to save (BUD::TYPE_NUMBER, BUD::TYPE_FLOAT, BUD::TYPE_STRING)
{Float,_}:...
The variable to load/save the player data to/from.

In the below example, we'll save player's nickname, kills, deaths, health, and armor.

pawn Code:

new
    g_PlayerNick[MAX_PLAYER_NAME + 1],
    g_PlayerKills,
    g_PlayerDeaths,
    Float: g_PlayerHealth,
    Float: g_PlayerArmour;

public OnGameModeInit()
{
    sampfw::AddAccountData("nickname", BUD::TYPE_STRING, g_PlayerNick);
    sampfw::AddAccountData("kills", BUD::TYPE_NUMBER, g_PlayerKills);
    sampfw::AddAccountData("deaths", BUD::TYPE_NUMBER, g_PlayerDeaths);
    sampfw::AddAccountData("health", BUD::TYPE_FLOAT, g_PlayerHealth);
    sampfw::AddAccountData("armour", BUD::TYPE_FLOAT, g_PlayerArmour);
    return 1;
}

And that's it! The data will automatically be stored to the database for the player, and their data will automatically be loaded into those variables when logging in. You are free to manipulate the variables as usual and the data will save.

pawn Code:

public OnPlayerDeath(playerid, killerid, reason)
{
        g_PlayerDeaths[playerid]++;
        return 1;
}

NOTE: The user's unique-ID, name, and password are already taken care of by BUD.

Dependencies (Currently)
This is a part of San Andreas Multiplayer Framework, and requires all of its dependencies. Check the GitHub for a list (docs/dependencies.txt).


GitHub
https://github.com/bwhitmire55/sampfw