# Poradnik nietechniczny: przejscia miedzy mapami

Ten poradnik jest pisany bez polskich znakow, bo w niektorych miejscach wyswietlanie znakow typu a z ogonkiem, l z kreska albo z z kropka potrafi sie popsuc.

## 1. O co chodzi

Jedna mapa nie musi pokazywac calej firmy.

Mozesz miec osobne mapy, np.:

- budynek glowny,
- hala produkcyjna,
- teren wokol fabryki,
- parking,
- serwerownia,
- biuro zarzadu,
- magazyn,
- strefa dostaw.

Gracz moze przechodzic miedzy nimi przez drzwi, bramy, windy, schody albo oznaczone pola przejscia.

Przyklad:

```text
Budynek fabryki -> drzwi wyjsciowe -> teren wokol fabryki
Teren wokol fabryki -> wejscie do budynku -> budynek fabryki
```

## 2. Najprostszy model myslenia

Przejscie sklada sie z dwoch rzeczy:

```text
1. Skad gracz wychodzi
2. Gdzie gracz pojawia sie na drugiej mapie
```

Czyli potrzebujesz:

```text
mapa A: pole wyjscia
mapa B: punkt startowy / spawn
```

Przyklad:

```text
Mapa A: data/maps/main-office-v01.json
Pole wyjscia: x=15, y=18

Mapa B: data/maps/factory-yard-v01.json
Spawn: SPAWN_FROM_FACTORY, x=15, y=2
```

## 3. Dwa sposoby robienia przejsc

### Sposob A: przejscie po wejsciu na pole

To jest najlepsze dla:

- bramy,
- wyjscia z budynku,
- schodow,
- przejscia korytarzem,
- teleportu scenariuszowego.

Gracz wchodzi na pole i automatycznie laduje na drugiej mapie.

W mapie zapis wyglada tak:

```json
{
  "transitions": [
    {
      "id": "TRN_MAIN_TO_FACTORY_YARD",
      "label": "Wyjscie na teren wokol fabryki",
      "trigger": "walk",
      "from": { "x": 15, "y": 18, "w": 1, "h": 1 },
      "to": {
        "mapFile": "data/maps/factory-yard-v01.json",
        "spawnId": "SPAWN_FROM_FACTORY",
        "direction": "down"
      }
    }
  ]
}
```

### Sposob B: przejscie po kliknieciu obiektu

To jest najlepsze dla:

- drzwi z menu,
- windy,
- recepcji,
- portierni,
- drzwi dostepnych dopiero po akcji,
- przejscia z warunkiem.

Gracz klika obiekt, np. drzwi, i wybiera akcje:

```text
Przejdz do innej mapy
```

Obiekt ma wtedy `mapTransition`.

```json
{
  "id": "OBJ_EXIT_DOOR",
  "type": "map_transition",
  "label": "Drzwi wyjsciowe z fabryki",
  "x": 15,
  "y": 18,
  "blocksMovement": false,
  "interactionTile": { "x": 15, "y": 17 },
  "mapTransition": {
    "mapFile": "data/maps/factory-yard-v01.json",
    "spawnId": "SPAWN_FROM_FACTORY",
    "label": "Wyjdz na teren wokol fabryki"
  }
}
```

Silnik sam doda akcje przejscia, jesli obiekt ma `mapTransition`.

## 4. Jak ustawic punkt wejscia na drugiej mapie

Na mapie docelowej dodajesz `spawnPoints`.

Przyklad mapy zewnetrznej:

```json
{
  "id": "factory-yard-v01",
  "name": "Teren wokol fabryki",
  "playerStart": { "x": 15, "y": 10, "direction": "down" },
  "spawnPoints": {
    "DEFAULT": { "x": 15, "y": 10, "direction": "down" },
    "SPAWN_FROM_FACTORY": { "x": 15, "y": 2, "direction": "down" }
  }
}
```

`DEFAULT` to awaryjny start.

`SPAWN_FROM_FACTORY` to miejsce, gdzie gracz pojawi sie po wyjsciu z fabryki.

## 5. Przejscie powrotne

Zawsze rob przejscie w obie strony, jezeli gracz ma moc wrocic.

Czyli:

```text
budynek -> teren zewnetrzny
teren zewnetrzny -> budynek
```

Na mapie zewnetrznej dodaj:

```json
{
  "id": "TRN_YARD_TO_MAIN_OFFICE",
  "label": "Powrot do budynku fabryki",
  "trigger": "walk",
  "from": { "x": 15, "y": 1, "w": 1, "h": 1 },
  "to": {
    "mapFile": "data/maps/main-office-v01.json",
    "spawnId": "SPAWN_FROM_YARD",
    "direction": "up"
  }
}
```

A na mapie budynku dodaj spawn:

```json
{
  "spawnPoints": {
    "SPAWN_FROM_YARD": { "x": 15, "y": 17, "direction": "up" }
  }
}
```

## 6. Jak to robic w Map Builderze

### Opcja najprostsza: obiekt wyjscia

1. Otworz Map Builder.
2. Wybierz preset obiektu:

```text
Wyjscie do innej mapy
```

3. Postaw obiekt na mapie.
4. Przejdz w tryb:

```text
Zaznacz / edytuj
```

5. Kliknij ten obiekt.
6. W panelu po prawej uzupelnij:

```text
Docelowy plik mapy: data/maps/factory-yard-v01.json
Spawn ID: SPAWN_FROM_FACTORY
Label akcji: Wyjdz na teren zewnetrzny
```

7. Kliknij:

```text
Zastosuj
```

8. Kliknij:

```text
Waliduj
```

9. Eksportuj mape.

### Opcja bardziej techniczna: transitions

Jesli chcesz, zeby przejscie odpalalo sie automatycznie po wejsciu na pole, uzyj `transitions` w JSON mapy.

Na razie najlatwiej zrobic to przez eksport mapy i dopisanie sekcji `transitions` recznie albo skopiowanie przykladu z tego poradnika.

## 7. Drzwi zamkniete + przejscie do innej mapy

Mozesz zrobic drzwi, ktore przenosza do innej mapy dopiero po akcji.

Przyklad:

```text
Do hali produkcyjnej wejdziesz dopiero po rozmowie z portiernia.
```

Flow:

```text
1. Gracz klika portiernie.
2. Dostaje przepustke.
3. Drzwi do hali staja sie dostepne.
4. Gracz klika drzwi.
5. Gra przenosi go na mape hali.
```

Akcja drzwi moze miec wymaganie:

```json
{
  "requirements": [
    { "type": "material_collected", "materialId": "ITEM_FACTORY_PASS" }
  ],
  "effects": [
    {
      "mapTransition": {
        "mapFile": "data/maps/production-hall-v01.json",
        "spawnId": "SPAWN_FROM_MAIN_BUILDING"
      }
    }
  ]
}
```

## 8. Nazewnictwo

Dobre nazwy map:

```text
data/maps/main-office-v01.json
data/maps/factory-yard-v01.json
data/maps/production-hall-v01.json
data/maps/server-room-v01.json
data/maps/parking-v01.json
```

Dobre nazwy spawnow:

```text
SPAWN_FROM_FACTORY
SPAWN_FROM_YARD
SPAWN_FROM_PARKING
SPAWN_FROM_SERVER_ROOM
SPAWN_DEFAULT
```

Dobre nazwy przejsc:

```text
TRN_MAIN_TO_YARD
TRN_YARD_TO_MAIN
TRN_MAIN_TO_PRODUCTION
TRN_PRODUCTION_TO_MAIN
```

Nie uzywaj:

```text
mapa2
nowa_final
spawn_tutaj_chyba
przejscie_test3
```

Bo za tydzien nikt nie bedzie wiedzial, co to znaczy.

## 9. Najczestsze bledy

### Blad: gracz pojawia sie w scianie

Powod:

```text
Spawn ID wskazuje pole zablokowane.
```

Naprawa:

```text
Przesun spawn na wolna podloge.
```

### Blad: gracz przechodzi na druga mape, ale nie moze wrocic

Powod:

```text
Brak przejscia powrotnego.
```

Naprawa:

```text
Dodaj transition z mapy B do mapy A.
```

### Blad: klikam drzwi i nic sie nie dzieje

Powod:

```text
Obiekt nie ma mapTransition albo akcja nie ma efektu mapTransition.
```

Naprawa:

```text
Uzupelnij Docelowy plik mapy i Spawn ID w Map Builderze albo dodaj efekt mapTransition w Scenario Editorze.
```

### Blad: wyskakuje blad mapFile

Powod:

```text
Sciezka do mapy jest zla.
```

Poprawny przyklad:

```text
data/maps/factory-yard-v01.json
```

### Blad: przejscie odpala sie od razu po wejsciu na mape

Powod:

```text
Spawn ustawiono na tym samym polu co transition powrotne.
```

Naprawa:

```text
Spawn ustaw jedna kratke dalej od pola przejscia.
```

## 10. Checklista

Przed uznaniem przejscia za gotowe sprawdz:

```text
[ ] czy mapa docelowa istnieje w data/maps/
[ ] czy mapFile jest poprawny
[ ] czy spawnId istnieje na mapie docelowej
[ ] czy spawn stoi na wolnej podlodze
[ ] czy przejscie dziala w jedna strone
[ ] czy przejscie dziala w druga strone
[ ] czy gracz nie wpada w petle przejscia
[ ] czy interactionTile drzwi jest dostepny
[ ] czy walidator nie pokazuje bledow krytycznych
[ ] czy zapis/wczytanie sesji pamieta aktualna mape
```