지오메트리 스크립트 사용자 가이드

지오메트리 스크립트 함수 및 블루프린트 노드 사용에 대한 가이드입니다.

Choose your operating system:

Windows

macOS

Linux

지오메트리 스크립트 개요

지오메트리 스크립트(Geometry Script)는 블루프린트 및 Python을 통해 메시 지오메트리를 생성 및 편집하는 기능을 제공하는 함수 라이브러리 세트를 포함하는 언리얼 엔진 플러그인입니다.

지오메트리 스크립트 UFunctions 및 블루프린트 노드는 UDynamicMesh 오브젝트에서 작동하며, 이는 FDynamicMesh3 C++ 트라이앵글 메시 데이터 구조체를 사용하여 생성되는 오브젝트입니다. 이 데이터 구조체는 지오메트리 프로세싱(Geometry Processing) 플러그인 및 모델링 에디터 모드(Modeling Editor Mode)에서 사용되는 것과 동일한 것입니다.

지오메트리 스크립트는 에디터 유틸리티 위젯(Editor Utility Widgets) 및 에셋 액션(Asset Actions)에서 커스텀 메시 분석/프로세싱/편집 툴을 만드는 데 사용될 수 있으며, 액터 블루프린트에서 '프로시저럴 오브젝트'를 생성하고 복잡한 지오메트리 쿼리를 구현하는 데 사용될 수도 있습니다.

지오메트리 스크립트는 잠재적으로 다음과 같은 경우에 사용할 수 있습니다.

  • 서드파티 메시 임포트 툴 테스트 및 퀄리티 분석

  • 메시 UV를 분석하여 낭비된 텍스처 스페이스가 있는 에셋 식별

  • 프로덕션 워크플로를 위한 스크립트식 메시 에셋 병합

  • 라이라 샘플 게임에서 사용된 레벨 디자인 툴 오브젝트 등 프로시저럴 메시 액터

DynamicMesh 오브젝트

지오메트리 스크립트는 다음과 같은 몇 가지 새로운 오브젝트 타입에서 작동합니다.

  • UDynamicMesh

  • UDynamicMeshComponent

  • ADynamicMeshActor

스태틱 메시/StaticMeshComponent/StaticMeshActor 아키텍처와 유사하게 이러한 클래스는 지오메트리 스크립트 플러그인의 일부가 아니며, 지오메트리 프레임워크 엔진 모듈 내에 위치하여 지오메트리 스크립트와 별개로 사용됩니다.

UDynamicMesh

지오메트리 스크립트를 지원하는 핵심 컴포넌트는 UDynamicMesh 오브젝트입니다. UObject는 특정 컴포넌트에 연결되지 않은 메시 데이터 구조체를 위한 컨테이너입니다. 이는 메시 지오메트리를 명시적인 씬 표현 없이도 생성 및 조작 가능하다는 점에서 UProceduralMeshComponent 등 이전의 언리얼 엔진 접근법과 다릅니다.

예를 들어 UDynamicMesh는 UStaticMesh 에셋을 기반으로 초기화되고 편집된 다음 에셋에 다시 저장될 수 있습니다. 에디터 유틸리티 위젯과 결합되어 유저 인터페이스를 제공하는 이 접근법은 테크 아티스트가 특정 용도로 빌드된 커스텀 메시 편집 툴을 블루프린트에서 생성하거나 Python을 통해 메시 에셋 쿼리/편집 작업을 스크립팅할 수 있도록 지원합니다.

게임플레이 볼륨(Gameplay Volumes) 등 다양한 기타 에디터 메시 지오메트리 타입도 UDynamicMesh로 변환되거나 여기에서 지오메트리로 변환될 수 있습니다.

DynamicMeshComponent

UDynamicMesh뿐 아니라 UDynamicMeshComponent 또한 '실제', 즉 트랜션트가 아닌 시리얼라이즈 가능한 컴포넌트로 승격되었습니다. 이 컴포넌트는 실질적으로 UProceduralMeshComponent와 유사하지만 UDynamicMesh를 기반으로 하며, GeometryScript를 통해 조작될 수 있습니다.

UDynamicMeshComponent는 지난 수년 동안 메시 모델링 툴세트의 일부로 개발되었으며, 메시 편집의 리얼타임 프리뷰를 제공하는 데 사용되었습니다. UProceduralMeshComponent와 유사하게 UDynamicMeshComponent는 메시 지오메트리에 대한 업데이트를 지원합니다. 이때 버텍스 어트리뷰트만 업데이트하는 것이 아니라 전체 메시 토폴로지를 생성 및 수정합니다. 이와 같은 작업은 에디터에서 뿐만 아니라 런타임에서도 모두 수행할 수 있습니다. 레이 트레이싱은 지원되지만 나나이트와 루멘은 지원되지 않습니다.

DynamicMeshActor

ADynamicMeshActor는 AStaticMeshActor와 유사하며 대체로 UDynamicMeshComponent에 대한 컴포넌트입니다. 하지만 DynamicMeshActor는 UDynamicMesh 기반 프로시저럴 메시 생성을 구현하는 액터 블루프린트에 대해 특정한 지원을 제공합니다.

이전에는 새 StaticMesh 에셋만 생성할 수 있었던 모델링 모드 툴은 이제 새 DynamicMeshActor도 생성할 수 있으며, 편집 툴은 볼륨뿐 아니라 어떤 타입의 메시 액터든 편집할 수 있습니다.

GeneratedDynamicMeshActor

AGeneratedDynamicMeshActor는 ADynamicMeshActor의 서브클래스이며 블루프린트 기반 프로시저럴 메시 액터 구현을 위한 추가 지원을 제공합니다. 특히 이 클래스는 컨스트럭션 스크립트(Construction Script)를 사용하는 대신 BP 서브클래스에서 메시를 생성하기 위해 구현될 수 있는 On Rebuild Generated Mesh 함수를 제공합니다. 이를 통해 에디터 내에서의 인터랙티브 퍼포먼스를 개선할 수 있으며 향후 대규모 프로시저럴 메시 생성을 세밀하게 관리할 수 있습니다.

GeneratedDynamicMeshActor는 현재 에디터 전용입니다.

UStaticMesh와 UDynamcMesh의 주요 차이점

UStaticMesh와 달리 UDyanmicMesh는 에셋이 아닙니다. UDynamicMeshComponent는 UDynamicMesh를 '소유'하며, UStaticMesh와 달리 여러 컴포넌트 간에 공유되지 않습니다. 예를 들어 인스턴스드 렌더링은 사용할 수 없습니다. UStaticMesh는 ProceduralMeshComponent와 유사하게 컴포넌트 및 액터의 일부로 저장됩니다. 즉, 메시가 별도의 에셋 파일이 아닌 '레벨 내에' 저장됩니다. UDynamicMeshComponent를 복제하면 메시의 사본 이 생성되며, 레벨 또는 프로젝트 간 전송은 복사 붙여넣기 를 통해 수행되어야 합니다.

여러 측면에서 UDynamicMeshComponent는 Autodesk 3ds Max, Autodesk Maya, Blender 등 DCC 툴의 메시 오브젝트와 훨씬 유사하게 작동합니다. 이는 대규모 메시의 레벨 파일 크기가 대폭 증가하는 잠재적인 문제를 수반합니다. 하지만 액터당 한 개의 파일(One File Per Actor) 기능을 통해 메시 데이터는 레벨이 아닌 OFPA 액터 파일로 저장됩니다. 따라서 여전히 크기는 하지만 별개의 파일이 됩니다.

지오메트리 스크립트 함수/노드 패턴

지오메트리 스크립트 함수/노드 대부분은 아래의 Apply Mesh Plane Cut 노드와 유사한 매우 표준적인 패턴을 따릅니다.

첫 인수인 타깃 메시(Target Mesh) 는 해당 연산에 의해 편집되는 UDynamicMesh입니다. 일반적으로 지오메트리 메시 연산은 새 메시를 생성하기보다는 입력 메시를 수정하여 임시 메시 오브젝트가 생성되는 것을 방지합니다. UDynamicMesh는 항상 출력으로 반환되므로 타깃 메시 라고도 합니다(동일한 이름==동일한 오브젝트). 이를 통해 여러 연산을 연속적으로 처리할 수 있게 됩니다.

지오메트리 스크립트 노드는 다양한 파라미터 및 세팅을 갖습니다. 자주 사용되는 옵션은 인수로 노출되지만, 그보다 많은 옵션은 연산별 옵션(Options) 구조체를 통해 제공됩니다. 적절한 옵션 구조체를 생성하는 가장 일반적인 방법은 빈 옵션 핀에서 드래그하는 것입니다. 이는 디폴트를 수정하려는 경우가 아니면 꼭 필요하지는 않습니다. 또한 옵션 핀을 우클릭하고 구조체 핀 분할(Split Struct Pin) 컨텍스트 메뉴 항목을 사용하여 아래와 같이 노드에서 옵션 구조체를 직접 확장할 수도 있습니다.

대부분의 노드에는 메시 제네레이터를 위한 지오메트릭 디버깅 지원을 제공하는 디버그 핀도 있습니다. 이는 자주 사용되지는 않지만 미래의 함수 기능을 위한 자리표시자입니다.

UDynamicMesh 풀 사용하기

메시 제네레이터 내에 임시 메시를 생성하는 것은 드문 경우가 아닙니다. 예를 들어 '메인' 메시에서 뺄 프리미티브 메시를 생성할 수 있습니다. 이렇게 하려면 임시 UDynamicMesh가 필요합니다. ConstructionObjectFromClass를 사용하여 생성할 수도 있지만, 프로시저럴 제네레이터에서 생성하는 경우 메시는 사용 후 가비지 콜렉션되어야 합니다. 제네레이터를 자주 실행하는 경우에는 실행 시 메시를 재사용하는 것이 더 효율적입니다.

DynamicMeshActor 는 UDynamicMeshPool을 사용하는 내장 지원 기능으로 이를 수행하는데, 이때 AllocateComputeMesh 를 호출하여 임시 메시를 가져오고 블루프린트 실행 패스가 끝나기 전의 지점에서 해제합니다. 각 임시 메시는 ReleaseComputeMesh 를 사용하여 명시적으로 해제하거나 ReleaseAllComputeMeshes 를 호출하여 현재 풀에서 할당된 모든 임시 메시를 해제할 수 있습니다.

에디터 유틸리티 위젯에는 메시를 할당할 디폴트 DynamicMeshPool이 없지만 CreateDynamicMeshPool 을 사용하여 생성할 수 있습니다. 예를 들어 에디터 유틸리티 위젯 또는 유틸리티 블루프린트의 변수로 생성할 수 있습니다.

액터 블루프린트를 사용하여 프로시저럴 메시 오브젝트 생성하기

위에서 설명했듯이 지오메트리 스크립트에서 흥미로운 기존 사용 사례는 액터 블루프린트를 사용하여 프로시저럴 메시 '오브젝트'를 생성하는 것입니다. 아래 예시와 같이 GeneratedDynamicMeshActor 의 BP 서브클래스를 사용합니다. On Rebuild Generated Mesh Event 를 사용하여 UDynamicMeshComponentUDynamicMesh 를 채웁니다. 이 클래스에 대한 자세한 내용은 지오메트리 스크립트 레퍼런스를 참고하세요. UDynamicMesh는 GeometryScript 함수 Append Box 로 전달되며, 여기서 입력 변수를 바탕으로 메시가 생성됩니다.

아래 클립에서는 이 BP 액터 인스턴스를 사용하는 예시를 보여줍니다. 이 예시에서는 몇 개의 BP 노드만으로 파라미터형 박스 프리미티브 메시를 생성합니다. 추가 노드를 더하면 매우 복잡한 메시 제네레이터를 블루프린트에서 직접 빌드할 수 있습니다. 현재 지오메트리 스크립트 라이브러리에서는 150개 이상의 메시 생성 및 편집용 함수/노드가 제공됩니다.

지오메트리 스크립팅을 사용하는 프로시저럴 메시