PySAMP Save
Create SA-MP gamemodes with Python
PySAMP
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/.
Getting Started
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 correct python version
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.
Make a python module
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.
Add PySAMP's API
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).
Server.cfg
- Add
PySAMP.dllto yourserver.cfgon thepluginsline. - Add an (empty) gamemode to the
gamemodesline. For example, usebarewhich 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
Run using docker
Requirements
- 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.
How to get started?
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
/dockerfolder 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 *.shinside the/dockerfolder. - 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/datawill appear.
Default actions and notes
-
If there are no existing
/docker/datadirectory, 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/udpinstead of-p 7777:7777/udp. -
if the
/docker/datadirectory 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 dochmodcommand 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.pyto your server root directory, renamed aspython.py - Copy
pysampfolder/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.
Community
Join us over at Discord! You can join the discussion or even ask for help/support.
Documentation
Documentation is generated using sphinx. Link to WIP documentation for v2.1 (temporary): https://pysamp.github.io/PySAMP/
Thanks to
Open Source Agenda Badge
