Using PySAMP with your SA-MP server allows you to create gamemodes with the python language. All API-functions, callbacks and constants except http functions can be accessed in python.
In case of the call-by-reference functions like GetPlayerName
are returning the value instead of using a reference, since call-by-reference isn't possible in python.
The following example shows the difference.
public OnPlayerConnect(playerid)
{
new name[MAX_PLAYER_NAME], string[MAX_PLAYER_NAME + 24];
GetPlayerName(playerid, name, MAX_PLAYER_NAME);
format(string, sizeof(string), "%s has joined the server.", name);
SendClientMessageToAll(0xFFFFFFFF, string);
}
from pysamp.player import Player
from pysamp import (
send_client_message_to_all
)
@Player.on_connect
def when_player_connects(player: Player):
name = player.get_name()
send_client_message_to_all(0xFFFFFFFF, f'{name} has joined the server.')
As you can see, all referenced return values are removed and instead the method returns either a value or a tuple.
The corresponding python gamemode has to be saved as python.py
module or a python/
package of your server directory. For a more complete python gamemode example, please check /gamemodes/grandlarc/
.
There are three different ways to install the plugin depending on your system. Recommended are the first two ways:
Windows
Using PySAMP on a Windows machine is possible! Just make sure you have 32-bit Python and the correct version that the plugin requires.
Install the correct version (written in the DLL name you downloaded). As of PySAMP 2.1.0
, this should be python version 3.10.4
. 64-bit or any other version will not work, and the plugin will not load.
The plugin will look for a module named python
in your server root. That means you can either create python.py
or python/__init__.py
.
In order to work with our v2.1 API, you need to copy the folder pysamp
to your server root directory. It includes snake_case versions of the default SA-MP functions, and classes for various objects such as Player
, Vehicle
, TextDraw
and so on. If you created a python
folder in last step, you should now have the normal SA-MP server folders, plus the two new ones (python and pysamp).
- Add
PySAMP.dll
to yourserver.cfg
on theplugins
line. - Add an (empty) gamemode to the
gamemodes
line. For example, usebare
which is a default, empty gamemode. Please note that this is not mandatory and you should be able to run both a pawn and a python gamemode alongside each other just fine. However if you start from scratch, we strongly recommend you to not mix, as it gives you much better control over your gamemode.
Using docker
- Docker 20.10.0 or greater. Previous versions may work, but they are not tested. Read more here how to install docker on your specific Linux Distribution.
- Your user needs to be added to the docker group, so you don't have to run as sudo.
With our docker setup, you can run your entire SA-MP server inside a docker container. Under /docker/data
you will find a 0.3.7 server root folder as you would recognise it. Our docker setup builds the container, builds the PySAMP plugin, and afterwards uses the /docker/data
directory to start up a SA-MP server for you.
- If you haven't already, please clone the latest main branch of the repository. You can clone the repository to your server using
git clone https://github.com/habecker/PySAMP.git
- Proceed to the
/docker
folder inside the repo, here you can find the docker-related files. Inspect the files if you need to know what they do in detail. - Next up, let us make the bash-scripts executable by running
chmod +x *.sh
inside the/docker
folder. - Inside the same folder (
/docker
), run the SA-MP server by running./run.sh
, and gently wait for the process to complete. This will build the docker container and start your server./docker/data
will appear.
-
If there are no existing
/docker/data
directory, it will be created. SA-MP server version 0.3.7-R2-1 will be downloaded and installed. -
If there is no .amx gamemode in
/docker/data/gamemodes
, the docker container will put one there to get the server started. If you have defined a different gamemode in/docker/data/server.cfg
, the default .amx file will not be loaded, but instead the one you defined will. -
The Crashdetect plugin is added automatically, unless it already exists.
-
Server starts at port 7777 and it is exposed at port 7777. If you change the port in the
/docker/data/server.cfg
, you will also need to change the docker arguments in/docker/run.sh
. For example, if you want to run on port 8888, the last line should contain-p 8888:8888/udp
instead of-p 7777:7777/udp
. -
if the
/docker/data
directory gives you "permission denied" on linux when you try to edit something, it is because the docker image runs with root, and the files are not accessible for the host user. You can dochmod
command on the folder to change the permissions to be more open, so that you can edit things in it.
Manual Installation (Linux)
- Install the python version as written in the name of the file on the releases page. This should be version 3.10.4 as of PySAMP 2.1. (32 bit version is required, and it needs to be on $PATH)
- Copy the downloaded PySAMP.so to the plugins directory of your server. (If it has a weird name, just rename it to PySAMP.so)
- Copy
/docker/server/empty.py
to your server root directory, renamed aspython.py
- Copy
pysamp
folder/module to your server root directory. - Run the server and verify that the plugin has loaded in your logs. If not, make sure step 1-4. is done correctly. You need exact versions of python.
Join us over at Discord! You can join the discussion or even ask for help/support.
Documentation is generated using sphinx. Link to WIP documentation for v2.1 (temporary): https://pysamp.github.io/PySAMP/