[Nimrod]

NOTE: This tutorial is aimed towards the less knowledgeable coders of SA-MP/PAWN and will seem obvious and boring to others.

Most of you probably know what stock functions are. They can speed up your coding greatly. I'm going to show you how to make a few and how they can be used.

The first one I'll talk about is "PColor":

pawn Код:

stock PColor(playerid)
{
    new color = GetPlayerColor(playerid) >>> 8;

    return color;
}

Possibly one of the shortest pieces of code you've ever seen. This simply returns the color of a player. So rather than having to type "GetPlayerColor(playerid) >>> 8" every time, you simply use this:

pawn Код:

format(string, sizeof(string), "{%06x}", PColor(playerid);

The next stock function is "SetPlayerPosEx".

pawn Код:

stock SetPlayerPosEx(playerid, Float:x, Float:y, Float:z, Float:a)
{
    if(IsPlayerInAnyVehicle(playerid) && GetPlayerState(playerid) == PLAYER_STATE_DRIVER)
    {
        SetVehiclePos(GetPlayerVehicleID(playerid), x, y, z);
        SetVehicleZAngle(GetPlayerVehicleID(playerid), a);
    }
    else
    {
        SetPlayerPos(playerid, x, y, z);
        SetPlayerFacingAngle(playerid, a);
    }
    return 1;
}

When teleporting a player, we usually check if they're in a vehicle first, so we don't remove them from their vehicle whilst teleporting them. If you have a lot of teleport commands in your script, it'll take a while to type out the above coding every time, so we simply use SetPlayerPosEx instead. Also, this function allows you to enter a facing angle for players or a z angle for vehicles.

Example:

pawn Код:

CMD:teleportme(playerid, params[])
{
    SetPlayerPosEx(playerid, 0.0, 0.0, 0.0, 270.0);
    return 1;
}

A related stock function to the above would be "GetPlayerFacingAngleEx":

pawn Код:

stock GetPlayerFacingAngleEx(playerid, Float:a)
{
    if(IsPlayerInAnyVehicle(playerid))
    {
        GetVehicleZAngle(GetPlayerVehicleID(playerid), a);
    }
    else
    {
        GetPlayerFacingAngle(playerid, a);
    }
    return 1;
}

With this function, we can check whether the player is in a vehicle, and accordingly choose whether to use GetVehicleZAngle or GetPlayerFacingAngle. Saves a lot of typing!


On almost every command you'll create in your script, you will need to check for errors in the command's usage and subsequently send an error message. You would usually type something like:

pawn Код:

CMD:ban(playerid, params[])
{
    if(!IsPlayerAdmin(playerid)) return SendClientMessage(playerid, 0xFF0000FF, "ERROR: {FFFFFF}You don't have permission to use this command!");

But we can shorten this and save time every time we have to send an error by using this function:

pawn Код:

stock Error(playerid, text[])
{
    new string[144];
    
    format(string, sizeof(string), "{FF0000}ERROR: {FFFFFF}%s", text);
    SendClientMessage(playerid, -1, string);
    
    return 1;
}

Which changes our error sending to:

pawn Код:

CMD:ban(playerid, params[])
{
    if(!IsPlayerAdmin(playerid)) return Error(playerid, "You don't have permission to use this command!");

It also ensures that our error messages are consistent throughout all of our commands in terms of color and styling.


So, there are some stock functions for you to use and hopefully gain some ideas from. Stock functions basically come in handy when
1) having to write out a large chunk of code that clutters up a certain callback, and
2) having to write out a certain bit of code over and over again.

[Vince]

Although the above functions may in fact appear in a library and therefore be declared stock, in nearly every instance where "stock" is mentioned around these forums, "function" would be the right word to replace it. Stock is a modifier. Its only use is to hide functions or variables if they aren't used. Their only use should therefore be in libraries. They have zero use in a normal filterscript or gamemode. It is an ongoing battle to get rid of this serious piece of misinformation around the SA-MP community.

[Pottus]

@Vince nailed it.