함수 라이브러리 생성 및 활용

지금까지는 변수, 함수, 매크로를 통한 코드 재사용과 데이터 테이블/세이브 오브젝트/에셋 레퍼런싱을 통한 데이터 관리 방법을 다뤘습니다.

이번 절에서는 여러 블루프린트에서 공통으로 쓰는 유틸리티 함수를 한곳에 모아 관리하는 블루프린트 함수 라이브러리(Blueprint Function Library)를 다룹니다.

클래스 생성
클래스 생성 Blueprint Function
Library를 선택하고 BFL_ 접두사로 이름을 고정합니다.
함수 정의
함수 정의 입력 핀
출력 핀을 먼저 정해 호출 계약을 작게 만듭니다.
계산 연결
계산 연결 ActorA, ActorB 같
입력을 계산 노드에 넣고 결과만 반환합니다.
컴파일 확인
컴파일 확인 다른 블루프린트
검색·호출·반환값 표시까지 확인합니다.

판정 축	라이브러리에 둔다	블루프린트에 남긴다	점검 신호
인스턴스 상태	월드·컴포넌트 멤버를 읽지 않는다	소유 액터의 현재 상태가 필요하다	Target 핀 없이 설명 가능
입력·출력 핀	입력값만 계산해 결과를 반환한다	내부 변수, 타이머, 이벤트에 의존한다	핀 이름만 보고 계약이 읽힘
호출 범위	여러 그래프에서 같은 로직을 반복한다	한 클래스의 전용 행동이다	검색해서 바로 배치할 가치가 있음
부작용	변환, 검증, 수치 계산이 중심이다	Spawn, Save, UI 변경이 중심이다	Pure 옵션 검토 대상

함수 라이브러리란 무엇인가?

아래 다이어그램은 공통 로직을 함수 라이브러리로 분리할 때 어떤 기준으로 묶고, 어디서 호출해 재사용하는지 정리한 것입니다.

넣어도 좋은 함수
Pure calculation 거리, 각도, 점수 공식 Format helper 텍스트 포맷, 단위 변환 Small utility 공통 검증, 배열 정리
넣으면 위험한 함수
Actor state 특정 Actor 변수 직접 수정 Widget state 화면 인스턴스에 강하게 의존 Hidden side effect 어디서 호출됐는지 추적 어려움

검수	의미
기준	입력만으로 결과가 정해지면 라이브러리에 맞다.
검수	World Context가 필요하면 정말 전역 함수인지 다시 본다.

블루프린트 함수 라이브러리는 특정 액터나 오브젝트에 종속되지 않고, 어디서든 호출할 수 있는 정적(Static) 함수들의 모음입니다.

즉, 특정 인스턴스(객체) 없이도 바로 호출하여 사용할 수 있는 기능들을 담는 블루프린트 클래스입니다.

일반적인 블루프린트의 함수는 해당 블루프린트의 인스턴스가 존재해야만 호출할 수 있습니다.

예를 들어, BP_PlayerCharacter의 Jump 함수를 호출하려면 BP_PlayerCharacter의 인스턴스가 있어야 합니다.

하지만 함수 라이브러리의 함수는 마치 Print String 노드처럼, 어떤 블루프린트에서든 바로 검색하여 사용할 수 있습니다.

함수 라이브러리가 필요한 이유

높은 재사용성: 게임 전반에 걸쳐 자주 사용되는 범용적인 유틸리티 기능을 한곳에 모아두면, 필요한 곳에서 쉽게 가져다 쓸 수 있습니다.
느슨한 결합: 특정 액터에 종속되지 않으므로, 다른 블루프린트와의 의존성을 줄여줍니다.
유지보수 용이성: 공통 기능이 수정될 경우, 함수 라이브러리에서 한 번만 수정하면 모든 호출 위치에 반영됩니다.
코드 깔끔함: 반복되는 로직을 함수 라이브러리로 분리하여 블루프린트 그래프를 간결하고 읽기 쉽게 만듭니다.
성능 최적화: 정적 함수는 특정 인스턴스에 대한 참조를 유지할 필요가 없으므로 미미하게나마 성능 이점을 가질 수 있습니다.

함수 라이브러리 생성 및 함수 정의

함수 라이브러리 블루프린트 생성

콘텐츠 브라우저에서 마우스 오른쪽 버튼을 클릭합니다.
블루프린트 클래스(Blueprint Class)를 선택합니다.
모든 클래스(All Classes)를 펼친 후 Blueprint Function Library를 검색하여 선택합니다.
이름을 지정합니다. (예: BFL_GameUtilities - 일반적으로 BFL_ 접두사를 사용합니다.)

함수 라이브러리에 함수 정의

생성된 BFL_GameUtilities 블루프린트 에디터를 엽니다.
일반 블루프린트와 유사하게 좌측 함수(Functions) 패널에서 + 함수(+ Function) 버튼을 클릭하여 새 함수를 추가합니다.
함수 이름을 지정합니다. (예: CalculateDistanceBetweenActors)
디테일 패널에서 필요한 입력(Inputs) 및 출력(Outputs) 핀을 추가합니다.
- 예시: ActorA (Actor Reference), ActorB (Actor Reference) 입력 핀, Distance (Float) 출력 핀
함수 로직 구현
- ActorA와 ActorB의 위치를 가져와 Vector Length 노드로 거리를 계산하고, 이 값을 Return Node의 Distance 출력 핀에 연결합니다.
- 함수 라이브러리 함수는 기본적으로 정적(Static) 으로 설정됩니다. 이 때문에 함수 노드에 Target 핀이 없습니다.

컴파일 및 저장: 함수를 정의한 후에는 블루프린트를 컴파일하고 저장해야 합니다.

함수 라이브러리 함수는 호출 위치가 많아질수록 입력, 검증, 계산, 반환의 계약이 명확해야 유지보수하기 쉽습니다.

Inputs
input Actor, Row Name, Save Slot처럼 함수가 의존하는 값을 호출자가 넘깁니다.
Validate
guard None, 빈 이름, 범위 오류를 먼저 걸러 Access None을 줄입니다.
Calculate
work 거리 계산, 테이블 조회, 문자열 포맷처럼 재사용 로직만 둡니다.
Return
output 결과 값과 성공 여부를 출력 핀으로 분리해 호출부가 분기합니다.

함수 라이브러리 활용 예시

이제 정의한 CalculateDistanceBetweenActors 함수를 다른 블루프린트에서 사용해 봅시다.

함수 호출할 블루프린트 열기: (예: BP_PlayerCharacter 또는 BP_GameManager)

함수 라이브러리 함수 호출

이벤트 그래프의 빈 공간에서 마우스 오른쪽 버튼을 클릭합니다.
여러분이 정의한 함수 이름(예: CalculateDistanceBetweenActors)을 검색합니다. 함수 라이브러리 함수의 경우, 검색 시 해당 함수가 속한 라이브러리 이름과 함께 표시됩니다. (예: Calculate Distance Between Actors (BFL_GameUtilities))
해당 함수 노드를 선택하여 그래프에 배치합니다.
ActorA와 ActorB 입력 핀에 적절한 액터 레퍼런스(예: Get Player Character, Get Actor Of Class 등으로 가져온 특정 적 액터)를 연결합니다.
Distance 출력 핀을 Print String 노드에 연결하여 계산된 거리를 화면에 출력합니다.

컴파일 및 실행: 블루프린트를 컴파일하고 게임을 실행하여 결과가 올바르게 나오는지 확인합니다.

함수 라이브러리의 고급 활용 및 고려사항

순수 함수(Pure Function) 생성
- 함수 라이브러리의 함수는 기본적으로 순수 함수로 설정될 수 있습니다. 순수 함수는 입력 핀을 기반으로 출력 값을 계산하며, 내부적으로 상태를 변경하거나 실행 핀을 가지지 않습니다. 노드에 아이콘이 붙어 있습니다.
- 디테일 패널에서 Pure 옵션을 체크/해제하여 설정할 수 있습니다.
- 순수 함수는 여러 번 호출되어도 항상 같은 입력에 대해 같은 출력을 반환하므로, 깔끔한 계산 로직에 적합합니다.
데이터 테이블 또는 저장 게임 오브젝트와 연동
- 함수 라이브러리에 데이터 테이블에서 데이터를 가져오는 함수나, 저장 게임 오브젝트를 로드/저장하는 유틸리티 함수 등을 만들어 두면, 여러 곳에서 동일한 로직을 쉽게 재사용할 수 있습니다.
- 예시: Get Item Data (By Row Name) 함수를 BFL_GameUtilities에 정의하여, 아이템 데이터 테이블에서 쉽게 데이터를 가져오는 로직을 캡슐화할 수 있습니다.
변수 사용 불가: 함수 라이브러리 블루프린트 자체에는 변수를 추가할 수 없습니다. 이는 함수 라이브러리가 특정 인스턴스에 종속되지 않는 정적 함수들의 모음이기 때문입니다. 데이터를 다루려면 함수의 입력/출력 핀을 사용하거나, Game Instance와 같은 전역적인 데이터 저장소에 접근해야 합니다.
상속 불가: 함수 라이브러리는 다른 블루프린트로부터 상속받을 수 없으며, 다른 블루프린트가 함수 라이브러리를 상속받을 수도 없습니다. 순수하게 유틸리티 함수 모음으로서의 역할에 집중합니다.

함수 라이브러리는 편리하지만, 모든 로직을 몰아넣는 장소가 아니라 호출 범위가 넓은 작은 도구만 모아두는 곳입니다.

호출 범위
여러 블루프린트에서 반복되는지 먼저 확인합니다.
입출력 계약
필요한 값은 입력 핀으로 받고 결과는 출력 핀으로 돌려줍니다.
상태 분리
액터 변수 변경은 호출한 블루프린트 안에 남깁니다.
검색 이름
BFL_ 접두사와 용도 중심 이름으로 검색 가능하게 만듭니다.

함수 라이브러리는 블루프린트 프로젝트의 구조를 깔끔하게 유지하고, 반복적인 작업을 줄이며, 팀원 간의 협업 효율성을 높이는 데 매우 중요한 도구입니다.

자주 사용되는 공통 기능을 함수 라이브러리에 모아두는 습관을 들이면, 장기적으로 훨씬 관리하기 쉬운 블루프린트 시스템을 구축할 수 있습니다.

이번 절에서는 블루프린트 함수 라이브러리의 개념, 생성 및 활용 방법, 그리고 그 장점에 대해 자세히 알아보았습니다.

함수 라이브러리는 유틸리티성 기능을 중앙 집중적으로 관리하는 데 최적의 솔루션입니다.

이로써 5장 기본 데이터 관리 기법의 모든 내용을 마쳤습니다.

마지막으로 함수 라이브러리에 넣을 로직과 블루프린트 안에 남길 로직을 구분하는 기준을 정리합니다.

재사용 계산은 라이브러리로 이동
거리 판정, 데이터 변환, 포맷팅처럼 입력과 출력이 명확한 로직은 라이브러리에 두고 액터 상태 변경은 호출자에게 남깁니다. 01 GetHealthPercent, FormatGoldText, IsInventoryFull처럼 같은 입력이면 같은 결과를 내는 함수는 Blueprint Pure가 어울립니다. 02 Spawn 관련 처리나 월드 접근이 필요한 함수는 World Context를 받고 실행 핀으로 성공 여부를 돌려줍니다. 03 플레이어 체력 저장, UI 열기, AI 상태 변경처럼 특정 객체의 책임인 로직은 해당 Blueprint에 둡니다.
재사용 계산은 라이브러리로 이동
거리 판정, 데이터 변환, 포맷팅처럼 입력과 출력이 명확한 로직은 라이브러리에 두고 액터 상태 변경은 호출자에게 남깁니다.
Pure 후보
GetHealthPercent, FormatGoldText, IsInventoryFull처럼 같은 입력이면 같은 결과를 내는 함수는 Blueprint Pure가 어울립니다.
Exec 후보
Spawn 관련 처리나 월드 접근이 필요한 함수는 World Context를 받고 실행 핀으로 성공 여부를 돌려줍니다.
제외 대상
플레이어 체력 저장, UI 열기, AI 상태 변경처럼 특정 객체의 책임인 로직은 해당 Blueprint에 둡니다.

함수 라이브러리에 넣을 로직과 제외할 로직의 기준을 추가합니다.

질문	판정
입력값만으로 계산되나?	Pure Function 후보. 라이브러리에 적합하다.
월드나 Actor를 찾아야 하나?	호출부에서 대상 참조를 넘기도록 바꾼다.
UI를 직접 바꾸나?	Widget 또는 Controller 책임으로 남긴다.
여러 프로젝트에서 복사해도 되나?	의존성이 작다면 좋은 유틸리티다.