Workflow: Game Start

Goal

This document describes step by step how a training session is started.

Non-technical hosts (teachers, practice supervisors): there is a detailed German user manual covering login, game code, session setup, and troubleshooting — Manual Room of Horror (DOCX).

Components involved

Component	Task at game start
Unity/VR game	Initializes the headset, creates/loads the game code, shows it in the lobby, polls the game status.
Backend/API	Stores game code, game status, patient, active errors, and mistake attempts; sends WebSocket events to the frontend.
Frontend/website	Login, game-code entry, patient selection, error configuration, game start, live progress.

Flow

 1. Backend is running (locally or on a server).
 2. Unity game starts.
 3. Unity sends POST /device/device-init to the API.
 4. API creates or loads the game (status LOBBY).
 5. API returns the game code to Unity.
 6. Unity shows the game code in the lobby.
 7. Instructor logs in on the website.
 8. Instructor enters the game code in the dashboard (POST /game/join-game).
 9. Status switches to SETUP; the frontend connects to the game via WebSocket.
10. Instructor selects a patient profile — targeted or random, with preview
    (PUT /game/edit-game?target=patientId).
11. Instructor selects errors (only those allowed for the patient) and mistake attempts.
12. Instructor clicks "START GAME" (PUT /game/edit-game?target=status&value=STARTED).
13. Unity detects the status change (1-second polling).
14. Unity activates the patient model, configures the room (e.g. the bed),
    and shows exactly the selected error objects.
15. Trainees search for errors; every event appears live in the dashboard.

Game code

The game code is created when Unity calls POST /api/device/device-init and is stored encrypted in the database. It is not created manually in the frontend — only entered there.

Login and registration

The website is intended for the supervising person (teacher, session host). Login is passwordless via e-mail links:

Registration/login
-> Backend creates an auth token + one-time session ID
-> Backend sends an e-mail link
-> User clicks the link (any device)
-> The original tab polls /account/use-session-id and receives the access token
-> Dashboard opens

For local development without a mail server: with DEV_MODE=true the auth token is included directly in the API response (see Local Setup).

Configuring the game

After connecting with a game code, the website can:

• select a patient profile (targeted or random, with preview and patient data)
• select the errors allowed for that patient
• set the number of mistake attempts (health bar)
• start, stop, or restart the game
• watch live progress and, after the game ends, the weighted evaluation

While a game is running (STARTED), the backend blocks changes to patient and errors (400 Bad Request).

Game status

Status	Meaning
LOBBY	The headset is initialized but not linked to a user.
SETUP	A user is connected; the game is being configured.
STARTED	The game is running.
ENDED	The game has ended (all errors found, mistake budget exhausted, or stopped manually); the evaluation is persisted.

Testing without a VR headset

Backend, frontend, and the complete game flow can be verified without a headset: Unity offers a desktop mode (mouse/keyboard), and the API can be driven directly via the Postman collection (roh_2_1.postman_collection.json).

---

Information sources

• room-of-horror-api/endpoints/device/DeviceInit.ts, endpoints/game/*, websocket/*
• room-of-horror-frontend/src/components/JoinContainer.tsx, GameInterface.tsx, PatientSelection.tsx
• room-of-horror-unity/Assets/Scripts/Main.cs, GameStatusController.cs

Suggested improvements

• Link a short demo video or GIF of the game start in docs/static/.

Last build: 19 Aug 2026, 05:20+00:00