How to Install MatchZy on a CS2 Server (Matches and Practice)

To install MatchZy on a CS2 server, first install Metamod:Source and CounterStrikeSharp (v369 or newer), then extract the MatchZy release zip into game/csgo/ so you get addons/counterstrikesharp/plugins/MatchZy/ and cfg/MatchZy/. Restart and check css_plugins list. Add your SteamID64 to cfg/MatchZy/admins.json. Players type .ready to start a match, admins use .prac for practice mode. When you update MatchZy later, keep your edited cfg/MatchZy files, because the release overwrites them.

What you are working with

MatchZy comes in two downloads on its GitHub releases page: plain MatchZy, and a bundle with CounterStrikeSharp included. Use the bundle on a fresh server, the plain one if CounterStrikeSharp is already installed.

Before you start

• Install Metamod first. It needs Game csgo/addons/metamod under Game_LowViolence csgo_lv in game/csgo/gameinfo.gi. Our CounterStrikeSharp guide walks through it.
• Check the CounterStrikeSharp version. The MatchZy install docs ask for CounterStrikeSharp v369 or newer, which uses the .NET 10 runtime. Use the with runtime package.
• Match the operating system. Linux packages for a Linux server, Windows packages for Windows.
• Stop the server while you upload.

Step 1: Upload MatchZy

1. Download the latest MatchZy release.
2. Unzip it. It contains addons and cfg.
3. Upload both into game/csgo/, merging with the existing folders.
4. Start the server and run meta list, then css_plugins list. MatchZy should be in the second list.

If MatchZy is missing, the usual cause is an older CounterStrikeSharp or a folder uploaded one level too deep (csgo/csgo/addons).

Step 2: Make yourself admin

MatchZy accepts admins in two ways. The simplest is its own file, cfg/MatchZy/admins.json, created on first load. Add your SteamID64 with an empty value for full access:

{
  "76561198000000000": ""
}

CounterStrikeSharp admins with @css/root in addons/counterstrikesharp/configs/admins.json also count. Run .reload_admins in chat or restart after editing.

Step 3: Set your defaults

Open cfg/MatchZy/config.cfg. It runs every time the plugin loads. The convars worth knowing, with their defaults:

Round settings for the live match itself (round time, overtime, money) live in cfg/MatchZy/live.cfg.

Step 4: Run a match

The quick way for a scrim:

1. Everyone joins. The server sits in warmup.
2. Each player types .ready. When enough are ready, the knife round starts.
3. The knife winners type .stay or .switch.
4. The match goes live with live.cfg.

Useful commands during a match: .pause and .unpause, .tech for a technical pause, .stop to restore the round. Admins have .start to force start, .restart, .endmatch, .forcepause, .map de_inferno and .readyrequired. Commands also work with ! instead of ..

Step 5: Load a match config for a series

For a best of three or a league night, write a JSON file and load it from the console. It needs maplist, team1, team2 and num_maps:

{
  "matchid": 27,
  "team1": { "name": "Team A", "players": { "76561198000000001": "Alice" } },
  "team2": { "name": "Team B", "players": { "76561198000000002": "Bob" } },
  "num_maps": 3,
  "maplist": ["de_mirage", "de_inferno", "de_ancient"],
  "map_sides": ["team1_ct", "team2_ct", "knife"],
  "players_per_team": 5,
  "clinch_series": true
}

Save it in game/csgo/ and run matchzy_loadmatch mymatch.json, or host it online and use matchzy_loadmatch_url "https://...". Players are placed by SteamID64, and players not listed in the config are not let in, so double check every ID.

Step 6: Practice mode

An admin types .prac to switch the server into practice mode, and .exitprac to go back. Players then get .bot, .crouchbot, .spawn 1, .rethrow, .last, .noflash, .god, .clear, .ff to fast forward smokes, and .savenade and .loadnade to keep lineups between sessions. Practice settings come from cfg/MatchZy/prac.cfg. If you only want practice and no match flow, see our plain CS2 practice server config.

The gotcha: updates overwrite your configs

Updating MatchZy is the step that quietly undoes your setup. The release zip contains the whole cfg/MatchZy folder, so extracting a new version over the old one replaces config.cfg, live.cfg and prac.cfg with the stock files. Your ready count drops back to 2, your knife setting resets and your custom round rules vanish, while the server starts with no error at all. The MatchZy docs confirm only the files it generates (admins.json, whitelist.cfg, database.json, savednades.json) survive.

The fix: before updating, download your cfg/MatchZy folder. Then upload only the new addons folder, including the new gamedata/matchzy.json, or re-apply your edits after extracting. Valve updates add a second trap: they can rewrite gameinfo.gi and drop the Metamod line, which unloads MatchZy completely. Run meta list after every CS2 patch.

Common problems

• Chat commands do nothing: MatchZy is not loaded. Check meta list and css_plugins list, and see CS2 Metamod not loading after update.
• Match starts with only two players ready: matchzy_minimum_ready_required is still 2.
• .rethrow fails in practice mode: the matchzy.json gamedata file is outdated. Upload it from the latest release.
• A player cannot join a loaded match: their SteamID64 is missing or mistyped in the match config.
• Admin commands refused: your SteamID64 is not in either admins file, or you have not run .reload_admins.

MatchZy on GamezServers

A GamezServers CS2 server starts in competitive mode with the server token made for you. Upload Metamod, CounterStrikeSharp and MatchZy in the Files tab, which extracts zips, or over the SFTP login in Settings, then edit gameinfo.gi and cfg/MatchZy right in the browser. Press Backup before updating plugins so your configs are one click away. The server updates CS2 on every restart, so run meta list after Valve patches.

FAQ

Does MatchZy need CounterStrikeSharp?

Yes. MatchZy is a CounterStrikeSharp plugin, so Metamod:Source and CounterStrikeSharp v369 or newer come first, unless you use the release bundled with CounterStrikeSharp.

How do I start a match with MatchZy?

Every player types .ready in chat. Once matchzy_minimum_ready_required players are ready, the knife round and then the live match start. Admins can force it with .start.

How do I turn on practice mode in MatchZy?

An admin types .prac in chat. Type .exitprac to return to match mode.

Why did my MatchZy settings reset after an update?

The release zip includes the cfg/MatchZy folder and replaces your edited config files. Back them up and restore them after each update.