Getting started with Server

Run your own Alt:SA dedicated server and join it.

Introduction#

This tutorial shows you how to run your own Alt:SA server and join it. You don't need to write any code for this part; that starts in Getting started with Development.

The dedicated server is the same engine as the game, running without graphics or a local player. Players connect to it on TCP port 7777. The launcher and websites read its status on TCP port 7780.

Requirements#

  • Windows 10 or 11, 64-bit, with about 4 GB of free memory.
  • Your own copy of the classic PC GTA San Andreas on the server machine. The server reads the map and collision from it, just like the game does.
  • The Alt:SA server: the package once released, or your own build (Tools/build-server.sh in the engine repo, which makes Build/Alt-SA-Server/Alt-SA-Server.exe).
  • TCP ports 7777 and 7780 open for players on other machines.

Set up the server#

Get the server files#

  1. Extract the server package to a folder you own, for example C:\altsa-server. It contains Alt-SA-Server.exe, server.json, start-server.cmd, and empty plugins and data folders.
  2. If you built the server yourself, use the Build/Alt-SA-Server folder. The first start writes a server.json with the defaults.

Point it at your game#

Open server.json and set your game folder and the server name:

JSON
1{2  "name": "My first Alt:SA server",3  "port": 7777,4  "queryPort": 7780,5  "maxPlayers": 50,6  "gameMode": "",7  "gtaDir": "C:/Games/GTA San Andreas"8}
KeyWhat it does
nameThe name players see in the launcher's server list.
gtaDirYour classic GTA San Andreas folder, with gta_sa.exe and models/gta3.img in it. Use forward slashes.
portThe TCP port players connect to.
queryPortThe TCP port of the status endpoint. 0 turns it off.
maxPlayersHow many players can be connected at once.
gameModeThe gamemode to run. Leave it empty for freeroam until Godfather gamemodes ship.

Start the server#

Run start-server.cmd, or from a terminal:

PowerShell
1.\Alt-SA-Server.exe -batchmode -nographics -dedicated

When it prints [Alt-SA][Server] listening on port 7777, players can connect. Loading the map takes about a minute; after that the status endpoint reports "ready": true.

If the server stops right away, the exit code tells you why:

Exit codeMeaning
2server.json is invalid. The log line says which key.
3The game port is already in use, often by another server.
4The GTA San Andreas folder in gtaDir is missing or isn't a classic PC install.

Check the status#

Open http://127.0.0.1:7780/status in a browser. You get the server's name, gamemode, player count, player names and whether it's ready:

JSON
1{ "name": "My first Alt:SA server", "gamemode": "Freeroam", "players": 0, "maxPlayers": 50, "online": true, "ready": true }

The launcher's server list reads this endpoint and times the request as the ping.

Join your server#

Start the Alt:SA game, open Join game, and connect to 127.0.0.1 on port 7777.

Next step#

Your server is running, but a gamemode decides what happens in it. Continue with Getting started with Development to write your first one in C#.

See also#