# COD Matchmaking - Team Deathmatch for Minecraft
Create arenas, set up spawn points, register weapons with unlock levels, and let players fight in fast-paced Red vs Blue matches — complete with a progression system, custom loadouts, a weapon catalog, and map voting.
---
## Features
### Matchmaking & Game Flow
- **Map Browser** — Browse all available maps with live player count, match status, and timer before joining
- **Auto-join** — `/play` drops you into the best available match instantly
- **Team auto-balance** — Players are automatically assigned to Red or Blue teams
- **Match lifecycle** — WAITING → COUNTDOWN → PLAYING → ENDED → MAP VOTE, fully automated
- **Map voting** — After each match, players vote for the next map
- **Mid-game join** — Players can join matches already in progress and receive their loadout immediately
### Weapon & Attachment System
- **Full TACZ integration** — All TACZ guns, attachments, and throwables are supported
- **Auto-scan** — One command (`/tdm weapon scan`) discovers every TACZ weapon and attachment on your server
- **6 attachment types** — Scope, Muzzle, Stock, Grip, Laser, Extended Mag
- **Weapon categories** — Primary, Secondary, Grenade, Armor, Items
- **Weapon Catalog GUI** — Players can browse all weapons/attachments with detailed stats (damage, RPM, ammo, headshot multiplier, armor pierce, fire modes, attachment modifiers)
- **Compatibility check** — Only compatible attachments are shown per weapon (uses TACZ tag matching)
### Progression System
- **XP on kill** — Earn XP for every kill, with bonus XP for headshots
- **Level 1–60** — Unlock weapons and attachments as you level up
- **Persistent stats** — Kills, deaths, headshots, and level are saved per player across sessions
- **XP HUD popup** — On-screen notification when you earn XP or level up
### Custom Loadouts
- **10 loadout slots per player** — Create and save personal loadouts
- **Full loadout editor GUI** — Pick your primary, secondary, grenade, attachments, armor, and extra items
- **Attachment selection** — Visual attachment picker filtered by weapon compatibility
- **Level-gated** — Weapons and attachments require the right level to equip
- **Creative ammo box** — Automatically included so you never run out of ammo
### Admin Loadouts (per-map)
- **Map-specific loadouts** — Create pre-made loadouts tied to specific maps
- **GUI editor** — Visual loadout manager for admins
- **Up to 20 loadouts per map** (configurable)
- **Loadout selection screen** — Players choose from available loadouts before spawning
### In-Game HUD
- **Live scoreboard** — Red vs Blue score, kill limit, and match timer always visible
- **TAB overlay** — Custom player list showing team, kills, and deaths
- **Team indicators** — Clear visual team identification
- **In-game buttons** — LOADOUT and WEAPONS buttons accessible during gameplay
### Combat Features
- **Friendly fire prevention** — No team damage
- **Respawn invincibility** — Configurable invincibility frames after respawn (default 3 seconds)
- **Headshot detection** — Integrated with TACZ headshot system
- **Kill tracking** — Accurate kill/death attribution with death deduplication
---
## Commands
### Player Commands
| Command | Description |
|---------|-------------|
| `/play` | Quick-join the best available match |
| `/play <map>` | Join a specific map |
| `/tdm join [map]` | Join a match (same as `/play`) |
| `/tdm leave` | Leave your current match |
| `/tdm list` | List all maps with status, players, and settings |
| `/tdm weapons` | Open the weapon catalog GUI |
### Admin Commands (Permission Level 2)
#### Map Management
| Command | Description |
|---------|-------------|
| `/tdm create <map>` | Create a new map |
| `/tdm delete <map>` | Delete a map |
| `/tdm setspawn <map> <red\|blue>` | Add a spawn point for a team at your position |
| `/tdm setobj <map> <killLimit>` | Set the kill limit (1–1000) |
| `/tdm settimer <map> <seconds>` | Set match duration (30–3600s) |
| `/tdm setminplayers <map> <count>` | Set minimum players to start (1–64) |
| `/tdm setlobby` | Set the lobby teleport point at your position |
| `/tdm start [map]` | Force-start a match |
| `/tdm stop [map]` | Force-stop a match |
#### Loadout Management
| Command | Description |
|---------|-------------|
| `/tdm loadout` | Open the loadout admin GUI |
| `/tdm loadout create <map> <name>` | Create a loadout for a map |
| `/tdm loadout delete <map> <name>` | Delete a loadout |
| `/tdm loadout setitem <map> <name> <slot>` | Set hotbar item (slot 0–8) from held item |
| `/tdm loadout setarmor <map> <name> <head\|chest\|legs\|feet>` | Set armor piece from held item |
| `/tdm loadout setoffhand <map> <name>` | Set offhand item from held item |
| `/tdm loadout list <map>` | List all loadouts for a map |
#### Weapon & Attachment Registry
| Command | Description |
|---------|-------------|
| `/tdm weapon editor` | Open the weapon editor GUI |
| `/tdm weapon scan` | Auto-discover all TACZ weapons and attachments |
| `/tdm weapon add hand <category> <level>` | Register held item as weapon |
| `/tdm weapon add <id> <category> <level> [name]` | Register weapon by ID |
| `/tdm weapon remove <id>` | Unregister a weapon |
| `/tdm weapon setlevel <id> <level>` | Set weapon unlock level (0–60) |
| `/tdm weapon list [category]` | List registered weapons |
| `/tdm weapon attachment add hand <level>` | Register held attachment |
| `/tdm weapon attachment add <id> <type> <level> [name]` | Register attachment by ID |
| `/tdm weapon attachment remove <id>` | Unregister an attachment |
| `/tdm weapon attachment setlevel <id> <level>` | Set attachment unlock level |
| `/tdm weapon attachment list` | List registered attachments |
**Weapon categories:** `primary`, `secondary`, `grenade`, `armor`, `items`
**Attachment types:** `SCOPE`, `MUZZLE`, `STOCK`, `GRIP`, `LASER`, `EXTENDED_MAG`
---
## Quick Start Guide
### 1. Install
- Install **Minecraft Forge 1.20.1** (47.2.20+)
- Install **TACZ** (Timeless and Classics Guns)
- Drop `codmatchmaking.jar` into your `mods/` folder
### 2. Create a Map
```
/tdm create MyArena
/tdm setspawn MyArena red (stand where red team should spawn, repeat for more spawns)
/tdm setspawn MyArena blue (stand where blue team should spawn, repeat for more spawns)
/tdm setobj MyArena 75 (75 kills to win)
/tdm settimer MyArena 600 (10 minute timer)
/tdm setlobby (set lobby return point)
```
### 3. Register Weapons
```
/tdm weapon scan (auto-imports all TACZ weapons & attachments)
```
Or manually:
```
/tdm weapon add hand primary 1 (hold a gun and register it as a primary, unlock level 1)
```
### 4. Set Unlock Levels
```
/tdm weapon setlevel tacz:ak47 5
/tdm weapon attachment setlevel tacz:red_dot_sight 3
```
Or use the GUI: `/tdm weapon editor`
### 5. Play!
```
/play MyArena
```
Players will see the **Map Browser**, pick a map, choose a loadout, and fight!
---
## Configuration
All settings are in `config/codmatchmaking-common.toml`:
| Setting | Default | Range | Description |
|---------|---------|-------|-------------|
| `defaultKillLimit` | 75 | 1–1000 | Default kill limit for new maps |
| `defaultTimerSeconds` | 600 | 30–3600 | Default match duration (seconds) |
| `defaultMinPlayers` | 2 | 1–64 | Minimum players to start |
| `defaultMaxPlayers` | 64 | 2–128 | Maximum players per match |
| `countdownSeconds` | 10 | 3–60 | Pre-match countdown |
| `respawnInvincibilityTicks` | 60 | 0–200 | Invincibility after respawn (ticks) |
| `endDelayTicks` | 200 | 40–600 | Delay before match reset (ticks) |
| `voteDurationSeconds` | 15 | 5–60 | Map vote phase duration |
| `maxLoadoutsPerMap` | 20 | 1–50 | Max admin loadouts per map |
| `xpPerKill` | 100 | 1–10000 | XP earned per kill |
| `xpHeadshotBonus` | 25 | 0–5000 | Bonus XP for headshots |
| `maxLevel` | 60 | 1–200 | Maximum player level |
| `maxCustomLoadouts` | 10 | 1–20 | Custom loadout slots per player |
---
## Requirements
- **Minecraft** 1.20.1
- **Forge** 47.2.20+
- **TACZ** (Timeless and Classics Guns) — Required
---
## Addon Compatibility
Supports TACZ addon packs (e.g. LesRaisins weapon packs). Throwables and melee weapons from addons are detected automatically via `/tdm weapon scan`.
---
## Data Storage
All data is stored in your world's `worlddata/` folder:
- **Maps** — JSON config per map
- **Weapons & Attachments** — Weapon registry JSON
- **Player Progression** — Per-player JSON (level, XP, stats)
- **Player Loadouts** — Per-player JSON (custom loadout slots)
No external database required. Everything persists across server restarts.
