API UO MoveXY

UO.MoveXY

Оглавление · Алфавитный указатель · Movement

ClassicUO • Runtime API

Перемещает персонажа к X/Y с пятью обязательными параметрами и ожидает результат.

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

UO.MoveXY(Xdst:Any, Ydst:Any, Optimized:Any, Accuracy:Any, Running:Any) -> Any

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

Параметры

• Xdst / x — Мировая координата X назначения, 0..65535. Это не serial и не позиция внутри гампа.
• Ydst / y — Мировая координата Y назначения, 0..65535.
• Optimized — TRUE — обычный режим поиска и проверки пути вперёд; FALSE — уменьшенная эвристика и проверка ближайшего шага. FALSE не отключает обход препятствий.
• Accuracy — Допуск по X и Y в клетках: оба отклонения должны укладываться в него. Значение ограничивается диапазоном 0..20; 0 требует точных X/Y.
• Running — TRUE/1 — запрос бега, FALSE/0 — шаг. Серверные задержки движения сохраняются; это не множитель скорости.

Возвращает

Integer 1 — в конце проверки персонаж находится в заданном допуске X/Y/Z, в том числе когда уже был там до вызова. Integer 0 — недопустимые координаты, отказ запуска, недостигнутая точка или сработавшее условие остановки. Это не число шагов и не serial; при аварийной отмене процедура прерывается вместо обычного возврата 0.

Это логический результат: 1 = TRUE, 0 = FALSE. После VAR result = команда(...) можно писать IF result = TRUE THEN или IF result = 1 THEN; для отрицательного результата — IF result = FALSE THEN или IF result = 0 THEN. TRUE/FALSE пишутся без кавычек. Вызовите команду один раз и сохраните результат: повторный вызов может повторить действие или прочитать уже изменившееся состояние.

Поведение

• Полный маршрут A* строится до первого шага, короткими порциями между обновлениями клиента. При Optimized=TRUE проверяются следующие 4 клетки пути; при FALSE — ближайший шаг. Это проверка уже рассчитанного пути, а не дальность всего маршрута и не ползунки обхода при движении мышью.
• Отказ сервера DenyWalk или новое препятствие запрашивает перерасчёт от текущей позиции после завершения очереди шагов. Число повторов и частота перерасчёта ограничены; отсутствие пути может завершить движение с 0.
• Маршрут принадлежит запустившей его процедуре: её аварийная остановка отменяет оставшийся автоматический путь. Если другой запуск или пользователь уже заменил маршрут, отмена прежнего владельца новый маршрут не трогает. Уже отправленные шаги не отзываются.
• SetBadLocation и SetBadObject применяются как снимок запретов текущего runtime при запуске маршрута. Они сохраняются при его внутреннем перерасчёте. Изменение или очистка списков влияет на следующий маршрут, а не переписывает уже выполняющийся.
• После принятия запроса вызов ждёт на потоке скрипта. Первоначальный поиск и пересчёт выполняются на игровом потоке порциями: максимум 32 раскрытия узлов и мягкий бюджет около 1 мс за порцию. Одна сложная проверка клетки или чтение карты может превысить этот бюджет. Между порциями клиент продолжает обновления; полный лимит поиска остаётся 10000 узлов.
• timeout отсчитывается после принятия запроса и включает последующие порции поиска и пересчёта. stopOnStuck не считает работающий поиск застреванием персонажа; после завершения планирования отсутствие изменений позиции снова учитывается. Итоговый 1/0 проверяет фактические координаты, а не только готовность пути.
• Результат учитывает локальную позицию клиента; последующая серверная коррекция всё ещё возможна. Запуск конкурирующих команд движения из разных процедур меняет общий маршрут персонажа.
• Настройки moveCheckStamina, moveExitOnDisconnect, moveOpenDoor, moveThroughCorner, moveThroughNPC, moveHeuristicMult, moveTurnCost и moveBetweenTwoCorners влияют на исполнение. Явные avoidMobiles/openDoors заменяют соответствующие значения для этого вызова.
• Результат 0 не сообщает точную причину. Проверяйте координаты, соединение, выносливость и журнал; не повторяйте движение бесконечно без WAIT и лимита попыток.
• Целевой Z берётся при вызове, допуск Z=255. Для дополнительных ограничений используйте NewMoveXY; для выбора высоты — MoveXYZ.

Внутренние функции: от вызова до результата

Ниже разобрана реальная цепочка клиента. Это описание внутренних C#-функций, а не дополнительные команды BASIC. Запускаемые функции примеров, включая GoToPoint и AfterStep, объявлены целиком в разделе «Примеры».

1. ExecuteStealthCompatibility

Ветка MoveXY разбирает пять аргументов X/Y/Optimized/Accuracy/Running; локальная функция MoveTo направляет их в MoveToCanonical с текущей Z и accuracyZ=255.

Передаёт подготовленные значения в MoveToCanonical. Это внутренний C#-метод; его имя нельзя вызвать как UO-команду.

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

2. MoveToCanonical

Принимает X/Y/Z, допуски и ограничения вызова. Проверяет диапазон координат, соединение, выносливость и maxDistance; ограничивает accuracy до 0..20, accuracyZ до 0..255. Уже достигнутая цель даёт 1 без нового поиска.

После bridge.MoveTo ждёт bridge.Move(), читает положение, проверяет timeout, callback, maxSteps и stopOnStuck. Между проверками вызывает bridge.Wait(5). После окончания сравнивает фактические координаты с допусками. Возврат 1/0 относится к достижению, а не к принятию маршрута.

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

3. MoveTo

Передаёт параметры из потока скрипта на игровой поток через Invoke. Создаёт снимок SetBadLocation/SetBadObject, вызывает Pathfinder.WalkTo и запоминает поколение маршрута для отмены владельцем.

Возвращает 1, если WalkTo принял маршрут, иначе 0. Это промежуточный результат: сама команда ещё ждёт завершения и проверяет цель.

Исходник проекта: src/ClassicUO.Client/Game/Managers/ClassicUOInjectionApiBridge.cs; функция MoveTo.

4. WalkTo

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

Вызовы из скрипта, интерфейса, следования и серверного запроса включают incremental: BeginPathSearch готовит поиск, AdvancePathSearch выполняет первую порцию. true может означать принятый незавершённый поиск; передвижение начинается только после полного пути. Старый синхронный режим C# сохранён для совместимости нативного PluginHost.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция WalkTo.

5. ResetSearchNodes

Аргументов нет. Сбрасывает использованные узлы, индексы открытых/закрытых состояний, очередь приоритетов, свободные слоты и длину пути.

Возвращаемого значения нет. Уже выделенные объекты узлов переиспользуются; это уменьшает повторные выделения памяти, но не меняет проходимость.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция ResetSearchNodes.

6. SetSearchStart

Аргументов нет. Получает GetEndPosition — положение после уже поставленных в очередь шагов и текущее направление.

Сохраняет старт X/Y/Z/направление и карту. При пересчёте ProcessAutoWalk сначала дожидается освобождения очереди; если исходная позиция или карта изменились между порциями, поиск запускается заново от актуальной точки.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция SetSearchStart.

7. FindPath

Принимает maxNodes. Синхронная совместимая обёртка: вызывает BeginPathSearch, затем AdvancePathSearch до завершения. Основные клиентские вызовы используют порции через ProcessAutoWalk и не вызывают эту обёртку.

true — полный путь построен; false — путь не найден в пределах лимитов. Этот C#-режим может занимать весь поиск за один вызов и сохранён для существующего контракта нативных плагинов.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция FindPath.

8. BeginPathSearch

Принимает общий maxNodes. Очищает признак результата, создаёт стартовый узел с X/Y/Z/направлением, задаёт оценку и сохраняет текущую позицию поиска.

Возвращаемого значения нет: состояние становится pending. Если старт уже в допусках X/Y/Z, сразу сохраняет одноточечный путь и состояние успеха. Пакеты движения здесь не отправляются.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция BeginPathSearch.

9. AdvancePathSearch

Аргументов нет: продолжает сохранённый поиск. Раскрывает максимум 32 узла через OpenNodes/FindCheapestNode. После примерно 1 мс возвращается между раскрытиями, оставляя очередь, родителей и текущий узел для следующего обновления.

При извлечении цели восстанавливает полный путь по Parent, включая старт, и отмечает успех. При исчерпании очереди или общего лимита отмечает неудачу. До завершения оставляет pending. Бюджет времени мягкий: текущее раскрытие и чтение геометрии сначала заканчиваются.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция AdvancePathSearch.

10. OpenNodes

Принимает текущий PathNode. Пробует восемь направлений через CanWalk. Если проверка сменила направление вместо запрошенного, такой сосед не добавляется.

Для допустимого соседа вызывает AddNodeToList; true означает, что хотя бы одно добавление не сообщило переполнение. Это не признак достижения конечной цели.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция OpenNodes.

11. CanWalk

Принимает направление и X/Y/Z по ссылке. GetNewXY выбирает соседнюю клетку; CalculateNewZ проверяет высоту и объекты, затем учитываются правила диагональных углов.

Возвращает bool проходимости и может изменить направление/координаты. Поэтому OpenNodes и ValidatePathLookahead проверяют не только true, но и совпадение с требуемым направлением и точкой.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция CanWalk.

12. GetNewXY

Принимает числовое направление, X и Y по ссылке. По таблице направлений добавляет смещение на одну клетку.

Меняет X/Y; ничего не отправляет серверу и не проверяет высоту или препятствия.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция GetNewXY.

13. CalculateNewZ

Принимает X/Y назначения, исходную Z по ссылке и направление. Учитывает прикладной запрет клетки и режим персонажа: обычный, мёртвый/GM, полёт или морской конёк. CalculateMinMaxZ вычисляет границы подъёма, CreateItemList собирает поверхности и препятствия.

Проверяет допустимый просвет и поверхность, при успехе записывает подходящую Z и возвращает true. false означает отсутствие допустимого локального прохода; сервер может иметь дополнительные правила.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция CalculateNewZ.

14. CalculateMinMaxZ

Получает границы высоты по ссылке, координаты/высоту, направление и режим движения. По исходной клетке, поверхностям и мостам уточняет нижнюю и верхнюю границы шага.

Возвращает вычисленную верхнюю границу и обновляет аргументы minZ/maxZ; при отсутствии исходной геометрии возвращает 0. Это вспомогательный расчёт геометрии, а не номер этажа или готовая команда движения.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция CalculateMinMaxZ.

15. CreateItemList

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

false — исходная клетка не получена из карты; true — сбор завершён, наполнение списка проверяется отдельно. Фильтры зависят от флагов персонажа, tiledata, настроек прохода и открывания дверей; функция не загружает весь неизвестный серверный мир.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция CreateItemList.

16. NodeKey

Получает X/Y/Z и направление. Формирует ключ состояния для словаря и множества.

При ненулевой цене поворота включает направление; иначе направление в ключе равно 0. Так одинаковые координаты с разным будущим штрафом поворота не объединяются ошибочно.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция NodeKey.

17. MovementCost

Получает родительский узел, направление нового шага и вид ребра. Для скриптов прямой шаг стоит 10, диагональный — 14. Если направление изменилось, добавляет moveTurnCost, ограниченный внутри WalkTo до 100000.

Возвращает стоимость одного ребра. Это внутренние весовые единицы, не миллисекунды, не число уже сделанных шагов и не скорость бега.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция MovementCost.

18. GetGoalDistCost

Получает точку-кандидат. dx=max(0,abs(goalX-X)-accuracy), dy=max(0,abs(goalY-Y)-accuracy). Для скриптов h=(10max(dx,dy)+4min(dx,dy))*multiplier/100 с целочисленным делением и ограничением сверху.

При Optimized=TRUE берётся moveHeuristicMult (по умолчанию 93, минимум 1); при FALSE используется 1. Высота проверяется при выборе цели и проходимости, а не прибавляется к этой эвристике. При значении выше 100 оптимальность по стоимости уже не гарантируется.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция GetGoalDistCost.

19. AddNodeToList

Получает тип списка, направление, X/Y/Z, родителя и вид ребра. Закрытые состояния не добавляет повторно. Для открытого состояния оставляет меньшую стоимость g; для нового выделяет или переиспользует слот. При закрытии переносит данные в стабильный закрытый узел.

Сохраняет Parent и f=g+h, добавляет приоритет в очередь. Возвращает индекс, -1 при нехватке места. Словарь/множество заменяют линейный поиск по 10000 ячейкам.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция AddNodeToList.

20. FindCheapestNode

Извлекает минимальный приоритет из очереди, пропускает устаревшие записи после уменьшения стоимости или переиспользования слота. Проверяет актуальный индекс состояния.

Закрывает узел; только теперь отмечает достигнутую цель. Возвращает индекс закрытого узла либо -1. Обнаружить цель среди соседей недостаточно для выбора лучшего маршрута.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция FindCheapestNode.

21. ValidatePathLookahead

Принимает индекс пути и прогнозируемое положение X/Y/Z. Проверяет до 4 следующих клеток при Optimized=TRUE, одну при FALSE, последовательно вызывая CanWalk.

true — все проверенные направления и X/Y/Z совпали с планом; false — нужен пересчёт. Это проверка части уже построенного пути, а не ограничение дальности всей цели.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция ValidatePathLookahead.

22. NotifyWalkDenied

Вызывается обработчиком отказа/коррекции шага. Если маршрут активен, выставляет флаг необходимости пересчёта.

Сам путь здесь не рассчитывается и новый пакет движения не отправляется.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция NotifyWalkDenied.

23. RebuildPathFromCurrentPosition

Аргументов нет. При отсутствии персонажа или восьми попытках без продвижения возвращает false. Сбрасывает поиск, обновляет старт, увеличивает счётчик и назначает следующий пересчёт не раньше чем через 40 мс.

Сохраняет цель и правила. В incremental-режиме начинает новый поиск через BeginPathSearch и возвращает true как принятие пересчёта; ProcessAutoWalk позже завершает его порциями. Синхронная ветка вызывает FindPath. false — повтор не принят либо синхронный поиск не удался. Изменение X/Y/Z сбрасывает счётчик попыток.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция RebuildPathFromCurrentPosition.

24. ProcessAutoWalk

Проверяет наличие персонажа, соединение/выносливость, актуальность старта и карты; при пересчёте ждёт окончания очереди и cooldown. Выполняет одну порцию незавершённого поиска. Пока путь не готов, шагов не отправляет. Затем соблюдает лимит Walker, выравнивает индекс по GetEndPosition и вызывает ValidatePathLookahead.

При openDoors пытается открыть соседнюю дверь через TryOpenDoor, затем делает Player.Walk. Отказ локального шага запрашивает пересчёт. Эта процедура вызывается клиентом при обновлениях; она не раскручивает бесконечный цикл отправки пакетов.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция ProcessAutoWalk.

25. StopAutoWalk

Останавливает автопуть и незавершённый поиск, меняет поколение, очищает параметры, запреты и флаг пересчёта. Последующие обновления не могут возобновить отменённый поиск.

Не отзывает уже отправленные серверу шаги. Поэтому остановка запроса не равна мгновенному откату позиции.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция StopAutoWalk.

26. StopAutoWalkIfGeneration

Получает сохранённый номер поколения маршрута.

Останавливает путь только при совпадении поколения. Отмена старого скрипта не отменяет новый маршрут другого владельца.

Исходник проекта: src/ClassicUO.Client/Game/Pathfinder.cs; функция StopAutoWalkIfGeneration.

Оптимизации здесь имеют конкретный смысл: очередь приоритетов, индексы состояний, повторное использование узлов, проверка ближайших клеток и ограниченный пересчёт. Они не увеличивают разрешённую сервером скорость. Ползунки обхода при ручном движении мышью относятся к другому механизму; Optimized и moveHeuristicMult не заменяют эти ползунки.

Примеры

Пример 1. Точная точка пешком

# Точная точка пешком
#
# Перемещает персонажа к X/Y с пятью обязательными параметрами и ожидает результат.
#
# Integer 1 — в конце проверки персонаж находится в заданном допуске X/Y/Z, в том числе когда
# уже был там до вызова. Integer 0 — недопустимые координаты, отказ запуска, недостигнутая точка
# или сработавшее условие остановки. Это не число шагов и не serial; при аварийной отмене
# процедура прерывается вместо обычного возврата 0.
#
# Это логический результат: 1 = TRUE, 0 = FALSE. После VAR result = команда(...) можно писать IF
# result = TRUE THEN или IF result = 1 THEN; для отрицательного результата — IF result = FALSE
# THEN или IF result = 0 THEN. TRUE/FALSE пишутся без кавычек. Вызовите команду один раз и
# сохраните результат: повторный вызов может повторить действие или прочитать уже изменившееся
# состояние.

SUB Main()
    # Xdst — две клетки восточнее; Ydst не меняется.
    # Optimized=TRUE, Accuracy=0, Running=FALSE. Вызов возвращает результат после завершения.

    VAR ok = UO.MoveXY(UO.GetX() + 2, UO.GetY(), TRUE, 0, FALSE)
    UO.Print(STR(ok))
END SUB

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

• Xdst — две клетки восточнее; Ydst не меняется.
• Optimized=TRUE, Accuracy=0, Running=FALSE. Вызов возвращает результат после завершения.

Пример 2. Подойти к объекту

# Подойти к объекту
#
# Перемещает персонажа к X/Y с пятью обязательными параметрами и ожидает результат.
#
# Integer 1 — в конце проверки персонаж находится в заданном допуске X/Y/Z, в том числе когда
# уже был там до вызова. Integer 0 — недопустимые координаты, отказ запуска, недостигнутая точка
# или сработавшее условие остановки. Это не число шагов и не serial; при аварийной отмене
# процедура прерывается вместо обычного возврата 0.
#
# Это логический результат: 1 = TRUE, 0 = FALSE. После VAR result = команда(...) можно писать IF
# result = TRUE THEN или IF result = 1 THEN; для отрицательного результата — IF result = FALSE
# THEN или IF result = 0 THEN. TRUE/FALSE пишутся без кавычек. Вызовите команду один раз и
# сохраните результат: повторный вызов может повторить действие или прочитать уже изменившееся
# состояние.

SUB Main()
    # Xdst/Ydst читаются из выбранного объекта; он должен быть объектом мира, не предметом внутри
    # контейнера.
    # Accuracy=1 позволяет стать рядом; Running=TRUE. Высота не ограничивается этим вызовом.

    IF UO.Exists('lasttarget') THEN
        VAR ok = UO.MoveXY(UO.GetX('lasttarget'), UO.GetY('lasttarget'), TRUE, 1, TRUE)
        UO.Print('Approach result: ' + STR(ok))
    END IF
END SUB

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

• Xdst/Ydst читаются из выбранного объекта; он должен быть объектом мира, не предметом внутри контейнера.
• Accuracy=1 позволяет стать рядом; Running=TRUE. Высота не ограничивается этим вызовом.

Пример 3. Временно задать минимальную выносливость

# Временно задать минимальную выносливость
#
# Перемещает персонажа к X/Y с пятью обязательными параметрами и ожидает результат.
#
# Integer 1 — в конце проверки персонаж находится в заданном допуске X/Y/Z, в том числе когда
# уже был там до вызова. Integer 0 — недопустимые координаты, отказ запуска, недостигнутая точка
# или сработавшее условие остановки. Это не число шагов и не serial; при аварийной отмене
# процедура прерывается вместо обычного возврата 0.
#
# Это логический результат: 1 = TRUE, 0 = FALSE. После VAR result = команда(...) можно писать IF
# result = TRUE THEN или IF result = 1 THEN; для отрицательного результата — IF result = FALSE
# THEN или IF result = 0 THEN. TRUE/FALSE пишутся без кавычек. Вызовите команду один раз и
# сохраните результат: повторный вызов может повторить действие или прочитать уже изменившееся
# состояние.

SUB Main()
    # Цель 1445/1690 замените своей. Порог выносливости задаётся отдельной настройкой, не шестым
    # параметром MoveXY.
    # После нормального возврата исходное значение восстанавливается. При аварийном прерывании
    # дальнейшие строки не выполняются.

    VAR previous = UO.moveCheckStamina()
    UO.moveCheckStamina(15)
    VAR ok = UO.MoveXY(1445, 1690, TRUE, 0, FALSE)
    UO.moveCheckStamina(previous)
    UO.Print(STR(ok))
END SUB

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

• Цель 1445/1690 замените своей. Порог выносливости задаётся отдельной настройкой, не шестым параметром MoveXY.
• После нормального возврата исходное значение восстанавливается. При аварийном прерывании дальнейшие строки не выполняются.