# COD Matchmaking - Team Deathmatch for Minecraft

**Call of Duty-style Team Deathmatch in Minecraft**, powered by [TACZ (Timeless and Classics Guns)](https://www.curseforge.com/minecraft/mc-mods/timeless-and-classics-zero) for realistic gunplay.

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 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`:

|---------|---------|-------|-------------|

| `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.

[TACZ] CallOfDuty Matchmaking