From SA-MP Wiki

Contents 1 Introduction 2 Features 3 Use 4 API Functions 4.1 Player_Player() 4.2 Player_OnGameModeInit() 4.3 Player_OnPlayerConnect(playerid) 4.4 Player_OnPlayerDisconnect(playerid, reason) 4.5 Player_OnPlayerLogin(playerid, uid) 4.6 Player_SetTag(tag[]) 4.7 Player_WriteString(name[], data[]) 4.8 Player_WriteInt(name[], data) 4.9 Player_WriteFloat(name[], Float:data) 4.10 Player_FindShortCut(playerid, shortcut, cmdname[]) 4.11 Language:Player_GetPlayerLanguage(playerid) 4.12 Player_SetPlayerLanguage(playerid, Language:languageID) 5 Commands 5.1 /register <password> 5.2 /login <password> 5.3 /groupnick <group> <password> 6 Compile Options 6.1 YSI_NO_USERS 6.2 PP_ADLER32 6.3 PP_MD5 6.4 PP_SHA1 7 Other Functions 7.1 YSIM_Player(command) 7.2 Player_LoginCheck(playerid) 7.3 Player_PlayersLoggedIn(tag[], identifier[], text[]) 7.4 ycmd_login(playerid, params[], help) 7.5 ycmd_register(playerid, params[], help) 7.6 ycmd_groupnick(playerid, params[], help) 7.7 Player_AddToGroup(playerid, password[], group[] = "", reg = 1) 7.8 Player_LoginCall(playerid, uid, text = 1) 7.9 Player_ReloginCall(playerid, uid) 7.10 Player_AddUser(playerid, name[], password[], &uid) 7.11 Player_Login(playerid, password[]) 7.12 LoginDat_ysi_core(playerid, identifier[], text[]) 7.13 Player_HashPass(pass[])

Introduction

The YSI user system provides an integrated user registration and login system for use in all running modes, allowing you to log in to all scripts at once with very little code in your mode. All that's required is very simple code to load and save variables specific to a mode - the actual file handling is done behind the scenes using a wrapper for the INI system and some extra custom code for the multi-name per account lookup system.

Features

• /register, /login and /groupnick commands built in.
• Multiple names per account using /groupnick if wanted, e.g. Y_Less and [KFC]Y_Less.
• Simple loading of data on login.
• Simple saving of data on logout.
• Multiple hash systems - adler32 and JSC hash included and options for SHA1 and MD5.
• Auto re-login to new mode on game mode change.

Use

90% of the user system functionality is available simply by including YSI, the other 10% is mode specific and very simple to implement. When a player is logged in the OnPlayerLogin callback is called, this allows you to initialize variables however is not where you load data from files - data loading is done using custom functions. When a player logs out the OnPlayerLogout code is called, this is where you save their data, first you set a unique identifier for the mode, e.g. "my_mode", then write all the data you want to the user file using the Player_WriteType(name,value) functions, the unique name you use here is the same as it used in the custom callback to load the data again on login.

new
	// Array to hold a player's unique identifier
	gPlayerLoggedIn[MAX_PLAYERS] = {-1, ...},
	// Array to hold a player's deaths
	gPlayerDeaths[MAX_PLAYERS],
	// Array to hold a player's kills
	gPlayerKills[MAX_PLAYERS];
 
forward LoginDat_my_mode(playerid, identifier[], text[]);
 
// When they log in save their ID
public OnPlayerLogin(playerid, yid)
{
	gPlayerLoggedIn[playerid] = yid;
	return 1;
}
 
public OnPlayerLogout(playerid, yid)
{
	// Reset the unique id to an invalid one (0 is valid)
	gPlayerLoggedIn[playerid] = -1;
 
	// Set the unique identifier for the mode
	Player_SetTag("my_mode");
 
	// Save the data for the player
	Player_WriteInt("kills", gPlayerKills[playerid]);
	Player_WriteInt("deaths", gPlayerDeaths[playerid]);
 
	// Random other data
	Player_WriteString("some_string", "hello");
	Player_WriteFloat("some_float", 2.0);
 
	return 1;
}
 
public OnPlayerDisconnect(playerid, reason)
{
	// Reset stats
	gPlayerDeaths[playerid] = 0;
	gPlayerKills[playerid] = 0;
 
	#pragma unused reason
	return 1;
}
 
// This is the function where stats are loaded, name is LoginDat_<unique identifier>
public LoginDat_my_mode(playerid, identifier[], text[])
{
	// Check which data is being loaded and store it
	if (!strcmp(identifier, "kills")) gPlayerKills[playerid] += strval(text);
	else if (!strcmp(identifier, "deaths")) gPlayerDeaths[playerid] += strval(text);
	else if (!strcmp(identifier, "some_string")) // Do something with "hello"
	else if (!strcmp(identifier, "some_float")) // Do something with floatstr("2.0")
	return 1;
}
 
// Just to make the kills and deaths mean something
public OnPlayerDeath(playerid, killerid, reason)
{
	gPlayerDeaths[playerid]++;
	if (killerid != INVALID_PLAYER_ID) gPlayerKills[playerid]++;
	return 1;
}

API Functions

These functions can be called by the scripter to get information from, or pass information to, the player system. Generally only four will ever be called, as described above.

Player_Player()

This function simply sets up the user system, initializes variables etc. It is called automatically by the Script_ system but if you're not using that it should be called from either OnGameModeInit or OnFilterScriptInit, depending on which you're writing.

Player_OnGameModeInit()

This function should only be called from OnGameModeInit in FILTERSCRIPTS, if you try call it from a gamemode you will get a compile error. Again this is called by the Script_ system automatically.

Player_OnPlayerConnect(playerid)

This function handles the auto-re-login system when a gamemode restarts, it is also called by the Script_ system or from OnPlayerLogin if not used.

Player_OnPlayerDisconnect(playerid, reason)

This function obviously logs people out when they leave the server, it should be called FIRST in OnPlayerDisconnect, as it is when the Script_ system is used.

Player_OnPlayerLogin(playerid, uid)

This function sets some internal variables in slave user systems which aren't controlling the /login command in distributed scripts. It should be called from OnPlayerLogin and is handled by the Script_ system.

Player_SetTag(tag[])

This function sets the unique identifier for your mode so loading will only load information for the single mode. For example you may have two modes running, LVDM and SFTDM, the user file (assuming the unique IDs are "LVDM" and "SFTDM" respectively) could look like:

[LVDM]
x = 1.0
y = 10.0
z = 20.0

[SFTDM]
x = 5.0
y = 12.0
z = 4.0

While both modes store the player's last position only the correct one will be loaded.

Player_WriteString(name[], data[])

This function can be used in OnPlayerLogout (and only there) to save a string to a player's user file:

Player_WriteString("name", "Y_Less");

Would result in:

name = Y_Less

in the user file.

Player_WriteInt(name[], data)

This file just writes a simple number to a user's file, e.g.:

Player_WriteInt("number", 7);

Would result in:

number = 7

Player_WriteFloat(name[], Float:data)

This function is obviously like the two above but writes a float value to the user's file.

Player_FindShortCut(playerid, shortcut, cmdname[])

This function finds a player's personal command for a single character and returns it in cmdname. It is used internally by the command system to allow people to set their own shortcuts for any commands on the server, e.g. for one player typing /a may result in /commands being called while for another typing /a may result in /arrest being called, this allows people to use short commands similar to how keyhooks work but within the rules of SA:MP. This is here as the data is automatically loaded for registered players.

Language:Player_GetPlayerLanguage(playerid)

This function obviously returns the language a player has selected to use and saved automatically. This is used internally by the text system.

Player_SetPlayerLanguage(playerid, Language:languageID)

This function saves a player's language after they change it, it is used internally by the text system.

Commands

/register <password>

Simply registers a user into the system and logs them in. If the nick is already taken they will not be logged in.

/login <password>

Logs a registered player into the server, affects all running (and to be run) YSI scripts.

/groupnick <group> <password>

Registers a nick as associated with an existing registered player's account. <group> is any name already associated with the account, <password> is the correct password for the account. Once this is done logging in as any of the names associated with the account will load the single account file.

Compile Options

Compile options are defines which can be placed ABOVE the:

#include <YSI>

line to alter how the code is compiled, the compile options specific to the users system are:

YSI_NO_USERS

#define YSI_NO_USERS

Excludes the user system from YSI entirely, with this defined (or uncommented in the YSI new file) you will not have any login or registration system.

PP_ADLER32

#define PP_ADLER32

This will make the user system use adler32 to hash passwords instead of JSC hash, useful for conversion from other user systems but far less secure.

PP_MD5

This would set the system to use MD5 hashing on passwords instead but the hash algorithm is not currently implemented.

PP_SHA1

This would set the system to use SHA1 hashing on passwords instead but the hash algorithm is not currently implemented.

Other Functions

These are functions internal in the user system and should not (and most can not) be called by the scripter.

YSIM_Player(command)

Processes commands from the master system for code distribution.

Player_LoginCheck(playerid)

Remote function called on gamemode change to check if a player was logged in.

Player_PlayersLoggedIn(tag[], identifier[], text[])

Callback from the INI system to process the file list of previously logged in players called from Player_LoginCheck.

ycmd_login(playerid, params[], help)

Processes the /login command.

ycmd_register(playerid, params[], help)

Processes the /register command.

ycmd_groupnick(playerid, params[], help)

Processes the /groupnick command.

Player_AddToGroup(playerid, password[], group[] = "", reg = 1)

Handles the registration of a player, if reg is not 1 then it adds the player to an existing name group for multiple names per account.

Player_LoginCall(playerid, uid, text = 1)

Logs a player in, if text is 0 it doesn't display the "logged in" message for relogins.

Player_ReloginCall(playerid, uid)

Called remotely by the master script to auto-log-in players in scripts they're not already logged in in.

Player_AddUser(playerid, name[], password[], &uid)

Adds a player account to the database and returns the new unique id.

Player_Login(playerid, password[])

Checks a player's password against their data in the index file and calls the login functions if correct.

LoginDat_ysi_core(playerid, identifier[], text[])

Unique callback for loading user data for core functions.

Player_HashPass(pass[])

Hashes the passed text according to the compile time selected hash.