# Wtyczka „Advanced Advertisements”

**Wersja:** 1.0
**Autor:** illusion @ CodeStrike.STORE
**Nazwa wtyczki:** Zaawansowane reklamy

## Opis

AdvertsNEW to wtyczka AMX Mod X przeznaczona dla serwerów Counter-Strike, która wyświetla graczom konfigurowalne, zmieniające się reklamy za pomocą komunikatów HUD oraz kolorowych wiadomości na czacie. Wtyczka obsługuje wiele trybów wyświetlania, losowe kolory (HUD) oraz różne efekty wizualne, pozwalające tworzyć przyciągające uwagę ogłoszenia serwerowe.

## Funkcje

- ✅ **Reklamy wyświetlane na zmianę**: Wyświetlanie wielu reklam po kolei lub w losowej kolejności
- ✅ **Reklamy HUD**: Wyświetla reklamy za pomocą kolorowych komunikatów HUD na ekranie
- ✅ **Reklamy na czacie**: wyświetla reklamy na czacie (obsługuje kolorowe tagi)
- ✅ **Polecenia czatu (wyzwalacze)**: Zdefiniuj je w`key = message` pliku INI i uruchom je, wpisując odpowiedni klucz na czacie
- ✅ **Losowe kolory (HUD)**: Każda reklama wyświetlana w interfejsie HUD ma losowo generowane kolory
- ✅ **Możliwość dostosowania położenia**: Skonfiguruj położenie komunikatów HUD w osiach X i Y
- ✅ **Efekty wizualne**: liczne efekty pojawiania się i zanikania oraz tryby wyświetlania
- ✅ **Symbole zastępcze**: Obsługa i`%map%` (`%servername%`HUD + czat)
- ✅ **Wielowierszowe komunikaty HUD**: Obsługa (`%newline%`tylko HUD)
- ✅ **Aktualizacja na żywo**: Aktualizacja konfiguracji bez konieczności ponownego uruchamiania serwera
- ✅ **Automatyczne tworzenie konfiguracji**: automatycznie tworzy domyślną konfigurację, jeśli jej brakuje

## Instalacja

1. **Skompiluj wtyczkę:**

```bash
amxxpc AdvertsNEW.sma
```

2. **Prześlij pliki:**

- Umieść w`AdvertsNEW.amxx` `/addons/amxmodx/plugins/`
- Dodaj do`AdvertsNEW.amxx` `/addons/amxmodx/configs/plugins.ini`

3. **Konfiguracja:**
- Wtyczka automatycznie utworzy `/addons/amxmodx/configs/adverts.ini`
- Edytuj ten plik, aby dodać własne reklamy

## Plik konfiguracyjny

**Plik:** `/addons/amxmodx/configs/adverts.ini`

### Format:

```ini
; Adverts Configuration File
; Lines starting with ; are comments and will be ignored
; Placeholders: %map% (current map), %servername% (hostname)
; Chat colors: !g = green, !t = team color, !n = normal

[HUD]
Welcome to %servername%!
Current map: %map%
Line 1%newline%Line 2 of same HUD advert

[CHAT]
!g[Info] !nWelcome to !t%servername%
!g[Map] !nCurrent map: !t%map%
discord = !g[Discord] !nJoin our Discord: !thttps://discord.gg/yourserver
```

### Symbole zastępcze i tagi:

- `%map%` - Zastąpiono aktualną nazwą mapy
- `%servername%` - Zastąpiono nazwą hosta serwera (`hostname`cvar)
- `%newline%` - Wstawia znak końca linii w komunikacie HUD (tylko w HUD)
- `!g` / /`!t` `!n`– Kolorowe znaczniki w czacie (tylko w czacie)
- Wiersze zaczynające się od lub`;` `/`są traktowane jako komentarze

### Działanie INI (ważne):

- Wiersze poniżej `[HUD]`są traktowane jako reklamy w interfejsie HUD.
- W sekcji`[CHAT]`:
- Wiersz **bez** `=`jest traktowany jako cykliczna reklama na czacie.
- Wiersz **zawierający** `key = message`jest zapisywany jako wyzwalacz polecenia czatu.
- Słowo kluczowe jest uznawane za dopasowane, jeśli pojawia się **w dowolnym miejscu wiadomości** (obsługiwane są wiadomości składające się z wielu słów).
- `/key` akceptowane są również przedrostki`!key`.
- Jeśli gracz wpisze **tylko** słowo kluczowe (np. lub`discord` `/discord`), jego wiadomość zostanie ukryta, a wyświetlona zostanie wyłącznie odpowiedź wtyczki.
- Jeśli słowo kluczowe pojawia się w dłuższej wiadomości (np. `how to join discord server?`), wiadomość gracza pozostaje widoczna, a odpowiedź wtyczki jest również wyświetlana.

## CVars (zmienne konsoli)

| CVar | Domyślnie | Opis |
| ---------------------- | ------- | ---------------------------------------------- |
| `amx_adverts_enabled` | `1` | Włącz/wyłącz system reklamowy |
| `amx_adverts_interval` | `60.0` | Odstęp czasowy między reklamami (w sekundach) |
| `amx_adverts_random` | `0` | Kolejność losowa (1) lub sekwencyjna (0) |
| `amx_adverts_effect` | `2` | Typ efektu komunikatu HUD (0–3) |
| `amx_adverts_holdtime` | `5.0` | Jak długo ma być wyświetlana każda reklama |
| `amx_adverts_fadein` | `0.1` | Czas trwania pojawiania się (w sekundach) |
| `amx_adverts_fadeout` | `0.2` | Czas wyciszenia (w sekundach) |
| `amx_adverts_x` | `-1.0` | Pozycja X (-1,0 = środek) |
| `amx_adverts_y` | `0.2` | Pozycja Y (0,0 = góra, 1,0 = dół) |

### Wartości CVAR w reklamach czatowych:

| CVar | Domyślnie | Opis |
| --------------------------- | ------- | ---------------------------------------------- |
| `amx_adverts_chat_enabled` | `1` | Włącz/wyłącz cykliczne reklamy na czacie |
| `amx_adverts_chat_interval` | `60.0` | Odstęp czasowy między reklamami na czacie (w sekundach) |
| `amx_adverts_chat_random` | `0` | Kolejność losowa (1) lub sekwencyjna (0) |

### CVAR-y poleceń czatu:

| CVar | Domyślnie | Opis |
| ------------------------------ | ------- | ----------------------------------------------- |
| `amx_adverts_chatcmd_enabled` | `1` | Włączanie/wyłączanie wyzwalaczy poleceń czatu |
| `amx_adverts_chatcmd_to_all` | `0` | 0 = pokaż tylko nadawcy, 1 = pokaż wszystkim |
| `amx_adverts_chatcmd_cooldown` | `5.0` | Czas odnowienia (w sekundach) na gracza dla wyzwalaczy czatu |

### Rodzaje efektów:

- `0` - Brak efektu
- `1` - Stopniowe pojawianie się/zanikanie
- `2` - Efekt błysku/stroboskopowy
- `3` - Efekt rozpisania

## Polecenia administracyjne

| Polecenie | Poziom dostępu | Opis |
| ------------------- | ------------ | --------------------------------------------------- |
| `amx_reloadadverts` | `ADMIN_CVAR` | Ponownie ładuje konfigurację reklam bez konieczności ponownego uruchamiania |

## Przykłady zastosowań

### Konfiguracja podstawowa:

```ini
[HUD]
Welcome to %servername%!
Visit our website: www.yoursite.com
Current map: %map%
Join our Discord: discord.gg/yourserver
Type !shop to open the store

[CHAT]
!g[Info] !nWelcome to !t%servername%
discord = !g[Discord] !nJoin our Discord: !thttps://discord.gg/yourserver
```

### Reklama wielowierszowa:

```ini
[HUD]
=== SERVER RULES ===%newline%1. No cheating%newline%2. No spam%newline%3. Have fun!
```

### Treści dynamiczne:

```ini
You are playing on: %map%
Server time: Check !time command
```

## Szczegóły techniczne

- **Wymagane biblioteki:** amxmodx, amxmisc, reapi, reapi_stocks
- **Maksymalna liczba ogłoszeń:** 32
- **Maksymalna długość wiadomości:** 192 znaki
- **Pamięć oparta na tablicach:** Wykorzystuje dynamiczne tablice w celu efektywnego zarządzania pamięcią
- **System kolorów:** losowe wartości RGB generowane dla każdego wyświetlacza

## Wskazówki dotyczące konfiguracji

1. **Ustawienia pozycji:**

- X: `-1.0`wyrównanie poziome, `0.0`= po lewej, `1.0`= po prawej
- Y: `0.0`= górna krawędź ekranu, `1.0`= dolna krawędź ekranu

2. **Zalecenia dotyczące terminów:**

- Odstęp: 30–120 sekund (unikaj spamowania)
- Czas wyświetlania: 3–8 sekund (czas, przez który napis jest czytelny)
- Czas wygaszania: 0,1–0,5 sekundy (płynne przejścia)

3. **Wytyczne dotyczące wiadomości:**
- Wiadomości powinny być zwięzłe i jasne
- Używaj tego z umiarem`%newline%`, aby uniknąć bałaganu
- Wypróbuj różne rodzaje efektów, aby uzyskać najlepszą widoczność

## Rozwiązywanie problemów

**Reklamy się nie wyświetlają?**

- Opcja „Sprawdź” `amx_adverts_enabled`jest ustawiona na `1`
- Opcja „Sprawdź” `amx_adverts_chat_enabled`jest włączona `1`dla reklam w czacie
- Sprawdź, czy plik konfiguracyjny istnieje i czy zawiera prawidłową treść
- Upewnij się, że w pliku konfiguracyjnym znajduje się co najmniej jeden wiersz, który nie jest komentarzem

**Problemy z pozycją?**

- Dostosuj wartości`amx_adverts_y` i`amx_adverts_x`
- Przetestuj przy różnych rozdzielczościach ekranu

**Obawy dotyczące wydajności?**

- Jeśli serwer ma opóźnienia, wydłuż czas między kolejnymi próbami
- Zmniejsz liczbę reklam, jeśli zużycie pamięci jest wysokie

## Pomoc techniczna

W razie problemów lub pytań:

- Autor: illusion @ CodeStrike.STORE
- Zapoznaj się z dokumentacją AMX Mod X, aby poznać ograniczenia dotyczące komunikatów wyświetlanych na HUD-zie
- Sprawdź, czy instalacja ReAPI działa poprawnie

---

**Uwaga:** Ta wtyczka wymaga biblioteki ReAPI do korzystania z zaawansowanych funkcji komunikatów HUD. Upewnij się, że biblioteka ReAPI jest poprawnie zainstalowana i skonfigurowana na serwerze Counter-Strike.