# ILLUSION SQL GAG SYSTEM v1.2

**Autor:** illusion @ CodeStrike.STORE
**Wtyczka:** AMX Mod X do gry Counter-Strike 1.6

---

## 🎯 PRZEGLĄD

Zaawansowany system blokad oparty na MySQL, charakteryzujący się silną ochroną przed obejściem, wysoką wydajnością na obciążonych serwerach oraz pełną kontrolą nad konfiguracją.

---

## ✨ CECHY

- **Rodzaje gagów**: czat, głos lub jedno i drugie
- **Elastyczny czas trwania**: kneble na minuty lub na stałe
- **Powody niestandardowe**: w pełni konfigurowalne za pomocą pliku INI oraz poprzez wpisywanie własnych powodów w grze
- **Filtr nieodpowiednich słów**: automatyczne blokowanie słów zabronionych (wykrywanie całych słów) z opcją obejścia przez administratora
- **System rejestracji**: Szczegółowe zapisy wszystkich zdarzeń związanych z blokadą
- **Zabezpieczenie przed obejściem**: Kakuły są kojarzone na podstawie SteamID **i** adresu IP – ponowne połączenie się czy zmiana nazwy nic tu nie pomogą
- **Nieobsługiwane przez Steam**: wspólne identyfikatory, takie jak `STEAM_ID_LAN`/ , `VALVE_ID_LAN`są dopasowywane wyłącznie na podstawie adresu IP, więc gracze spoza platformy Steam nigdy nie dzielą się tym samym gagiem
- **Synchronizacja oparta na rundach**: automatycznie wykrywa zmiany dotyczące gagów (dodawanie/edycja/usuwanie) w bazie danych (np. ze strony internetowej)
- **Interfejs poleceń bezpośrednich**: Szybkie zakneblowanie za pomocą `amx_gag`– wystarczy podać nazwę gracza
- **Obsługa konsoli serwera / RCON**: Wszystkie polecenia administracyjne działają zarówno z poziomu konsoli serwera, jak i RCON
- **Powiadomienia HUD**: Wyświetlanie stanu blokady w czasie rzeczywistym wraz z licznikiem czasu
- **Efekty dźwiękowe**: Konfigurowalne dźwięki towarzyszące sytuacjom komicznym
- **Profesjonalne menu**: Kolorowy interfejs administracyjny
- **Odporność administratora**: system ochrony oparty na flagach
- **Stopniowe kary**: osoby, które popełniają wykroczenia wielokrotnie, automatycznie otrzymują dłuższe kneble
- **Obsługa cyrylicy / UTF-8**: Nazwy i przyczyny w dowolnym języku są zapisywane poprawnie

---

## 📋 WYMAGANIA

- AMX Mod X w wersji 1**.9 lub nowszej**
- **ReAPI**
- **CromChat**
- Moduł **MySQL** włączony (`mysql`włączony`modules.ini`)
- Baza danych MySQL / MariaDB

---

## 🚀 INSTALACJA

1. Prześlij `ILLUSION_GagSystem.amxx`do `addons/amxmodx/plugins/`
2. Dodaj do`ILLUSION_GagSystem.amxx` `plugins.ini`
3. Prześlij pliki dźwiękowe do `sound/gagsystem/`(`mute.wav`, `unmute.wav`) – lub pozostaw ścieżki do plików dźwiękowych puste w pliku konfiguracyjnym
4. Utwórz bazę danych MySQL
5. Uruchom serwer raz – `configs/gagsystem.ini`zostanie utworzony automatycznie
6. Edytuj `configs/gagsystem.ini`z wykorzystaniem ustawień bazy danych
7. Uruchom ponownie serwer

Tabele bazy danych są tworzone automatycznie.

### ⬆️ Aktualizacja z wersji 1.1

1. **Najpierw wykonaj kopię zapasową bazy danych** – istniejące tabele zostaną automatycznie przekonwertowane do formatu UTF-8
2. Zastąp plik`.amxx`
3. Opcjonalnie: dodaj nową opcję`BYPASS_ACCESS` do (`[Bad Words]`patrz poniżej). Jeśli jej brakuje, domyślną wartością jest `ADMIN_SLAY`
4. Opcjonalnie: usuń `VOICE_BLOCKING_DELAY`z `[Tasks]`– nie jest już używane

Obecna konfiguracja nadal działa – nie trzeba wprowadzać żadnych innych zmian.

---

## ⚙️ KONFIGURACJA

Automatycznie generuje się z`gagsystem.ini` następującymi sekcjami:

- **Baza danych**: ustawienia połączenia z MySQL
- **Menu**: Dostosowywanie interfejsu
- **Czat**: Prefiks wiadomości na czacie
- **Powody**: Lista powodów związanych z gagami
- **Times**: Opcje czasu trwania
- **Rodzaje komunikacji**: Czat / Głos / Obie opcje
- **HUD**: Położenie i czas wyświetlania komunikatów HUD
- **Zadania**: Harmonogram sprawdzania przeszłości
- **Dostęp**: Poziomy uprawnień administratora
- **Wulgarne słowa**: Filtr automatycznie blokujący wulgarne słowa
- **Ograniczenia**: Maksymalna liczba powodów/wystąpień/wulgarnych słów do załadowania
- **Dzienniki**: Konfiguracja rejestrowania zdarzeń (`LOGS_ENABLED = 1`, `LOGS_FILE = gagsystem.log`)
- **Dźwięki**: Efekty dźwiękowe
- **Kontrole**: Synchronizacja bazy danych w cyklach
- **Progresywny**: Współczynnik dla recydywistów
- **Odliczanie**: licznik czasu HUD dla graczy z zakneblowanymi ustami

### Filtr nieodpowiednich słów

```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` przyjmuje nazwy flag (`ADMIN_SLAY`, `ADMIN_KICK`, ...) lub litery flag (np. `e`).

### Kary o rosnącej surości

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

Każdy poprzedni gag wydłuża czas trwania o `MULTIPLIER`, maksymalnie do razy`MAX_MULTIPLIER` w stosunku do pierwotnego czasu.
Przykład: 10-minutowa blokada wydłuża się do 15 minut przy drugiej blokadzie, do 23 minut przy trzeciej… aż do 50 minut. Nie ma to wpływu na blokady stałe.

---

## 🎮 POLECENIA

### Polecenia administracyjne

- `amx_gagmenu` – Otwiera interaktywne menu żartów (tylko w grze)
- `amx_gag <user> [minutes] [reason] [type]` – Bezpośrednie polecenie blokujące
- Wymagane jest jedynie podanie nazwy gracza. Ustawienia domyślne: **30 minut**, powód **„Nie określono”**, typ: **Czat + Głos**
- Powód może zawierać spacje bez cudzysłowów
- **Przykłady**:
```
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
```
- **Protokół**: `0`= stały
- **Typy** (ostatni argument):
- `0` = Tylko czat
- `1` = Tylko głos
- `2` = Czat + Głos
- `amx_ungag <player>` – Zdejmuje graczowi knebel
- `amx_gaginfo <player>` – Wyświetla szczegóły blokady gracza (SteamID, adres IP, typ, administrator, powód, pozostały czas)
- `amx_gaglist` – Wyświetla listę wszystkich aktywnych gagów z bazy danych
- `amx_cleangags` – Usuwa wszystkie kneble

Wszystkie polecenia administracyjne działają również z **konsoli** **serwera** oraz za pośrednictwem **rcon**.

### Polecenia dla gracza

- `/gagstatus` lub `/mygag`– Wyświetla status Twojego gag’a oraz pozostały czas

---

## 🛡️ BEZPIECZEŃSTWO

- **Podwójna identyfikacja**: SteamID + dopasowanie adresu IP – ponowne połączenie nie powoduje usunięcia blokady
- **Ochrona przed użytkownikami spoza platformy Steam**: identyfikatory LAN nie są nigdy wykorzystywane do dobierania graczy, dzięki czemu gracze nie mogą zostać przypadkowo zablokowani
- **Asynchroniczne zapytania SQL**: operacje i kontrole przebiegają w tle – serwer nie zawiesza się, nawet w przypadku zdalnej bazy danych
- **Ochrona przed atakami typu SQL injection**: Wszystkie dane wprowadzane przez użytkownika są poddawane eskapowaniu
- **Ochrona przed nadużyciami**: Dostęp do menu i wprowadzanie własnych powodów mają wyłącznie administratorzy; wszystkie dane są sprawdzane pod kątem poprawności
- **Synchronizacja oparta na rundach**: Automatyczna synchronizacja wszystkich zmian gagów z bazy danych
- **Automatyczne wykrywanie**: wykrywa nowe, zmienione lub usunięte żarty
- **Aktualizacje w czasie rzeczywistym**: automatyczna synchronizacja przyczyny, godziny i typu
- **Nie trzeba ponownie łączyć się z grą**: zmiany zostaną zastosowane automatycznie w następnej rundzie

---

## 📝 FORMAT DZIENNIKA

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

---

## 🆕 NAJNOWSZA AKTUALIZACJA (wersja 1.2)

### 🐞 Poprawki błędów
- Naprawiono lukę w zabezpieczeniach, która pozwalała zwykłym graczom na otwarcie menu żartów
- Gracze z zakneblowanymi ustami widzą teraz wszystkie wiadomości na czacie (wiadomości z wtyczek wysyłane do nich były wcześniej blokowane)
- Mikrofon jest teraz prawidłowo przywracany po wygaśnięciu blokady funkcji „Czat + Głos”
- Gracze spoza platformy Steam (`STEAM_ID_LAN`, `VALVE_ID_LAN`) nie mają już tego samego żartu
- Kary progresywne teraz faktycznie działają (wcześniej nigdy nie wydłużały czasu trwania)
- Stałe ograniczenia mają teraz zawsze pierwszeństwo przed tymczasowymi
- Jeśli ktoś ponownie połączy się z tym samym slotem, nie będzie już można nałożyć knebla na niewłaściwego gracza
- Nieprawidłowe wartości w `amx_gag`(np. `abc`w minutach) nie powodują już trwałego zablokowania
- Gdy dwóch administratorów jednocześnie nakłada cenzurę na tego samego gracza, ich uzasadnienia nie zastępują się już nawzajem
- `GAG_TIME = 0` w filtrze nieodpowiednich słów oznacza to teraz „na stałe” (wcześniej wygasało natychmiast)
- Polecenia konsoli serwera nie są już przekazywane wszystkim graczom
- Stały pasek informacyjny „knebel” wyświetla teraz rzeczywisty rodzaj knebla
- Naprawiono awarie spowodowane nieprawidłowymi typami gagów w bazie danych lub pliku konfiguracyjnym

### 🚀 Nowe funkcje
- `amx_gag` teraz wystarczy podać tylko nazwę gracza – liczba minut, powód i typ są opcjonalne
- Wypowiedzi w mogą`amx_gag` zawierać spacje bez cudzysłowów
- Wszystkie polecenia administracyjne wyświetlają teraz komunikaty w konsoli (i działają z poziomu konsoli serwera / rcon)
- Dodano opcję`BYPASS_ACCESS` – administratorzy z tą opcją omijają filtr słów nieodpowiednich
- Pełna obsługa cyrylicy i standardu UTF-8 w przypadku nazw i uzasadnień
- Tabela historii gagów w ramach stopniowego zwiększania surowości kary

### ⚙️ Optymalizacje
- **1 zapytanie do bazy danych na rundę zamiast maksymalnie 64** (synchronizacja rundy dla wszystkich graczy jednocześnie)
- Mechanizm ograniczania przepustowości nie blokuje już serwera podczas oczekiwania na odpowiedź z bazy danych
- `amx_gaglist` nie powoduje już zawieszenia serwera podczas korzystania z niego w grze
- Dodano indeksy bazy danych w celu przyspieszenia wyszukiwania (utworzone automatycznie)
- Plik konfiguracyjny jest odczytywany tylko raz, a nie osobno dla każdego ustawienia
- Ochrona przed spamem dla komunikatu „masz zakneblowane usta”
- Automatyczne ponowne nawiązanie połączenia z bazą danych w przypadku utraty połączenia
- Usunięto zbędne zadania i nieużywany kod

---

## 🕘 POPRZEDNIA AKTUALIZACJA (wersja 1.1)

### 🐞 Poprawki błędów
- Naprawiono wykrywanie flagi administratora (immunitetu)
- Naprawiono zawieszanie się serwera spowodowane zapytaniami SQL (teraz przetwarzane asynchronicznie)
- Naprawiono problem z podwójnymi karami przy ponownym połączeniu
- Naprawiono działanie filtra nieodpowiednich słów (teraz uwzględnia wyłącznie całe słowa)
- Usunięto luki związane z wstrzyknięciem kodu SQL
- Naprawiono problemy z menu administratora występujące u wielu graczy
- Zapewniono niezawodność przechowywania informacji o karach w bazie danych
- Usunięto zbędny/przestarzały kod

### 🚀 Nowe funkcje
- Dodano system immunitetu administratora (oparty na flagach)
- Dodano licznik czasu dla kar o rosnącej surowości
- Dodano polecenie dla gracza`/gagstatus`
- Dodano polecenie administracyjne`amx_gaginfo`
- Dodano licznik czasu na HUDzie dla graczy z zakneblowanymi ustami
- Ulepszony system konfiguracji (więcej opcji, łatwiejsza konfiguracja)

---

## 📞 KONTAKT

illusion @ CodeStrike.STORE