API UO FindMobile

UO.FindMobile

UO API · Все команды · Constants & Special Values

Находит одного ближайшего загруженного персонажа/существо по совместным строковым фильтрам. Самого игрока исключает.

Точный синтаксис

UO.FindMobile() -> Integer
UO.FindMobile(stateFilter:Any) -> Integer
UO.FindMobile(stateFilter:Any, rangeFilter:Any) -> Integer
UO.FindMobile(stateFilter:Any, rangeFilter:Any, verticalFilter:Any) -> Integer
UO.FindMobile(stateFilter:Any, rangeFilter:Any, verticalFilter:Any, directionOrKind:Any) -> Integer
UO.FindMobile(stateFilter:Any, rangeFilter:Any, verticalFilter:Any, directionFilter:Any, kindFilter:Any) -> Integer

Выберите одну из зарегистрированных форм. Параметры передаются позиционно. Any означает значение BASIC с преобразованием внутри команды; Unit — отсутствие возвращаемого значения.

Параметры

• stateFilter — Обычно all / alive / dead; необязателен. Все аргументы в реализации являются строками фильтров, поэтому допустимо объединить несколько слов в одном аргументе.
• rangeFilter — Обычно all / near (0..4) / medium (5..9) / far (от 10 до общего радиуса). Числовой радиус в этой позиции не принимается; общий предел меняется через UO.FindDistance(value).
• verticalFilter — all / above / below. above: candidate.Z > self.Z, below: candidate.Z < self.Z. Это не этаж и не числовой допуск Z.
• directionOrKind — Четвёртая позиция формы с четырьмя аргументами: all, north/south/east/west или human/npc/mob. Может быть составной строкой.
• directionFilter — Четвёртая позиция формы с пятью аргументами: all или сравнение X/Y north/south/east/west. Это расположение относительно self, а не направление взгляда.
• kindFilter — Пятая позиция: all / human / npc / mob. human определяется списком graphic тела; npc — IsNpc и human; mob — IsNpc и НЕ human. Слово monster не принимается.

Возвращает

Integer: serial одного mobile, либо 0, если совпадений нет. Это не количество, не массив, не type и не Boolean. Проверка found <> 0 означает наличие результата; сравнение found = TRUE сравнивало бы ID с 1 и здесь неверно.

Поведение

• Применяется в UO.FindMobile: от 0 до 5 аргументов. Пропущенные хвостовые аргументы равны all. Каждый аргумент может содержать одно слово или несколько слов, разделённых пробелом, табуляцией, запятой, точкой с запятой, | или +. Все условия объединяются через AND; символ | здесь не означает OR.
• Поиск просматривает только загруженные mobiles, исключает self и ограничивает расстояние величиной max(1, UO.FindDistance()). Расстояние измеряется по правилу max(abs(dx), abs(dy)); диагональная клетка считается одной. Для движущихся объектов дистанция может учитывать очередь шагов, а сравнения X/Y/Z читают текущие координаты.
• Из подходящих выбирается ближайший; при равной дистанции — меньший serial. Возвращается Integer serial или 0, а не true/false, количество или массив.
• UO.FindMobile не меняет FindItem/FindCount/GetFoundItems, не применяет Ignore и UO.FindVertical, не проверяет видимость, проходимость или линию обзора. Он не выполняет перемещение, выбор target либо загрузку удалённых объектов.
• Числовые радиусы/Z/направления, слова monster, northeast, northwest, southeast, southwest не являются фильтрами. Неизвестное слово вызывает ошибку при проверке кандидата; если кандидатов нет, этот участок может не выполниться. Для диагональной области объединяйте north east и т. п.; для числовой проверки используйте свойства найденных объектов или UO.GetMobiles().

Как это выполняется внутри

Ниже описана реализация этого движка. Имена внутренних методов не являются дополнительными командами BASIC.

1. AddFilterValue

Регистрирует чтение bare-имени без скобок.

Возвращает String с написанием имени в нижнем регистре. Это строка-селектор, а не запускаемая процедура.

Исходник проекта: external/InjectionScript/src/InjectionScript/Runtime/InjectionApiUO.cs; функция AddFilterValue.

2. FindMobile

Дополняет отсутствующие аргументы значением all; получает список mobiles, координаты self и FindDistance.

Исключает self и кандидатов за горизонтальной границей.

Исходник проекта: external/InjectionScript/src/InjectionScript/Runtime/InjectionApiUO.cs; функция FindMobile.

3. ExpandMobileFilters / MatchesMobileFilters

Разбивает строки на отдельные слова и проверяет состояние, дистанцию, Z, X/Y и вид тела.

Каждый кандидат должен удовлетворить всем словам. above/below сравнивают высоты строго, near/medium/far имеют фиксированные границы.

Исходник проекта: external/InjectionScript/src/InjectionScript/Runtime/InjectionApiUO.cs; функция ExpandMobileFilters / MatchesMobileFilters.

4. OrderBy / ThenBy / FirstOrDefault

Сортирует прошедших по расстоянию, затем serial.

Первый serial становится результатом. Пустая выборка даёт Integer 0.

Исходник проекта: external/InjectionScript/src/InjectionScript/Runtime/InjectionApiUO.cs; функция OrderBy / ThenBy / FirstOrDefault.

Последовательность поиска можно увидеть в полностью приведённом помощнике FindAndDescribe ниже. Это пользовательская обёртка над реальной командой, а не обещание доступа ко всем внутренним методам.

Примеры

Пример 1. Поиск и проверка результата

SUB Main()
    # Высота объекта строго больше Z персонажа. Равная Z не подходит.
    VAR found = UO.FindMobile(all, all, above)
    IF found = 0 THEN
        UO.Print("No matching mobile")
        RETURN
    END IF
    # found — ID, а не graphic/type и не логическое значение.
    UO.Print("ID: " + CStr(found) + " | Name: " + UO.GetName(found))
    UO.Print("Z: " + CStr(UO.GetZ(found)) + " | Self Z: " + CStr(UO.GetZ(self)))
END SUB

Разбор параметров и выполнения:

• Передано all, all, above: Высота объекта строго больше Z персонажа. Равная Z не подходит.
• 0 обрабатывается до чтения свойств. Print показывает ID, имя и высоты; никакое игровое действие не запускается.

Пример 2. Сочетание условий с временным радиусом

SUB Main()
    # Радиус общий для FindMobile; сохраняем настройку скрипта.
    VAR previous = UO.FindDistance()
    TRY
        UO.FindDistance(18)
        VAR found = UO.FindMobile(alive, near, all, all, mob)
        IF found <> 0 THEN
            UO.Print("Match: " + CStr(found))
            UO.Print("Distance: " + CStr(UO.GetDistance(found)))
        ELSE
            UO.Print("No match in the loaded area")
        END IF
    FINALLY
        UO.FindDistance(previous)
    END TRY
END SUB

Разбор параметров и выполнения:

• 18 — внешний предел; alive, near, all, all, mob задаёт совместные условия. near остаётся диапазоном до 4, medium — 5..9, far — от 10.
• Finally возвращает прежний радиус при обычном завершении или обрабатываемой ошибке. Скрипт не расширяет загрузку мира.

Пример 3. Полная функция для составного фильтра

SUB Main()
    # Пробел объединяет условия через AND.
    VAR id = FindAndDescribe("north east")
    UO.Print("Returned ID: " + CStr(id))
END SUB

FUNCTION FindAndDescribe(filters)
    # filters — строка, например "north east".
    VAR id = UO.FindMobile(filters)
    IF id = 0 THEN
        UO.Print("Nothing matched: " + filters)
        RETURN 0
    END IF
    UO.Print(UO.GetName(id) + " | " + CStr(id))
    RETURN id
END FUNCTION

Разбор параметров и выполнения:

• В helper передаётся строка "north east". Это несколько условий одного запроса, а не последовательный поиск разных целей.
• FindAndDescribe объявлена целиком. Она возвращает ID/0, не меняя target или персонажа.

Пример 4. Найти существо и отдельно проверить точную дистанцию

SUB Main()
    # Этот вызов ищет ближайшего живого нечеловеческого NPC.
    VAR found = UO.FindMobile(alive, all, all, all, mob)
    IF found = 0 THEN
        UO.Print("No loaded creature")
        RETURN
    END IF
    # Число 2 — условие BASIC, а не строковый фильтр FindMobile.
    IF UO.GetDistance(found) <= 2 THEN
        UO.Print("Creature within two tiles: " + CStr(found))
    ELSE
        UO.Print("Nearest creature is farther away")
    END IF
END SUB

Разбор параметров и выполнения:

• alive/all/all/all/mob — пять поддерживаемых позиций. Дистанция 2 проверяется после получения ближайшего результата.
• Такой скрипт не проверяет путь до существа и не начинает движение.

Проверка примеров: скрипты загружены и выполнены в тестовом окружении движка с известными объектами и без выбранной цели/слоя. Отдельно проверены границы расстояния и высоты. Это не тест торговли на игровом сервере.