Opracowanie modułu React mini-gry "Szczęśliwy Bilet" dla Telegram Mini App (WebSocket, TypeScript)

Opracowanie modułu gry w React “Lucky Ticket” dla Telegram Mini App (WebSocket, TypeScript)

1. Ogólny opis projektu
   Zadanie: Opracować część kliencką (frontend) wieloosobowej mini-gry “Lucky Ticket” (Szczęśliwy bilet).
   Środowisko: Moduł jest wbudowywany w istniejącą aplikację Telegram Mini App.
   Stos technologiczny:

• Główna logika i renderowanie gry: React.

• Język: TypeScript.

• Interakcja z backendem: WebSocket (głównie) + REST API (dodatkowo, w razie potrzeby).

2. Architektura i zakres odpowiedzialności (Ważne!)
   Aplikacja wykorzystuje hybrydowe podejście.
   NIE wchodzi w zakres zadań wykonawcy (już zrealizowane w aplikacji):

• Górny pasek (liczniki walut, menu hamburgerowe).

• Dolne menu nawigacyjne (Sklep, Zadania, Ptaki...).

• Ogólna inicjalizacja Telegram WebApp, autoryzacja użytkownika.

Wchodzi w zakres zadań wykonawcy:

1. Realizacja modułu gry w React, który jest montowany w dostarczonym kontenerze HTML w centralnej części ekranu.

2. Realizacja całej wewnętrznej logiki gry: siatka biletów, zakładki pokoi, animacja losowania, wewnętrzne popupy (Zasady, Historia).

3. Responsywne formatowanie zawartości Canvas, aby poprawnie wypełniał wyznaczoną przestrzeń na różnych urządzeniach, zachowując proporcje projektu.

4. Podłączenie do backendu gry przez WebSocket w celu uzyskania stanów i wysyłania działań gracza.

3. Rozgrywka i stany UI
   Cały UI gry musi ściśle odpowiadać dostarczonemu szablonowi w Figma (link zostanie dostarczony wykonawcy).

3.1. Stan 1: Aktywny runda (Zbieranie uczestników)
Główny ekran, na którym gracze kupują bilety.

• Zakładki pokoi (Bet Tiers): Przełączniki “1k”, “5k”, “10k”.

  • Przy przełączaniu zmienia się aktywny pokój, aktualizuje się cena biletu, pula nagród i stan siatki.

• Blok informacyjny:

  • Aktualna pula nagród (Current Prize Pool) — aktualizowana w czasie rzeczywistym.

  • Cena biletu w aktualnym pokoju.

• Siatka biletów (20 komórek):

  • Wolny bilet: Ikona biletu. Klikalny. Po kliknięciu przechodzi w stan “Wybrany”.

  • Wybrany bilet: Nieco przyciemniony i mniejszy (jak w Figma).

  • Zajęty bilet (Obcy): Wyświetlana jest zatyczka awatara innego gracza. Nieklikalny.

  • Zajęty bilet (Własny): Wyświetlany jest awatar aktualnego użytkownika (dane awatara mają być przekazywane do modułu przy inicjalizacji). Nieklikalny.

• Przycisk akcji (Kup):

  • Zawsze szary (jak w Figma).

  • Jeśli bilety są wybrane i wystarczają fundusze: aktywny (pomarańczowy), wyświetla całkowitą kwotę zakupu. Po naciśnięciu wysyła zapytanie o zakup.

  • Jeśli wybrane, ale brakuje funduszy: nieaktywny, na górze wyświetla się komunikat “Nie masz wystarczająco srebra”.

• Timer: Odliczanie czasu do automatycznego rozpoczęcia losowania (HH:MM).

3.2. Stan 2: Losowanie (Spinning)
Przejście do tego stanu inicjowane jest zdarzeniem z backendu (czas minął LUB wszystkie 20 biletów zostało sprzedanych).

• Blokada: Siatka biletów i przycisk zakupu są blokowane/przyciemniane.

• Animacja spinera: Na siatce pojawia się panel z trzema “slotami”. W slotach uruchamiana jest szybka animacja przewijania awatarów uczestników aktualnej rundy (efekt maszyny do gier).

• Określenie zwycięzców:

  • Backend wysyła listę trzech zwycięzców.

  • Sloty zatrzymują się jednocześnie: 1. miejsce, 2. i 3., pokazując awatar, imię zwycięzcy oraz kwotę wygranej.

• Zakończenie: Po pokazaniu wszystkich wyników gra automatycznie wraca do Stanu 1 (nowa runda) po kilku sekundach.

3.3. Dodatkowe elementy (wewnątrz Pixi)

• Pasek “5 Ostatnich gier”: Tabela na dole ekranu. Dane pochodzą z backendu przy inicjalizacji i są aktualizowane po każdym losowaniu.

• Popup “Info” (Zasady): Otwierany za pomocą przycisku (?). Modalne okno wewnątrz Canvas, które nakłada się na grę. Statyczny tekst.

• Popup “Historia” (Moje gry): Modalne okno z tabelą historii osobistych gier użytkownika i paginacją. Dane są ładowane z backendu.

4. Interakcja z backendem (Data Flow)
   Moduł ma być “cienkim klientem”. Cała logika walidacji, obliczania wygranych i timerów znajduje się na serwerze. Połączenie przez WebSocket.

5. Wymagania dotyczące realizacji

6. Grafika i zasoby:

   • Wszystkie elementy wizualne należy pobierać ściśle z Figma.

   • Używać atlasów tekstur (sprite sheets) dla optymalizacji.

7. Animacje: Zrealizować płynne animacje (spinner, otwieranie popupów, podświetlanie przycisków).

8. Optymalizacja: Gra powinna działać płynnie na urządzeniach mobilnych średniej klasy. Należy monitorować zużycie pamięci, unikać wycieków przy przełączaniu pokoi.

9. Typizacja: Ścisłe użycie TypeScript, typizacja wszystkich danych wejściowych i wyjściowych API.