WBP_SmartLayoutTool 기술 문서

01 / OVERVIEW

툴 개요

문제 정의 · 버튼 구성 · 워크플로

수동 배치는 두 가지 문제가 있다. 개수가 많을수록 시간이 오래 걸리고, 배치 후 드로우콜 최적화를 위한 ISM 변환을 에디터가 기본으로 제공하지 않아 매번 수동으로 처리해야 했다. 이 두 작업을 자동화하기 위해 만들었다.

인터페이스

버튼 2

독립 동작 · 순서 무관

스폰 방식

타이머

틱 분산 · 에디터 멈춤 없음

ISM 변환 결과

N → 1

Actor N개 → 컨테이너 1개

버튼 구성

버튼	하는 일	입력
1. 생성하기	선택한 액터 위치를 기준으로 메시를 랜덤 스폰	선택된 액터, Settings 파라미터
2. 인스턴스 변환하기	선택한 Static Mesh Actor들을 ISM 하나로 병합	선택된 Static Mesh Actor 목록 (같은 메시 + 같은 머티리얼)

두 버튼은 독립적으로 동작한다. 생성하기로 만든 오브젝트에 바로 변환을 적용할 수도 있고, 씬에 이미 있는 오브젝트를 선택해서 변환만 실행할 수도 있다.

실행 전제조건 (Guard Clause)

두 버튼 모두 Get Selected Level Actors가 빈 배열을 반환하면 실행을 중단한다. 선택이 없는 상태에서 버튼 1을 실행하면 기준 위치를 추출할 수 없고, 버튼 2를 실행하면 Centroid 계산 시 0으로 나누기 오류가 발생한다. 각 버튼 On Clicked 진입 직후 배열 길이를 확인하고, 비어 있으면 노티피케이션을 출력하고 종료한다.

On Clicked → Get Selected Level Actors → Length == 0 → Print "선택된 액터 없음" → Return
                                                         → Length > 0  → 이후 로직 진행

Settings 파라미터

파라미터	역할
Drop Count	생성할 메시 수
Drop Mesh List	랜덤 선택할 메시 목록. 배열 안에서 매 스폰마다 RANDOM으로 하나를 선택한다
X/Y/Z Random Range Min/Max	기준 위치에서 각 축 방향으로 이동할 랜덤 범위
Always Respawn	실행 시 이전에 생성된 오브젝트를 지우고 재생성할지 여부. OFF면 기존 오브젝트에 추가로 스폰. 동작에 필요한 구현 조건은 아래 별도 항목 참조
Auto Run	버튼 클릭 없이 파라미터 변경 시 자동 실행
Run on Start-up	위젯이 열리는 시점에 자동으로 생성하기 실행

Always Respawn 구현 조건

이전에 스폰된 오브젝트를 삭제하려면 위젯 변수로 Actor 레퍼런스 배열을 유지해야 한다. 스폰할 때마다 반환된 Actor를 이 배열에 추가하고, 재실행 시 배열을 순회하며 Destroy Actor를 호출한 뒤 배열을 초기화한다.

변수: SpawnedActors (Array of Actor)

생성하기 실행 시:
  Always Respawn == true → SpawnedActors 순회 → Destroy Actor → 배열 Clear
  SpawnActor 반환값 → SpawnedActors에 Add

주의: SpawnedActors는 위젯 인스턴스 변수다.
      에디터를 닫거나 위젯을 재시작하면 배열이 초기화된다.
      위젯 재시작 후 Always Respawn을 실행해도 이전 세션에서
      만들어진 오브젝트는 자동 삭제되지 않는다. 씬에서 수동 삭제 필요.

워크플로

1

기준 액터 선택

분수, 화분, 오브젝트 등 배치의 기준이 될 액터를 뷰포트에서 선택한다. 이 위치를 기준으로 메시가 랜덤 산포된다. 선택 없이 버튼을 누르면 Guard Clause에서 종료된다.

2

Settings 설정

메시 목록, 개수, X/Y/Z 범위를 설정한다. 범위는 기준 액터로부터의 오프셋 값이다.

3

생성하기 실행 → 결과 확인

버튼을 누르면 매 틱마다 1개씩 분산 스폰된다. 결과가 마음에 들지 않으면 Always Respawn ON 상태에서 다시 실행하면 이전 오브젝트는 제거되고 새로 산포된다.

4

같은 메시 + 같은 머티리얼끼리 선택

아웃라이너에서 메시 이름으로 필터링해 같은 종류끼리 선택한다. Actor Label이 메시 이름으로 자동 설정되어 있어 선택이 편하다. ISM은 메시와 머티리얼이 모두 동일한 액터끼리만 묶어야 드로우콜 절감 효과가 유효하다.

5

인스턴스 변환하기 실행

버튼을 누르면 선택된 Actor들이 ISM 하나로 병합된다. 씬에는 BP_DropContainer 하나만 남고, 드로우콜이 N → 1로 줄어든다.

02 / SPAWN LOGIC

1. 생성하기

Set Timer by Event로 틱 분산 스폰 · 랜덤 Transform 계산

루프 대신 타이머를 선택한 이유

처음에는 For Loop로 Drop Count만큼 한 번에 스폰했다. 개수가 많아지면 루프가 끝날 때까지 에디터가 멈추는 문제가 생겼다. Set Timer by Event로 바꿔 Custom Event Ev_SpawnStep을 매 틱마다 호출하도록 했다.

Interval 0 동작 주의 — Set Timer by Event에 Interval 0, Looping true를 설정하면 에디터 틱마다 이벤트가 반복 호출된다. "다음 틱에 한 번" 실행되는 것이 아니라 매 틱마다 계속 호출된다. 카운트가 Drop Count에 도달하는 시점에 반드시 Clear and Invalidate Timer by Handle을 호출해 루프를 종료해야 한다. 게임 런타임 Tick과 달리 에디터 틱은 뷰포트 갱신에 묶여 있어, 에디터 포커스가 없을 때 호출 빈도가 달라질 수 있다.

스폰 로직 흐름 — Button 1 On Clicked

랜덤 Transform 계산

요소	방법	이유
위치	X/Y/Z 각각 `Random Float in Range`로 계산 후 기준 위치에 더함	축별로 범위를 독립적으로 설정할 수 있어 방향에 따라 다른 산포 범위 지정 가능
회전	`Make Rotator(Pitch=0, Yaw=Random Float in Range(0,360), Roll=0)` — Z축(Yaw) 회전만 적용	바닥에 놓이는 소품은 Pitch/Roll을 랜덤화하면 오브젝트가 옆으로 눕거나 뒤집힌다. Make Rotator에서 Yaw 값만 랜덤으로 지정하면 의도를 코드에서 직접 읽을 수 있어 유지보수가 쉽다. 이전 구현에서 사용하던 Rotation From X Vector는 "입력 벡터 방향으로 X축을 정렬하는 회전"을 반환하는 노드로, Yaw-only 회전을 보장하지 않는다. Make Rotator로 교체해 의도를 명확히 했다.
스케일	`Random Float in Range` (기본 0.5 ~ 1.0)	같은 메시가 동일한 크기로 반복되면 패턴이 보인다. 크기 변화로 단조로움 방지
메시 선택	Drop Mesh List 배열에서 `RANDOM`으로 인덱스 선택	목록에 여러 메시를 넣으면 매 스폰마다 다른 메시가 섞여 자연스러운 산포 연출
Actor Label	`Get Display Name → Set Actor Label`	아웃라이너에서 메시 이름으로 표시. ISM 변환 단계에서 같은 메시끼리 필터링해 선택하기 위한 준비 ISM은 메시 종류와 머티리얼이 동일한 Actor끼리 묶어야 하기 때문

03 / ISM CONVERSION

2. 인스턴스 변환하기

선택된 Static Mesh Actor → ISM 하나로 병합 · 드로우콜 N → 1

같은 메시 100개가 Actor로 분산되어 있으면 드로우콜이 100개다. ISM으로 묶으면 1개로 줄어든다. 변환은 네 단계로 진행된다.

ISM 변환 흐름 — Button 2 On Clicked

1

Centroid 계산

선택된 Actor 전체의 위치를 For Each Loop로 누적한 뒤 개수로 나눠 평균을 구한다. 이 위치가 BP_DropContainer의 스폰 위치가 된다.

For Each → Get Actor Location → 누적 합산 → ÷ 개수 → SET Centroid

원점(0,0,0) 고정으로 하면 오브젝트가 씬 원점에서 멀리 있을 때 컨테이너와 인스턴스 간 상대 트랜스폼이 어긋난다. 선택 오브젝트 중심에 컨테이너를 스폰해야 인스턴스 트랜스폼이 정확히 유지된다.

2

컨테이너 스폰 · Static Mesh 지정 · 인스턴스 등록

Centroid 위치에 BP_DropContainer를 스폰한다. 스폰 직후 ISM 컴포넌트를 취득하고, Add Instance를 호출하기 전에 반드시 Set Static Mesh로 렌더링할 메시를 지정해야 한다. 메시가 지정되지 않은 상태에서 Add Instance를 호출하면 인스턴스가 등록되더라도 씬에 아무것도 렌더링되지 않는다. 선택된 첫 번째 Actor의 Static Mesh를 기준으로 지정한다. 이후 For Each에서 각 Actor의 월드 트랜스폼을 Add Instance로 넘긴다.

SpawnActor(BP_DropContainer, Centroid) → Get ISM Component → Set Static Mesh (첫 번째 Actor의 Mesh 기준) → For Each Actor → Add Instance (World Space ON)

World Space ON으로 설정해야 컨테이너 위치 기준으로 재계산되지 않고, 원본 Actor의 월드 트랜스폼(위치·회전·스케일)이 그대로 유지된다.

3

원본 Actor 제거

인스턴스 등록이 끝나면 같은 루프 안에서 Destroy Actor를 호출한다. ISM과 원본 Actor가 같은 위치에 겹쳐 있으면 렌더링이 중복 발생한다. 루프가 끝나면 씬에는 BP_DropContainer 하나만 남는다.

For Each → Add Instance → Destroy Actor (같은 루프 내 순차 실행)

루프 종료 후 일괄 삭제하면 중간 상태에서 렌더링이 중복될 수 있다. Add Instance 직후 같은 순서에서 바로 Destroy한다.

ISM은 같은 메시 + 같은 머티리얼끼리만 묶어야 한다 — ISM 컴포넌트 하나는 하나의 Static Mesh와 하나의 머티리얼 세트에 대한 인스턴스만 처리한다. 다른 메시나 머티리얼을 섞어 선택하면 Set Static Mesh에서 첫 번째 Actor 기준 메시만 적용되어 나머지 Actor의 외형이 잘못 렌더링된다. 머티리얼이 다른 경우에도 드로우콜이 분리되므로 인스턴싱의 이점이 사라진다. 워크플로 4단계에서 Actor Label(메시 이름)과 머티리얼을 함께 확인하고 나눠 선택한 뒤 변환하면 된다.

04 / ISM vs HISM

컴포넌트 선택 기준

규모에 따른 ISM · HISM 판단

이 툴은 ISM(Instanced Static Mesh Component)을 사용한다. 수십 개 단위의 씬 드레싱 오브젝트에는 ISM이 충분하지만, 규모가 커지면 HISM(Hierarchical Instanced Static Mesh Component)이 더 유리한 상황이 생긴다. 아래 기준으로 선택한다.

항목	ISM	HISM
인스턴스 수 기준	수십 ~ 수백 개 (씬 드레싱 규모)	수백 ~ 수천 개 이상 (자연물, 대규모 반복 오브젝트)
LOD 자동 처리	지원하지 않음. 카메라 거리와 무관하게 동일 LOD 렌더링	지원. 거리에 따라 LOD 자동 전환, 성능 절감 효과 큼
Cull Distance 관리	수동 설정 필요	인스턴스별 Cull Distance 내장 지원
BVH 기반 컬링	없음	있음. 카메라 Frustum 안에 있는 인스턴스만 렌더링
개별 인스턴스 Update 비용	낮음	트리 재구성 비용 존재, 잦은 동적 변경에는 불리
이 툴의 현재 선택	씬 드레싱 단위(수십 개)는 ISM으로 충분. 수백 개 이상, 야외 대규모 배치로 확장 시 BP_DropContainer 내부 컴포넌트를 HISM으로 교체하면 된다. 툴 외부 로직 변경 없이 컨테이너 내부 컴포넌트 타입만 바꾸면 전환 가능.

전환 방법 — BP_DropContainer 블루프린트를 열고, ISM 컴포넌트를 삭제한 뒤 HISM 컴포넌트를 추가한다. WBP_SmartLayoutTool의 변환 로직은 Add Instance와 Set Static Mesh를 사용하는데, HISM도 동일한 인터페이스를 지원하므로 위젯 코드를 수정하지 않아도 된다.

05 / SUMMARY

핵심 설계 결정 정리

각 선택의 이유

설계 결정

루프 → 타이머 분산 스폰

For Loop는 완료될 때까지 에디터를 블록한다. Set Timer by Event로 전환해 매 틱 1개씩 스폰함으로써 에디터 응답성을 유지한다. Interval 0 + Looping true로 매 틱 반복 호출되며, Drop Count 도달 시 Clear and Invalidate Timer by Handle로 루프를 종료한다.

Make Rotator로 Yaw만 적용

바닥 소품에 Pitch/Roll을 랜덤화하면 오브젝트가 눕거나 뒤집힌다. Make Rotator(0, Random 0~360, 0)으로 Yaw만 무작위 지정해 의도를 코드에서 바로 읽을 수 있게 했다. Rotation From X Vector는 벡터 방향으로 X축을 정렬하는 노드로, Yaw-only를 보장하지 않아 제외했다.

Centroid 기준 컨테이너 스폰

원점 고정 시 오브젝트가 씬 원점에서 멀리 있으면 컨테이너와 인스턴스 간 상대 트랜스폼이 어긋난다. 선택된 오브젝트의 평균 위치에 컨테이너를 배치해 World Space ON과 함께 정확한 위치를 보장한다.

Set Static Mesh 선행 호출

ISM 컴포넌트는 Add Instance 전에 Set Static Mesh로 렌더링할 메시를 지정해야 한다. 미지정 상태에서 호출하면 인스턴스 데이터는 등록되지만 씬에 아무것도 표시되지 않는다. 첫 번째 Actor의 메시를 기준으로 스폰 직후 지정한다.

Guard Clause — 빈 선택 차단

두 버튼 모두 진입 시 선택된 액터 수를 확인한다. 0이면 노티피케이션 출력 후 즉시 종료한다. 빈 배열로 Centroid를 계산하면 0 나누기 오류가 발생하고, 타이머가 기동된 상태에서 종료 조건이 충족되지 않아 무한 루프로 이어질 수 있다.

SpawnedActors 배열 추적

Always Respawn은 위젯 변수 SpawnedActors 배열로 이전 스폰 Actor를 추적해 재실행 시 삭제한다. 위젯 인스턴스 변수이므로 에디터 재시작 또는 위젯 재오픈 시 배열이 초기화된다. 이전 세션의 오브젝트는 자동 삭제되지 않으므로 수동 제거가 필요하다.

메시 + 머티리얼 동일 조건

ISM은 메시뿐 아니라 머티리얼도 동일해야 드로우콜 절감이 유효하다. 머티리얼이 다른 인스턴스는 내부적으로 별도 드로우콜로 분리된다. 변환 전 워크플로에서 Actor Label(메시 이름)과 머티리얼을 함께 확인해 선택 범위를 맞춰야 한다.

두 버튼의 독립성

생성과 변환을 분리해 각각 단독으로 쓸 수 있다. 씬에 이미 배치된 오브젝트를 선택해 변환만 실행하거나, 생성만 반복해 결과를 조정한 뒤 나중에 변환해도 된다.

반복 배치와 ISM 변환을 하나의 툴 안으로 통합했다. 작업자는 메시 종류, 개수, 범위만 결정하면 되고, 타이밍 제어·트랜스폼 계산·레퍼런스 추적은 툴이 처리한다. 이후 같은 구조로 스폰 조건(표면 법선 정렬, 충돌 감지), 다중 컨테이너 분리(메시별 자동 그룹화), 또는 ISM → HISM 교체를 통한 대규모 배치 지원으로 확장할 수 있다.

WBP_SmartLayoutTool씬 드레싱 자동화 에디터 툴