# ILLUSION SQL GAG SYSTEM v1.2

**Author:** illusion @ CodeStrike.STORE
**Plugin:** AMX Mod X for Counter-Strike 1.6

---

## 🎯 OVERVIEW

Advanced MySQL-based gag system with strong anti-bypass protection, high performance on full servers, and full configuration control.

---

## ✨ FEATURES

- **Gag Types**: Chat, Voice, or Both
- **Flexible Duration**: Minutes-based or permanent gags
- **Custom Reasons**: Fully configurable via INI file, plus custom reasons typed in-game
- **Bad Word Filter**: Automatic gagging for forbidden words (whole-word detection), with admin bypass flag
- **Logging System**: Detailed logs of all gag events
- **Anti-Bypass**: Gags are matched by SteamID **and** IP – reconnecting or changing name doesn't help
- **Non-Steam Safe**: Shared IDs like `STEAM_ID_LAN` / `VALVE_ID_LAN` are matched by IP only, so non-steam players never share one gag
- **Round-Based Sync**: Automatically detects gag changes (add/edit/remove) from the database (e.g. from a website)
- **Direct Command Interface**: Quick gagging with `amx_gag` – only the player name is required
- **Server Console / RCON Support**: All admin commands work from the server console and rcon
- **HUD Notifications**: Real-time gag status display with countdown timer
- **Sound Effects**: Configurable sounds for gag events
- **Professional Menus**: Colored admin interface
- **Admin Immunity**: Flag-based protection system
- **Progressive Punishments**: Repeat offenders automatically get longer gags
- **Cyrillic / UTF-8 Support**: Names and reasons in any language are stored correctly

---

## 📋 REQUIREMENTS

- AMX Mod X **1.9 or newer**
- **ReAPI**
- **CromChat**
- **MySQL** module enabled (`mysql` in `modules.ini`)
- MySQL / MariaDB database

---

## 🚀 INSTALLATION

1. Upload `ILLUSION_GagSystem.amxx` to `addons/amxmodx/plugins/`
2. Add `ILLUSION_GagSystem.amxx` to `plugins.ini`
3. Upload the sound files to `sound/gagsystem/` (`mute.wav`, `unmute.wav`) – or leave the sound paths empty in the config
4. Create a MySQL database
5. Start the server once – `configs/gagsystem.ini` is created automatically
6. Edit `configs/gagsystem.ini` with your database settings
7. Restart the server

The database tables are created automatically.

### ⬆️ Updating from v1.1

1. **Back up your database first** – existing tables are converted to UTF-8 automatically
2. Replace the `.amxx` file
3. Optional: add the new `BYPASS_ACCESS` option to `[Bad Words]` (see below). If it's missing, it defaults to `ADMIN_SLAY`
4. Optional: remove `VOICE_BLOCKING_DELAY` from `[Tasks]` – it's no longer used

Your existing config keeps working – no other changes are required.

---

## ⚙️ CONFIGURATION

Auto-generates `gagsystem.ini` with sections:

- **Database**: MySQL connection settings
- **Menu**: Interface customization
- **Chat**: Chat message prefix
- **Reasons**: Gag reasons list
- **Times**: Duration options
- **GagTypes**: Chat/Voice/Both options
- **HUD**: Position and timing of HUD messages
- **Tasks**: Timing of background checks
- **Access**: Admin permission levels
- **Bad Words**: Auto-gag filter
- **Limits**: Maximum number of reasons/times/bad words to load
- **Logs**: Event logging configuration (`LOGS_ENABLED = 1`, `LOGS_FILE = gagsystem.log`)
- **Sounds**: Audio effects
- **Checks**: Round-based database sync
- **Progressive**: Repeat offender multiplier
- **Countdown**: HUD timer for gagged players

### Bad Words filter

```ini
[Bad Words]
ENABLED = 1
; Gag duration in minutes (0 = permanent)
GAG_TIME = 5
; 0 = Chat, 1 = Voice, 2 = Both
GAG_TYPE = 0
; Admins with this flag are not checked by the filter (leave empty = nobody bypasses)
BYPASS_ACCESS = ADMIN_SLAY
WORD_1 = example
```

`BYPASS_ACCESS` accepts a flag name (`ADMIN_SLAY`, `ADMIN_KICK`, ...) or flag letters (e.g. `e`).

### Progressive punishment

```ini
[Progressive]
ENABLED = 1
MULTIPLIER = 1.5
MAX_MULTIPLIER = 5
```

Every previous gag multiplies the duration by `MULTIPLIER`, up to `MAX_MULTIPLIER` times the original.
Example: a 10 minute gag becomes 15 min on the 2nd gag, 23 min on the 3rd ... up to 50 min. Permanent gags are not affected.

---

## 🎮 COMMANDS

### Admin commands

- `amx_gagmenu` – Opens the interactive gag menu (in-game only)
- `amx_gag <user> [minutes] [reason] [type]` – Direct gag command
- Only the player name is required. Defaults: **30 minutes**, reason **"Not specified"**, type **Chat + Voice**
- The reason can contain spaces without quotes
- **Examples**:
```
amx_gag John
amx_gag John 60
amx_gag John 60 spamming in chat
amx_gag John 60 spam 0
amx_gag John 0 advertising 2
```
- **Minutes**: `0` = permanent
- **Types** (last argument):
- `0` = Chat Only
- `1` = Voice Only
- `2` = Chat + Voice
- `amx_ungag <player>` – Removes a player's gag
- `amx_gaginfo <player>` – Shows gag details for a player (SteamID, IP, type, admin, reason, time left)
- `amx_gaglist` – Lists all active gags from the database
- `amx_cleangags` – Removes all gags

All admin commands also work from the **server console** and **rcon**.

### Player commands

- `/gagstatus` or `/mygag` – Shows your gag status and remaining time

---

## 🛡️ SECURITY

- **Dual Identification**: SteamID + IP matching – reconnecting doesn't remove a gag
- **Non-Steam Protection**: LAN IDs are never used for matching, so players can't be gagged by mistake
- **Async SQL Queries**: Gagging and checks run in the background – no server freezes, even with a remote database
- **SQL Injection Protection**: All user input is escaped
- **Exploit Protection**: Menu and custom reason input are admin-only, all input is validated
- **Round-Based Sync**: Auto-sync all gag changes from the database
- **Auto-Detection**: Detects new, edited, or removed gags
- **Real-Time Updates**: Syncs reason, time, and type automatically
- **No Reconnect Required**: Changes apply automatically next round

---

## 📝 LOG FORMAT

```
L MM/DD/YYYY - HH:MM:SS: Admin X gagged player Y for Z minutes with reason 'ABC' (Type: Chat)
L MM/DD/YYYY - HH:MM:SS: Admin X permanently gagged player Y with reason 'ABC' (Type: Chat)
L MM/DD/YYYY - HH:MM:SS: Admin X ungagged player Y
L MM/DD/YYYY - HH:MM:SS: Gag expired for player Y (Type: Voice)
L MM/DD/YYYY - HH:MM:SS: SYSTEM automatically gagged player Y for Z minutes (0 = permanent) with reason 'Swearing (badword)' (Type: Both)
L MM/DD/YYYY - HH:MM:SS: Gag validation failed for player Y - gag was manually removed from database
L MM/DD/YYYY - HH:MM:SS: Gag details updated for player Y - Admin: X, Reason: ABC, Type: 0
```

---

## 🆕 LATEST UPDATE (v1.2)

### 🐞 Bug Fixes
- Fixed a security issue that allowed regular players to open the gag menu
- Gagged players now see all chat messages (plugin messages sent to them were being blocked)
- Microphone is now properly restored when a Chat + Voice gag expires
- Non-steam players (`STEAM_ID_LAN`, `VALVE_ID_LAN`) no longer share the same gag
- Progressive punishment now actually works (it never increased the duration before)
- Permanent gags now always take priority over temporary ones
- Gags can no longer be applied to the wrong player if someone reconnects into the same slot
- Invalid values in `amx_gag` (e.g. `abc` as minutes) no longer result in a permanent gag
- Two admins gagging the same player at once no longer overwrite each other's reason
- `GAG_TIME = 0` in the bad words filter now means permanent (it expired instantly before)
- Server console commands no longer broadcast their output to all players
- Permanent gag HUD now shows the real gag type
- Fixed crashes caused by invalid gag types in the database or config

### 🚀 New Features
- `amx_gag` now only requires the player name – minutes, reason and type are optional
- Reasons in `amx_gag` can contain spaces without quotes
- All admin commands now reply in the console (and work from server console / rcon)
- Added `BYPASS_ACCESS` option – admins with this flag skip the bad words filter
- Full Cyrillic / UTF-8 support for names and reasons
- Gag history table for progressive punishment

### ⚙️ Optimizations
- **1 database query per round instead of up to 64** (round sync for all players at once)
- Gagging no longer blocks the server while waiting for the database
- `amx_gaglist` no longer blocks the server when used in-game
- Database indexes added for fast lookups (created automatically)
- Config file is read once instead of once per setting
- Anti-spam for the "you are gagged" message
- Automatic database reconnect if the connection is lost
- Removed unnecessary tasks and dead code

---

## 🕘 PREVIOUS UPDATE (v1.1)

### 🐞 Bug Fixes
- Fixed admin flag (immunity) detection
- Fixed server freezes caused by SQL queries (now async)
- Fixed duplicate punishments on reconnect
- Fixed bad word filter (now matches whole words only)
- Fixed SQL injection vulnerabilities
- Fixed admin menu issues with many players
- Fixed punishment storage reliability in database
- Removed unnecessary/legacy code

### 🚀 New Features
- Added admin immunity system (flag-based)
- Added progressive punishment timer
- Added `/gagstatus` player command
- Added `amx_gaginfo` admin command
- Added HUD timer for gagged players
- Improved configuration system (more options, easier setup)

---

## 📞 CONTACT

illusion @ CodeStrike.STORE