chore: Add some more docs idc

projektdokumentation/Inhalt.tex

@@ -6,5 +6,7 @@
 \input{Inhalt/Dice.tex}
 \input{Inhalt/Slots.tex}
 \input{Inhalt/Coinflip.tex}
+\input{Inhalt/Blackjack.tex}
+\input{Inhalt/Lootboxes.tex}
 
 \input{Inhalt/Deployment.tex}

projektdokumentation/Inhalt/Blackjack.tex

@@ -0,0 +1,52 @@
+\section{Blackjack}
+
+\subsection{Was ist Blackjack?}
+Blackjack ist eines der populärsten Kartenspiele in Casinos weltweit und wurde als vollständiges Spiel in die Casino-Plattform integriert. Das Ziel des Spiels ist es, mit den eigenen Karten einen Wert von 21 zu erreichen oder näher an 21 heranzukommen als der Dealer, ohne dabei über 21 zu gehen (Bust). Das Spiel kombiniert Strategie und Glück, da Spieler Entscheidungen über ihre Spielzüge treffen müssen, während sie gegen einen automatisierten Dealer antreten.
+
+Die Implementierung folgt den klassischen Blackjack-Regeln: Zahlenkarten haben ihren Nennwert, Bildkarten (König, Dame, Bube) zählen 10 Punkte, und Asse können je nach Situation als 1 oder 11 gewertet werden. Ein "Blackjack" (21 mit den ersten beiden Karten) zahlt mit einem Bonus von 1,5x des Einsatzes aus, während reguläre Gewinne den doppelten Einsatz zurückgeben.
+
+\subsubsection{Kartensystem und Deck-Verwaltung}
+Das Blackjack-System verwendet ein vollständiges 52-Karten-Deck mit vier Farben (Herz, Karo, Kreuz, Pik) und 13 Rängen (2-10, Bube, Dame, König, Ass). Die Karten werden in der Datenbank als separate Entitäten gespeichert, wobei jede Karte einem Typ zugeordnet ist: DECK (noch im Stapel), PLAYER (Spielerhand) oder DEALER (Dealerhand).
+
+Die DeckService-Klasse verwaltet die Kartenerstellung und -verteilung. Bei Spielbeginn wird ein neues, gemischtes Deck erstellt und die Karten werden entsprechend den Spielregeln verteilt: Der Spieler erhält zwei Karten, der Dealer erhält eine Karte. Die Zufallsmischung erfolgt über java.util.Random, um eine faire Kartenverteilung zu gewährleisten.
+
+\subsubsection{Spielzustände und Ablauf}
+Das Spiel durchläuft verschiedene definierte Zustände:
+\begin{itemize}
+    \item \textbf{IN\_PROGRESS:} Das Spiel läuft aktiv, der Spieler kann Aktionen ausführen
+    \item \textbf{PLAYER\_BLACKJACK:} Der Spieler hat einen natürlichen Blackjack (21 mit zwei Karten)
+    \item \textbf{PLAYER\_WON:} Der Spieler hat gewonnen ohne Blackjack
+    \item \textbf{PLAYER\_LOST:} Der Spieler hat verloren oder sich überkauft
+    \item \textbf{DRAW:} Unentschieden zwischen Spieler und Dealer
+\end{itemize}
+
+Der Spielablauf gestaltet sich folgendermaßen:
+\begin{enumerate}
+    \item Spieler startet das Spiel mit einem Einsatz
+    \item Austeilung der Anfangskarten (2 für Spieler, 1 für Dealer)
+    \item Spieler trifft Entscheidungen: Hit (weitere Karte), Stand (keine weitere Karte), Double Down (Einsatz verdoppeln und eine Karte)
+    \item Bei Stand aktiviert sich die Dealer-Logik: Dealer zieht Karten bis mindestens 17 erreicht sind
+    \item Gewinnermittlung und Auszahlung entsprechend des Ergebnisses
+\end{enumerate}
+
+\subsubsection{Handwertberechnung}
+Die Berechnung des Handwerts stellt den Kern der Spiellogik dar. Zunächst werden die Grundwerte aller Karten addiert, wobei Asse initial mit 11 bewertet werden. Falls die Summe 21 übersteigt und Asse vorhanden sind, werden diese nacheinander von 11 auf 1 reduziert, bis entweder die Summe unter 22 liegt oder keine Asse mehr als 11 gewertet werden können.
+
+Diese flexible Ass-Bewertung ermöglicht optimale Strategien: Ein Ass kann als "Soft" (11) oder "Hard" (1) gewertet werden, abhängig von den anderen Karten in der Hand. Die Implementierung sorgt automatisch für die bestmögliche Bewertung der Spielerhand.
+
+\subsubsection{Wettsystem und Auszahlungen}
+Das Blackjack-Spiel ist vollständig in das Wettsystem der Plattform integriert. Der Einsatz wird zu Spielbeginn vom Spielerkonto abgebucht und bei Gewinn entsprechend der Auszahlungsregeln gutgeschrieben:
+
+\begin{itemize}
+    \item \textbf{Blackjack:} 1,5x Einsatz plus ursprünglicher Einsatz zurück
+    \item \textbf{Regulärer Gewinn:} 2x Einsatz (Verdopplung)
+    \item \textbf{Unentschieden:} Ursprünglicher Einsatz wird zurückerstattet
+    \item \textbf{Niederlage:} Kein Gewinn, Einsatz verloren
+\end{itemize}
+
+Die Double-Down-Funktion verdoppelt den ursprünglichen Einsatz und gibt dem Spieler genau eine weitere Karte, danach ist das Spiel automatisch beendet. Diese Aktion ist nur mit den ersten beiden Karten möglich und erfordert ausreichendes Guthaben für den zusätzlichen Einsatz.
+
+\subsubsection{Frontend-Integration}
+Das Frontend bietet eine vollständig animierte Blackjack-Erfahrung mit visueller Kartenrepräsentation und intuitiver Benutzeroberfläche. Die Spielerkarten werden offen dargestellt, während die zweite Dealer-Karte bis zum Spielende verdeckt bleibt. Sound-Effekte und Animationen verstärken die Spielerfahrung.
+
+Die Zustandssynchronisation zwischen Frontend und Backend erfolgt über reactive Programmierung mit Angular Signals, wodurch Änderungen in Echtzeit dargestellt werden. Fehlerbehandlung sorgt für robuste Spielzustände auch bei Netzwerkproblemen, und die Benutzeroberfläche passt sich dynamisch an verschiedene Spielsituationen an.

projektdokumentation/Inhalt/Lootboxes.tex

@@ -0,0 +1,78 @@
+\section{Lootboxes}
+
+\subsection{Was sind Lootboxes?}
+Lootboxes sind digitale Belohnungsbehälter, die gegen eine feste Gebühr geöffnet werden können und dem Spieler einen zufälligen Gewinn basierend auf vordefinierten Wahrscheinlichkeiten gewähren. Das System orientiert sich an bekannten Gaming-Mechaniken und bietet Spielern die Möglichkeit, durch Glück höhere Gewinne zu erzielen als den bezahlten Einsatz. Jede Lootbox enthält verschiedene Belohnungen mit unterschiedlichen Gewinnwahrscheinlichkeiten, wodurch ein Spannungselement entsteht.
+
+Das Lootbox-System der Casino-Plattform umfasst sowohl die Verwaltung verschiedener Lootbox-Typen als auch ein animiertes Öffnungserlebnis, das an populäre Spiele wie Counter-Strike erinnert. Spieler können zwischen verschiedenen Lootboxes wählen, die sich in Preis und Belohnungsstruktur unterscheiden.
+
+\subsubsection{Wahrscheinlichkeitssystem und Belohnungsverteilung}
+Das Herzstück des Lootbox-Systems ist der Wahrscheinlichkeitsalgorithmus, der faire und nachvollziehbare Belohnungsverteilungen gewährleistet. Jede Belohnung in einer Lootbox hat eine definierte Wahrscheinlichkeit zwischen 0,0 und 1,0 (0\% bis 100\%). Die Gewinnermittlung erfolgt durch einen kumulativen Wahrscheinlichkeitsansatz:
+
+\begin{enumerate}
+    \item Generierung einer Zufallszahl zwischen 0 und 1
+    \item Iteration durch alle Belohnungen mit Akkumulation der Wahrscheinlichkeiten
+    \item Rückgabe der ersten Belohnung, bei der die Zufallszahl kleiner oder gleich der kumulativen Wahrscheinlichkeit ist
+    \item Fallback zur letzten Belohnung bei keiner Übereinstimmung (Sicherheitsmechanismus)
+\end{enumerate}
+
+Dieses System ermöglicht eine präzise Kontrolle über die Verteilung der Belohnungen und gewährleistet, dass seltene Gegenstände entsprechend ihrer konfigurierten Wahrscheinlichkeit auftreten.
+
+\subsubsection{Seltenheitssystem}
+Die Lootboxes verwenden ein sechsstufiges Seltenheitssystem, das visuell durch Farbkodierung dargestellt wird:
+
+\begin{itemize}
+    \item \textbf{Common (Häufig):} 40\%+ Wahrscheinlichkeit - Blau
+    \item \textbf{Uncommon (Ungewöhnlich):} 20-40\% Wahrscheinlichkeit - Grün  
+    \item \textbf{Rare (Selten):} 10-20\% Wahrscheinlichkeit - Blau
+    \item \textbf{Epic (Episch):} 5-10\% Wahrscheinlichkeit - Lila
+    \item \textbf{Legendary (Legendär):} 1-5\% Wahrscheinlichkeit - Gold
+    \item \textbf{Mythic (Mythisch):} <1\% Wahrscheinlichkeit - Rot
+\end{itemize}
+
+Die Farbkodierung wird sowohl in der Auswahlansicht als auch während der Öffnungsanimation verwendet, um Spielern sofort die Seltenheit ihrer Belohnung zu kommunizieren.
+
+\subsubsection{Animiertes Öffnungserlebnis}
+Das Frontend bietet ein hochgradig animiertes Öffnungserlebnis, das die Spannung und das Engagement der Spieler steigert. Die Öffnungssequenz umfasst:
+
+\begin{enumerate}
+    \item \textbf{Auswahlphase:} Rasteranzeige verfügbarer Lootboxes mit Preis und möglichen Belohnungen
+    \item \textbf{Öffnungsanimation:} 10-sekündige horizontale Scrollanimation mit 120 Gegenständen
+    \item \textbf{Gewinnermittlung:} Hervorhebung des Gewinnergegenstands an Position 60
+    \item \textbf{Ergebnisdarstellung:} Einblendanimation für Gewinn und Gewinn-/Verlustberechnung
+\end{enumerate}
+
+Die Animation generiert eine Walze mit 120 Gegenständen, wobei der tatsächliche Gewinn immer an der mittleren Position (60) platziert wird. Dies erzeugt den Eindruck einer echten Zufallsauswahl, obwohl das Ergebnis bereits vorher feststeht.
+
+\subsubsection{Datenmodell und Verwaltung}
+Das Backend verwendet ein flexibles Datenmodell, das die Erstellung und Verwaltung verschiedener Lootbox-Typen ermöglicht:
+
+\textbf{LootBoxEntity:} Repräsentiert eine Lootbox mit Namen, Preis und zugehörigen Belohnungen. Die Beziehung zu Belohnungen erfolgt über eine Viele-zu-Viele-Verknüpfung, wodurch Belohnungen zwischen verschiedenen Lootboxes geteilt werden können.
+
+\textbf{RewardEntity:} Definiert einzelne Belohnungen mit Wert und Wahrscheinlichkeit. Die Wahrscheinlichkeit wird als Dezimalzahl mit einer Genauigkeit von 5 Stellen und 2 Nachkommastellen gespeichert.
+
+Die Verwaltung erfolgt über REST-Endpunkte, die sowohl das Abrufen verfügbarer Lootboxes als auch das Kaufen und Öffnen ermöglichen. Administrative Funktionen erlauben das Erstellen neuer Lootboxes und das Löschen bestehender.
+
+\subsubsection{Kaufprozess und Guthaben-Integration}
+Der Lootbox-Kaufprozess ist nahtlos in das Guthaben-Management-System der Plattform integriert:
+
+\begin{enumerate}
+    \item Validierung des Benutzerguthabens gegen den Lootbox-Preis
+    \item Sofortige lokale Guthabenabzug für responsives Benutzererlebnis
+    \item Backend-API-Aufruf zur Kaufabwicklung
+    \item Server-seitige Belohnungsermittlung mittels Wahrscheinlichkeitsalgorithmus
+    \item Guthaben-Update (Preis abziehen, Belohnung hinzufügen)
+    \item Frontend-Synchronisation und Animationsstart
+\end{enumerate}
+
+Das System gewährleistet durch transaktionale Datenbankoperationen, dass Guthaben-Updates atomisch erfolgen und keine inkonsistenten Zustände entstehen können.
+
+\subsubsection{Sicherheit und Fairness}
+Die Lootbox-Implementierung legt besonderen Wert auf Sicherheit und Fairness:
+
+\textbf{Server-seitige Autorität:} Alle Belohnungsermittlungen erfolgen ausschließlich auf dem Server, wodurch Client-seitige Manipulationen ausgeschlossen werden.
+
+\textbf{Eingabevalidierung:} Sowohl die Datenübertragungsobjekte als auch die Backend-Services validieren alle Eingaben auf Korrektheit und Bereichsgrenzen.
+
+\textbf{Wahrscheinlichkeitsintegrität:} Das System überwacht die Wahrscheinlichkeitswerte und gewährleistet, dass sie im gültigen Bereich (0,0-1,0) liegen.
+
+Die Implementierung bietet somit ein vollständiges, produktionsreifes Lootbox-System mit robusten Frontend-Animationen, ordnungsgemäßer Backend-Validierung und nahtloser Benutzerintegration.