Локации - TrueCat17/Ren-Engine GitHub Wiki

$ 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 параметров (или None - просто место, не выход):
  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)
с аналогичными предыдущей функции параметрами.
Она устанавливает пути и громкость по умолчанию для тех локаций, у которых фоновые звуки не установлены отдельно.

Также весьма часто может быть необходимо ставить разные звуки для разных времён суток. Именно для этого и существует возможность передавать вместо пути словарь путей. Днём, например, в парке должно быть пение птиц, а ночью - стрекотание сверчков:

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 и значением строки:

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(), free() и, возможно, метод over() для возврата соответствующих изображений.

Следует учитывать, что эти свойства и методы желательны, но не обязательны, некоторых из них может и не быть.
Например, пользовательский объект "Снегопад" вряд ли будет иметь метод over() или свойство xanchor, поэтому при обработке списка объектов нужно проверять их существование при желании их использовать:

for obj in loc.objects:
	# ...
	if 'xanchor' in obj:
		# ...
	
	# ...
	over = obj.over and obj.over()
	if over is not None:
		# ...

Отдельно стоит отметить, что метод free() должен быть всегда (пусть даже он всегда возвращает 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']) и проверить наличие опциональных ('xsize' in obj).
• anchor - точка в объекте, координату которой мы и хотим получить. None (по умолчанию) означает, что для персонажа будет взята центральная нижняя точка ((0.5, 1.0)), для остальных же типов - центр ((0.5, 0.5)).

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

Далее ->
<- Назад