Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

NavigationPathQueryObject 사용

팁

경로 쿼리 매개변수는 경로 찾기 성능을 향상하거나 메모리 소비를 낮추기 위한 다양한 옵션을 제공합니다.

이는 높은 수준의 노드가 항상 처리할 수 없는 고급 경로 찾기 요구 사항을 충족합니다.

아래의 해당 옵션 섹션을 참조하세요.

``NavigationPathQueryObjects``를 ``NavigationServer.query_path()``와 함께 사용하면 경로에 대한 선택적 메타데이터**를 포함하여 크게 **맞춤형 탐색 경로를 얻을 수 있습니다.

일반 NavigationPath를 얻는 것보다 더 많은 설정이 필요하지만 경로 찾기 및 제공된 경로 데이터를 프로젝트의 다양한 요구 사항에 맞게 조정할 수 있습니다.

NavigationPathQueryObjects는 한 쌍의 객체, 즉 쿼리에 대한 사용자 정의 옵션을 보유하는 NavigationPathQueryParameters 객체와 쿼리의 결과 경로 및 메타데이터로 (정기) 업데이트를 수신하는 ``NavigationPathQueryResult``로 구성됩니다.

``NavigationPathQueryParameters``의 2D 및 3D 버전은 각각 NavigationPathQueryParameters2D 및 :ref:`NavigationPathQueryParameters3D<class_NavigationPathQueryParameters3D>`로 제공됩니다.

``NavigationPathQueryResult``의 2D 및 3D 버전은 각각 NavigationPathQueryResult2D 및 :ref:`NavigationPathQueryResult3D<class_NavigationPathQueryResult3D>`로 제공됩니다.

기초 경로 쿼리 만들기

매개변수와 결과는 모두 NavigationServer.query_path() 기능과 함께 쌍으로 사용됩니다.

사용 가능한 사용자 정의 옵션은 아래를 참조하세요. 클래스 참조의 각 매개변수에 대한 설명도 참조하세요.

엄격한 요구 사항은 아니지만 두 개체 모두 미리 한 번 생성되어 에이전트의 영구 변수에 저장되고 업데이트된 매개 변수를 사용하여 모든 후속 경로 쿼리에 재사용됩니다.

동일한 객체를 재사용하면 객체를 자주 생성하거나 메모리를 할당할 때 성능이 향상됩니다.

다음 스크립트는 객체를 생성하고 query_path() 함수를 제공하여 새 탐색 경로를 생성합니다. 결과 경로는 객체를 재사용하는 동안 ``NavigationServer.map_get_path()``를 사용하는 것과 동일합니다.

extends Node2D

# Prepare query objects.
var query_parameters := NavigationPathQueryParameters2D.new()
var query_result := NavigationPathQueryResult2D.new()

func query_path(p_start_position: Vector2, p_target_position: Vector2, p_navigation_layers: int = 1) -> PackedVector2Array:
    if not is_inside_tree():
        return PackedVector2Array()

    var map: RID = get_world_2d().get_navigation_map()

    if NavigationServer2D.map_get_iteration_id(map) == 0:
        # This map has never synced and is empty, no point in querying it.
        return PackedVector2Array()

    query_parameters.map = map
    query_parameters.start_position = p_start_position
    query_parameters.target_position = p_target_position
    query_parameters.navigation_layers = p_navigation_layers

    NavigationServer2D.query_path(query_parameters, query_result)
    var path: PackedVector2Array = query_result.get_path()

    return path

프로세싱(Processing)

내비게이션 메시 폴리곤 레이아웃에 따른 경로 후처리 차이

내비게이션 메시 다각형 레이아웃에 따른 경로 후처리 차이.

경로 쿼리 검색은 가장 가까운 내비게이션 메시 다각형 가장자리에서 사용 가능한 다각형을 따라 가장 가까운 가장자리로 이동합니다. 가능하다면 목표 위치 폴리곤을 향해 폴리곤 복도를 만듭니다.

이 원시 "검색" 다각형 복도 경로는 그다지 최적화되지 않았으며 일반적으로 에이전트가 이동하기에 적합하지 않습니다. 예: 내비게이션 메시 다각형에서 가장 가까운 가장자리 지점은 더 큰 다각형에 있는 에이전트에게 큰 우회를 초래할 수 있습니다. 쿼리에서 반환된 경로의 품질을 향상시키기 위해 다양한 path_postprocessing 옵션이 존재합니다.

  • PATH_POSTPROCESSING_CORRIDORFUNNEL 후처리는 사용 가능한 다각형 복도 내부 모퉁이 주위에 경로를 퍼널링하여 경로를 단축합니다.

    이는 기본 후처리이며 일반적으로 **사용 가능한 다각형 복도 내부**에서 최단 경로 결과를 제공하므로 가장 유용합니다. 폴리곤 복도가 이미 최적이 아닌 경우(예: 최적이 아닌 탐색 메시 레이아웃으로 인해 깔때기가 예상치 못한 다각형 모서리에 맞춰져 우회할 수 있습니다.

  • PATH_POSTPROCESSING_EDGECENTERED 사후 처리는 모든 경로 지점이 교차된 다각형 가장자리의 사용 가능한 다각형 복도 내부에 배치되도록 강제합니다.

    이 후처리는 일반적으로 크기가 모두 균일하고 예상 경로 따르기도 셀 중심으로 제한되는 엄격한 타일형 내비게이션 메시 다각형과 함께 사용될 때만 유용합니다. 그리드 셀 중심으로 이동이 제한된 일반적인 그리드 게임입니다.

  • PATH_POSTPROCESSING_NONE 사후 처리는 **사용 가능한 다각형 복도 내부**에서 경로 찾기가 이동한 방식대로 경로를 반환합니다.

    이 사후 처리는 경로 검색이 가장 가까운 가장자리 지점에서 가장 가까운 가장자리 지점으로 이동한 방법과 선택한 다각형을 보여주기 때문에 디버그에 매우 유용합니다. 예상치 못한 경로나 최적이 아닌 경로 결과는 이 원시 경로와 다각형 통로를 보면 즉시 설명될 수 있습니다.

간단한 애니메이션 만들기

팁

경로 단순화는 얇은 다각형 가장자리에서 흔들리는 에이전트나 에이전트를 조정하는 데 도움이 될 수 있습니다.

경로 단순화 유무에 따른 경로 지점 차이

경로 단순화 유무에 따른 경로 지점 차이.

``simplify_path``가 활성화되면 Ramer-Douglas-Peucker 경로 단순화 알고리즘의 변형이 경로에 적용됩니다. 이 알고리즘은 사용된 ``simplify_epsilon``에 따라 관련성이 낮은 경로 점을 제거하여 경로를 직선화합니다.

경로 단순화는 불필요한 다각형 가장자리가 많아 발생하는 "개방 필드"의 모든 종류의 에이전트 이동 문제를 해결하는 데 도움이 됩니다. 예: 내비게이션 메시에 구워진 지형 메시는 지형의 모든 작은(그러나 경로 찾기의 경우 거의 무의미한) 높이 변화로 인해 과도한 다각형 수를 유발할 수 있습니다.

경로 단순화는 에이전트가 목표로 삼을 중요한 코너 경로 지점만 더 많이 갖고 있기 때문에 "조정" 에이전트에도 도움이 됩니다.

경고

경로 단순화는 경로의 추가적인 최종 후처리입니다. 쿼리에 추가 성능 비용이 추가되므로 실제로 필요할 때만 활성화합니다.

참고

경로 단순화는 NavigationServer에 일반 기능으로 노출됩니다. 모든 종류의 위치 배열에 대한 탐색 쿼리 외부에서도 사용할 수 있습니다.

경로 메타데이터

팁

불필요한 경로 메타데이터 옵션을 비활성화하면 성능이 향상되고 메모리 소비가 줄어들 수 있습니다.

경로 쿼리는 모든 경로 지점에 대한 추가 메타데이터를 반환할 수 있습니다.

  • PATH_METADATA_INCLUDE_TYPES 플래그는 포인트 소유자에 대한 기본 정보가 포함된 배열을 수집합니다. 포인트가 지역이나 링크에 속하는 경우.

  • PATH_METADATA_INCLUDE_RIDS 플래그는 포인트 소유자의 :ref:`RIDs<class_RID>`가 포함된 배열을 수집합니다. 포인트 소유자 프리미티브에 따라 이러한 RID는 지역 또는 링크와 관련된 다양한 NavigationServer 기능과 함께 사용될 수 있습니다.

  • PATH_METADATA_INCLUDE_OWNERS 플래그는 포인트 소유자의 ``ObjectIDs``가 포함된 배열을 수집합니다. 이러한 객체 ID는 :ref:`@GlobalScope.instance_from_id()<class_@GlobalScope_method_instance_from_id>`와 함께 사용하여 해당 객체 인스턴스 뒤의 노드를 검색할 수 있습니다. NavigationRegion 또는 NavigationLink 노드.

기본적으로 모든 경로 메타데이터는 고급 탐색 게임플레이에 필수적일 수 있으므로 수집됩니다.

  • 예: 어떤 경로 점이 SceneTree 내부의 어떤 객체 또는 노드 소유자에 매핑되는지 확인합니다.

  • 예: 경로 지점이 스크립트된 인계가 필요한 탐색 링크의 시작 또는 끝인지 확인합니다.

가장 기본적인 경로 사용의 경우 메타데이터가 항상 필요한 것은 아닙니다. 일부 성능을 얻고 메모리 소비를 줄이기 위해 경로 메타데이터 수집을 선택적으로 비활성화할 수 있습니다.

지역 제외 또는 포함

팁

지역 필터는 지역으로 분할된 대규모 내비게이션 지도의 성능에 큰 도움이 될 수 있습니다.

쿼리 매개변수를 사용하면 경로 찾기를 특정 영역 탐색 메시로 제한할 수 있습니다.

큰 내비게이션 지도가 더 작은 영역으로 잘 분할되어 있는 경우 쿼리가 경로 검색의 초기 확인 중 하나에서 많은 수의 다각형을 건너뛸 수 있으므로 이는 성능에 큰 도움이 될 수 있습니다.

  • 기본적으로 비어 있는 경우 쿼리된 내비게이션 지도의 모든 영역이 포함됩니다.

  • 영역 RID<class_RID>`가 ``excluded_regions` 배열에 추가되면 경로 검색에서 해당 영역의 탐색 메시가 무시됩니다.

  • 영역 RID<class_RID>`가 ``included_regions` 배열에 추가되면 해당 영역의 탐색 메시가 경로 검색에서 고려되며 포함되지 않은 다른 모든 영역도 무시됩니다.

  • 지역이 포함됨과 제외됨이 모두 종료되면 제외된 것으로 간주됩니다.

영역 필터는 그리드에 정렬된 탐색 영역 청크와 쌍을 이룰 때 성능에 매우 효과적입니다. 이렇게 하면 전체 내비게이션 지도 대신 시작 위치 청크와 주변 청크만 포함하도록 필터를 설정할 수 있습니다.

대상이 이러한 주변 청크 외부에 있더라도(항상 더 많은 "링"을 추가할 수 있음) 경로 찾기는 대상에 가장 가까운 다각형에 대한 경로를 만들려고 시도합니다. 이는 일반적으로 전체 지도 검색 성능 비용의 일부에 해당하는 일반 방향으로 향하는 절반 경로를 생성합니다.

기본 경로 쿼리 스크립트에 다음 추가 내용은 영역 청크 매핑을 영역 필터와 통합하는 방법을 보여줍니다. 이것은 완전한 작업 예가 아닙니다.

extends Node2D

# ...

var chunk_id_to_region_rid: Dictionary[Vector2i, RID] = {}

func query_path(p_start_position: Vector2, p_target_position: Vector2, p_navigation_layers: int = 1) -> PackedVector2Array:

    # ...

    var regions_around_start_position: Array[RID] = []

    var chunk_rings: int = 1 # Increase for very small regions or more quality.
    var start_chunk_id: Vector2i = floor(p_start_position / float(chunk_size))

    for y: int in range(start_chunk_id.y - chunk_rings, start_chunk_id.y + chunk_rings):
        for x: int in range(start_chunk_id.x - chunk_rings, start_chunk_id.x + chunk_rings):
            var chunk_id: Vector2i = Vector2i(x, y)
            if chunk_id_to_region_rid.has(chunk_id):
                var region: RID = chunk_id_to_region_rid[chunk_id]
                regions_around_start_position.push_back(region)

    query_parameters.included_regions = regions_around_start_position

    # ...

경로 클리핑 및 제한

팁

합리적으로 설정된 제한은 특히 목표에 도달할 수 없는 경우 대형 내비게이션 지도의 성능에 큰 도움이 됩니다.

반환된 경로를 특정 거리까지 클리핑

반환된 경로를 특정 거리까지 클리핑합니다.

쿼리 매개변수를 사용하면 반환된 경로를 특정 길이로 클리핑할 수 있습니다. 이러한 옵션은 사후 처리의 일부로 경로를 자릅니다. 경로는 여전히 전체 길이인 것처럼 검색되므로 동일한 품질을 갖게 됩니다. 경로 길이 클리핑은 제한된 게임플레이에 더 적합한 경로를 만드는 데 도움이 될 수 있습니다. 이동 범위가 제한된 전술 게임.

  • path_return_max_length 속성은 반환된 경로를 특정 최대 길이로 자르는 데 사용할 수 있습니다.

  • path_return_max_radius 속성을 사용하면 시작 위치 주변의 원(2D) 또는 구(3D) 반경 내에서 반환된 경로를 클리핑할 수 있습니다.

쿼리 매개변수를 사용하면 특정 거리 또는 검색된 특정 수의 다각형까지만 검색하도록 경로 검색을 제한할 수 있습니다. 이러한 옵션은 성능을 위한 것이며 경로 검색에 직접적인 영향을 미칩니다.

  • path_search_max_distance 속성을 사용하면 시작 위치에서 이 거리 이상으로 이동할 때 경로 검색을 중지할 수 있습니다.

  • path_search_max_polygons 속성은 검색된 폴리곤 번호 위로 이동할 때 경로 검색을 중지하는 데 사용할 수 있습니다.

한계에 도달하여 경로 검색이 중지되면 경로가 재설정되고 시작 위치 다각형에서 지금까지 찾은 대상 위치에 가장 가까운 다각형까지의 경로가 생성됩니다.

경고

성능에는 좋지만 경로 검색 제한 값이 너무 낮게 설정되면 경로 품질에 매우 부정적인 영향을 미칠 수 있습니다. 다각형 레이아웃 및 검색 패턴에 따라 반환된 경로는 대상 방향이 아닌 완전히 잘못된 방향으로 이동할 수 있습니다.