매크로 생성 및 간단한 사용 예

앞서 함수를 통해 반복되는 로직을 묶어 재사용하는 방법을 알아보았습니다.

블루프린트에는 함수와 유사하면서도 다른 특징을 가진 또 다른 재사용 가능한 로직 묶음인 매크로(Macro)가 있습니다.

매크로는 특정 노드들의 조합을 하나의 블록으로 만들어, 블루프린트 그래프를 더욱 깔끔하고 읽기 쉽게 만드는 데 도움을 줍니다.

함수와 매크로는 모두 재사용 가능한 로직 묶음이라는 공통점을 가지고 있지만, 내부적으로 작동하는 방식과 사용 시점에 미묘한 차이가 있습니다.

매크로는 함수와 달리 컴파일 시 해당 매크로 내부의 노드들이 호출 위치에 그대로 복사되어 붙여넣어지는 방식으로 작동합니다.

이는 템플릿처럼 작동한다고 이해하시면 됩니다.

매크로와 함수 선택, 실행 핀, 컴파일 펼침 구조

매크로는 편리하지만 컴파일 시 그래프가 펼쳐지고 디버깅 경계가 흐려지므로 함수, 매크로, 이벤트의 책임을 구분해야 합니다.

1. 목적 확인

   계산 재사용인지, 실행 흐름 제어인지, 이벤트 분배인지 먼저 구분합니다. intent

2. 함수 우선 검토

   입출력 계약으로 표현 가능하고 부작용이 명확하면 함수로 만듭니다. function

3. 매크로 기준 확인

   여러 실행 핀, 반복 흐름, early exit 같은 그래프 형태 재사용이 필요할 때 매크로를 씁니다. macro

4. 확장 비용 확인

   매크로는 호출 위치마다 펼쳐져 그래프와 디버깅 비용이 커질 수 있습니다. expand

5. 공유 범위 결정

   프로젝트 전체 공통이면 Macro Library나 Function Library로 위치를 명확히 합니다. library

---

매크로란 무엇인가?

매크로는 호출 위치에 그래프 조각이 펼쳐지는 재사용 단위다

함수처럼 보이지만 컴파일 때 내부 노드가 호출 지점에 인라인으로 붙는다는 점이 핵심 차이다.

1. Macro가 맞는 경우

   실행 핀 모양 Success/Fail처럼 여러 실행 출력이 필요하다. 그래프 패턴 검증 후 분기 같은 노드 모양을 반복한다. 디버그 헬퍼 Print, Gate, Sequence를 묶어 호출 그래프를 줄인다.

2. Function이 맞는 경우

   값 계산 입력값으로 결과값을 돌려준다. 로컬 변수 내부 상태를 함수 안에 격리한다. 명확한 반환 호출자가 결과를 다음 분기에 쓴다.

검수	의미
주의	매크로는 숨긴 것이 아니라 호출 위치마다 펼쳐진다고 이해해야 한다.
판단	값 계약이면 함수, 실행선 형태 재사용이면 매크로다.

매크로는 여러 개의 노드를 하나로 묶어놓은 재사용 가능한 그래프 조각입니다.

매크로는 함수처럼 입출력 핀을 가질 수 있으며, 복잡한 로직을 추상화하여 블루프린트 그래프의 가독성을 크게 향상시킵니다.

특히, 매크로는 함수가 제공하지 않는 특정 유연성을 제공하여, 특정 상황에서 함수보다 더 적합할 수 있습니다.

---

매크로 정의 및 생성하기

매크로를 생성하는 과정은 함수와 매우 유사합니다.

---

매크로 사용 예시: 간편한 디버그 메시지 출력

이제 정의한 PrintDebugMessage 매크로를 이벤트 그래프에서 사용해 봅시다.

이처럼 매크로를 사용하면 복잡한 노드 그룹을 하나의 간결한 블록으로 만들 수 있습니다.

특히, 자주 사용하지만 여러 입출력 흐름을 가져야 하거나, 특정 노드의 내부 구조를 그대로 복사해야 하는 경우에 매우 유용합니다.

---

함수와 매크로의 차이점 및 적절한 사용 시점

함수와 매크로는 모두 재사용성을 위한 도구이지만, 그 특성 때문에 적절한 사용 시점이 다릅니다.

언제 무엇을 사용해야 할까요?

함수는 계산 계약, 매크로는 실행선 모양을 재사용한다

입력과 출력값이 중심인지, 여러 실행 핀과 그래프 형태가 중심인지에 따라 선택이 갈린다.

1. Function

   시점 입력 → 처리 → 반환 맞는 일 대미지 계산, 점수 추가 주의 Delay 같은 latent 금지

2. Macro

   시점 실행선 패턴 재사용 맞는 일 검증 후 Success/Fail 주의 큰 로직 은닉 금지

3. Collapsed Graph

   시점 현재 그래프 정리 맞는 일 한 번만 쓰는 묶음 주의 재사용 계약 아님

4. Custom Event

   시점 외부 호출 신호 맞는 일 비동기/분산 호출 주의 반환값 기대 금지

기준	해석
좋은 기준	“값을 돌려주는가”와 “실행 갈래를 보존해야 하는가”를 먼저 묻는다.
실무 기준	함수와 매크로를 이름만 보고 구분할 수 있어야 유지보수가 쉽다.

• 함수: 특정 기능을 깔끔하게 묶어 재사용하고 싶을 때, 재귀 호출이 필요하거나 로컬 변수를 사용하여 데이터 범위를 제한하고 싶을 때 사용합니다. 예를 들어, 체력 감소 로직, 아이템 사용 효과, 특정 계산 등.
• 매크로: 여러 개의 실행 흐름이 필요하거나, Sequence, Branch, Loop 등 복잡한 흐름 제어 노드를 특정 패턴으로 묶어 재사용하고 싶을 때 유용합니다. 또는 단순히 그래프의 가독성을 높이고 싶을 때도 사용합니다. 예를 들어, 안전한 대미지 적용 (체력 0 이하로 안 내려가게), 특정 조건 시 여러 이벤트 순차 실행 등.

처음에는 함수와 매크로의 구분이 모호하게 느껴질 수 있지만, 실제로 블루프린트를 작성하면서 이들의 특징을 이해하고 적절히 활용하는 연습을 하다 보면 자연스럽게 숙달될 것입니다.

마지막으로 앞에서 만든 PrintDebugMessage 예시를 다시 보면, 매크로 정의 그래프와 이벤트 그래프의 호출 위치가 어떻게 나뉘는지 더 분명해집니다.

PrintDebugMessage 매크로 흐름

매크로 정의 그래프에서는 Input과 Output 사이에 실제 노드를 넣고, 이벤트 그래프에서는 완성된 매크로를 하나의 노드처럼 호출합니다.

1. definition
   매크로 탭 안에서 만드는 구조

   definition Exec Message Duration 디테일 패널에서 Text와 Float 입력 핀을 추가해 호출할 때 받을 값을 정합니다. In String Duration Message는 In String으로, Duration은 표시 시간 핀으로 연결합니다. Then Print String 실행이 끝난 뒤 다음 실행 핀으로 흐름을 돌려줍니다.

2. 2
   Input 노드

   Exec Message Duration 디테일 패널에서 Text와 Float 입력 핀을 추가해 호출할 때 받을 값을 정합니다.

3. 3
   Print String

   In String Duration Message는 In String으로, Duration은 표시 시간 핀으로 연결합니다.

4. 4
   Output 노드

   Then Print String 실행이 끝난 뒤 다음 실행 핀으로 흐름을 돌려줍니다.

5. call site
   이벤트 그래프에서 호출하는 모습

   call site 게임 시작 시 한 번 실행 핀을 내보냅니다. 검색하거나 매크로 패널에서 드래그해 배치한 뒤 Message와 Duration을 채웁니다. 매크로를 이용한 메시지! 가 설정한 초 동안 화면에 표시됩니다.

6. 6
   Event BeginPlay

   게임 시작 시 한 번 실행 핀을 내보냅니다.

7. 7
   PrintDebugMessage

   검색하거나 매크로 패널에서 드래그해 배치한 뒤 Message와 Duration을 채웁니다.

8. 8
   화면 메시지

   매크로를 이용한 메시지! 가 설정한 초 동안 화면에 표시됩니다.

---

이번 절에서는 블루프린트의 또 다른 재사용 단위인 매크로의 개념, 생성 및 활용법, 그리고 함수와의 차이점에 대해 알아보았습니다.

이제 블루프린트의 기본적인 요소인 변수, 함수, 이벤트, 흐름 제어, 그리고 매크로에 대한 이해를 바탕으로, 더 복잡한 로직을 구축할 준비가 되었습니다.

함수와 매크로 선택 매트릭스

매크로는 편한 축약이 아니라 실행 핀 구조를 재사용해야 할 때 선택합니다. 계산이나 캡슐화는 함수가 더 안전한 기본값입니다.

1. 목적 확인

   계산인지 실행 흐름 제어인지 먼저 나눕니다.

2. 핀 구조 확인

   실행 출력이 여러 개 필요하면 매크로 후보입니다.

3. 디버깅 방식

   내부로 진입해 값을 보고 싶으면 함수가 관리하기 쉽습니다.

4. 호출 비용 판단

   매크로는 호출 위치마다 구조가 복사되므로 남용하지 않습니다.

매크로와 함수를 구분해 선택하는 판단표를 추가합니다.

매크로는 실행 핀 구조까지 재사용할 때만 선택한다

반복 노드 묶음이라도 실행선 모양이 중요하지 않으면 함수가 더 읽기 쉽다.

질문	판정
성공/실패 실행 핀이 필요한가?	매크로 후보. 호출 그래프에서 두 갈래가 보여야 한다.
단순 계산 결과만 필요한가?	함수 후보. 값 계약을 반환값으로 둔다.
숨긴 노드가 너무 많은가?	매크로가 호출 위치마다 복제되므로 작게 나눈다.
여러 그래프에서 같은 모양인가?	작은 검증·디버그 패턴이면 매크로로 유지한다.

신호	해석
좋은 매크로	IsValid 후 Valid/Invalid 실행 핀을 제공한다.
나쁜 매크로	거대한 이벤트 그래프를 한 노드처럼 숨긴다.

매크로를 사용할 때는 함수와의 차이를 먼저 확인하고, 실행 핀 구조를 재사용해야 하는 경우로 범위를 좁힙니다.

함수와 매크로는 재사용 목적이 다르다

둘 다 그래프를 짧게 만들지만, 함수는 호출 계약을 만들고 매크로는 실행 패턴을 펼친다.

1. Function 선택

   입력/출력 명확 인자와 반환값으로 계약을 설명할 수 있다. 로컬 변수 필요 임시 값을 함수 내부에 가둔다. 테스트 쉬움 같은 입력에 같은 결과를 기대한다.

2. Macro 선택

   여러 Exec 출력 Success/Fail, Loop Body/Completed를 노출한다. 노드 패턴 재사용 검증, 로그, 분기 모양을 반복한다. 인라인 확장 컴파일 후 호출 위치에 펼쳐짐을 감수한다.

검수	의미
핵심	반환값 중심이면 함수, 실행선 형태 중심이면 매크로다.
검수	호출 위치에서 내부 부작용이 예상 가능한지 확인한다.