Фокусировка камеры

В одиночной игре скрипт может плавно направить камеру первого лица на точку или объект, уменьшить FOV и удерживать взгляд на цели. Позиция актёра не меняется. Не нужны бинокль, текстура прицела или файл анимации камеры.

API

local params = camera_focus_params()

-- Возвращают true, если режим запущен, иначе false.
db.actor:actor_focus_point(point, params)
db.actor:actor_focus_object(object, offset, params)

-- Использовать настроенный blend_out: -1. Немедленно закончить: 0.
db.actor:actor_stop_focus(-1)

local active = db.actor:actor_focus_active()
local state = db.actor:actor_focus_state()

point и offset — vector, object — онлайн game_object. Смещение прибавляется к позиции объекта в мировых координатах. Например, vector():set(0, 1.6, 0) направляет камеру выше основания NPC. Это постоянное смещение, а не привязка к кости головы.

Для запуска актёр должен быть жив, находиться под управлением игрока и использовать камеру первого лица. Запуск отклоняется в мультиплеере, на выделенном сервере, в диалоге, транспорте, при внешнем управлении камерой через абсолютный эффектор или demo_record. Сам актёр не может быть целью.

Ошибочные параметры, nil вместо объекта или вызов на другом типе объекта возвращают false и сохраняют текущую фокусировку. Параметры копируются при запуске; изменение Lua-объекта params не изменяет работающий режим.

Параметры

Поле	По умолчанию	Назначение
fov	35	Целевой угол обзора в градусах, от 5 до 170. Меньше — сильнее приближение.
blend_in	1	Длительность наведения и изменения FOV, в секундах.
hold_time	-1	Удержание после завершения наведения, в секундах. -1 — до явной отмены; 0 — сразу начать выход.
blend_out	0.5	Длительность выхода, в секундах.
tracking_speed	8	Скорость сглаживания слежения после наведения, в 1/с. Больше — быстрее реакция на движение цели.
lock_input	true	Заблокировать игровой ввод актёра до завершения выхода.
track	true	Обновлять позицию объекта каждый кадр. false — запомнить его позицию при запуске. Для точки не используется.
restore_direction	false	При выходе плавно вернуть исходное направление взгляда. false — оставить взгляд в последнем направлении.

Числа должны быть конечными. Длительности неотрицательны, кроме специального значения hold_time = -1. tracking_speed должен быть положительным. Длительность 0 задаёт мгновенный переход.

Вход и выход используют smoothstep. Слежение использует экспоненциальное сглаживание по времени кадра и кратчайший поворот через границу углов. Учитываются ограничения поворота камеры. Если цель совпадает с позицией камеры, сохраняется последнее направление.

Точка patrol-пути

function show_waypoint()
    if not db.actor then return false end

    local point = patrol("quest_view_point"):point(0)
    local params = camera_focus_params()
    params.fov = 30
    params.blend_in = 1.2
    params.hold_time = 3
    params.blend_out = 0.8
    params.restore_direction = true
    return db.actor:actor_focus_point(point, params)
end

Индекс точки начинается с нуля. Путь и индекс должны существовать: их проверка относится к API patrol, а не к фокусировке камеры.

Слежение за NPC

function watch_npc(npc)
    if not db.actor or not npc then return false end

    local params = camera_focus_params()
    params.fov = 40
    params.hold_time = -1
    params.track = true
    params.lock_input = true
    return db.actor:actor_focus_object(npc, vector():set(0, 1.6, 0), params)
end

function stop_watching()
    if db.actor then db.actor:actor_stop_focus(-1) end
end

Для свободного перемещения во время слежения задайте lock_input = false. Фокусировка продолжает управлять направлением камеры и FOV. После начала выхода направление освобождается, если не запрошен restore_direction.

Состояние и завершение

actor_focus_state()	Состояние
0	Неактивно
1	Наведение
2	Удержание / слежение
3	Выход

actor_focus_active() возвращает true и на фазе выхода. Завершение можно отследить из обычного update скрипта по переходу в состояние 0; Lua callback из обновления камеры не вызывается.

Повторный успешный запуск заменяет текущую цель и начинает переход от текущего направления и видимого FOV. Для restore_direction сохраняется направление до первого запуска в этой последовательности.

actor_stop_focus(seconds) задаёт длительность выхода для текущего режима. -1 использует blend_out. Повторная отмена не перезапускает выход. Другие отрицательные значения и неконечные числа игнорируются. При 0 ввод освобождается сразу; если запрошен возврат направления, он выполняется сразу.

При удалении отслеживаемого объекта начинается обычный выход. При track = false ссылка на объект не хранится, поэтому удаление объекта не прерывает просмотр сохранённой точки. Смерть NPC сама по себе не отменяет слежение, пока его объект существует.

Смерть актёра, загрузка сохранения, уничтожение/повторный спавн актёра, смена камеры, диалог, транспорт или передача управления другой сущности сбрасывают режим. Абсолютные эффекты камеры и demo_record имеют приоритет. При таких сбросах переход и возврат направления не выполняются. Режим не сохраняется в save-файле; квест при необходимости запускает его заново после загрузки.

При обычном выходе FOV возвращается к текущему значению игровой камеры, включая спринт и прицеливание. Пользовательская настройка FOV и глобальный g_fov не переписываются. Обычные эффекты камеры (качание, отдача, камера-риг) продолжают применяться поверх фокусировки.

При блокировке ввода прекращаются движение, стрельба и прицеливание. События отпускания кнопок продолжают обрабатываться, чтобы не оставлять действия зажатыми. Меню и консоль доступны. Система не вызывает level.enable_input() и не снимает запреты ввода других скриптов. После выхода ввод снова обрабатывается обычным способом, включая продолжающие удерживаться клавиши движения.

Система не скрывает HUD и оружие, не перемещает персонажа, не обеспечивает видимость цели через препятствия и не меняет игровое время.