# Analytics, heatmapy i spaghetti - poradnik nietechniczny

Ten poradnik jest pisany bez polskich znakow, zeby nie rozwalal sie przy wyswietlaniu.

## Po co jest analityka

Analityka nie jest po to, zeby oceniac graczy jak w call center z piekla.

Jest po to, zeby po grze pokazac:

- gdzie zespoly chodzily,
- ktore mapy odwiedzily,
- ktore obiekty klikaly,
- ktore miejsca ignorowaly,
- czy szukaly przyczyny problemu, czy tylko biegaly jak Plant Manager po hali,
- jakie decyzje i interakcje mozna omowic w debriefingu.

## Gdzie wejsc

Po zalogowaniu admina wejdz:

```text
/admin/tools/workshop-analytics.html
```

Albo z panelu admina kliknij:

```text
Workshop Analytics
```

## Jak wczytac dane

Najprosciej:

1. Wpisz kod sesji, np. `FIRMA-742`.
2. Kliknij `Wczytaj z backendu`.
3. Poczekaj az pojawia sie KPI, mapa, heatmapa i spaghetti.

Alternatywnie:

1. Wyeksportuj sesje jako JSON.
2. Wklej JSON w pole reczne.
3. Kliknij `Wczytaj z pola JSON`.

## Co oznaczaja kafle KPI

- `Logi` - ile zdarzen zapisano.
- `Ruch` - ile razy gracz zmienil kratke.
- `Interakcje` - ile razy klikano obiekty, akcje, dialogi.
- `Zespoly` - ile zespolow jest w danych.
- `Mapy odwiedzone` - ile map pojawilo sie w logach.
- `Przejscia` - ile razy gracze przeszli miedzy mapami.

## Heatmapa

Heatmapa pokazuje, gdzie gracze chodzili najczesciej.

Im mocniej podswietlona kratka, tym czesciej ktos tam byl.

Symbole:

```text
●  obiekt albo NPC
■  mebel / przeszkoda
⇄  przejscie do innej mapy
```

Jak tego uzywac w debriefingu:

- zapytaj, czemu zespol ominal wazny obszar,
- pokaz, czy wszyscy biegali do CFO zamiast do IT,
- pokaz, czy hala albo serwerownia byly w ogole odwiedzone,
- pokaz, czy ktos znalazl wlasciwa sciezke diagnostyczna.

## Spaghetti diagram

Spaghetti diagram pokazuje trase zespolu po mapie.

Kazda linia to ruch zespolu. Mozesz wybrac:

```text
Wszystkie zespoly
albo jeden konkretny zespol
```

Jak tego uzywac:

- zobacz, czy zespol chodzil logicznie,
- zobacz, czy wracal kilka razy do tego samego miejsca,
- zobacz, czy najpierw szukal danych, czy od razu kupowal rozwiazania,
- porownaj zespoly podczas debriefingu.

## Interakcje z obiektami

Sekcja `Interakcje z obiektami` pokazuje:

- najczesciej klikane obiekty,
- najczesciej wykonywane akcje.

Przyklad pytania po grze:

```text
Dlaczego wszyscy klikali linie produkcyjna, ale nikt nie kliknal backup servera?
```

## Timeline

Timeline pokazuje wazniejsze zdarzenia w kolejnosci:

- start sesji,
- przejscia miedzy mapami,
- wykonane akcje,
- decyzje eventowe,
- interwencje prowadzacego.

To jest dobra lista do prowadzenia rozmowy po grze.

## Siec map i przejsc

Sekcja `Siec map i przejsc` pokazuje, ktora mapa prowadzi do ktorej mapy.

Pomaga znalezc bledy typu:

```text
z mapy da sie wyjsc, ale nie da sie wrocic
przejscie prowadzi do zlego spawn pointu
mapa jest osierocona i nikt do niej nie wejdzie
```

## Eksport CSV

Kliknij:

```text
Pobierz CSV analityki
```

Dostaniesz plik z logami w prostszej formie. Mozesz go otworzyc w Excelu.

## Jak przygotowac scenariusz pod dobra analityke

1. Dawaj obiektom jasne nazwy.
2. Dawaj akcjom jasne nazwy.
3. Uzywaj mapFile i spawnPoints konsekwentnie.
4. Nie rob wszystkiego na jednej mapie, jezeli scenariusz naturalnie ma kilka stref.
5. Wazne miejsca rob jako obiekty interaktywne, nie tylko dekoracje.
6. Po tescie otworz analytics i sprawdz, czy dane sa czytelne.

## Najczestsze problemy

### Brak danych

Mozliwe powody:

- nikt nie gral w sesji,
- zespol nie zapisal stanu,
- backend dziala w SQLite, a patrzysz na demo JSON,
- kod sesji jest zly,
- sesja wygasla.

### Heatmapa jest pusta na danej mapie

Mozliwe powody:

- nikt nie wszedl na te mape,
- logi nie maja map_path,
- mapa ma inne id niz logi.

### Spaghetti jest za geste

Mozliwe rozwiazania:

- wybierz tylko jeden zespol,
- testuj krotsza sesje,
- w przyszlej wersji dodamy filtrowanie po czasie.

## Minimalny test analityki

1. Wejdz do gry.
2. Przejdz z campusu do biura.
3. Kliknij obiekt w biurze.
4. Wroc na campus.
5. Przejdz na hale.
6. Kliknij linie A.
7. Przejdz do serwerowni.
8. Kliknij backup rack.
9. Otworz Workshop Analytics.
10. Sprawdz, czy widac heatmape, spaghetti, interakcje i timeline.

---

# v1.3.2 - poprawki spaghetti i NPC

W v1.3.2 poprawiono wczytywanie map w widoku `admin/tools/workshop-analytics.html`. Problem byl taki, ze widok jest w katalogu `admin/tools/`, a czesc sciezek do danych zaczynala sie od `data/...`. Przegladarka probowala wtedy pobrac `admin/tools/data/...`, czyli zle miejsce. Teraz analityka sama poprawia takie sciezki.

## Spaghetti diagram

Spaghetti jest teraz dzielone na segmenty. To znaczy, ze gdy gracz przechodzi miedzy mapami, wykres nie rysuje jednej dlugiej linii przez cala plansze. Kazda mapa pokazuje tylko ruch z tej mapy.

Widok pokazuje tez diagnostyke:

- ile jest wszystkich logow MOVE_TILE,
- ile ruchow pasuje do wybranej mapy,
- jakie aliasy mapy sa uzywane,
- co sprawdzic, jesli ruchu jest 0.

## Ruch NPC

Chodzace NPC loguja zdarzenia `NPC_MOVE_TILE`. Nie sa one liczone jako ruch gracza w heatmapie i spaghetti. Dzieki temu debriefing pokazuje decyzje i trase graczy, a nie spacer lidera zmiany.