# Multi-floor maps - guide without tech pain

This guide is written without Polish diacritics on purpose.

## Main rule

Do not build all floors as one giant map.

Use this simple rule:

```text
one floor = one map file
stairs / elevator = transition between maps
```

Example:

```text
office-floor-01.json
office-floor-02.json
server-room.json
```

The player sees it as one building, but the engine loads another map when they use stairs, elevator or door.

## Good structure

For a building with 2 floors:

```text
campus-ground.json
  -> office-floor-01.json
       -> office-floor-02.json
       -> server-room.json
  -> production-hall.json
       -> warehouse.json
```

## How to create stairs

In Map Studio:

1. Open the map, for example `office-floor-01`.
2. Choose object preset: `Schody w gore`.
3. Put stairs on the map.
4. Select the stairs object.
5. Fill transition fields:

```text
Target map: data/maps/office-floor-02.json
Target spawn: SPAWN_FROM_STAIRS
Action label: Wejdz na pietro 1
Hover text: Schody na pietro 1
```

6. Save the map.
7. Open target map `office-floor-02`.
8. Add spawn point:

```text
SPAWN_FROM_STAIRS
```

9. Add return stairs:

```text
Target map: data/maps/office-floor-01.json
Target spawn: SPAWN_FROM_STAIRS
Action label: Zejdz na parter
```

## How to create elevator

Elevator is also a transition.

Use preset:

```text
Winda
```

Recommended hover text:

```text
Winda na pietro 1
Winda na parter
Winda do serwerowni
```

## How to test

In Map Studio:

1. Turn on double click transition test.
2. Double click the stairs/elevator object.
3. Map Studio should check target map and target spawn.
4. If option is enabled, it loads target map automatically.
5. Check if camera focuses on spawn.
6. Double click return transition.

## oneWay transitions

Sometimes a transition has no return.

Examples:

```text
emergency exit
one-way delivery gate
story jump / cutscene
```

Then mark it as:

```text
oneWay = true
```

If you do not mark it, validator can warn that return path is missing.

## Most common mistakes

```text
- target map does not exist
- target spawn does not exist
- spawn is inside wall or furniture
- stairs go to wrong floor
- return stairs are missing
- hover text is empty and player does not know where the transition leads
```

## Best practice

Name maps clearly:

```text
demo-office-floor-01-v01.json
demo-office-floor-02-v01.json
demo-server-room-v01.json
```

Name spawns clearly:

```text
SPAWN_FROM_STAIRS
SPAWN_FROM_ELEVATOR
SPAWN_FROM_OFFICE
SPAWN_FROM_CAMPUS
```