qStore

qStore to rozbudowany sklep do Counter-Strike 2 oparty o CounterStrikeSharp. Plugin obsługuje walutę graczy, zakup i wyposażanie przedmiotów, transfer monet między graczami, webhooki, boosty punktów oraz publiczne API dla innych pluginów.

README opisuje używanie pluginu na serwerze: instalację, konfigurację i integrację. Nie opisuje kodu źródłowego.

Funkcje

• System waluty gracza zapisanej w bazie danych.
• Sklep z wieloma kategoriami przedmiotów.
• Zakup przedmiotów czasowych i permanentnych.
• Automatyczne wyposażanie po zakupie.
• Transfer waluty między graczami.
• Webhooki dla zakupów i sprzedaży.
• Boosty punktów zależne od permisji, nicku i liczby śmierci.
• Licencja oparta o LicenseKey oraz automatyczną walidację adresu serwera.
• Publiczne API qshop:api dla innych pluginów CounterStrikeSharp.

Zawartość sklepu

Domyślnie plugin zawiera konfiguracje sklepów dla:

• bulletsTracer
• clanTag
• colorSmoke
• coupon
• gravity
• hats
• health
• itemShop
• killEffects
• killerSound
• killFeeds
• mvpMusic
• nadeTails
• nameColor
• nickTag
• nickTagColor
• parachute
• pets
• playerModel
• playerModelColor
• playerTrail
• rankXp
• showDamage
• speed
• textColor
• textDrop
• weapons
• welcomeMsg

Każdy sklep jest trzymany jako osobny plik JSON w configs/Qesik/qShop/Shops/.

Instalacja

1. Wgraj paczkę do folderu csgo.
2. Skonfiguruj plugin.
3. Zrestartuj serwer bądź przeładuj plugin.

Pierwsza konfiguracja

Najważniejszy plik:

addons/counterstrikesharp/configs/Qesik/qShop/Main.json

Najważniejsze sekcje:

Database

Konfiguracja połączenia z bazą:

"Database": {
  "Hostname": "hostname",
  "Database": "database",
  "UserName": "username",
  "Password": "password"
}

Main

Podstawowe ustawienia działania pluginu:

"Main": {
  "MinPlayers": 2,
  "LicenseKey": "TOKEN",
  "RoundEndSum": true,
  "SaveDataTick": 240,
  "AutoEquipAfterBuy": false,
  "DatabaseLogs": false
}

Znaczenie pól:

• MinPlayers - minimalna liczba graczy potrzebna do naliczania systemu punktów.
• LicenseKey - klucz licencyjny pluginu. Bez poprawnego klucza plugin nie wystartuje.
• RoundEndSum - wyświetlanie podsumowania waluty po rundzie.
• SaveDataTick - co ile sekund zapisywać dane graczy do bazy.
• AutoEquipAfterBuy - czy przedmiot ma się automatycznie wyposażyć po zakupie.
• DatabaseLogs - czy zapisywać dodatkowe logi zakupów do bazy.

CustomMenu

Układ głównego menu sklepu. Możesz ustawić własne grupy i przypisać do nich konkretne shopKey.

AccountBalance

Ustawienia komend sprawdzania stanu konta:

"AccountBalance": {
  "enable": true,
  "commands": [ "css_stankonta", "css_currency", "css_waluta" ],
  "checkOtherBalance": true
}

• enable - włącza komendy stanu konta.
• commands - aliasy komend.
• checkOtherBalance - pozwala sprawdzać stan innych graczy po nazwie.

Transfer

Transfer waluty między graczami:

"Transfer": {
  "enable": true,
  "commands": [ "css_przelew", "css_transfer" ],
  "permission": null,
  "excludePermission": null,
  "fees": 0.05,
  "minValue": 10,
  "maxValue": 0,
  "log": false
}

• permission - wymagana permisja do używania transferu.
• excludePermission - permisja blokująca dostęp do transferu.
• fees - prowizja od przelewu.
• minValue - minimalna wartość transferu.
• maxValue - maksymalna wartość transferu; 0 oznacza brak limitu.
• log - zapis transferów do logów serwera.

PermissionBoost

Dodatkowy mnożnik punktów dla wybranych permisji.

NameBoost

Dodatkowy mnożnik punktów dla określonego tagu w nicku.

DeathBoost

Boost punktów zależny od liczby śmierci.

Webhooks

Webhooki Discord lub inne webhooki HTTP dla zakupów i sprzedaży.

Points

Pełna konfiguracja przyznawania waluty/punktów za:

• zabójstwa,
• headshoty,
• asysty,
• flash asysty,
• obrażenia,
• czas gry,
• MVP,
• cele rundy,
• topkę mapy,
• wybrane bronie.

Konfiguracja sklepów

Każdy sklep ma osobny plik w:

addons/counterstrikesharp/configs/Qesik/qShop/Shops/

W plikach sklepów definiujesz:

• czy sklep jest aktywny,
• listę przedmiotów,
• ceny,
• warianty czasowe,
• wymagane permisje,
• dane dodatkowe zależne od typu przedmiotu.

Jeżeli dany przedmiot lub sklep używa pola permission, gracz musi mieć odpowiednią permisję, aby z niego skorzystać.

Komendy gracza

• css_qshop
• css_store
• css_shop
• css_sklep

Otwiera główne menu sklepu lub konkretny sklep.

• css_szukaj
• css_qszukaj
• css_search
• css_qsearch

Wyszukuje przedmiot w sklepach.

• css_equip <shopKey> <itemKey>

Wyposaża przedmiot.

• komendy z AccountBalance.commands

Sprawdzają stan waluty.

• komendy z Transfer.commands

Wykonują przelew waluty do innego gracza.

Komendy administracyjne

• css_addcurrency <steamid64> <value> Permisja: @qshop/addcurrency

• css_setcurrency <steamid64> <value> Permisja: @qshop/setcurrency

• css_resetscurrency [steamid64] Permisja: @qshop/setcurrency

• css_qshop_refresh <steamid64> Permisja: @qshop/refresh

Uprawnienia

Najważniejsze permisje używane przez plugin:

• @qshop/addcurrency
• @qshop/setcurrency
• @qshop/refresh

Dodatkowo plugin może używać:

• permisji ustawionych przy konkretnych przedmiotach w plikach sklepów,
• permisji z sekcji Transfer.permission,
• blokady z Transfer.excludePermission,
• permisji z PermissionBoost.

API pluginu

Plugin rejestruje capability:

qshop:api

Interfejs:

public interface IShopAPI
{
    int GetPlayerCurrency(CCSPlayerController clientId);

    void SetPlayerCurrency(CCSPlayerController clientId, int value);

    int AddPlayerCurrency(CCSPlayerController clientId, int value, bool isBoost);

    bool PlayerHasItem(CCSPlayerController clientId, string shopKey, string itemKey);

    string? GetEquippedItem(CCSPlayerController clientId, string shopKey);

    bool EquipItem(CCSPlayerController clientId, string shopKey, string itemKey);

    bool UnequipItem(CCSPlayerController clientId, string shopKey);

    bool GiveItem(CCSPlayerController clientId, string shopKey, string itemKey);
}

Opis metod:

• GetPlayerCurrency - zwraca aktualną ilość waluty gracza.
• SetPlayerCurrency - ustawia dokładną ilość waluty.
• AddPlayerCurrency - dodaje walutę i zwraca końcową wartość. Parametr isBoost pozwala uwzględnić logikę boostów.
• PlayerHasItem - sprawdza, czy gracz posiada konkretny przedmiot.
• GetEquippedItem - zwraca aktualnie wyposażony itemKey w danym sklepie.
• EquipItem - oznacza przedmiot jako wyposażony.
• UnequipItem - zdejmuje aktualnie wyposażony przedmiot z danego sklepu.
• GiveItem - nadaje graczowi przedmiot permanentny.

Przykładowe użycie capability:

using CounterStrikeSharp.API.Core.Capabilities;
using qShopApi;

public static PluginCapability<IShopAPI> ShopCapability { get; } = new("qshop:api");

Licencja

Plugin korzysta z walidacji licencji przy starcie.

• klucz wpisujesz w Main.LicenseKey,
• adres serwera ip:port jest pobierany automatycznie,
• jeśli walidacja lub połączenie z licencją chwilowo nie działa, plugin próbuje ponownie,
• jeśli licencja jest niepoprawna, plugin nie zostanie uruchomiony.

Typowe problemy

Plugin nie startuje

Sprawdź:

• poprawność LicenseKey,
• poprawność danych bazy,
• czy serwer może połączyć się z MySQL,
• czy serwer ma poprawnie ustawione ip i hostport.

Gracze nie dostają waluty

Sprawdź:

• sekcję Points,
• MinPlayers,
• permisje z PermissionBoost,
• logikę pluginów zewnętrznych, jeśli modyfikują walutę przez API.

Transfer nie działa

Sprawdź:

• czy Transfer.enable jest ustawione na true,
• czy gracz ma wymaganą permisję,
• czy nie ma permisji z excludePermission,
• czy wartość transferu mieści się w limitach.

Wsparcie przy integracji

Jeżeli integrujesz qShop z innym pluginem, trzymaj się IShopAPI i capability qshop:api. To najbezpieczniejsza droga do:

• odczytu waluty,
• modyfikacji waluty,
• sprawdzania posiadanych przedmiotów,
• nadawania i wyposażania przedmiotów.