Grid Graph Rules > Writing Custom Grid Graph Rules

사용자 정의 그리드 그래프 규칙 작성
이 튜토리얼은 그리드 그래프 규칙에 대해 어느 정도 익숙하다는 전제를 가지고 있습니다.

익숙하지 않다면 먼저  Grid Graph Rules 을 확인하십시오.

Contents

• Why write a grid graph rule
• How a rule works conceptually
• Unity Job System or Main Thread
• Writing a simple example rule
• Writing a rule that uses the Unity Job System
• Connection filters using the Unity Job System
• Data layout

Why write a grid graph rule(왜 그리드 그래프 규칙을 작성하는가)

때로는 스캐닝 프로세스를 어떤 방식으로든 수정하고 싶을 때가 있습니다. 예를 들어, 게임에 자체적인 노드 이동 가능 규칙이 있고 이를 그리드 그래프와 동기화하고 싶을 수 있습니다. 그래프가 스캔된 후 모든 노드를 반복하며 원하는 수정을 적용할 수도 있지만, 이는 복잡성을 추가하고 그래프 업데이트와 잘 맞지 않습니다.

그리드 그래프 규칙으로 로직을 작성하면 그래프 업데이트 및 ProceduralGraphMover 와 같은 스크립트와 원활하게 작동합니다. 또한 유니티 작업 시스템과 Burst 컴파일러를 사용하여 코드를 크게 가속화할 수 있습니다. 또한 그리드에서 어떤 연결이 유효하고 어떤 연결이 유효하지 않은지에 대한 필터를 쉽게 만들 수 있는 몇 가지 도우미 메서드도 포함되어 있습니다.

How a rule works conceptually(규칙이 개념적으로 작동하는 방식)

규칙은 개념적으로 다음과 같이 작동합니다:

1. 규칙은 자체 등록을 하고 스캐닝 프로세스에 훅을 겁니다.
2. 그래프가 스캔되거나 업데이트될 때, 해당 훅을 호출합니다.
3. 훅 내부에서 규칙은 그래프 데이터를 원하는 대로 수정할 수 있습니다.

규칙은 스캐닝 프로세스의 다른 지점에 훅을 걸도록 등록할 수 있습니다. 이러한 지점을 패스라고 합니다. 대부분의 규칙은 단일 패스만 사용하지만, 원한다면 여러 개를 등록할 수도 있습니다.

 

Pass
스캐닝 프로세스의 어느 지점에서 규칙이 실행될지 지정합니다.

 GridGraphScanData  문서를 확인하여 어떤 데이터 필드가 어떤 패스에서 유효한지 확인하십시오.

BeforeCollision	충돌 테스트 단계 이전, 높이 테스트 이후에 실행됩니다. 이 단계는 매우 초기 단계로, 이 시점에서는 대부분의 데이터가 유효하지 않습니다. 이 패스를 사용하면 노드 위치를 수정하고 충돌 테스트 코드에서 이를 반영할 수 있습니다.
BeforeConnections	연결이 계산되기 이전에 실행됩니다. 이 시점에서는 높이 테스트와 충돌 테스트가 완료된 상태입니다(둘 다 활성화된 경우). 이는 가장 일반적으로 사용되는 패스입니다. 이 지점에서 이동 가능성을 수정하면 연결과 침식이 올바르게 계산됩니다.
AfterConnections	연결이 계산된 후에 실행됩니다. 연결을 직접 수정하려면 이 패스에서 수행해야 합니다.
	참고 침식이 사용되는 경우 이 패스는 두 번 실행됩니다. 한 번은 침식 이전, 다른 한 번은 침식 이후 연결이 다시 계산될 때 실행됩니다.
AfterErosion	침식이 계산된 후, 연결이 다시 계산되기 이전에 실행됩니다. 침식이 사용되지 않는 경우 이 패스는 실행되지 않습니다.
PostProcess	모든 작업이 끝난 후에 실행됩니다. 이 패스는 모든 작업이 완료된 후에 실행됩니다. 이 패스에서 이동 가능성을 수정해서는 안 됩니다. 이 경우 노드 연결이 최신 상태가 아니게 됩니다.
AfterApplied	그래프 업데이트가 그래프에 적용된 후에 실행됩니다. 이 패스는 메인 스레드 패스로만 추가할 수 있습니다.
	경고 이 시점에서는 컨텍스트의 네이티브 데이터가 유효하지 않습니다. 모든 데이터가 삭제된 상태입니다. 이 패스에서는 데이터를 수정할 수 없습니다.

 

이 설정은 Pathfinding.Graphs.Grid.Rules.GridGraphRule.Pass 멤버에 해당합니다.

 

규칙은 그래프를 스캔할 때와 그래프가 업데이트될 때 모두 호출됩니다. 그러나 그래프가 업데이트될 때는 그리드의 더 작은 부분 사각형에 대해서만 데이터를 제공합니다. 따라서 그리드 그래프 규칙은 항상 전체 그래프에 사용된다고 가정해서는 안 되며, 이를 염두에 두어야 합니다( Data layout 참조).

규칙은 프로젝트의 어느 곳에나 배치할 수 있습니다. 동적으로 찾아지고 그리드 그래프 인스펙터에서 'Add Rule' 버튼을 사용하여 추가할 수 있습니다. 또한 인스펙터에서 설정을 변경할 수 있도록 사용자 지정 편집기 GUI를 규칙에 추가할 수도 있습니다.

Unity Job System or Main Thread

규칙을 실행하는 방법에는 두 가지 옵션이 있습니다:

 

• 메인 스레드에서 실행합니다. 이 방법은 더 쉽고 보일러플레이트 코드가 적으며, 규칙에서 스레드에 안전하지 않은 데이터에 접근할 수 있습니다.
• 유니티 작업 시스템을 사용하여 실행합니다. 이 방법은 추가적인 보일러플레이트 코드가 있지만, 작업이 다른 그리드 그래프 스캔 코드와 병렬로 실행될 수 있으며 Burst 컴파일러를 사용할 수 있습니다. 이를 통해 매우 빠른 작업을 작성할 수 있습니다.

 

처음 작업을 작성할 때는 메인 스레드에서 실행되는 작업을 작성하는 것을 권장하며, 성능이 필요할 경우 작업 시스템으로 전환할 수 있습니다.

다음 섹션에서는 몇 가지 규칙 예제를 보여드립니다.

Writing a simple example rule

노이즈 함수를 기반으로 노드의 이동 가능성을 설정하는 간단한 규칙을 작성해보겠습니다. 결과는 다음과 같을 것입니다:

이를 수행하기 위해 모든 노드를 반복하면서 이동 가능성을 설정해야 합니다.

이를 수행하기 위해 모든 노드를 반복하면서 이동 가능성을 설정해야 합니다.

using UnityEngine;
using Pathfinding;
using Pathfinding.Graphs.Grid.Rules;

// Preserve 속성으로 표시하여 바이트코드 스트리핑이 사용될 때 이 클래스가 제거되지 않도록 합니다. 자세한 내용은 https://docs.unity3d.com/Manual/IL2CPP-BytecodeStripping.html 참조
[Pathfinding.Util.Preserve]
public class RuleExampleNodes : GridGraphRule {
    public float perlinNoiseScale = 10.0f;
    public float perlinNoiseThreshold = 0.4f;

    public override void Register (GridGraphRules rules) {
        // Register 메서드는 규칙이 처음 사용될 때 한 번 호출되고,
        // 인스펙터에서 규칙 설정이 변경될 때 다시 호출됩니다.
        // 필요한 경우 이 부분에서 사전 계산을 수행합니다.

        // 그리드 그래프의 계산 코드에 훅을 겁니다
        rules.AddMainThreadPass(Pass.BeforeConnections, context => {
            // 이 콜백은 그래프를 스캔할 때와 그래프 업데이트 중에 호출됩니다.
            // 여기서 원하는 대로 그래프 데이터를 수정할 수 있습니다.
            // context.data 객체는 모든 노드 데이터를 NativeArrays로 포함하고 있습니다.
            // 모든 데이터가 모든 패스에서 유효한 것은 아니며, 특정 시간에 계산되지 않았을 수 있습니다.
            // GridGraphScanData 객체에 대한 문서에서 이에 대한 자세한 정보를 찾을 수 있습니다.

            // 필요한 데이터 배열을 가져옵니다
            var nodeWalkable = context.data.nodes.walkable;
            var nodePositions = context.data.nodes.positions;

            //  모든 노드를 반복하면서 일부 페를린 노이즈에 따라 이동 가능하거나 불가능하도록 표시합니다
            for (int i = 0; i < nodePositions.Length; i++) {
                var position = nodePositions[i];
                nodeWalkable[i] &= Mathf.PerlinNoise(position.x / perlinNoiseScale, position.z / perlinNoiseScale) > perlinNoiseThreshold;
            }
        });
    }
}

 

확인이 필요하다면 규칙이 실행될 때 콜백에서 그래프에 대한 많은 데이터를 포함하는 context 객체를 받게 됩니다. 사용할 수 있는 데이터에 대한 자세한 내용은  GridGraphRules.Context 클래스를 참조하십시오. 특히, 이 클래스의 data 필드는  GridGraphScanData 클래스의 인스턴스입니다.

이 코드는 프로젝트의 어느 곳에나 배치할 수 있으며, GridGraph 인스펙터에서 "Add Rule" 버튼을 클릭하면 표시됩니다.
모든 규칙에는 설정을 표시할 수 있는 대응되는 에디터 스크립트가 필요합니다. 이 스크립트는 Editor folder 에 배치해야 합니다.

using Pathfinding.Graphs.Grid.Rules;
using UnityEditor;
using UnityEngine;

namespace Pathfinding {
    [CustomGridGraphRuleEditor(typeof(RuleExampleNodes), "Simple Example Rule")]
    public class RuleExampleNodesEditor : IGridGraphRuleEditor {
        public void OnInspectorGUI (GridGraph graph, GridGraphRule rule) {
            var target = rule as RuleExampleNodes;

            target.perlinNoiseScale = EditorGUILayout.FloatField("Noise Scale", target.perlinNoiseScale);
            target.perlinNoiseThreshold = EditorGUILayout.FloatField("Noise Threshold", target.perlinNoiseThreshold);
        }

        public void OnSceneGUI (GridGraph graph, GridGraphRule rule) { }
    }
}

이제 규칙이 작동할 것입니다! 아래에서 이 간단한 규칙이 어떻게 작동하는지 보여주는 비디오를 볼 수 있습니다.

 

 

 

Writing a rule that uses the Unity Job System

유니티 작업 시스템을 사용할 때는  AddJobSystemPass 대신  AddMainThreadPass 메서드를 사용합니다. 이 메서드에서는 데이터에 직접 접근하지 않고 작업을 예약해야 합니다.

이전의 간단한 규칙을 작업 시스템을 사용하도록 다시 작성할 수 있습니다. 또한, GridIterationUtilities.ForEachNode 라는 유용한 도우미 함수를 사용할 것입니다. 이를 사용하려면 작업 구조체가 GridIterationUtilities.INodeModifier 인터페이스를 구현해야 합니다. 이 인터페이스는 관련된 각 노드에 대해 한 번씩 호출됩니다. 그래프 업데이트 중에는 그래프의 모든 노드가 아니라 몇몇 노드에 대해서만 호출될 수 있습니다.

using UnityEngine;
using Unity.Collections;
using Unity.Jobs;
using Unity.Burst;
using Unity.Mathematics;
using Pathfinding;
using Pathfinding.Jobs;
using Pathfinding.Graphs.Grid;
using Pathfinding.Graphs.Grid.Rules;

[Pathfinding.Util.Preserve]
public class RuleExampleNodesBurst : GridGraphRule {
    public float perlinNoiseScale = 10.0f;
    public float perlinNoiseThreshold = 0.4f;

    public override void Register (GridGraphRules rules) {
        // 여기서 규칙을 메인 스레드에서 실행하는 대신 작업 시스템을 사용합니다.
        // 이 경우 콜백 내부에서는 작업을 예약하기만 해야 합니다.
        // 콜백에서 데이터를 직접 접근하는 것은 안전하지 않습니다.
        rules.AddJobSystemPass(Pass.BeforeConnections, context => {
            // 이 콜백은 그래프를 스캔할 때와 그래프 업데이트 중에 호출됩니다.
            // 우리가 해야 할 일은 유니티 작업 시스템을 사용하여 작업을 예약하는 것뿐입니다.
            // 종속성을 직접 처리할 필요는 없습니다.
            // 적절한 [ReadOnly] 또는 [WriteOnly] 태그를 사용하는지 확인하십시오.
            // 자세한 내용은 https://docs.unity3d.com/Manual/JobSystem.html 를 참조하십시오.
            // context.data 객체는 모든 노드 데이터를 NativeArrays로 포함하고 있습니다.
            new JobExample {
                bounds = context.data.nodes.bounds,
                nodeWalkable = context.data.nodes.walkable,
                nodePositions = context.data.nodes.positions,
                nodeNormals = context.data.nodes.normals,
                perlinNoiseScale = perlinNoiseScale,
                perlinNoiseThreshold = perlinNoiseThreshold,
            }.Schedule(context.tracker);
        });
    }

    [BurstCompile]
    struct JobExample : IJob, GridIterationUtilities.INodeModifier {
        public IntBounds bounds;
        public float perlinNoiseScale;
        public float perlinNoiseThreshold;

        public NativeArray<bool> nodeWalkable;
        [ReadOnly]
        public NativeArray<Vector3> nodePositions;
        [ReadOnly]
        public NativeArray<float4> nodeNormals;

        public void Execute () {
            // 계산 중인 모든 노드를 효율적으로 반복하는 데 사용됩니다.
            // ForEachNode 함수는 nodeNormals 배열을 사용하여 노드가 존재하는지 확인합니다.
            // 노드가 존재하지 않는 경우 노말은 (0,0,0)입니다 (중요: 계층 그리드 그래프).
            GridIterationUtilities.ForEachNode(bounds.size, nodeNormals, ref this);
        }

        public void ModifyNode (int dataIndex, int dataX, int dataLayer, int dataZ) {
            var position = nodePositions[dataIndex];

            nodeWalkable[dataIndex] &= Mathf.PerlinNoise(position.x / perlinNoiseScale, position.z / perlinNoiseScale) > perlinNoiseThreshold;
        }
    }
}

주의사항 일반적으로 유니티 작업 시스템을 사용할 때는 작업의 종속성을 수동으로 지정해야 합니다. 이는 번거롭고 오류가 발생하기 쉽기 때문에, 작업 구조체의 필드에 사용한 [ReadOnly] 및 [WriteOnly] 속성을 읽고 종속성을 자동으로 계산해주는 도우미 스크립트를 사용합니다. 자세한 내용은 JobDependencyTracker 클래스를 참조하십시오.

 

Connection filters using the Unity Job System

또 다른 일반적인 상황은 어떤 노드 연결이 이동 가능한지, 어떤 노드 연결이 이동 불가능한지를 제어하고자 할 때입니다.  IConnectionFilter 인터페이스와  FilterNodeConnections 함수를 사용하면 이를 쉽게 수행할 수 있습니다.

using UnityEngine;
using Unity.Collections;
using Unity.Jobs;
using Unity.Burst;
using Unity.Mathematics;
using Pathfinding;
using Pathfinding.Jobs;
using Pathfinding.Graphs.Grid.Rules;
using Pathfinding.Graphs.Grid;

[Pathfinding.Util.Preserve]
public class RuleExampleConnection : GridGraphRule {
    public override void Register (GridGraphRules rules) {
        rules.AddJobSystemPass(Pass.AfterConnections, context => {
            new JobExample {
                bounds = context.data.nodes.bounds,
                nodeConnections = context.data.nodes.connections,
                nodeWalkable = context.data.nodes.walkable,
                nodePositions = context.data.nodes.positions,
                layeredDataLayout = context.data.nodes.layeredDataLayout,
            }.Schedule(context.tracker);
        });
    }

    [BurstCompile]
    struct JobExample : IJob, GridIterationUtilities.IConnectionFilter {
        public IntBounds bounds;
        public NativeArray<ulong> nodeConnections;

        [WriteOnly]
        public NativeArray<bool> nodeWalkable;
        [ReadOnly]
        public NativeArray<Vector3> nodePositions;
        public bool layeredDataLayout;

        public void Execute () {
            GridIterationUtilities.FilterNodeConnections(bounds, nodeConnections, layeredDataLayout, ref this);
        }

        public bool IsValidConnection (int dataIndex, int dataX, int dataLayer, int dataZ, int direction, int neighbourDataIndex) {
            // 현재 노드와 인접 노드의 위치를 가져옵니다.
            var position = nodePositions[dataIndex];
            var neighbourPosition = nodePositions[neighbourDataIndex];

            // 인접 노드가 이 노드와 Y 좌표가 1미터 이하로 다를 경우에만 연결을 허용합니다.
            // 이는 GridGraph 설정의 "Max Climb"와 유사합니다.
            return math.abs(position.y - neighbourPosition.y) < 1.0f;
        }
    }
}

노드가 메모리에 어떻게 배치되는지에 대한 자세한 내용은 Data layout 을 참조하십시오.

IsValidConnection 메서드는 업데이트되는 모든 연결에 대해 호출됩니다. 이 메서드는 스캐닝 프로세스에서 해당 시점에 유효한 연결에 대해서만 호출됩니다. 이는 이전에 비활성화된 연결을 다시 활성화할 수 없다는 것을 의미합니다.

Data layout

그리드 그래프가 스캔되거나 업데이트될 때, 모든 임시 데이터는 NativeArrays에 저장됩니다. 그리드 그래프의 작은 부분만 업데이트되는 경우, 이러한 임시 배열은 전체 그래프보다 작으므로 일반 노드와 동일한 인덱스로 접근할 수 없습니다.

참고 코드에서는 이 그래프 업데이트/스캔에 사용된 NativeArrays에서 x 및 z 좌표를 나타내기 위해 dataX와 dataZ라는 명명 규칙을 사용합니다.

dataX 와  dataZ 는 실제 그래프의 x 및 z 좌표와 일치하지 않을 수 있습니다. 이는 그래프 업데이트가 일반적으로 그래프의 작은 부분에만 영향을 미치기 때문입니다. 다음과 같이 이를 그리드의 x 및 z 좌표로 변환할 수 있습니다:

gridX = dataX + bounds.xmin;
gridZ = dataZ + bounds.zmin;

IConnectionFilter 를 사용하지 않는 경우, GridIterationUtilities.GetNeighbourDataIndex 메서드를 사용하여 노드의 이웃에 접근할 수 있습니다.