Upgrade Guide

 A* Pathfinding Project를 최신 버전으로 업그레이드하기

Contents

• 4.x에서 5.0으로 업그레이드
  
  • 업데이트 설치
  • Seeker.StartPath 대신 ai.SetPath 사용
  • Seeker.pathCallback 사용 중단
  • 스캔은 Awake 대신 OnEnable에서 발생
  • 경로 찾기 태그는 이제 구조체로 표현
  • RVOSquareObstacle 지원 제거
  • RVONavmesh 사용 중단
  • 커스텀 그래프 인터페이스 변경
  • 그래프 업데이트는 비동기적으로 더 많은 작업 수행
  • 그리드 그래프의 경우 GraphUpdateObject.Apply 대신 ApplyJob 사용
  • 더 나은 성능을 위한 그리드 노드 일괄 업데이트
  • 육각형 그래프의 비용이 잘못된 비율로 조정됨
  • NavGraph.GetNearest는 이제 항상 제약 조건을 고려
  • 이동 스크립트는 더 이상 Update 및 FixedUpdate를 사용하지 않음
  • ProceduralGridMover는 이제 ProceduralGraphMover로 변경
  • 네임스페이스 구조
•  일반 업그레이드 노트
  
  

4.x에서 5.0으로 업그레이드

5.0 릴리스에는 많은 변경 사항이 있습니다. 대부분의 경우 업그레이드는 원활하게 진행되며 코드 변경이 필요 없지만, 몇 가지 주요 변경 사항으로 인해 코드나 설정을 업데이트해야 할 수 있습니다.

업데이트 설치

업그레이드할 때는 새 버전을 가져오기 전에 기존 AstarPathfindingProject 폴더를 삭제해야 합니다. 그렇지 않으면 오래된 파일이 남아 문제를 일으킬 수 있습니다.

Installation Guide 참조

 

Seeker.StartPath 대신 ai.SetPath 사용

내장된 이동 스크립트는 이제 부착된 Seeker 컴포넌트가 계산한 모든 경로를 청취하지 않고, 요청한 경로만 청취합니다. 다른 스크립트에서 seeker.StartPath를 호출하고 이동 스크립트가 경로를 따라가도록 의존하고 있었다면, 이제  ai.SetPath 를 호출해야 합니다. 지금은 호환성 코드가 있어 작동하지만, 경고 메시지가 계속 표시됩니다.

참고:   자체 커스텀 이동 스크립트를 작성한 경우, 이 변경 사항은 영향을 미치지 않습니다. 이 경우 계속해서 Seeker를 사용하면 됩니다.

 

이전에는 코드가 다음과 같을 수 있습니다:

var ai = GetComponent<IAstarAI>();
var seeker = GetComponent<Seeker>();
seeker.StartPath(ai.position, ai.destination);

위 코드는 다음과 같이 변경해야 합니다:

var ai = GetComponent<IAstarAI>();
var path = ABPath.Construct(ai.position, ai.destination);
ai.SetPath(path);

 

참조: Searching for paths 에 대한 자세한 정보

Seeker.pathCallback 사용 중단

Seeker.pathCallback 필드는 이제 사용 중단되었습니다. 대신 `StartPath` 메서드에 콜백을 전달해야 합니다.

참고:   이 변경 사항은 자체 이동 스크립트를 작성하는 경우에만 영향을 미칩니다. 내장된 이동 스크립트를 사용하는 경우, 이전 섹션에서 설명한 대로 `ai.SetPath`를 사용해야 합니다.

이전 코드 예시:

Seeker seeker;

void OnEnable () {
    // Seeker 컴포넌트를 가져옵니다.
    seeker = GetComponent<Seeker>();
    // 경로가 완료될 때 호출될 콜백을 추가합니다.
    seeker.pathCallback += OnPathComplete;
}

void OnDisable () {
    // 경로 완료 콜백을 제거합니다.
    seeker.pathCallback -= OnPathComplete;
}

void DoSomething() {
    // 지정된 위치에서 대상 위치까지의 경로 찾기를 시작합니다.
    seeker.StartPath(transform.position, target.position);
}

void OnPathComplete (Path path) {
    // 경로와 관련된 작업을 수행합니다.
}

 

새 코드 예시:

Seeker seeker;
OnPathDelegate onPathComplete;

void OnEnable () {
    // Seeker 컴포넌트를 가져옵니다.
    seeker = GetComponent<Seeker>();
    // OnPathComplete 콜백을 onPathComplete 변수에 할당합니다.
    onPathComplete = OnPathComplete;
}

void DoSomething() {
    // 지정된 위치에서 대상 위치까지의 경로 찾기를 시작하며,
    // 경로가 완료되면 onPathComplete 콜백이 호출됩니다.
    seeker.StartPath(transform.position, target.position, onPathComplete);
}

void OnPathComplete (Path path) {
    // 경로와 관련된 작업을 수행합니다.
}

 

참조: Searching for paths 에 대한 자세한 정보

 

스캔은 Awake 대신 OnEnable에서 발생

게임 시작 시 스캔이 초기 Awake 대신 초기 OnEnable에서 발생합니다. 일반적으로 이는 문제를 일으키지 않지만, 매우 특정한 초기화 순서에 의존하는 경우 문제가 발생할 수 있습니다.

경로 찾기 태그는 이제 구조체로 표현

일부 태그 필드의 타입이 `int`에서  PathfindingTag 로 변경되었습니다. 이전에 태그를 할당한 경우 이제 이를 `PathfindingTag`로 변환해야 합니다:

GetComponent<GraphUpdateScene>().setTag = new PathfindingTag((uint)tag);

또는  PathfindingTag.FromName 메서드를 사용하여 문자열에서 태그를 가져올 수 있습니다.

인스펙터에 태그 열거형을 표시하려면 PathfindingTag 유형의 public 필드를 노출하면 됩니다. 이렇게 하면 태그 이름이 드롭다운으로 자동 표시됩니다.

RVOSquareObstacle 지원 제거

RVOSquareObstacle은 더 이상 지원되지 않습니다. 이는 성능이 좋지 않고 제대로 작동하지 않았기 때문입니다.

하지만 로컬 회피 시스템이 이제 경로 찾기 그래프를 더 잘 고려하게 되었기 때문에(`RVOSimulator` 컴포넌트에서 이 기능을 활성화하면), 그래프 업데이트를 사용하여 경로 찾기 그래프를 업데이트할 수 있습니다.

RVONavmesh 사용 중단

RVONavmesh 컴포넌트는 사용 중단되었습니다. 이제 RVOSimulator.useNavmeshAsObstacle 옵션을 활성화하여 자동으로 처리됩니다.

커스텀 그래프 인터페이스 변경

자체 커스텀 그래프 클래스를 작성한 경우, 여러 메서드의 시그니처가 변경되었습니다.

자세한 내용은  Writing Graph Generators 에서 확인할 수 있습니다.

그래프 업데이트가 비동기적으로 더 많은 작업 수행

그리드 그래프 및 Recast 그래프에 대한 그래프 업데이트는 이제 더 많은 작업을 비동기적으로 수행합니다. 이는 일반적으로 프레임 속도를 개선하지만, 그래프 업데이트가 완료되는 데 더 많은 프레임이 걸릴 수 있습니다.

그래프 업데이트가 즉시 완료되도록 하려면  AstarPath.FlushGraphUpdates 를 호출할 수 있습니다.

그리드 그래프의 경우 GraphUpdateObject.Apply 대신 ApplyJob 사용

그리드 그래프에 대한 그래프 업데이트는 더 이상 `GraphUpdateObject.Apply` 메서드를 호출하지 않고, 대신 `GraphUpdateObject.ApplyJob` 메서드를 호출합니다. 커스텀 그래프 업데이트를 위해 `GraphUpdateObject`를 상속한 경우, 코드를 Burst와 호환되도록 변환해야 합니다.

참조:   Writing Custom Grid Graph Rules 에도 관심이 있을 수 있습니다.

 

 

그리드 노드 일괄 업데이트로 성능 향상

새로운 Burst 및 작업 시스템 덕분에 개별 노드 업데이트는 이전보다 약간 느려졌지만, 일괄 업데이트는 훨씬 빠를 수 있습니다.

기존 코드에서 노드 이동 가능성을 수동으로 업데이트했다면 다음과 같을 수 있습니다:

var grid = AstarPath.active.data.gridGraph;
grid.GetNodes(node => {
    if (someCondition) {
        node.Walkable = false;
    }
});
grid.GetNodes(node => grid.CalculateConnections(node);

이제 다음과 같이 변경해야 합니다:

var grid = AstarPath.active.data.gridGraph;
grid.GetNodes(node => {
    if (someCondition) {
        node.Walkable = false;
    }
});
grid.RecalculateAllConnections();

또는 새로운 편의 메서드  GridGraph.SetWalkability 를 사용할 수 있습니다:

AstarPath.active.AddWorkItem(() => {
    var grid = AstarPath.active.data.gridGraph;
    // 그래프의 왼쪽 상단 모서리에 있는 10x10 사각형의 모든 노드를 이동 불가로 표시합니다.
    grid.SetWalkability(new bool[10*10], new IntRect(0, 0, 9, 9));
});

비슷하게, 여러 노드를 업데이트하기 위해  GridGraph.CalculateConnectionsForCellAndNeighbour 를 사용해 왔다면, GridGraph.RecalculateAllConnections 또는 GridGraph.RecalculateConnectionsInRegion 을 사용하는 것이 좋습니다. 한두 개의 노드만 업데이트하는 경우에는 GridGraph.CalculateConnectionsForCellAndNeighbours 를 계속 사용하는 것이 괜찮습니다.

그래프의 더 복잡한 업데이트를 수행하는 경우, 대신 커스텀 그리드 그래프 규칙을 작성하는 것이 좋습니다. 그리드 그래프 규칙은 5.0의 새로운 기능으로, 스캐닝 프로세스와 훨씬 더 긴밀하게 통합되는 코드를 작성할 수 있게 합니다. 이는 또한 그래프 업데이트 및 ProceduralGraphMover 컴포넌트와 자동으로 작동함을 의미합니다.

Writing Custom Grid Graph Rules 참조

 

 

육각형 그래프의 비용이 잘못된 비율로 조정됨

육각형 그래프의 노드 간 비용이 sqrt(3/2)≈1.22배로 너무 크게 설정되었습니다. 이제 연결 비용은 노드 간 거리의 약 1000배로 설정됩니다.

예를 들어, 육각형 너비를 1로 설정한 경우, 인접한 두 육각형 간 이동 비용은 이전의 1224 대신 이제 1000이 됩니다. 대부분의 사용자에게는 영향을 미치지 않지만, 경로 찾기 성능이 약간 향상될 수 있습니다.

그래프에 페널티를 사용한 경우, 동일한 동작을 얻기 위해 페널티를 1.22로 나누어야 할 수 있습니다. 비슷하게, ConstantPath 를 사용하여 노드 집합을 얻은 경우, `maxGScore` 매개변수를 1.22로 나누어야 할 수 있습니다.

NavGraph.GetNearest는 이제 항상 제약 조건을 고려

NavGraph.GetNearest는 이제 항상 제약 조건을 고려합니다. 이전에는 그래프 유형에 따라 달라졌으며 일관된 결과를 얻기가 어려웠습니다. `NavGraph.GetNearestForce` 메서드는 제거되었으며, 이제 `NavGraph.GetNearest` 메서드로 대체되었습니다.

참고:    AstarPath.GetNearest 와 혼동하지 마세요.  AstarPath.GetNearest 는 항상 제약 조건을 고려했습니다.

 

이동 스크립트는 더 이상 Update 및 FixedUpdate를 사용하지 않음

`AIPath` 및 `RichAI` 스크립트는 더 이상 `Update` 및 `FixedUpdate` 메서드를 사용하지 않습니다. 대신 모든 특정 타입의 컴포넌트를 한 번에 처리할 수 있는 별도의 스크립트( BatchedEvents )를 사용합니다. 이는 약간 더 빠르며 AIBase.rvoDensityBehavior 구현에 필요합니다. `Update` 또는 `FixedUpdate` 메서드를 재정의해 왔다면, 대신 `OnUpdate` 메서드를 재정의하도록 코드를 변경해야 합니다.

ProceduralGridMover는 이제 ProceduralGraphMover로 변경

ProceduralGridMover 컴포넌트는 이제  ProceduralGraphMover 로 이름이 변경되었습니다. 이는 이제 그리드뿐만 아니라 더 많은 것을 지원하기 때문입니다.

스크립트에서 이를 참조하고 있다면, 참조 이름을 변경해야 합니다.

네임스페이스 구조

네임스페이스 구조가 크게 개선되었습니다. 대부분의 변경 사항은 사용자가 자주 사용하지 않는 내부 클래스에 적용되었습니다. `using` 문을 약간 조정해야 할 수 있습니다. 주요 변경 사항은 다음과 같습니다:

• Pathfinding.Graphs.Grid 가 추가되어 그리드 그래프와 관련된 많은 클래스가 이곳으로 이동되었습니다.
• Pathfinding.Graphs.Grid.Jobs 는 새로 추가되었으며, 많은 내부 그리드 스캔 코드를 포함합니다.
• Pathfinding.Graphs.Grid.Rules 는 새로 추가되었으며, 그리드 그래프 규칙을 포함합니다.
• Pathfinding.Graphs.Grid.Rules 는 `Pathfinding.Recast`를 대체합니다.
• Pathfinding.Graphs.Navmesh.Voxelization 은 `Pathfinding.Voxels`를 대체합니다.

불행히도 C#은 public 네임스페이스 별칭을 지원하지 않으므로, 이러한 변경 사항은 이전 버전과의 호환성을 유지할 수 없습니다.

일반 업그레이드 노트

업그레이드에 문제가 있는 경우, Unity에서 `AstarPathfindingProject` 폴더를 삭제하고 패키지를 다시 가져와 보세요. 이렇게 하면 프로젝트에 더 이상 포함되지 않은 오래된 스크립트를 제거하는 데 도움이 될 수 있습니다. UnityPackages는 디렉토리를 병합하므로, 여전히 남아 있을 수 있습니다.

클래스에 일부 멤버나 함수가 존재하지 않는다는 컴파일러 메시지가 표시되는 경우, 이는 프로젝트에 전역 네임스페이스에 해당 이름의 클래스가 포함되어 있기 때문일 가능성이 큽니다. 이로 인해 클래스 간에 충돌이 발생합니다. 이를 해결하는 가장 간단한 방법은 충돌하는 클래스를 네임스페이스에 넣거나 이름을 변경하는 것입니다.