fbpx
Vorschlag Datenstruktur Sphery Racer <!-- omit in toc -->

Vorschlag Datenstruktur Sphery Racer

...für die Kommunikation mit der online Rest-API

Stand 25. November 2020 - Julian Schönbächler

Inhalt

Login / Registrierung

Das Spiel wird ein Login-, sowie Registrierungsformular beinhalten. Die gesendeten Requests der Formulare beinhalten folgende Daten:

Registrierung

{ "username": "Christoph", "email": "stophel@blocher.ch", "password": "schlumpfgate" }

Login

{ "email": "stophel@blocher.ch", "password": "schlumpfgate" }

Sync-Points im Spiel

Ausgehend vom jetzigen Spielaufbau und den aktuellen Anforderungen bezüglich der Kommunikation, sind 3 drei verschiedene Sync-Points vorgesehen, an welchen das Spiel mit der API interagiert.

Start der Session

Direkt nach dem Login und dem Erhalt des Authentifizierungs-Tokens und der Benutzer ID wird eine neue Spiel-Session gestartet.

Request

Das Spiel sendet folgenden Request:

{ "requestType": "session-start", "requestTime": 1234567890, "data": { "loginAt": 1234567890, "exercube": "SpheryCube1" } }
KeyTypBeschreibung
requestTypestringBeschreibt den Typ des Requests
requestTimeintDer Zeitstempel des Requests (Unix-Timestamp)
data{}Objekt mit den Request-spezifischen Daten
→ loginAtintDer Zeitstempel des Logins (Unix-Timestamp)
→ exercubestringDie ID des ExerCubes

Response

Als Antwort werden vom Server Benutzerspezifische Daten erwartet, welche für das Spiel erforderlich sind.

{ "session": { "id": 1, "healthData": <health-data>, "workoutPresets": [...<workout>] } ... }
KeyTypBeschreibung
session{}Objekt mit Session-spezifischen Daten
→idintDie ID der soeben gestarteten Session
→ healthData{}Spielerspezifische körperliche Daten (siehe: Health Data)
→ workoutPresets[]Ein Array an gespeicherten Workout Presets

Info: Momentan werden keine "Workout Presets" gespeichert, sondern einfach die standard Workouts des Spiels verwendet. Der Wert für workoutPresets kann also immer ein leeres Array ([]) sein.

Ende der Session

Direkt nach dem Login und dem Erhalt des Authentifizierungs-Tokens und der Benutzer ID wird eine neue Spiel-Session gestartet. Das Spiel sendet folgenden Request:

Request

{ "requestType": "session-close", "requestTime": 1234567890, "data": { "logoutAt": 1234567890, "sessionTime": 1800, "netPromoterScore": 10 } }
KeyTypBeschreibung
requestTypestringBeschreibt den typ des Requests
requestTimeintDer Zeitstempel des Requests (Unix-Timestamp)
data{}Objekt mit den Request-spezifischen Daten
→ logoutAtintDer Zeitstempel des Logouts (Unix-Timestamp)
→ sessionTimeintDie Dauer der Session (in Sekunden)
→ netPromoterScoreintDie Bewertung der Session [0-10]

Response

Undefiniert

Abgeschlossenes Workout

Ein Workout beschreibt eigentlich immer ein einzelnes Rennen im Spiel. Nachdem der Spieler das Rennen beendet hat (sprich das Ziel erreicht hat), wird ein Request mit den gesamten Workout-Daten erstellt.

Request

{ "requestType": "workout-put", "requestTime": 1234567890, "data": { "workout": <workout>, "challenge": -1, "duration": 600, "hrTracking": true, "hrAdaptivity": true, "hrValues": [ { "time": 3.02, "value": 82 }, { "time": 6.13, "value": 83 }, ... ], "hrAverage": 163, "hrMax": 199, "score": 756388, "maxCombo": 123, "bodyScore": 0.9, "brainScore": 0.8, "dualflowScore": 0.85, "exercises": [...<exercise>] } }
KeyTypBeschreibung
requestTypestringBeschreibt den typ des Requests
requestTimeintDer Zeitstempel des Requests (Unix-Timestamp)
data{}Objekt mit den Request-spezifischen Daten
→ workoutintWorkout data that was used for this workout (siehe Workout)
→ challengeintDie ID der Challenge mit welcher dieses Workout verlinkt ist; -1 falls keine Verlinkung besteht (momentan werden Challenges noch nicht gehandled, der Wert wird immer auf -1 gesetzt sein)
→ durationintDie effektive Trainingsdauer des Workouts (in Sekunden)
→ hrTrackingboolWurde die Herzrate getracked?
→ hrAdaptivityboolWurde HR adaptiv gespielt? false für Performance adaptiv
→ hrValues[]Array von allen gemessenen HR-Werten; in der angegebenen Struktur
- time = Zeit nach start des Workouts (in Sekunden)
- value = HR-Wert
→ hrAverageintDie Durchschnittliche Herzrate über das ganze Workout gemessen
→ hrMaxintDie tatsächlich erreichte maximale Herzrate
→ scoreintDie erreichte Punktzahl in diesem Workout
→ maxCombointMaximum Combo, welcher erreicht wurde
→ bodyScorefloatWorkout BodyScore (prozentualer Wert [0.0-1.0])
→ brainScorefloatWorkout BrainScore (prozentualer Wert [0.0-1.0])
→ dualflowScorefloatWorkout DualflowScore (prozentualer Wert [0.0-1.0])
→ exercises[]Array, welches geordnet alle abgeschlossenen Übungen der Rennstrecke fasst (siehe Exercise)

Response

Undefiniert

Allgemeine Datensätze

Hier werden alle Datensätze aufgeschlüsselt welche oft Inhalt der einzelnen Requests sein können und als eigene "Objekte" oder "Typen" gehandhabt werden.

Health Data

{ "hrRestingPulse": 80, "hrReserve": 116, "hrMax": 196, "weight": 75, "age": 30 }
KeyTypBeschreibung
hrRestingPulseintRuhepuls der HR; -1 falls undefiniert
hrReserveintReservepuls der HR; -1 falls undefiniert
hrMaxintHR Max; -1 falls undefiniert
weightintGewicht (in kg); -1 falls undefiniert
ageintAlter; -1 falls undefiniert

Workout

{ "name": "MyCustomWorkout", "race": { "difficulty": 2, "duration": 900, "tutorial": false, "startSpeed": 5, "hrTarget": 0.9 }, "exercises": [ "touches", "punches" ], "tiers": [ { "cognitiveChallenges": [ "mirror", "lights" ], "cognitiveMin": 0.0, "cognitiveMax": 1.0, "physicalMin": 0.0, "physicalMax": 1.0 }, ... ] }
KeyTypBeschreibung
namestringDer Name (und ID; unique) des Workouts
race{}Renn-spezifische Daten
→ difficultyintSchwierigkeit des Rennens [0-2]
→ durationintDauer des Rennens (in Sekunden)
→ tutorialboolBoxenstopp Tutorials verwendet?
→ startSpeedfloatStartgeschwindigkeit des Rennens [0.0-1.0]
→ hrTargetintDie Ziel-HR für HR-adaptives Spiel
exercises[...string]Array an Übungs-Typen welche für das Spiel ausgewählt wurden
tiers[...{}]Alle Combo-Tier informationen als Array; Länge des Arrays ist die Anzahl der Tiers
→ cognitiveChallenges[...string]Array an kognitiven Challenge-Typen welche für das Spiel ausgewählt wurden
→ cognitiveMinfloatMinimale kognitive Adaptivität [0.0-1.0]
→ cognitiveMaxfloatMaximale kognitive Adaptivität [0.0-1.0]
→ physicalMinfloatMinimale physische Adaptivität [0.0-1.0]
→ physicalMaxfloatMaximale physische Adaptivität [0.0-1.0]

Exercise

{ "id": "midPunchLeft", "name": "Punch Left", "time": 2.14, "tier": 2, "precision": 3, "score": 230 }
KeyTypBeschreibung
idstringDie ID (unique) der Übung
namestringDer (human readable) Name der Übung
timefloatDie Zeit nach Start des Workouts nachdem die Übung passiert wurde
tierintDer Combo-Tier mit welchem die Übung passiert wurde
precisionintDer Evaluierungswert der Übung (Anzahl Sterne; 0 falls fehlerhaft)
scoreintDie erhaltene Punktzahl für diese Übung

Beispiele

Diese Beispiele zeigen wie jeweils ein voller Request für die oben beschriebenen Sync-Points am Ende strukturiert ist und aussehen könnte.

Start der Session

{ "requestType": "session-start", "requestTime": 1606381769, "data": { "loginAt": 1606381767, "exercube": "SpheryCube1" } }

Ende der Session

{ "requestType": "session-close", "requestTime": 1606383628, "data": { "logoutAt": 1606383614, "sessionTime": 1847, "netPromoterScore": 8 } }

Abgeschlossenes Workout

{ "requestType": "workout-put", "requestTime": 1234567890, "data": { "workout": { "name": "DualFlow", "race": { "difficulty": 2, "duration": 900, "tutorial": false, "startSpeed": 5, "hrTarget": 0.9 }, "exercises": [ "touches", "punches" ], "tiers": [ { "cognitiveChallenges": [ "mirror", "lights" ], "cognitiveMin": 0.0, "cognitiveMax": 1.0, "physicalMin": 0.0, "physicalMax": 1.0 }, { "cognitiveChallenges": [ "audio", "mirror" ], "cognitiveMin": 0.3, "cognitiveMax": 1.0, "physicalMin": 0.5, "physicalMax": 1.0 } ] }, "challenge": -1, "duration": 600, "hrTracking": true, "hrAdaptivity": true, "hrValues": [ { "time": 3.02, "value": 82 }, { "time": 6.13, "value": 83 }, ... ], "hrAverage": 163, "hrMax": 199, "score": 756388, "maxCombo": 123, "bodyScore": 0.9, "brainScore": 0.8, "dualflowScore": 0.85, "exercises": [ { "id": "midPunchLeft", "name": "Punch Left", "time": 2.14, "tier": 0, "precision": 3, "score": 60 }, { "id": "lowTouchRight", "name": "Low Touch Right", "time": 5.72, "tier": 0, "precision": 2, "score": 60 } ... ] } }