How to Add Lua Scripts to a CS2D Server (Admin, Modes, Maps)

To add a Lua script to a CS2D server, upload the script's folder into sys/lua, load it from sys/lua/server.lua with a dofile line (or drop it in sys/lua/autorun if the script says to), make sure mp_luaserver in sys/server.cfg is set to server.lua, then restart and read the console for errors. Map scripts are separate: they sit next to the map and load only when mp_luamap is 1.

How Lua works in CS2D

Lua is CS2D's modding system. Scripts run on the server only, so players never install anything. A script registers hooks, functions that CS2D calls when something happens (a player joins, says something in chat, dies, a round starts), and uses commands like msg, parse and player() to react.

That is how communities build admin menus, rank systems, shops, class mods, RPG servers and entire new modes on top of the base game. The Unreal Software file archive holds hundreds of these scripts, and many still work years after release because the Lua API has stayed stable.

The files involved

mp_luaserver defaults to server.lua. Setting it to an empty string turns server scripts off entirely, which is the first thing to check if nothing you add ever runs.

Step 1: Download and read the script

Get scripts from the Unreal Software file archive, where most CS2D scripts are published, or from the author's own page. Before uploading, open the archive and look for a readme. It tells you three things you need:

• Which folder it expects to live in (for example sys/lua/hc/).
• Whether you load it from server.lua or it belongs in autorun.
• Any settings file you should edit first, such as an admin list with U.S.G.N. or Steam IDs.

Keep the folder structure exactly as the author packed it. Most "file not found" errors come from an extra or missing folder level.

Step 2: Upload it

Copy the script into sys/lua on the server. On your own PC, that is the CS2D folder. On a hosted server, use the file manager or SFTP. Our SFTP guide covers connecting with a client like FileZilla. If the script came with sounds or images for players, check whether it also needs entries in sys/servertransfer.lst so players download them.

Step 3: Load it

Open sys/lua/server.lua and add a line for the script's main file:

dofile("sys/lua/hc/hc.lua")

Paths are relative to the CS2D folder. One dofile per script. If the readme says to use autorun, skip this and put the file in sys/lua/autorun/ instead. Do not do both, or the script loads twice and its hooks fire twice.

Then check sys/server.cfg:

mp_luaserver "server.lua"

Step 4: Restart and read the console

Restart the server. Lua problems show up in the console and log as lines starting with LUA ERROR, with the file and line number. A broken script can stop the scripts after it from loading, so one error can look like several scripts failing.

When you see one:

1. Note the file and line in the message.
2. Check the path in your dofile line matches the real location.
3. Check the script's own settings file for a typo, often a missing quote or comma.
4. If it is the script's own code, check its archive page for an update or a known fix.
5. Comment out the dofile line with -- to get the server running while you work on it.

The console command luareset clears all loaded scripts and hooks. Useful for testing, but a clean restart is the reliable way to reload.

A tiny script of your own

Writing a small script is a good way to learn what your downloads are doing. This one greets every player and adds a !rules chat command:

addhook("join", "gs_join")
function gs_join(id)
    msg2(id, "Welcome " .. player(id, "name") .. "! Type !rules")
end

addhook("say", "gs_say")
function gs_say(id, text)
    if text == "!rules" then
        msg2(id, "No spawn killing. No team flashing. Have fun.")
        return 1
    end
end

Save it as sys/lua/autorun/welcome.lua and restart. Returning 1 from the say hook hides the !rules message from chat. The full hook and command reference is on cs2d.com.

Admin scripts and RCon

Admin scripts usually identify admins by U.S.G.N. ID or Steam ID, not by name, since names are easy to fake. Two server settings help them work safely:

• sv_checkusgnlogin 1 (the default) verifies U.S.G.N. IDs before players join. Keep it on when a script trusts those IDs.
• sv_rconusers limits built in RCon to listed IDs, so you can use both a script's menus and RCon without exposing a password.

Do not paste RCon or admin passwords into scripts you share. Many old scripts store admin lists in plain text files under sys/lua, which is fine on your server but not in a public download.

Map scripts

A map can have its own script saved as maps/<mapname>.lua, for example maps/de_dust.lua. CS2D ignores these unless mp_luamap is 1, and the setting only takes effect on the next map load. Maps with trigger_if entities also need it on. Only enable it for maps you trust, since a map script runs with the same power as your own.

Running scripts on a hosted server

Lua scripts are the main reason people run their own CS2D server, and they need file access more than anything else. A hosted CS2D server on GamezServers gives you the file manager and SFTP straight into sys/lua, maps and sys/server.cfg, plus a live console where LUA ERROR lines show the moment you restart. One click backups let you save the working setup before trying a new script. If you have not set up the server yet, start with how to host a CS2D server.

FAQ

Where do Lua scripts go on a CS2D server?

In sys/lua. Load each one from sys/lua/server.lua with dofile, or put it in sys/lua/autorun if the script is built for that.

Why is my CS2D Lua script not loading?

Check that mp_luaserver is server.lua and not empty, that the dofile path matches the real file, and look for LUA ERROR lines in the console after a restart.

Do players need to download Lua scripts?

No. Scripts run on the server only. Players only download extra files the script lists for transfer, like sounds or images.

What does mp_luamap do?

It lets maps run their own maps/<mapname>.lua script. It is off by default and takes effect on the next map load.