Setting up an MTA:SA server is the easy part; what actually makes it your server is the scripts you add. But adding a script is not just dropping a file into a folder and restarting. In MTA every script runs as a resource, and without the right folder structure, a valid meta.xml and the right permissions, the server will either never see your script or see it and refuse to run it. This guide walks through adding scripts to an MTA server from scratch, including how to debug it when nothing happens.
A standalone .lua file does nothing in MTA:SA. The server manages scripts in packages called resources. A resource is a folder that contains, at minimum, a meta.xml.
A typical resource folder looks like this:
Turkey (Türkçe)
Worldwide (English)
meta.xml — the resource's ID card: which script files load, which files are sent to the client, which functions are exported.server.lua — code that runs on the server.client.lua — code that runs on the player's machine.shared.lua, plus images, sounds, models and other assets.This split matters: server-side code is never sent to players, client-side code is. Putting sensitive logic on the client by accident is one of the most common security mistakes in MTA scripting.
If you do not have a server yet, it makes sense to follow our guide on how to set up an MTA:SA server step by step first.
If the extracted archive has a meta.xml at its root, that folder is the resource. Some archives ship several resources nested together; each one needs to sit in its own folder. Skim the code: if you see fetchRemote calls to unfamiliar addresses or pointlessly obfuscated blocks, do not use that script.
Copy the resource folder to:
server/mods/deathmatch/resources/
You can group resources into subfolders to stay organised, for example resources/[gamemodes]/ or resources/[custom]/. MTA treats folders in square brackets as categories and scans every resource inside them automatically. This is the most practical way to keep things manageable once you have dozens of scripts.
A minimal meta.xml looks like this:
The most common mistake is a filename that does not match what meta.xml declares. On Linux-based servers filenames are case sensitive: Client.lua and client.lua are not the same file.
To start the resource automatically at boot, add this line to mtaserver.conf:
If you are adding a gamemode, it is usually healthier to have it start after the other resources; order your entries accordingly.
You do not need to shut the server down. From the server console or in-game, use:
refresh — rescans for newly added resources. If you added a subfolder, use refreshall.start resource_name — starts the resource.restart resource_name — reloads it after you change the code.stop resource_name — stops it.If you see Starting resource_name in the console, you are done. Any errors will surface in the same place.
If your script "runs but does nothing", the problem is almost certainly permissions. In MTA, some functions — banning, kicking, editing the ACL, reading server settings — are only available to authorised resources.
You grant that by adding your resource to the relevant group in acl.xml. Admin panels and management scripts almost always want to be an object in the Admin group:
Run aclreload after the change. The golden rule here: never give admin rights to a resource that does not need them. An authorised resource that is malicious or sloppily written puts the entire server at risk.
Roleplay systems, account and inventory scripts usually want MySQL. When you add one:
.sql file that ships with the script into your database.root.Database load depends directly on disk performance, especially on busy roleplay servers. Turkey location VDS servers with NVMe M2 SSD storage and DDR5 RAM make a visible difference in these scenarios. If you are building roleplay infrastructure, our MTA roleplay server setup guide is a useful companion.
logs/server.log usually tell you the exact line that failed./debugscript 3 shows both client and server errors on screen.Once you can add a resource, writing your own is closer than you think. Create a folder, put two files in it, and work like this:
onPlayerJoin, onPlayerChat or onResourceStart with addEventHandler.addCommandHandler lets you define your own commands for players.restart after every change. Writing a large system in one go and only then testing makes bugs far harder to find.When resources need to share data, use the exports mechanism rather than copying the same code into two places.
onClientRender; the impact on ping and FPS is significant. We cover this in detail in our guide on lowering ping on your MTA server.As script count grows, the bottleneck usually appears in one of three places: single-core CPU performance, database disk access, or memory. The MTA server process is largely single-threaded, so a many-core CPU with a low clock speed will not deliver what you expect — high single-core performance matters more. To size memory against your player count, see our article on how much RAM an MTA server needs.
No. After placing the files, refresh and start are enough in most cases. A full restart is only needed when you edit core configuration files such as mtaserver.conf.
Check these in order: is the folder in the right directory, does it contain a meta.xml, does the folder name contain spaces or special characters, and did you run refreshall. Those four explain the vast majority of cases.
Scripts from well-known community sources are generally fine, but review anything before you add it. Stay away from packages of unknown origin that contain compiled Lua files — you cannot see what is inside them.
There is no technical limit; your hardware is the limit. Heavy roleplay systems run dozens of resources, and at that point single-core CPU performance and disk speed become the deciding factors.
Remove the resource you added last from mtaserver.conf and start the server. Then read the logs to find the error. If you have a backup, rolling back takes minutes — which is why taking one is step zero.
meta.xml, it is not recognised at all.server/mods/deathmatch/resources/ and are auto-started via mtaserver.conf.refresh, start and restart let you work without taking the server offline.acl.xml — and never given more rights than they need.server.log, and /debugscript 3.As your script load grows, hardware becomes the deciding factor. To run your project on a DDoS-protected network in an Istanbul location, on AMD Ryzen 9 9950X hardware with DDR5 RAM and NVMe M2 SSD storage, take a look at our MTA server plans and game server solutions, and contact our 24/7 support team for setup help.