Ort

resources/js/components/uebung-statistics/UebungStatisticsComponent.vue

Abhängigkeiten

resources/js/components/uebung-statistics/UebungStatisticsData.jsresources/js/components/uebung-statistics/UebungPlayer.js

Zweck

Darstellung verschiedener spielerbezogener Statistiken und Daten wie abgelaufene Zeit, erreichbare Gravitas usw. Für Einzel- und Mehrspielermodus benutzbar. Sinn der Model-Klassen UebungPlayer und UebungStatisticsData ist es, die bestimmte Daten als verpflichtend oder optional zu markieren und den gesamten Zustand der Komponente transparenter zu machen (durch "sprechende" Klassennamen und Konstruktoren). Alle Daten werden zwar mit Defaultwerten initialisiert, es findet aber im Anschluss eine Validierung statt; diese sorgt dafür, dass z.B. bei Fehlen erforderlicher Werte (oder falls diese unplausibel sind) eine Fehlermeldung auf die Konsole geloggt wird.

Verwendung

Welche Daten werden angezeigt?

• Name des Spiels/Übung (optional, default "Übung")
• Fortschrittsbalken (bei einem Spieler), oder
• Verteilungsbalken (PrimeVues "MeterGroup" Komponente, Fortschritt pro Spieler bei mehreren Spielern)
• Zeitmessung (optional)
• Spielerkarte (eine pro Spieler) mit folgenden Daten:
  • Name
  • Avatarbild (optional, sonst Platzhalter)
  • Gravitas zu Beginn des Spiels (statisch)
  • Anzahl richtiger Antworten
  • Anzahl falscher Antworten
  • Anzahl verwendeter Hinweise (MedPack-Symbol)

Initialisierung

Signatur:

<uebung-statistics-component v-model:data="statisticsData"/>

Props

Die Komponente unterstützt folgende Props:

• v-model:data (required): Enthält die Daten, auf denen UebungStatisticsComponent aufbaut. Nutzt Component v-model, um Daten zwischen der Statistik-Komponente und der Elternkomponente auszutauschen.
• darkmode (optional, default: false): Boolean-Flag für Dark Mode. Wenn gesetzt, wird die Komponente mit dunklem Hintergrund (bg-primary-800) und hellen Texten dargestellt.
• meterGroupColors (optional): Array von Farbwerten für den MeterGroup-Balken bei mehreren Spielern.

Beispiel mit Dark Mode:

<uebung-statistics-component
    v-model:data="statisticsData"
    darkmode
/>

Die Variable, die in v-model:data gesetzt wird (im Beispiel oben: statisticsData) muss in der Elternkomponente befüllt werden. Dazu eine Variable definieren:

const statisticsData = ref(new UebungStatisticsData(
    [player],
    props.data.uebung.specific_uebung.title,
    props.data.uebung.specific_uebung.content_data.length)
);

Domain-Objekte

UebungStatisticsData

Mit einem Objekt dieser Klasse muss v-model:data befüllt werden. Signatur:

class UebungStatisticsData {
    constructor(players, gameName, totalTasks, showTimeline = true, meterGroupColors = ["#4287f5", "#e64210", "#3ca80a"]) {
    this.players = Array.isArray(players) ? players : [];
    this.gameName = typeof gameName === 'string' ? gameName : 'Übung';
    this.totalTasks = (Number.isFinite(totalTasks) && totalTasks > 0) ? totalTasks : 0;
    this.tasksDone = 0;
    this.showTimeline = showTimeline;
    this.meterGroupColors = meterGroupColors;
}

Konstruktor-Params (müssen in Elternkomponente bei new UebungStatisticsData() gesetzt werden):

• players: Array von einem oder mehr UebungPlayer-Objekten. Darf nicht leer sein, sonst Validierungsfehler
• gameName: String, darf leer oder null sein
• totalTasks: Number, darf nicht leer oder kleiner 0 sein, sonst Validierungsfehler
• showTimeline: optional, default true. Zeitmessung anzeigen oder ausblenden
• meterGroupColors: optional, Standardwerte sind blau, rot, grün. Farben, die im Verteilungsbalken verwendet werden.

Weitere Felder, die bei Bedarf in der Elternkomponente ausgelesen werden können, aber intern berechnet werden:

• tasksDone: Number Anzahl der erledigten Aufgaben

UebungPlayer

Verwenden, um im Konstruktor von UebungStatisticsData das Feld "players" zu befüllen. Signatur:

class UebungPlayer {
    constructor(playerName, initialGravitas, avatar = 'hi-user-user') {
        this.playerName = typeof playerName === 'string' ? playerName : '';
        this.initialGravitas = Number.isFinite(initialGravitas) ? Number(initialGravitas) : 0;

        // werden nicht via Konstruktor gesetzt
        this.correctResponses = 0;
        this.wrongResponses = 0;
        this.hintsUsed = 0;
        this.timeSpent = 0; // Sekunden
        this.avatar = typeof avatar === 'string' ? avatar : 'hi-user-user';
    }
}

Konstruktor-Params:

• playerName: String
• initialGravitas: Number, wieviel Gravitas der Spieler vor dem Spiel besitzt. Wird innerhalb der Komponente nicht dynamisch verändert; das muss z.B. mittels UebungenLibrary aus der Elternkomponente heraus erledigt werden
• avatar: String, optional. Name des Icons/Bildes, das für den Avatar verwendet wird. Im Hintergrund wird die <hermeneus-icon> Komponente verwendet. Dessen Benutzungshinweise beachten, v.a. wenn "externe" Bilder für den Avatar verwendet werden sollen!

Weitere Felder, die bei Bedarf in der Elternkomponente ausgelesen werden können, aber intern berechnet werden, sind aus dem Codeblock oben ersichtlich.

UebungStatisticsComponent

Die gesamte Komponente wird, wie erwähnt, in der Elternkomponente als template ref in einer Variable gespeichert. Das ist wichtig, um den Spielfortschritt an die Komponente weitergeben zu können. Dazu gibt es die Funktion proceed(player, isCorrect, hintUsed = false), die man nach jedem Spielschritt aufruft. Params sind der beantwortende Spieler, ob die Antwort richtig war (boolean) und optional ob ein Hinweis benutzt wurde (default: nein). Zur Verwendung vgl. auch das Beispiel unten.

Hinweise zur Verwendung und Beispiel

Die Daten können nach Initialisierung (s.o.) über die entspr. Variablen abgerufen werden. Man setzt also die Komponente ein:

<uebung-statistics-component v-model:data="statisticsData"/>

Im <script> Block statisticsData als ref() setzen:

<script setup>
import UebungStatisticsComponent from "@components/uebung-statistics/UebungStatisticsComponent.vue";
import UebungStatisticsData from "@components/uebung-statistics/UebungStatisticsData.js";
import UebungPlayer from "@components/uebung-statistics/UebungPlayer.js";

const player = new UebungPlayer(UserData.username, UserData.gravitas);
const statisticsData = ref(new UebungStatisticsData(
    [player],
    props.data.uebung.specific_uebung.title,
    props.data.uebung.specific_uebung.content_data.length)
);
</script>

Sobald ein Spielschritt erledigt wurde, proceed() aufrufen:

statisticsData.value.proceed(player, true);

Schließlich können die Statistiken z.B. in der Evaluationskomponente einer Übung benutzt werden:

<uebung-verwechslungsgefahr-evaluate-component :data="statisticsData"/>

Dark Mode

Die Komponente unterstützt einen Dark Mode durch das darkmode-Prop:

<uebung-statistics-component
    v-model:data="statisticsData"
    darkmode
/>

Unterschiede zwischen Light und Dark Mode:

• Light Mode (default): Weißer Hintergrund, dunkle Texte
• Dark Mode: bg-primary-800 Hintergrund, helle Texte, angepasste Spielerkarten-Farben

Der Dark Mode eignet sich besonders für Spiele mit dunklem Hintergrund (z.B. Ludus Cursus).