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

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

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

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

블루프린트 함수 라이브러리는 특정 액터나 오브젝트에 종속되지 않고, 라이브러리 인스턴스 없이 호출하는 정적(Static) 함수들의 모음입니다.

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

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

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

함수 라이브러리의 함수는 라이브러리 객체를 만들지 않고 검색해 호출합니다. 다만 World Context나 특정 대상 참조가 필요한 함수는 호출 문맥과 입력을 충족해야 합니다.

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

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

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

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

콘텐츠 브라우저에서 마우스 오른쪽 버튼을 클릭합니다.
블루프린트(Blueprints) 메뉴에서 Blueprint Function Library 에셋을 생성합니다. 에디터 버전에 따라 메뉴 배치는 달라질 수 있습니다.
이름을 지정합니다. (예: BFL_GameUtilities - 일반적으로 BFL_ 접두사를 사용합니다.)

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

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

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

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

함수 라이브러리 활용 예시

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

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

함수 라이브러리 함수 호출

이벤트 그래프의 빈 공간에서 마우스 오른쪽 버튼을 클릭합니다.
여러분이 정의한 함수 이름(예: CalculateDistanceBetweenActors)을 검색합니다. 함수 라이브러리 함수의 경우, 검색 시 해당 함수가 속한 라이브러리 이름과 함께 표시됩니다. (예: Calculate Distance Between Actors (BFL_GameUtilities))
해당 함수 노드를 선택하여 그래프에 배치합니다.
ActorA와 ActorB 입력 핀에 적절한 액터 레퍼런스(예: Get Player Character, Get Actor Of Class 등으로 가져온 특정 적 액터)를 연결합니다.
유효한 두 액터를 준비한 뒤 실행 선을 함수 호출 → Print String으로 연결하고, Distance 값을 문자열로 변환해 출력합니다. 찾지 못한 액터를 그대로 넘기지 않습니다.

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

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

순수 함수(Pure Function) 생성
- 함수 라이브러리 함수도 목적에 따라 Pure 또는 실행 핀이 있는 함수로 정의할 수 있습니다. 순수 함수는 입력 핀을 기반으로 출력 값을 계산하며, 내부적으로 상태를 변경하거나 실행 핀을 가지지 않습니다. 노드에 아이콘이 붙어 있습니다.
- 디테일 패널에서 Pure 옵션을 체크/해제하여 설정할 수 있습니다.
- Pure 표시는 결과 캐시나 같은 인자에 대한 결정성을 강제하지 않습니다. 예를 들어 같은 Actor 참조라도 액터가 움직이면 거리 결과는 달라집니다. 호출 부작용을 피하고, 입력값만으로 계산하는 작은 함수에 적용하세요.
데이터 테이블 또는 저장 게임 오브젝트와 연동
- 함수 라이브러리에 데이터 테이블에서 데이터를 가져오는 함수나, 저장 게임 오브젝트를 로드/저장하는 유틸리티 함수 등을 만들어 두면, 여러 곳에서 동일한 로직을 쉽게 재사용할 수 있습니다.
- 예시: Get Item Data (By Row Name) 함수를 BFL_GameUtilities에 정의하여, 아이템 데이터 테이블에서 쉽게 데이터를 가져오는 로직을 캡슐화할 수 있습니다.
상태 소유: 라이브러리를 액터처럼 인스턴스 상태의 저장소로 쓰지 않습니다. 함수의 지역 변수와 입출력은 사용할 수 있으며, 외부 상태가 필요하면 참조를 입력으로 받아 의존성을 드러냅니다.
클래스 역할: 라이브러리는 UBlueprintFunctionLibrary 계열의 공용 정적 함수 모음입니다. 액터 인스턴스의 다형적 행동을 오버라이드하는 상속 설계와 구분합니다.

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

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

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

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

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

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

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

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

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

함수 라이브러리 활용 예시

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

이 페이지의 목차