## Переключение между локациями

`$ set_location("location_name", place)`  
Где `place` - имя места в локации `location_name` или словарь (`dict`) со свойствами `x`, `y` (опционально - ещё и с `xsize` и `ysize`).
В его центр устанавливается ГГ (Главный Герой, `me`).

***

## Скрытие локации

`$ hide_location()`

***

## Регистрация локации

`$ register_location("location_name", "path_to_images", is_room, xsize, ysize)`  
Где
* `location_name` - имя локации,
* `path_to_images` - путь к каталогу с картинками (png) локаций (относительно resources),  
Имена этих картинок (ожидается, что их размеры одинаковы):
	+ `main.png` - основное изображение,
	+ `over.png` - изображение с тем, что находится сверху и под чем персонажи могут проходить
		(может отсутствовать),
	+ `free.png` - изображение, где доступные для передвижения места закрашены цветом 0x000000FF (полностью чёрный и непрозрачный)
		(может отсутствовать, тогда персонаж может ходить где угодно),
* `is_room` - является ли данная локация помещением (`True`) или улицей (`False`),
влияет на масштабирование локации и необходимость нажатия "кнопки действия" для входа и выхода,
* `xsize` - ширина картинки `main.png` локации, целое число,
* `ysize` - высота картинки `main.png` локации, целое число.

Почему размеры нужно указывать вручную?  
Для ускорения запуска, потому что иначе для этого пришлось бы открывать все `main`-изображения, что долго.  
Размеры эти нужны для вычисления масштабирования (чтобы все локации и объекты на них имели один и тот же масштаб).

***

## Регистрация места в локации

`$ register_place("location_name", "place_name", x, y, ysize, xsize, to = None)`  
Где
* `location_name` - имя локации,
* `place_name` - имя места,
* `x`, `y` - координаты (целые числа) места в локации (отступ в пикселях от левого верхнего угла `main.png`),
* `xsize`, `ysize` - ширина и высота (целые числа) места (в пикселях).
* `to` - список из `3` или `4` параметров:
	1. `exit_side` - сторона выхода, противоположная сторона будет стороной входа, значения:
		`"left", "right", "up", "down"` (кавычки важны) - лево, право, верх и низ,
		а значение `None` означает, что вся площадь места целиком будет и входом и выходом,
	2. `"to_location_name"` - в какую локацию будет переход,
	3. `"to_place_name"` - в какое место в этой локации будет переход,
	4. `to_side` - сторона, в которую нужно повернуть игрока после перехода:
		* `None` - оставить как есть (по умолчанию, если отсутствует),
		* `to_left`, `to_right`, `to_forward`, `to_back` (всё без кавычек) - влево, вправо, вперёд и назад.

***

## Фоновые звуки

Вы можете захотеть установить для каждой локации звуки, которые бы воспроизводились при входе в неё и
останавливались бы при выходе. Например, завывание ветра или пение птиц.

Для этой цели существует функция  
`set_location_ambience("location_name", paths, volume = 1.0)`  
Где:
* `location_name` - название локации,
* `paths` - путь (или словарь (`dict`) путей),
* `volume` - громкость фоновых звуков.

Но указывать пути отдельно для каждой локации - дело довольно утомительное, поэтому существует функция  
`set_default_location_ambience("paths", volume = 1.0)`  
с аналогичными предыдущей функции параметрами.  
Она устанавливает пути и громкость по умолчанию для тех локаций, у которых фоновые звуки не установлены отдельно.

Также весьма часто может быть необходимо ставить разные звуки для разных [времён суток](./Времена-суток).
Именно для этого и существует возможность передавать вместо пути словарь путей.
Днём, например, в парке должно быть пение птиц, а ночью - стрекотание сверчков:
```python
set_location_ambience('park', {
	'night': 'sound/ambience/park_night.ogg',
	None:    'sound/ambience/park_day.ogg'
})
```
* Для ночи (`night`) будет воспроизводиться файл `sound/ambience/park_night.ogg`,
* Для всех остальных времён (утро/день/вечер) - `sound/ambience/park_day.ogg`.

Кстати, передача простой строки - всё равно, что передача словаря с ключом `None` и значением строки:
```python
set_location_ambience('name', 'sound/ambience/park_day.ogg') # то же самое, что и
set_location_ambience('name', {None: 'sound/ambience/park_day.ogg'}) # это
```

То же самое относится и к `paths` в `set_default_location_ambience`.

Вообще, поиск пути к файлу происходит примерно следующим образом:
* У текущей локации берётся путь к файлу по названию времени в качестве ключа в переданном словаре.
* Если такой ключ отсутствует, то в качестве ключа берётся `None`.
* Если после этого получено значение `None`, то первые 2 пункта проделываются для "общих" звуков.
* Если после этого получено не `None` и не пустая строка, то файл по полученному пути проигрывается.

Соответственно, если для локации в качестве пути к звуку указать пустую строку,
то при входе в неё звукового фона не будет вообще, и он не будет браться из "общих" звуков.

***

## Программный доступ к локациям и их "внутренностям"

Иногда (например, при реализации автопилота) нужно иметь доступ ко всем "внутренностям" локаций из питона.

Локации хранятся в словаре `rpg_locations`, где ключом выступает название локации (указанное при регистрации),
а значением - экземпляр класса `RpgLocation`. Например:  
`loc = rpg_locations['square']`

`RpgLocation` имеет свойства:
* `name` - название локации,
* `xsize`, `ysize`, `is_room` - параметры, указанные при регистрации (ширина, высота и "комнатность"),
* `places` - словарь мест (ключ - имя места, значение - экземпляр класса `RpgPlace`),
* `objects` - список объектов на локации (включая слои `main` и `over`, персонажей, обычные объекты и пользовательские).

Также имеются методы:
* `main(), over(), free()` для получения путей (или `None`) к соответствующим изображениям (с учётом системы времени),
* `get_place('place_name')` для получения места (или `None`, если такого места нет).

`RpgPlace` имеет свойства:
* `name` - название,
* `x`, `y`, `xsize`, `ysize`, а также
* `exit_side`, `to_location_name`, `to_place_name`, `to_side` - параметры, заданные при регистрации.

Методы:
* `inside(x, y)` - возвращает `True`, если точка `(x, y)` находится внутри, иначе - `False`,
* `inside_exit(x, y)` - `True`, если точка `(x, y)` находится внутри части выхода, иначе - `False`,
* `get_rect(of_exit = False)` - возвращает координаты прямоугольника `x, y, w, h`
	для выхода (если передан параметр `of_exit = True`) или места.

У объектов (и персонажей) обычно есть:
* такие нужные свойства как `x, y, xsize, ysize, crop, alpha`,
* менее часто-используемые свойства вроде `xanchor, yanchor, xoffset, yoffset`,
* метод `main()` и, возможно, методы `over()` и `free()` для возврата соответствующих изображений.

Следует учитывать, что эти свойства и методы желательны, но не обязательны, некоторых из них может и не быть.  
Например, пользовательский объект "Снегопад" вряд ли будет иметь метод `free()` или свойство `xanchor`, поэтому
при обработке списка объектов нужно проверять их существование при желании их использовать:
```python
for obj in loc.objects:
	# ...
	if obj.xanchor is not None:
		# ...
	
	# ...
	free = obj.free and obj.free()
	if free is not None:
		# ...
```

***

## Центр места

Для получения координат объекта или места можно использовать функцию `get_place_center`:  
`x, y = get_place_center(obj, anchor=None)`  
Где:
* `obj` обязан иметь свойства `x` и `y`, а также опционально `xsize`, `ysize`, `xanchor`, `yanchor` (при недоступности они будут приняты за `0`).
Иными словами, сюда подходят места (именно `RpgPlace`, а не названия мест), персонажи (`Character`), объекты (`RpgLocationObject`), словари (`dict`)
и просто любые объекты, которые позволяют получить доступ к нужным свойствам (`obj['x']`) и проверить наличие опциональных (`obj.has_key('xsize')`).
* `anchor` - точка в объекте, координату которой мы и хотим получить.
`None` (по умолчанию) означает, что для **персонажа** будет взята центральная нижняя точка (`(0.5, 1.0)`), для **остальных** же типов - центр (`(0.5, 0.5)`).

В случае, если `obj` является местом с выходом, возвращается центр прямоугольника, не включающего прямоугольник выхода
(т. к. в подавляющем большинстве случаев требуется именно такое поведение).

***

[Далее ->](./Объекты-локаций)  
[<- Назад](./Быстрый-старт-RPG)
