Documented template for new SAMP (0.3.7) scripts

samp-new.pwn

// This is a comment
// uncomment the line below if you want to write a filterscript
//#define FILTERSCRIPT

#include <a_samp>

#if defined FILTERSCRIPT

/**
 * This callback is called when a filterscript is initialized (loaded). It is only called inside the filterscript which is starting.
 *
 * @returns This callback does not handle returns.
 */
public OnFilterScriptInit()
{
    print("\n--------------------------------------");
    print(" Blank Filterscript by your name here");
    print("--------------------------------------\n");
    return 1;
}

/**
 * This callback is called when a filterscript is unloaded. It is only called inside the filterscript which is unloaded.
 *
 * @returns This callback does not handle returns.
 */
public OnFilterScriptExit()
{
    return 1;
}

#else

main()
{
    print("\n----------------------------------");
    print(" Blank Gamemode by your name here");
    print("----------------------------------\n");
}

#endif

/**
 * This callback is triggered when the gamemode starts.
 *
 * @returns This callback does not handle returns.
 */
public OnGameModeInit()
{
    // Don't use these lines if it's a filterscript
    SetGameModeText("Blank Script");
    AddPlayerClass(0, 1958.3783, 1343.1572, 15.3746, 269.1425, 0, 0, 0, 0, 0, 0);
    return 1;
}

/**
 * This callback is called when a gamemode ends, either through 'gmx', the server being shut down, or GameModeExit.
 *
 * @returns This callback does not handle returns.
 */
public OnGameModeExit()
{
    return 1;
}

/**
 * Called when a player changes class at class selection (and when class selection first appears).
 *
 * @param playerid  The ID of the player that changed class.
 * @param classid   The ID of the current class being viewed (returned by AddPlayerClass).
 *
 * @returns Returning 0 in this callback will prevent the player from spawning. The player can be forced to spawn when SpawnPlayer is used, however the player will re-enter class selection the next time they die.
 */
public OnPlayerRequestClass(playerid, classid)
{
    SetPlayerPos(playerid, 1958.3783, 1343.1572, 15.3746);
    SetPlayerCameraPos(playerid, 1958.3783, 1343.1572, 15.3746);
    SetPlayerCameraLookAt(playerid, 1958.3783, 1343.1572, 15.3746);
    return 1;
}

/**
 * This callback is called when an IP address attempts a connection to the server. To block incoming connections, use BlockIpAddress.
 *
 * @param playerid      The ID of the player attempting to connect
 * @param ip_address[]  The IP address of the player attempting to connect
 * @param port          The port of the attempted connection
 *
 * @returns This callback does not handle returns.
 */
public OnIncomingConnection(playerid, ip_address[], port)
{
    return 1;
}

/**
 * This callback is called when a player connects to the server.
 *
 * @param playerid  The ID of the player that connected.
 *
 * @returns 0 - Will prevent other filterscripts from receiving this callback.
 *          1 - Indicates that this callback will be passed to the next filterscript.
 */
public OnPlayerConnect(playerid)
{
    return 1;
}

/**
 * This callback is called when a player disconnects from the server.
 *
 * @param playerid  The ID of the player that disconnected.
 * @param reason    The reason for the disconnection. See table below.
 *                  0 - Timeout / Crash
 *                  1 - Quit
 *                  2 - Kick / Ban
 *
 * @returns 0 - Will prevent other filterscripts from receiving this callback.
 *          1 - Indicates that this callback will be passed to the next filterscript.
 */
public OnPlayerDisconnect(playerid, reason)
{
    return 1;
}

/**
 * This callback is called when a player spawns.(i.e. after caling SpawnPlayer function)
 *
 * @param playerid  The ID of the player that spawned.
 *
 * @returns Returning 0 in this callback will force the player back to class selection when they next spawn.
 */
public OnPlayerSpawn(playerid)
{
    return 1;
}

/**
 * This callback is called when a player gives damage to another player.
 *
 * @param playerid  The ID of the player that gave damage.
 * @param damagedid The ID of the player that received damage.
 * @param amount    The amount of health/armour damagedid has lost (combined).
 * @param weaponid  The reason that caused the damage.
 *                  See: https://wiki.sa-mp.com/wiki/Weapons
 * @param bodypart  The body part that was hit. (NOTE: This parameter was added in 0.3z. Leave it out if using an older version!)
 *
 * @returns  1 - Callback will not be called in other filterscripts.
 *           0 - Allows this callback to be called in other filterscripts.
 *           It is always called first in filterscripts so returning 1 there blocks other filterscripts from seeing it
 */
public OnPlayerGiveDamage(playerid, damagedid, Float:amount, weaponid, bodypart)
{
    return 1;
}

/**
 * This callback is called when a player takes damage.
 *
 * @param playerid  The ID of the player that took damage.
 * @param issuerid  The ID of the player that caused the damage. INVALID_PLAYER_ID if self-inflicted.
 * @param amount    The amount of damage the player took (health and armour combined).
 * @param weaponid  The ID of the weapon/reason for the damage.
 *                  See: https://wiki.sa-mp.com/wiki/Weapons
 * @param bodypart  The body part that was hit. (NOTE: This parameter was added in 0.3z. Leave it out if using an older version!)
 *
 * @returns 1 - Callback will not be called in other filterscripts.
 *          0 - Allows this callback to be called in other filterscripts.
 *          It is always called first in filterscripts so returning 1 there blocks other filterscripts from seeing it
 */
public OnPlayerTakeDamage(playerid, issuerid, Float:amount, weaponid, bodypart)
{
    return 1;
}

/**
 * This callback is called when a player dies, either by suicide or by being killed by another player.
 *
 * @param playerid  The ID of the player that died.
 * @param killerid  The ID of the player that killed the player who died, or INVALID_PLAYER_ID if there was none.
 * @param reason    The ID of the reason for the player's death. See: https://wiki.sa-mp.com/wiki/Weapons
 *
 * @returns This callback does not handle returns.
 */
public OnPlayerDeath(playerid, killerid, reason)
{
    return 1;
}

/**
 * This callback is called when a vehicle respawns.
 *
 * @param vehicleid The ID of the vehicle that spawned.
 *
 * @returns This callback does not handle returns.
 */
public OnVehicleSpawn(vehicleid)
{
    return 1;
}

/**
 * This callback is called when a vehicle is destroyed - either by exploding or becoming submerged in water.
 *
 * @param vehicleid The ID of the vehicle that was destroyed.
 * @param killerid  The ID of the player that reported (synced) the vehicle's destruction (name is misleading). Generally the driver or a passenger (if any) or the closest player.
 *
 * @returns This callback does not handle returns.
 */
public OnVehicleDeath(vehicleid, killerid)
{
    return 1;
}

/**
 * This callback is called when a vehicle's siren is toggled.
 *
 * @param playerid  The ID of the player that toggled the siren (driver).
 * @param vehicleid The ID of the vehicle of which the siren was toggled for.
 * @param newstate  0 if siren was turned off, 1 if siren was turned on.
 *
 * @returns This callback does not handle returns.
 */
public OnVehicleSirenStateChange(playerid, vehicleid, newstate)
{
    return 1;
}

/**
 * Called when a player sends a chat message.
 *
 * @param playerid  The ID of the player who typed the text.
 * @param text      The text the player typed.
 *
 * @returns Returning 0 in this callback will stop the text from being sent to all players
 */
public OnPlayerText(playerid, text[])
{
    return 1;
}

/**
 * This callback is called when a player enters a command into the client chat window. Commands are anything that start with a forward slash, e.g. /help.
 *
 * @param playerid  The ID of the player that entered a command.
 * @param cmdtext   The command that was entered (including the forward slash)
 *
 * @returns Return 1 if the command was processed, otherwise 0.
 */
public OnPlayerCommandText(playerid, cmdtext[])
{
    if (strcmp("/mycommand", cmdtext, true, 10) == 0)
    {
        // Do something here
        return 1;
    }
    return 0;
}

/**
 * This callback is called when a player starts to enter a vehicle, meaning the player is not in vehicle yet at the time this callback is called.
 *
 * @param playerid      ID of the player who attempts to enter a vehicle.
 * @param vehicleid     ID of the vehicle the player is attempting to enter.
 * @param ispassenger   0 if entering as driver. 1 if entering as passenger.
 */
public OnPlayerEnterVehicle(playerid, vehicleid, ispassenger)
{
    return 1;
}

/**
 * This callback is called when a player starts to exit a vehicle.
 *
 * @param playerid  The ID of the player that is exiting a vehicle.
 * @param vehicleid The ID of the vehicle the player is exiting.
 *
 * @returns This callback does not handle returns.
 */
public OnPlayerExitVehicle(playerid, vehicleid)
{
    return 1;
}

/**
 * This callback is called when a player changes state. For example, when a player changes from being the driver of a vehicle to being on-foot.
 * See: https://wiki.sa-mp.com/wiki/State
 *
 * @param playerid  The ID of the player that changed state.
 * @param newstate  The player's new state.
 * @param oldstate  The player's previous state.
 *
 * @returns This callback does not handle returns.
 */
public OnPlayerStateChange(playerid, newstate, oldstate)
{
    return 1;
}

/**
 * This callback is called when a player enters the checkpoint set for that player.
 *
 * @param playerid  The player who entered the checkpoint.
 *
 * @returns This callback does not handle returns.
 */
public OnPlayerEnterCheckpoint(playerid)
{
    return 1;
}

/**
 * This callback is called when a player leaves the checkpoint set for them by SetPlayerCheckpoint. Only one checkpoint can be set at a time.
 *
 * @param playerid  The ID of the player that left their checkpoint.
 *
 * @returns This callback does not handle returns.
 */
public OnPlayerLeaveCheckpoint(playerid)
{
    return 1;
}

/**
 * This callback is called when a player enters a race checkpoint.
 *
 * @param playerid  The ID of the player who entered the race checkpoint.
 *
 * @returns This callback does not handle returns.
 */
public OnPlayerEnterRaceCheckpoint(playerid)
{
    return 1;
}

/**
 * This callback is called when a player leaves the race checkpoint.
 *
 * @param playerid  The ID of the player that left the race checkpoint.
 *
 * @returns This callback does not handle returns.
 */
public OnPlayerLeaveRaceCheckpoint(playerid)
{
    return 1;
}

/**
 * This callback is called when a command is sent through the server console, remote RCON, or via the in-game /rcon command.
 *
 * @param cmd   A string containing the command that was typed, as well as any passed parameters.
 *
 * @returns 0 if the command was not processed, it will be passed to another script or 1 if the command was processed, will not be passed to other scripts.
 */
public OnRconCommand(cmd[])
{
    return 1;
}

/**
 * Called when a player attempts to spawn via class selection either by pressing SHIFT or clicking the 'Spawn' button.
 *
 * @param playerid  The ID of the player that requested to spawn.
 *
 * @returns Returning 0 in this callback will prevent the player from spawning.
 */
public OnPlayerRequestSpawn(playerid)
{
    return 1;
}

/**
 * This callback is called when an object is moved after MoveObject (when it stops moving).
 *
 * @param objectid  The ID of the object that was moved.
 *
 * @returns This callback does not handle returns.
 */
public OnObjectMoved(objectid)
{
    return 1;
}

/**
 * This callback is called when a player object is moved after MovePlayerObject (when it stops moving).
 *
 * @param playerid  The playerid the object is assigned to.
 * @param objectid  The ID of the player object that was moved.
 */
public OnPlayerObjectMoved(playerid, objectid)
{
    return 1;
}

/**
 * Called when a player picks up a pickup created with CreatePickup.
 *
 * @param playerid  The ID of the player that picked up the pickup.
 * @param pickupid  The ID of the pickup, returned by CreatePickup.
 *
 * @returns This callback does not handle returns.
 */
public OnPlayerPickUpPickup(playerid, pickupid)
{
    return 1;
}

/**
 * This callback is called when a vehicle is modded.
 *
 * @param playerid      The ID of the driver of the vehicle.
 * @param vehicleid     The ID of the vehicle which is modded.
 * @param componentid   The ID of the component which was added to the vehicle.
 *
 * @returns Return 0 to desync the mod (or an invalid mod) from propagating and / or crashing players.
 */
public OnVehicleMod(playerid, vehicleid, componentid)
{
    return 1;
}

/**
 * Called when a player changes the paintjob of their vehicle (in a modshop).
 *
 * @param playerid      The ID of the player that changed the paintjob of their vehicle.
 * @param vehicleid     The ID of the vehicle that had its paintjob changed.
 * @param paintjobid    The ID of the new paintjob.
 *
 * @returns This callback does not handle returns. Returning 0 won't deny the paintjob change.
 */
public OnVehiclePaintjob(playerid, vehicleid, paintjobid)
{
    return 1;
}

/**
 * The callback name is deceptive, this callback is called when a player exits a mod shop, regardless of whether the vehicle's colors were changed, and is NEVER called for pay 'n' spray garages.
 *
 * @param playerid  The ID of the player that is driving the vehicle.
 * @param vehicleid The ID of the vehicle that was resprayed.
 * @param color1    The color that the vehicle's primary color was changed to.
 * @param color2    The color that the vehicle's secondary color was changed to.
 *
 * @returns Returning 0 in this callback will deny the colour change. Returning 1 will allow it. This can be used to prevent hackers from changing vehicle colours using cheats.
 */
public OnVehicleRespray(playerid, vehicleid, color1, color2)
{
    return 1;
}

/**
 * This callback is called when a player selects an item from a menu (ShowMenuForPlayer).
 *
 * @param playerid  The ID of the player that selected a menu item.
 * @param row       The ID of the row that was selected. The first row is ID 0.
 *
 * @returns This callback does not handle returns.
 */
public OnPlayerSelectedMenuRow(playerid, row)
{
    return 1;
}

/**
 * Called when a player exits a menu.
 *
 * @param playerid  The ID of the player that exited the menu
 *
 * @returns This callback does not handle returns.
 */
public OnPlayerExitedMenu(playerid)
{
    return 1;
}

/**
 * Called when a player changes interior. Can be triggered by SetPlayerInterior or when a player enter/exits a building.
 *
 * @param playerid The playerid who changed interior.
 * @param newinteriorid   The interior the player is now in.
 * @param oldinteriorid   The interior the player was in before.
 *
 * @returns This callback does not handle returns.
 */
public OnPlayerInteriorChange(playerid, newinteriorid, oldinteriorid)
{
    return 1;
}

/**
 * This callback is called when the state of any supported key is changed (pressed/released). Directional keys do not trigger OnPlayerKeyStateChange (up/down/left/right).
 * See: https://wiki.sa-mp.com/wiki/Keys
 *
 * @param playerid The ID of the player that pressed or released a key.
 * @param newkeys A map (bitmask) of the keys currently held.
 * @param oldkeys A map (bitmask) of the keys held prior to the current change.
 */
public OnPlayerKeyStateChange(playerid, newkeys, oldkeys)
{
    return 1;
}

/**
 * This callback is called when someone attempts to log in to RCON in-game; successful or not.
 *
 * @param ip        The IP of the player that tried to log in to RCON.
 * @param password  The password used to login with.
 * @param success   0 if the password was incorrect or 1 if it was correct.
 *
 * @returns This callback does not handle returns.
 */
public OnRconLoginAttempt(ip[], password[], success)
{
    return 1;
}

/**
 * This callback is called everytime a client/player updates the server with their status.
 *
 * @param playerid  ID of the player sending an update packet.
 *
 * @returns 0 - Update from this player will not be replicated to other clients.
 *          1 - Indicates that this update can be processed normally and sent to other players.
 */
public OnPlayerUpdate(playerid)
{
    return 1;
}

/**
 * This callback is called when a player is streamed by some other player's client.
 *
 * @param playerid      The ID of the player who has been streamed.
 * @param forplayerid   The ID of the player that streamed the other player in.
 *
 * @returns This callback does not handle returns.
 */
public OnPlayerStreamIn(playerid, forplayerid)
{
    return 1;
}

/**
 * This callback is called when a player is streamed out from some other player's client.
 *
 * @param playerid      The player who has been destreamed.
 * @param forplayerid   The player who has destreamed the other player.
 *
 * @returns This callback does not handle returns.
 */
public OnPlayerStreamOut(playerid, forplayerid)
{
    return 1;
}

/**
 * Called when a vehicle is streamed to a player's client.
 *
 * @param vehicleid     The ID of the vehicle that streamed in for the player.
 * @param forplayerid   The ID of the player who the vehicle streamed in for.
 *
 * @returns This callback does not handle returns.
 */
public OnVehicleStreamIn(vehicleid, forplayerid)
{
    return 1;
}

/**
 * This callback is called when a vehicle is streamed out for a player's client (it's so far away that they can't see it).
 *
 * @param vehicleid     The ID of the vehicle that streamed out.
 * @param forplayerid   The ID of the player who is no longer streaming the vehicle.
 *
 * @returns This callback does not handle returns.
 */
public OnVehicleStreamOut(vehicleid, forplayerid)
{
    return 1;
}

/**
 * This callback is called when a player responds to a dialog shown using ShowPlayerDialog by either clicking a button, pressing ENTER/ESC or double-clicking a list item (if using a list style dialog).
 *
 * @param playerid  The ID of the player that responded to the dialog.
 * @param dialogid  The ID of the dialog the player responded to, assigned in ShowPlayerDialog.
 * @param response  1 for left button and 0 for right button (if only one button shown, always 1)
 * @param listitem  The ID of the list item selected by the player (starts at 0) (only if using a list style dialog).
 * @param inputtext The text entered into the input box by the player or the selected list item text.
 *
 * @returns Returning 0 in this callback will pass the dialog to another script in case no matching code were found in your gamemode's callback.
 */
public OnDialogResponse(playerid, dialogid, response, listitem, inputtext[])
{
    return 1;
}

/**
 * Called when a player double-clicks on a player on the scoreboard.
 *
 * @param playerid  The ID of the player that clicked on a player on the scoreboard.
 * @param clickedplayerid   The ID of the player that was clicked on.
 * @param source            The source of the player's click.
 *                          See: https://wiki.sa-mp.com/wiki/Click_Sources
 *
 * @returns This callback does not handle returns.
 */
public OnPlayerClickPlayer(playerid, clickedplayerid, source)
{
    return 1;
}