코딩 부부

[언리얼엔진] Localization

테디슨 — Fri, 24 Apr 2026 11:55:51 +0900

언리얼 엔진 현지화

게임 개발을 하다 보면 언젠가 마주치게 되는 현지화(Localization). 언리얼 엔진은 강력한 내장 현지화 시스템을 제공하지만, 처음 접하면 "어디서부터 시작해야 하지?" 하는 생각이 들기 마련이다.

이 글은 현지화에 대해 아무것도 모르는 상태에서 시작해, 실제로 동작하는 시스템을 구축하기까지의 과정을 정리한 글이다.

1. 현지화 방식 선택 : 내장 vs 자체 구현

언리얼에서 현지화를 구현하는 방식은 크게 두 가지다.

언리얼 내장 (String Table + Localization Dashboard)

장점

UMG 위젯에서 바로 연동 (별도 코드 없이 자동 교체)
LOCTEXT / NSLOCTEXT 매크로로 코드에서 간편하게 사용
한국어 조사 자동 처리 ({변수}(을,를))
복수형(Plural Form) 처리 내장
숫자/날짜/통화 자동 포맷
.po 표준 포맷 지원 → PoEdit 등 외부 툴과 호환

단점

번역 데이터가 패키지 안에 묶여 핫픽스 배포가 까다로움
외부 서버에서 번역 데이터 받아오기 불편

자체 구현 (CSV/JSON 직접 로드)

장점

런타임 중 언어 데이터 동적 로드/교체 가능
외부 서버에서 실시간 번역 데이터 다운로드
핫픽스로 번역만 별도 배포 가능

단점

직접 구현해야 할 코드가 많음
한국어 조사, 복수형, 숫자 포맷 등을 모두 직접 구현해야 함

상황	추천
패키지 게임 (스팀, 콘솔)	언리얼 내장
라이브 서비스 모바일	자체 구현 또는 내장 + Pak 패치
소규모 팀, 빠른 개발	언리얼 내장

2. 한국어 조사 자동 처리 - 가장 큰 강점

한국어 현지화에서 가장 골치 아픈 부분이 조사 처리다. 동적인 아이템 이름이 들어갈 때마다 받침 유무에 따라 조사가 바뀌어야 하기 때문이다.

언리얼 내장 시스템은 이를 매크로 문법 하나로 해결해준다.

FText Format = LOCTEXT("ItemGet", "{ItemName}(을,를) 획득했습니다.");

FFormatNamedArguments Args;
Args.Add("ItemName", FText::FromString("사과"));
// 결과 : "사과를 획득했습니다."

Args.Add("ItemName", FText::FromString("사탕"));
// 결과 : "사탕을 획득했습니다."

지원하는 조사 쌍

(을,를) (이,가) (은,는) (와,과) (아,야)
(으로,로) (이어,여) (이에,에) (이었,였)

이것만으로도 언리얼 내장 시스템을 쓸 이유가 충분하다.

3. 핵심 개념 이해

Target과 Namespace의 차이

개념	역할
Target	.locres 파일 단위 (배포 단위)
Namespace	코드 내에서의 논리적 그룹핑

하나의 Target 안에 여러 Namespace가 들어갈 수 있다.

Target : Game  (= Game.locres 하나)
└── Namespace들 (한 파일 안에 다 들어감)
    ├── "Game"
    ├── "GameQuest"
    ├── "GameItem"
    └── "GameUI"

수집 기준

Gather는 Search Directory 하위의 모든 LOCTEXT를 Namespace 이름과 무관하게 모두 수집한다.

// Search Directory가 Source/Client/ 일 때

// Source/Client/Player.cpp
#define LOCTEXT_NAMESPACE "Game"
LOCTEXT("Hello", "안녕")          → 수집됨

// Source/Client/Quest.cpp
#define LOCTEXT_NAMESPACE "GameQuest"
LOCTEXT("StartQuest", "시작")     → 수집됨 (Namespace 달라도)

// Source/Editor/Tool.cpp  ← Search Directory 밖
LOCTEXT("Tool", "도구")           → 수집 안됨

4. 전체 워크플로우 5단계

Step 1 : 코드에서 텍스트 작성

// .cpp 파일 상단에 네임스페이스 정의
#define LOCTEXT_NAMESPACE "Game"

void AMyCharacter::ShowGreeting()
{
    // LOCTEXT(Key, DefaultText)
    FText Greeting = LOCTEXT("HelloKey", "안녕하세요");

    // 동적 값을 포맷에 끼워넣기
    LevelText->SetText(
        FText::Format(
            NSLOCTEXT("Game", "GearLevel", "Lv. {0}"),
            Gear->GetLevel()
        )
    );
}

#undef LOCTEXT_NAMESPACE

항목	역할
Namespace	"Game" → 그룹 식별자
Key	"HelloKey" → 고유 식별자
DefaultText	"안녕하세요" → 원본 텍스트

Step 2 : Gather (수집)

Tools → Localization Dashboard에서 Target을 생성하고 Gather를 실행한다.

설정 시 가장 중요한 항목

Search Directories : 코드가 있는 폴더 (예: Source/Game/)
Native Culture : 원본 언어 (예: ko)
Supported Cultures : 지원할 언어 목록

Gather 실행 후 생성되는 파일들

Content/Localization/Game/
├── Game.manifest         ← 원본 텍스트 마스터 (자동 생성)
├── Game.csv              ← 전체 텍스트 요약 (참고용)
├── Game_Conflicts.txt    ← Key 충돌 보고서
├── en/Game.archive       ← 영어 번역 데이터 (현재 비어있음)
└── ko/Game.archive       ← 한국어 번역 데이터

Step 3 : Export → 번역 → Import

번역가에게 전달할 .po 파일을 추출한다.

Localization Dashboard
└── Cultures 섹션
    └── 각 언어별 Export Translations 클릭
        └── ko/Game.po 생성

생성된 .po 파일 내용

msgctxt "Game,GearLevel"
msgid "Lv. {0}"
msgstr ""           ← 여기에 번역 입력

번역 작업은 PoEdit 같은 외부 툴을 사용한다. (PoEdit은 언리얼이 제공하는 게 아니라 .po가 GNU gettext 표준 포맷이라 호환되는 것이다.)

번역 완료 후

msgctxt "Game,GearLevel"
msgid "Lv. {0}"
msgstr "Lv. {0}"

번역된 .po를 Localization Dashboard에서 Import하면 archive 파일에 반영된다.

Step 4 : Compile (.locres 생성)

Localization Dashboard → Compile Text 클릭

결과물

Content/Localization/Game/
├── ko/Game.locres   ← 게임 런타임에 실제로 로드되는 파일
├── en/Game.locres
└── ja/Game.locres

Step 5 : 게임에서 확인

PIE 실행 후 콘솔(`)에서

culture=en   → 영어로 즉시 전환
culture=ko   → 한국어로 즉시 전환

5. UMG에서 번역 대상 제외하기

UMG 에디터에서 레이아웃 미리보기용으로 임시 텍스트(100%, 999/999 같은 값)를 입력하는 경우가 많다. 이런 텍스트들은 번역 대상에서 제외해야 한다.

Is Localized 체크 해제

TextBlock 선택
└── Details 패널
    └── Content 섹션
        └── Text 우측의 ▼ 화살표
            └── ☐ Is Localized   ← 체크 해제

효과

에디터/디자인 타임에는 그대로 표시 (레이아웃 확인 OK)
Gather 시 수집 대상에서 자동 제외

동적 값은 코드에서 SetText

// 동적 값은 FText::FromString으로 처리
HealthText->SetText(
    FText::FromString(FString::Printf(TEXT("%d%%"), Percent))
);

// FText::FromString은 런타임 생성이라 Gather 대상이 아님

6. 라이브 서비스를 위한 Target 분리 전략

모바일 라이브 서비스에서는 앱 본체는 가볍게, 본문 텍스트는 다운로드 후 로드 패턴이 유리하다.

Target을 2개로 분리

GamePatch.locres  (앱에 항상 포함, 가벼움)
├── 패치 안내 문구
├── 다운로드 진행 텍스트
├── 네트워크 에러 메시지
└── 점검 안내

Game.locres  (리소스 다운로드 후 사용, 큼)
├── UI 텍스트
├── 퀘스트
├── 아이템 설명
└── 스토리

주의할 점

다운로드 이전 단계에서 보이는 모든 텍스트는 반드시 GamePatch에 포함해야 한다. Game.locres가 다운로드되기 전이라 표시할 수 없기 때문이다.

런타임 동적 로드

// 다운로드 완료 후 호출
FTextLocalizationManager::Get().LoadLocalizationResourcesForCulture(
    TEXT("Game"),
    FInternationalization::Get().GetCurrentCulture()->GetName(),
    ELocalizationLoadFlags::Game
);

7. Perforce / Git 형상 관리

항상 등록해야 할 파일

Config/Localization/Game_*.ini       ← Target 설정 파일 (필수)
DefaultEditor.ini, DefaultEngine.ini ← Target 추가 시 자동 수정됨

Content/Localization/Game/
├── Game.manifest         ← 원본 마스터
├── Game.csv              ← 참고용
├── Game_Conflicts.txt    ← 충돌 추적
├── en/Game.archive       ← 영어 번역
├── ko/Game.archive       ← 한국어 번역
└── *.po                  ← 번역 작업 파일

.locres 등록 여부는 팀 정책

방식	장점	단점
.locres 등록	빌드 시 즉시 사용	저장소 용량 증가
.locres 미등록 (CI 자동 생성)	저장소 깔끔	빌드 파이프라인 필요

소규모 팀은 등록, 빌드 자동화가 갖춰진 팀은 미등록을 권장한다.

8. 자주 하는 실수와 해결법

Gather가 동작하지 않을 때

가장 흔한 원인은 Search Directories 미설정이다.

Localization Dashboard
└── Target : Game
    └── Gather Text 섹션
        └── Gather from Text Files
            └── Search Directories : Source/Game/ 추가  ← 90% 이 문제

Native Culture 미설정

Cultures 섹션
└── Native Culture : ko (또는 en) 반드시 설정

9. 정리

언리얼 내장 현지화 시스템의 핵심 흐름을 다시 한 번 정리하면 다음과 같다.

[코드 작성] LOCTEXT("Key", "원본 텍스트")
        ↓
[Gather]   Localization Dashboard에서 수집 → .manifest
        ↓
[Export]   번역가에게 전달할 .po 파일 추출
        ↓
[번역]     PoEdit 등 외부 툴로 번역 작업
        ↓
[Import]   번역된 .po를 다시 가져오기 → .archive
        ↓
[Compile]  .archive → .locres 바이너리 생성
        ↓
[런타임]   FInternationalization이 .locres 로드 → 자동 교체

처음에는 단계가 많아 보이지만, 한 번 파이프라인을 구축해두면 이후 텍스트 추가는 매우 빠르게 진행된다. 무엇보다 한국어 조사 자동 처리 하나만으로도 자체 구현 대비 엄청난 시간을 절약할 수 있다.

처음 현지화를 시작하시는 분들께 이 글이 도움이 되었으면 한다.

[회고] 주부의 삶 회고

최리 — Fri, 26 Apr 2024 11:04:11 +0900

육아 휴직 기록

아이가 태어나기 전 우리 부부의 퇴근 후 일상은 이랬다. 저녁 간단히 해결 후 밤 9시까지 적당히 공부하고 그날 공부한 내용 정리 후 놀다가 취침. 이걸 매일 반복. 왜냐면 습관이라는 건 하루 미루면 무뎌지니까...

그리고 출산 한지 약 10개월이 지났다. 육아 전만 해도 애는 혼자서 놀고 나는 책이나 보면서 자기개발 할 수 있을 줄 알았는데 개뿔... 밤 9시가 되면 겨우 육퇴하고 그때부터 밀린 집안일 시작. 나도 씻고 정신 좀 차리면 11시. 아 이제 자야지. 새벽에 이앓이라도 하는 날에는 너도 나도 초주검.

어린이집에 가면 이제 내 공부 다시 하겠구나 싶었는데. 약 두 달 동안 겨우 반정도 등원한 듯하다. 무슨 감기가 이렇게 오래가는지 당최 이해할 수 없다. 귀여운 건 귀여운 거고 아이란 정말 내 시간, 내 공간, 내 체력을 잡아먹는 괴... 아니 귀여운 생명체다.

아무튼 이 글은 복직 전 다시 내 뇌에 시동을 걸기 위한 다짐 같은 글!!! 5월에는 반드시 하루에 조금씩 뇌에 기름칠하자

참고로 출산 직전까지 공부하던 쿠버네티스 자격증은 떨어졌다. 나는 바보니까 더 열심히 공부해야 해.

5월의 목표 - 일상

가계부 정리
옵시디언 사용법 정리 후 새로 세팅

5월의 목표 - 자기개발

커리어 스킬 책 완독
말해보카 재신청
유데미 웹 강의 하나 들어보기

[언리얼엔진] 입력 개요

테디슨 — Wed, 31 May 2023 22:34:22 +0900

플레이어 입력(PlayerInput) 오브젝트는 플레이어의 입력을 플레이어 컨트롤러 또는 폰과 같은 액터가 이해하고 사용할 수 있는 데이터로 변환하는 기능을 한다. 이는 플레이어의 하드웨어 입력을 플레이어 입력 매핑 및 입력 컴포넌트를 통한 움직임과 게임 이벤트로 변환하는 입력 처리 흐름의 일부다.

하드웨어 입력

플레이어의 하드웨어 입력은 일반적으로 키 누름, 마우스 클릭 또는 마우스 움직임, 컨트롤러 버튼 누름 또는 조이스틱 움직임 등이 있다. 표준 축 또는 버튼 인덱스를 따르지 않거나 특이한 입력 범위를 갖는 특수 입력 디바이스는 RawInput 플러그인을 사용하여 수동으로 설정할 수 있다.

플레이어 입력

PlayerInput은 플레이어 입력을 관리하는 플레이어 컨트롤러 클래스 내의 UObject다. 클라이언트 측에서만 스폰된다. 두 구조체가 PlayerInput 내에서 정의된다. FInputActionKeyMapping 은 액션 매핑을 정의하고, FInputAxisKeyMapping 은 축 매핑을 정의한다. 액션 매핑과 축 매핑에 사용되는 하드웨어 입력 정의는 InputCoreTypes에서 확립한다.

액션 매핑

개별 버튼 또는 키 입력을 이후 이벤트 주도 행동에 바인딩될 '친근한 이름'으로 매핑한다. 최종 이펙트는 키, 마우스 버튼, 키패드 버튼을 누르거나 놓는 입력으로 일부 게임 행동을 직접 트리거한다.

축 매핑

키보드, 컨트롤러, 마우스 입력을 이후 이동과 같은 지속적인 게임 행동에 바인딩될 '친근한 이름'으로 매핑한다. 축 매핑에 매핑된 입력은 현재 입력값을 0이라고 보고해도 지속적으로 조사된다. 액션 매핑 입력으로 트리거되는 이산적 게임 이벤트는 분리된 반면에와 달리 축 매핑은 게임 행동 사이의 부드러운 전환을 가능하게 한다. 트랜지션이 가능하다. 예를 들어 플레이어 이동 등이 있다.

컨트롤러 조이스틱과 같은 하드웨어 축은 1(눌림) 또는 0(눌리지 않음)과 같이 분리된 입력이 아니라 입력의 강도를 제공한다. 축은 살짝 움직일 수도 있고 크게 움직일 수도 있으며, 그에 따라 캐릭터의 움직임이 달라질 수 있습니다. 이러한 입력 방법은 이동 입력에 스케일 조절 가능한 강도를 제공한다는 점이다. WASD 또는 화살표 같은 일반 이동 키 또한 축 매핑으로 지속적으로 조사되는 게임 행동에 매핑할 수 있다.

입력 매핑 설정하기

입력 매핑은 환경설정 파일에 저장되며, 프로젝트 세팅의 입력 섹션에서 편집 가능하다.

레벨 에디터에서 편집 > 프로젝트 세팅을 선택

프로젝트 세팅 탭에서 입력을 클릭

축 입력의 프로퍼티 변경

액션 매핑 편집

축 매핑 편집

입력 컴포넌트

입력 컴포넌트(InputComponent)는 보통 폰과 컨트롤러에 있지만 필요한 경우 다른 액터나 레벨 스크립트에서도 설정할 수 있다. 입력 컴포넌트는 프로젝트의 축 매핑과 액션 매핑을 C++ 코드 또는 블루프린트 그래프로 게임 액션에 연결한다.

입력 컴포넌트의 입력 처리 우선순위 스택은 다음과 같은 우선순위를 따른다.

최소로 최근에 사용한거부터 최대로 최근에 사용한것 까지 "입력 허용"이 활성화된 모든 액터
컨트롤러
레벨 스크립트.
폰

입력을 받은 입력 컴포넌트는 더 이상 스택 아래로 내려갈 수 없다.

입력 프로세싱 절차

예시 - 앞으로 이동

1인칭 템플릿에서 가져옴

플레이어의 하드웨어 입력 : 플레이어가 w를 누른다.
플레이어 입력 매핑 : 축 매핑이 w를 스케일이 1인 'MoveForward'로 변환

입력 컴포넌트 우선순위 스택 : 입력 컴포넌트 우선순위 스택을 거칠 때 'MoveForward' 입력의 첫 바인딩은 AFirstPersonBaseCodeCharacter 클래스다. 현재 플레이어의 폰으로, 입력 컴포넌트가 마지막으로 체크된다.

    void AFirstPersonBaseCodeCharacter::SetupPlayerInputComponent(class UInputComponent* InputComponent)
        {
            // 게임플레이 키 바인딩 설정
            check(InputComponent);
            ...
            InputComponent->BindAxis("MoveForward", this, &AFirstPersonBaseCodeCharacter::MoveForward);
            ...
        }

게임로직 : AFirstPersonBaseCodeCharacter의 MoveForward 함수가 실행.

    void AFirstPersonBaseCodeCharacter::MoveForward(float Value)
        {
            if ( (Controller != NULL) && (Value != 0.0f) )
            {
                // 앞쪽 찾기
                FRotator Rotation = Controller->GetControlRotation();
                // 걷거나 떨어질 때 피치 제한
                if ( CharacterMovement->IsMovingOnGround() || CharacterMovement->IsFalling() )
                {
                    Rotation.Pitch = 0.0f;
                }
                // 해당 방향으로 이동 추가
                const FVector Direction = FRotationMatrix(Rotation).GetScaledAxis(EAxis::X);
                AddMovementInput(Direction, Value);
            }
        }

터치 인터페이스

기본적으로 터치 디바이스에서 실행되는 게임에는 콘솔 컨트롤러처럼 두 가지 가상 조이스틱이 있다. 프로젝트 세팅(Project Settings) 의 입력(Input) 섹션에 있는 기본 터치 인터페이스(Default Touch Interface) 프로퍼티로 이를 변경할 수 있다. 이는 터치 인터페이스 구성 에셋을 가리킨다. 디폴트는 DefaultVirtualJoysticks이며 공유 엔진 콘텐츠에 있다. 카메라를 돌릴 필요가 없는 게임을 위해 왼쪽 스틱만 있는 버전인 LeftVirtualJoystickOnly 도 있다.

오브젝트 선택 툴 뷰 옵션(View Options) 세팅에서 엔진 콘텐츠 표시(Show Engine Content) 체크박스를 체크해야 하는 점을 유의하자

가상 조이스틱이 필요하지 않은 경우 디폴트 터치 인터페이스 프로퍼티만 지운다. 또한 항상 터치 인터페이스 표시(Always Show Touch Interface)에 체크하거나 PC 게임을 -faketouches로 실행하여 플랫폼과 무관하게 게임에 터치 인터페이스를 강제할 수 있다.

향상된 입력 플러그인

실험단계 기능인 향상된 입력 플러그인은 복잡한 입력처리나 런타임 제어 리매핑 등의 고급 입력 기능이 필요한 프로젝트에서 개발자가 엔진의 디폴트 입력 시스템을 쉽게 업그레이드하고 하위 호환도 확보하도록 지원한다. 이 플러그인은 방사상 데드존, 조화된 액션, 컨텍스트 입력 및 우선순위, 원본 입력 데이터의 필터링 및 프로세싱 확장 기능 등을 에셋 기반 환경에서 제공한다.

시작하기

플러그인을 활성화 하기위해 에디터의 편집(Edit) 드롭다운 메뉴를 열고 플러그인(Plugin) 을 선택한다. 플러그인 목록의 입력(Input) 섹션에서 향상된 입력 플러그인을 활성화하고 에디터를 재시작한다.

에디터가 재시작되면 프로젝트가 기본 언리얼 엔진 입력 핸들러 대신 향상된 입력 플러그인 클래스를 사용하도록 설정할 수 있다. 편집(Edit) 드롭다운 메뉴에서 프로젝트 세팅(Project Settings) 을 선택한다. 엔진(Engine) 소제목 아래의 입력(Input) 섹션에서 Default Classes 세팅을 찾는다. 초기에는 표준 PlayerInput 및 InputComponent 클래스가 포함되어 있다.

향상된 입력을 사용하려면 Dafulat Player Input Class를 EnhancedPlayerInput 으로 Default Input Component Class를 EnhancedInputComponent 로 변경한다

핵심 개념

향상된 입력 시스템에는 다음 4가지 주요 개념이 있다.

입력 액션은 향상된 입력 시스템과 프로젝트 코드 사이의 커뮤니케이션 링크이다. 입력 액션은 점프, 문 열기 등 인터랙티브 캐릭터가 할 수 있는 모든 것을 아우르며, 버튼을 길게 눌러서 걷기를 달리기로 바꾸는 등 사용자 입력 상태를 나타내는 데도 사용될 수 있다. 입력 액션은 원본 입력과 구분된다. 입력 액션은 어떤 입력에 의해 트리거됐는지와 무관하게 현재 상태를 알고 있으며 입력 값을 최대 3개의 독립 부동 소수점 축에서 보고할 수 있다. 예를 들어 '아이템 획득' 액션은 사용자가 뭔가를 획득했는지 여부를 나타내는 켜기/끄기 상태만을 필요로 하는 반면 '걷기' 액션은 사용자가 걷는 방향과 속도를 나타내는 두 개의 축을 필요로 한다.
입력 매핑 컨텍스트(Input Mapping Context)는 사용자의 입력을 액션으로 매핑하며 각 사용자에 대해 동적으로 추가, 제거, 우선순위 지정될 수 있다. 향상된 입력의 로컬 플레이어 서브시스템을 통해 로컬 플레이어에게 하나 이상의 컨텍스트를 적용할 수 있으며, 동일한 입력을 소화하려는 여러 액션 사이의 충돌을 해소하도록 우선순위를 지정할 수 있다. 이에 대한 일반적인 예시는 캐릭터가 월드에서 걷는 동안 문을 여는 버튼, 또는 캐릭터의 가방을 보는 동안 아이템을 선택하는 버튼 등이다. 캐릭터가 가방을 열 때마다 '아이템 선택' 입력 매핑 컨텍스트를 추가하여 '문 열기' 컨텍스트보다 높은 우선순위를 부여하고, 캐릭터가 가방을 닫으면 '아이템 선택' 컨텍스트를 제거하는 것이다. 이를 통해 입력 처리 레벨에서 문과 가방 시스템을 인지하도록 코드를 프로그래밍하지 않아도 사용자의 입력을 캐릭터의 상황에 맞춰 올바르게 해석할 수 있습니다.
모디파이어(Modifiers)는 사용자 디바이스의 원본 입력 값을 조절한다. 입력 매핑 컨텍스트는 각 입력 액션의 원시 입력(raw input)과 관련된 모디파이어를 얼마든지 가질 수 있다. 일반적인 모디파이어로는 데드존, 다수 프레임에서 입력 스무딩, 입력 벡터를 로컬에서 월드 스페이스로 변환, 기타 플러그인에 포함되는 것들이 있다. 개발자는 자신만의 모디파이어를 생성할 수도 있다.
트리거는 모디파이어 이후 입력 값이나 다른 입력 액션의 출력 규모를 사용하여 입력 액션을 활성화할지 여부를 결정한다. 입력 매핑 컨텍스트 내의 입력 액션은 각 입력에 대해 하나 이상의 트리거를 가질 수 있다. 예를 들어 사진을 찍으려면 사용자는 왼쪽 마우스 버튼을 4분의 1초 동안 눌러야 하는데, 이때 카메라를 조준하는 별도의 입력 액션 또한 활성화되어 있는 것이다.

입력 액션

입력 액션은 시스템과 프로젝트 코드 사이의 연결 고리이다. 컨텍스트 브라우저(Context Browser) 에서 우클릭하고 입력(Input) 옵션을 펼친 다음 입력 액션(Input Action) 을 선택하여 입력 액션을 생성할 수 있다. 입력 액션을 트리거하려면 입력 매핑 컨텍스트에 포함시키고 해당 입력 매핑 컨텍스트를 로컬 플레이어의 향상된 입력 로컬 플레이어 서브시스템(Enhanced Input Local Player Subsystem) 에 추가해야 한다.

폰 클래스가 트리거된 입력 액션에 반응하게 하려면 SetupPlayerInputComponent에서 해당 폰 클래스를 적절한 유형의 트리거 이벤트(Trigger Event) 에 바인딩해야 한다. 다음은 SetupPlayerInputComponent를 오버라이드하여 입력 액션인 MyInputAction과 MyOtherInputAction을 핸들러 함수에 바인딩하는 샘플 코드다.

 // UEnhancedInputComponent를 사용하는지 확인해야 한다. 그러지 않으면 프로젝트가 제대로 설정되지 않음.
 if (UEnhancedInputComponent* PlayerEnhancedInputComponent = Cast<UEnhancedInputComponent>(PlayerInputComponent))
 {
    // UInputAction*을 핸들러 함수 및 관심 대상인 각종 ETriggerEvent에 바인딩하는 방법은 여러 가지.

    // 액션 버튼을 누를 때와 같이 MyInputAction이 시작될 때 틱에서 핸들러 함수를 호출.
    if (MyInputAction)
    {
        PlayerEnhancedInputComponent->BindAction(MyInputAction, ETriggerEvent::Started, this, &AMyPawn::MyInputHandlerFunction);
    }

    // 이동 키를 길게 누를 때 등 입력 조건이 충족되면 모든 틱에서 이름으로 핸들러 함수(UFUNCTION)를 호출.
    if (MyOtherInputAction)
    {
        PlayerEnhancedInputComponent->BindAction(MyOtherInputAction, ETriggerEvent::Triggered, this, TEXT("MyOtherInputHandlerFunction"));
    }
 }

입력 액션에는 블루프린트 스크립팅에 노출되는 내장 이벤트가 있다. C++ 개발자는 블루프린트 스크립팅 개발자에게 입력 액션 이벤트 액세스를 제공하려고 패스스루 함수를 만들 필요가 없다. 일반적인 핸들러 함수는 다음과 같은 양식을 취할 수 있다.

 void AMyPawn::MyFirstAction(const FInputActionValue& Value)
 {
    // 핸들러 함수가 실행되고 있음을 확인해 주는 디버그 로그 출력.
    UE_LOG(LogTemp, Warning, TEXT("%s called with Input Action Value %s (magnitude %f)"), TEXT(__FUNCTION__), *Value.ToString(), Value.GetMagnitude());
    // GetType() 함수를 사용하여 값의 유형을 결정하고, [] 연산자를 0~2 사이의 인덱스와 함께 사용하여 데이터에 액세스.
 }

대부분의 사용 사례에서 void (const FInputActionValue&) 시그니처를 사용하는 것이 권장된다. 입력 액션을 핸들러 함수와 바인딩하면 폰이 트리거된 특정 방식에 따라 반응하게 만들 수 있다. 가장 일반적인 트리거 유형은 버튼을 누른 즉시 한 번 발생하는 Started, 입력을 누르고 있는 동안 매 프레임마다 지속적으로 액션이 발생하는 Triggered 등이 있으며, 전체 목록은 Plugins/EnhancedInput/ETriggerEventETriggerEvent의 API 레퍼런스 페이지에서 볼 수 있다.

입력 매핑 컨텍스트

하나 이상의 입력 액션을 트리거하는 규칙을 입력 매핑 컨텍스트(Input Mapping Context)라고 한다. 최상위 레벨의 입력 액션 목록을 갖춘 계층구조를 기본구조로 한다. 입력 액션 레벨 아래에는 키, 버튼, 움직임 축 등 각 입력 액션을 트리거할 수 있는 사용자 입력 목록이 있다. 하단 레벨에는 각 사용자 입력에 대한 입력 트리거와 입력 모디파이어 목록이 있다. 여기서는 입력의 원본 값을 어떻게 필터링하고 프로세스할지, 어떤 제한을 충족해야 계층구조 상위의 입력 액션을 주도할 수 있는지 결정한다. 입력은 다수의 입력 모디파이어와 입력 트리거를 가질 수 있다. 각 단계의 출력을 다음 단계의 입력으로 사용하여 순차적으로 평가된다.

입력 매핑 컨텍스트를 생성하려면 컨텍스트 브라우저(Context Browser) 에서 우클릭하고 입력(Input) 옵션을 펼친 다음 입력 매핑 컨텍스트(Input Mapping Context) 를 선택한다.

입력 매핑 컨텍스트에 연관성 있는 입력 액션을 모두 채우자. 간단한 프로젝트의 경우 입력 매핑 컨텍스트 하나에 모든 입력 액션을 넣는 것이 가능할 수도 있다. 보다 복잡한 프로젝트는 다수의 입력 매핑 컨텍스트가 있어야 더 잘 작동한다. 로컬 플레이어가 한 번에 하나 이상의 활성 입력 매핑 컨텍스트를 가질 수 있기 때문. 또한 상호 배타적인 입력 매핑 컨텍스트를 통해 서로 다른 입력 액션에 사용되는 사용자 입력 간의 입력 콜리전을 피할 수 있다.

위 입력 매핑 컨텍스트는 달리기를 위한 입력 액션이다. 게임패드의 왼쪽 섬스틱 기울이기 등 다수의 입력을 통해 실행되며, 두 축을 하나의 입력으로 결합한다. 위 입력의 원본 값은 '데드존' 입력 모디파이어를 지나며, 결과 값은 '홀드' 입력 트리거로 전달되어 'RunAction' 입력 액션을 주도한다.

드롭다운 목록에서 다수의 입력 바인딩을 이용할 수 있다. 입력 바인딩을 더 빠르게 선택하려면 드롭다운 왼쪽의 작은 버튼을 누른 다음 바인딩하고 싶은 키나 버튼을 누르면 된다.

위 입력 매핑 컨텍스트는 달리기와 점프를 위한 입력 액션을 지원한다. 입력 매핑 컨텍스트를 채우면 폰의 플레이어 컨트롤러와 연결된 로컬 플레이어에게 이를 추가할 수 있다. 이를 위해 PawnClientRestart 함수를 오버라이드하고 다음과 같은 코드 블록을 추가하였다.

 // 유효한 플레이어 컨트롤러가 있는지 확.
 if (APlayerController* PC = Cast<APlayerController>(GetController()))
 {
    // 향상된 입력 로컬 플레이어 서브시스템을 플레이어 컨트롤러와 관련된 로컬 플레이어로부터 가져옴
    if (UEnhancedInputLocalPlayerSubsystem* Subsystem = ULocalPlayer::GetSubsystem<UEnhancedInputLocalPlayerSubsystem>(PC->GetLocalPlayer()))
    {
        // PawnClientRestart가 액터의 수명에서 2회 이상 실행될 수 있으므로 잔여 매핑을 우선 제거
        Subsystem->ClearAllMappings();

        // 각 매핑 컨텍스트를 우선순위 값과 함께 추가. 높은 값이 낮은 값에 우선
        Subsystem->AddMappingContext(MyInputMappingContext, MyInt32Priority);
    }
 }

입력 매핑 컨텍스트를 추가하면 폰이 SetupPlayerInputComponent에 바인딩했거나 블루프린트 스크립팅 사용자가 구성한 입력 액션 이벤트에 반응할 수 있게 된다. 게임플레이 도중 이용 가능한 입력 매핑 컨텍스트를 변경하는 이벤트가 발생하면 ClearAllMappings, AddMappingContext, RemoveMappingContext를 사용하여 이용 가능한 명령 세트를 동적으로 업데이트할 수 있다. 자세한 정보는 Plugins/EnhancedInput/IEnhancedInputSubsystemInterfaceIEnhancedInputSubsystemInterface API 레퍼런스 페이지를 참조하자.

입력 모디파이어

입력 모디파이어(Input Modifier)는 언리얼 엔진이 수신한 원본 입력을 입력 트리거로 전달하기 전에 변경하는 프리 프로세서이다. 모디파이어들은 축 순서 변경, '데드존' 구현, 축 입력을 월드 스페이스로 변환 등 다양한 작업을 수행한다. 입력 매핑 컨텍스트 내의 입력 액션과 연결된 각 입력은 사용자가 정의한 일련의 입력 모디파이어 시리즈를 통과한 이후에 해당 입력의 입력 트리거로 진행한다. 입력 모디파이어는 목록에 나열된 순서대로 적용되며 각 입력 모디파이어의 출력 값은 다음 입력 모디파이어의 입력 값이 된다. 향상된 입력 플러그인에 포함된 입력 모디파이어 목록 전체를 보려면 Plugins/EnhancedInput/UInputModifierUInputModifier API 레퍼런스 페이지를 참조하자. 아직 존재하지 않는 입력 모디파이어가 프로젝트에 필요하다면 UInputModifier 클래스를 직접 만들 수 있다.

입력 트리거

입력 트리거(Input Trigger)는 사용자 입력이 입력 모디파이어 목록을 통과한 뒤 입력 매핑 컨텍스트 내에서 해당되는 입력 액션을 활성화할지 여부를 결정한다. 대다수 입력 트리거는 최소 활성화 값을 확인하고 짧은 탭, 길게 누르기, 일반적인 '누르기' 또는 '놓기' 이벤트와 같은 패턴을 검증하여 입력 자체를 분석한다. 'Chorded Action' 입력 트리거만 예외적으로 이 규칙에서 다른 입력 액션이 트리거되어야 한다. 기본으로 입력에 대한 사용자 활동은 모든 틱에서 트리거된다. 향상된 입력 플러그인에 포함된 입력 트리거 목록 전체를 보려면 Plugins/EnhancedInput/UInputTriggerUInputTrigger API 레퍼런스 페이지를 참조하자. 향상된 입력 플러그인에 존재하지 않는 입력 트리거가 프로젝트에 필요하다면 UInputTrigger 클래스를 직접 만들 수 있다.

문서

https://docs.unrealengine.com/5.2/ko/input-overview-in-unreal-engine/

[언리얼엔진] BindWidget

테디슨 — Wed, 24 May 2023 22:15:48 +0900

시작하며

코드에서 UI 로직을 만들려고 할 때 블루프린트에서 디자인한 위젯을 제어하려할때 BindWidget meta 지정자를 이용하여 제어할 수 있다.

BindWidget 예제

UPROPERTY(BlueprintReadWrite, meta = (BindWidget))
class UTextBlock* TextName;

UPROPERTY(BlueprintReadWrite, meta = (BindWidget))
class UImage* ImgIcon;

정작 UPROPERTY 공식문서에서는 없지만 UI개발시 가장 많이 사용하는 태그이다.
블루프린트에 동일한 클래스와 동일한 이름을 가진 위젯이 있다면 해당 위젯포인터로 코드(C++)에서 런타임에 엑세스 할 수 있다.

적용 방법

#pragma once 

#include "CoreMinimal.h"
#include "Blueprint/UserWidget.h"
#include "MyBindWidget.generated.h"

UCLASS(Abstract)
class UMyBindWidget : public UUserWidget
{
    GENERATED_BODY()

protected:
    UPROPERTY(BlueprintReadWrite, meta=(BindWidget))
    class UTextBlock* TextName;

    UPROPERTY(BlueprintReadWrite, meta = (BindWidget))
    class UImage* ImgIcon;
};

위와같이 클래스를 추가하고 MyBindWidget 클래스를 상속받은 위젯블루프린트를 생성한다. 해당 블루프린트 안에 TextName 이름을 가진 TextBlock을 반드시 추가하도록 하자 없다면 컴파일에 실패하게 된다. 무조건 해당 위젯이 있어야 블루프린트 컴파일이 되므로 해당 포인터는 널이 아님을 보장하게 된다.

BindWidgetOptional

UPROPERTY(BlueprintReadWrite, meta = (BindWidgetOptional))
class UTextBlock* TextName;

UPROPERTY(BlueprintReadWrite, meta = (BindWidgetOptional))
class UImage* ImgIcon;

특정 위젯을 BindWidgetOptional 지정자로 입력하게 되면 블루프린트에서 해당 이름의 위젯이 없어도 컴파일 오류가 발생하지 않는다. 하지만 코드에서 사용할 때에는 항상 nullptr 이 아닌지 확인하고 사용하여야 한다.

BindWdigetAnim

위젯애니메이션도 바인딩 가능하다. BindWidgetAnim / BindWidgetAnimOptional 로 사용가능하다

UPROPERTY(Transient, meta = (BindWidgetAnim))
UWidgetAnimation* Anim_Show;

언리얼 엔진 5.0 부터는 해당 프로퍼티를 Transient로 선언해야한다. Trasient로 하지 않으면 다음과 같이 컴파일 에러가 발생한다.

요약

코드에서 블루프린트 위젯을 바인딩 하고자 할때 BindWidget/BindWidgetOptional 메타 지정자를 이용하자
위젯 애니메이션을 바인딩할때는 BindWidgetAnim / BindWidgetAnimOptional 메타 지정자를 이용하자

[언리얼엔진] 비헤이비어 트리 개요

테디슨 — Wed, 17 May 2023 21:54:12 +0900

언리언 엘진의 비헤이비어 트리 개념과 일반적인 비헤이비어 트리와의 차이점을 알아보자

언리얼 엔진 5(언리얼 엔진)에서 캐릭터에 사용할 인공 지능(AI)을 생성하는 방법은 다양하다. 블루프린트 비주얼 스크립팅(Blueprint Visual Scripting)을 사용하면 캐릭터가 애니메이션을 재생하거나, 특정 위치로 이동하거나, 충돌에 반응하는 등 '무언가를 하도록' 지시할 수 있다. AI 캐릭터가 스스로 생각하고 결정을 내리도록 하려면 비헤이비어 트리(Behavior Tree)를 사용해보자. 아래 비헤이비어 트리는 AI 캐릭터가 순찰과 플레이어 추격 사이에서 행동을 전환하는 예시다.

비헤이비어 트리 기본

비헤이비어 트리는 블루프린트와 유사한 시각적 방식으로 생성된다. 기능이 탑재된 다양한 노드를 추가하고 연결하여 비헤이비어 트리 그래프(Behavior Tree Graph)를 만드는 방식이다. 비헤이비어 트리가 로직을 실행하는 한편, 비헤이비어 트리가 결정을 내리는 데 필요한 정보인 블랙보드 키(Blackboard Key) 는 블랙보드(Blackboard) 라는 별도의 에셋에 저장된다. 일반적인 워크플로는 블랙보드를 생성하고, 블랙보드 키를 추가한 다음, 블랙보드 에셋을 사용하는 비헤이비어 트리를 생성한다. 블랙보드는 아래에서처럼 비헤이비어 트리에 할당된다.

언리얼 엔진의 비헤이비어 트리는 왼쪽에서 오른쪽, 위에서 아래 순서로 로직을 실행한다. 실행 순서는 그래프에 배치된 노드의 우측 상단에 표시되는 숫자로 확인할 수 있다. 아래 이미지의 비헤이비어 트리 그래프에서 가장 왼쪽의 샘플 분기에 연결된 노드들은 블랙보드 키 HasLineOfSight 가 설정된 경우 AI가 플레이어를 추격하도록 지시한다.

파란색 노드는 데코레이터(Decorator)이다. 다른 비헤이비어 트리 시스템의 조건문에 해당한다. 데코레이터는 컴포짓(Composite)노드에 어태치되어 블랙보드 키가 True인지 검증하는데 사용된다. 이를 통해 나머지 분기를 실행할지 결정된다. 보라색 노드는 태스크(Task) 노드이며, AI가 수행할 수 있는 액션이다.

비헤이비어 트리와 로직을 생성했다면 트리를 실행해보자. 보통은 폰(Pawn) 또는 캐릭터거나 다른 엔티티인 AI의 '바디'가 있고, 거기 연결된 AI 컨트롤러(AI Controller)를 사용해서 폰을 제어하고 액션을 지시한다. 비헤이비어 트리를 실행하는 것도 액션 중 하나다. 아래는 폰에 커스텀 AI 컨트롤러 클래스를 할당했다.

그리고 AI 컨트롤러에서는 컨트롤러가 폰에 '빙의'할 때 비헤이비어 트리를 실행한다.

폰이 환경을 탐색하게 하려면 내비메시 바운드 볼륨(Nav Mesh Bounds Volume) 을 레벨에 추가해야 한다.

언리얼 엔진 비헤이비어 트리의 차별점

이벤트 주도형 비헤이비어 트리

언리얼 엔진 비헤이비어 트리가 다른 비헤이비어 트리 시스템과 다른 점 중 하나는 이벤트로 주도되기 때문에 프레임마다 불필요한 작업이 수행되지 않는다는 점이다. 관련 변경 사항이 발생했는지 지속적으로 확인하는 대신에, 비헤이비어 트리는 트리 내 변경 사항을 트리거하는 데 사용할 수 있는 '이벤트'를 수동적으로 리스닝한다. 아래는 블랙보드 키 HasLineOfSight를 업데이트하는 데 이벤트가 사용되었다.

이벤트 주도형 아키텍처가 있으면 퍼포먼스와 디버깅이 모두 개선된다. 그러나 이러한 개선 사항을 최대한 활용하기 위해서는 언리얼 엔진 비헤이비어 트리의 나머지 차이점도 이해하여 비헤이비어 트리의 구조를 적절하게 구성해야 한다. 코드가 매 틱마다 전체 트리를 반복작업할 필요가 없기 때문에 퍼포먼스가 훨씬 뛰어나다. 개념적으로는, 도착했는지 계속해서 묻지 않고 도착할 때까지 쉬다가 도착했다는 알림을 받는 것과 동일하다.

비헤이비어 트리의 실행 히스토리를 한 단계씩 앞뒤로 이동하면서 비헤이비어를 시각적으로 디버깅하는 경우, 연관성이 있는 변경 사항만 히스토리에 표시하고 무관한 사항은 표시하지 않는 것이 이상적이다. 언리얼 엔진의 이벤트 주도형 구현 방식에서는 트리를 반복작업하여 이전과 동일한 비헤이비어를 선택하는 연관성 낮은 단계를 필터로 걸러낼 필요가 없다. 추가적인 반복 작업이 애초에 발생하지 않기 때문, 대신에 트리 내에서의 실행 위치 또는 블랙보드 값의 변경만 고려하면 되고, 이러한 차이점을 표시하는 것은 쉽다.

조건문이 리프 노드가 아님

비헤이비어 트리 표준 모델에서의 조건문은 '태스크' 리프 노드로, 성공이나 실패 이외에는 아무것도 하지 않는다. 물론 전통적인 조건문 태스크를 만들지 못할 이유는 없지만, 조건문에는 데코레이터(Decorator)를 사용하는 것을 권장함
조건문을 태스크가 아닌 데코레이터로 만들면 다음과 같은 이점이 있다.

조건문 데코레이터는 비헤이비어 트리 UI를 보다 직관적이고 읽기 쉽게 만들어 준다.
모든 리프가 액션 태스크이므로 트리를 통해 실제 어떤 액션이 지시되는지 알기가 더 쉽다.

조건문은 자신이 제어하는 서브트리의 루트에 있으므로 조건이 충족되지 않은 경우 트리의 어떤 부분이 '닫혔는지' 바로 알 수 있다. 또한 모든 리프가 액션 태스크이므로 실제 액션을 알기가 더 쉽다. 기존에는 조건문이 리프 사이에 있으므로 어떤 리프가 조건문이고 어떤 리프가 액션인지 알아내기 어려웠다.

위 비헤이비어 트리 섹션에서는 'Close Enough'와 블랙보드 데코레이터가 시퀀스 노드의 자손이 실행되는 것을 방지한다. 조건문 데코레이터의 또 다른 이점은 트리 내 중요 노드에서 이벤트를 기다리는 관찰자 역할로 만들기 쉽다는 것이다. 트리의 이벤트 주도형 속성을 최대한 활용하는 데 매우 중요하다.

동시 발생 비헤이비어

표준적인 비헤이비어 트리는 보통 병렬 컴포짓 노드를 사용하여 동시 발생 행동을 처리하며, 이 병렬 노드는 모든 자손에서 동시에 실행되기 시작한다. 자손 트리 중 하나 이상이 종료되었을 때 어떤 액션을 취할지는 (원하는 행동에 따라) 특수 규칙으로 결정한다.

언리얼 엔진 비헤이비어 트리는 복잡한 병렬 노드 대신 단순 병렬(Simple Parallel) 노드, 서비스(Services)라는 특수 노드, 데코레이터의 관찰자 중단(Observer Aborts) 프로퍼티를 사용하여 동일한 유형의 행동을 달성한다.

단순 병렬 노드

단순 병렬 노드는 자손을 두 개만 갖는다. 한 자손은 반드시 단일 태스크 노드여야 하며(데코레이터 선택 가능), 나머지 자손은 완전한 서브트리일 수 있다. 단순 병렬 노드는 'A를 수행하는 동안 B도 수행한다'로 생각하면 된다. 기본적으로 A는 주요 태스크이고, B는 A가 완료되기까지 기다리는 도중의 부가 태스크 또는 필러 태스크다.

부가 태스크(태스크 B)를 처리하는 방법에는 몇 가지 옵션이 있지만, 노드 개념은 전통적인 병렬 노드에 비해 비교적 단순하다. 그러면서도 병렬 노드가 사용되는 일반적인 경우를 대부분 지원한다. 단순 병렬 노드를 사용하면 이벤트 주도형 최적화를 활용하기 쉽지만, 완전 병렬 노드는 최적화하기 훨씬 까다롭다.

서비스

서비스는 셀렉터, 시퀀스, 단순 병렬 등 모든 컴포짓 노드와 연관되는 특수 노드로, 지정된 시간(초)마다 콜백을 등록하고 주기적으로 발생시킬 필요가 있는 다양한 유형의 업데이트를 수행한다. 예를 들어 AI 폰이 현재의 적을 쫓는 비헤이비어 트리를 정상적으로 따라가는 동안 어느 적이 최적의 대상인지 결정하기 위해 서비스를 사용할 수 있다. 서비스는 자신이 추가된 컴포짓 노드의 서브트리에 실행이 머물러 있는 동안만 활성화된다.

관찰자 중단

표준 병렬 노드의 흔한 용도 중 하나는 조건을 지속적으로 확인하여 요구 조건이 False가 되는 경우 태스크를 중단하는 것이다.

예를 들어 '쉭쉭거리기' 와 '달려들기' 시퀀스를 수행하는 고양이가 있다면, 쥐가 쥐구멍으로 도망치는 순간 즉시 포기하도록 하는 것이 좋다. 병렬 노드로는 쥐에게 달려들 수 있는지 확인하는 자손과 시퀀스가 수행할 자손을 가질 수 있다. 언리얼 엔진 비헤이비어 트리는 이벤트 주도형이므로 이렇게 하는 대신에 조건문 데코레이터에서 해당 값을 관찰하게 하고 필요시 중단시키는 방식으로 처리한다. 이 예시에서는 '쥐에게 달려들 수 있는가?'를 들 수 있다. 이 경우, 시퀀스의 데코레이터에서 '관찰자 중단'을 '셀프(Self)'로 설정하면 된다.

동시 발생 비헤이비어에 대한 언리얼 엔진 접근법의 장점

언리얼 엔진에서 동시 발생 비헤이비어를 처리하는 방법에는 다음과 같은 세 가지 주요 장점이 있다.

명료성 - 서비스와 단순 병렬 노드를 사용하여 읽기 쉽고 이해하기 쉬운 단순한 트리를 만들 수 있다.
쉬운 디버깅 - 그래프가 명료하므로 디버깅도 쉽다. 또한 동시 실행 경로가 더 적어서 지금 어떤 것이 실행되고 있는지 파악하기 더 쉽다.
더 쉬운 최적화 - 이벤트 주도형 그래프는 동시에 실행되는 서브트리가 많지 않다면 최적화하기 더 쉽다.

문서

https://docs.unrealengine.com/5.2/ko/behavior-tree-in-unreal-engine---overview/

[언리얼엔진] 슬레이트 위젯 예제

테디슨 — Wed, 10 May 2023 20:59:38 +0900

공용 슬레이트 인수

다음은 공통 인수이다.

IsEnabled - 상호작용(Interation) 가능한 위젯인지를 지정한다. 끄면 회식으로 비활성화 된다.
ToolTip - 툴팁에 사용할 커스텀 SToolTip 위젯 종류를 지정한다. 지정되지 않으면 툴팁이 나타나지 않는다.
ToolTipText - 간단한 툴팁으로 표시할 텍스트 유형을 지정한다. 지정되지 않거나, ToolTip 특성이 사용된 경우 나타나지 않는다.
Cursor - 마우스를 올렸을 때 표시할 커서를 지정합니다.
Visibility - 아래 Visibility 부분을 참고.
Text - 텍스트가 적용 가능하다면 지정할 문구
Content - 콘텐츠가 적용 가능하다면 지정할 위젯
ReadOnly - True 면 이 위젯은 수정할 수 없다.
Style - 위젯에 사용되는 이미지나 텍스트 스타일을 지정한다. 적용 방식은 위젯마다 다르다.
[...]ColorAndOpacity - 위젯이나 지정된 시스템의 색과 불투명도
Padding - 위젯의 상하좌우 주변에 패딩으로 댈 Slate 유닛 단위 여백의 양이다.
HAlign - 위젯 안 콘텐츠의 가로 정렬 방식
VAlign - 위젯 안 콘텐츠의 세로 정렬 방식

Visibility

Visibility는 위젯을 표시할 것인지와 상호작용 여부도 결정한다.

Visible - 위젯이 보통의 경우 나타난다. (Default)
Collapsed - 위젯이 보이지 않으며 레이아웃에서 자리를 차지하지 않는다. 상호작용되지도 않는다.
Hidden - 위젯이 보이지는 않으며 레이아웃에서 자리는 차지한다. 상호작용되지는 않는다.
HitTestInvisible - 보이지만 상호작용되지는 않는다.
SelfHitTestInvisible - HitTestInvisible 와 같지만 자손 위젯에 적용되지 않는다.

Alignment

Alignment는 위젯의 부모 안에서 그 위젯의 위치를 결정한다. 위젯 부모 크기가 위젯과 같다면 정렬은 의미가 없다.위젯에 "Fill"을 지정하거나 박스 슬롯에 Fill Size가 지정된 경우, 그 박스 슬롯에 기본으로 적용된다.

HAlign_Fill / VAlign_Fill - 가로 세로 가득 채운 정렬
HAlign_Left - 왼쪽 정렬
VAlign_Top - 위쪽 정렬
HAlign_Center / VAlign_Center - 가로 세로 가운데 정렬
HAlign_Right - 오른쪽 정렬
VAlign_Bottom - 아래쪽 정렬

Box 패널

SHorizontalBox, SVerticalBox 는 레이아웃 배치에 있어 가장 흔한 위젯이다. 이 박스 패널은 위젯으로 선언되나, 그 이후 슬롯이 삽입된다. 이 슬롯의 배치 순서는 SHorizontalBox 의 경우 좌에서 우, SVerticalBox 는 위에서 아래다.
SScrollBox 는 SVerticalBox 와 비슷하게 작동하는데, 자손 슬롯의 세로 스크롤이 가능하다는 점이 다르다.

Slot 특성

Width or Height (폭 또는 높이) 세팅 (다음 옵션은 상호 배제적이다):
- Auto Size (자동 크기, 기본) - 슬롯에 딱 필요한 만큼만 공간을 지정. 슬롯 내 정렬은 중요치 않음.
- Fill Size (필 크기) - 필 계수를 지정하면 다른 슬롯의 필 계수에 따라 공간을 채움. 슬롯 정렬은 중요치 않음.
Max Size (최대 크기) - 슬롯의 최대 크기를 Slate 유닛 단위로 지정.
Padding (패딩) - 패널 네 슬롯의 패딩을 지정.
Alignment (정렬) - 슬롯 내 자손 위젯의 정렬 방식을 결정. 이 옵션은 같은 방향의 Fill Size 가 적용되어 있으면 의미가 없다.

SNew(SScrollBox)
+SScrollBox::Slot() .Padding(10,5)
[
    SNew(SHorizontalBox)
    +SHorizontalBox::Slot() .HAlign(HAlign_Left)
    [
        ...
    ]
    +SHorizontalBox::Slot() .HAlign(HAlign_Center)
    [
        ...
    ]
    +SHorizontalBox::Slot() .HAlign(HAlign_Right)
    [
        ...
    ]
]
+SScrollBox::Slot() .Padding(10,5)
[
    SNew(SHorizontalBox)
    +SHorizontalBox::Slot() .FillWidth(2)
    [
        ...
    ]
    +SHorizontalBox::Slot() .FillWidth(1)
    [
        ...
    ]
    +SHorizontalBox::Slot() .FillWidth(3)
    [
        ...
    ]
]

Uniform Grid Panel

SUniformGridPanel 은 자손 위젯을 가로 세로 모두 고르게 분배하는 패널이다. 자손 슬롯은 자손의 인덱스를 나타내는 정수 한 쌍으로 지정된다.

SNew(SUniformGridPanel)
.SlotPadding( FMargin( 5.0f ) )
+SUniformGridPanel::Slot(0,0)
.HAlign(HAlign_Right)
[
    ...
]
+SUniformGridPanel::Slot(0,1)
.HAlign(HAlign_Right)
[
    ...
]
+SUniformGridPanel::Slot(0,2)
.HAlign(HAlign_Center)
[
    ...
]
+SUniformGridPanel::Slot(1,0)
[
    ...
]
+SUniformGridPanel::Slot(1,1)
[
    ...
]

Warp Box

SWrapBox 는 줄바꿈 상자, 즉 일정 폭까지 위젯이 가로로 배치되다가 다음 줄에 놓이는 식이다.

SNew(SWrapBox)
.PreferredWidth( 300.f )
+SWrapBox::Slot()
.Padding( 5 )
.VAlign(VAlign_Top)
[
    ...
]
+SWrapBox::Slot()
.Padding( 5 )
.VAlign(VAlign_Bottom)
[
    ...
]
+SWrapBox::Slot()
.Padding( FMargin(20, 5, 0, 5) )
.VAlign(VAlign_Center)
[
    ...
]
+SWrapBox::Slot()
.Padding( 0 )
.VAlign(VAlign_Fill)
[
    ...
]

Radio Button

라디오 버튼은 Slate의 체크박스다. 체크 박스는 체크 여부 결정을 위해 델리게이트가 필요하기 때문, 라디오 버튼 시리즈를 만드는 가장 쉬운 방법은 어떤 체크박스가 체크되었는지 결정하는 enum을 만드는 것이다. 현재 선택한 내용을 enum 값으로 저장한다. 그 다음 검사하는 델리게이트에 대해 함수를 전달하고, 파라미터로 같이 전달된 enum값과 현재 선택된 내용을 검사한다. 선택 변경시에는 현재 내용을 업데이트 해줘야 한다.

ERadioChoice CurrentChoice;

...

ECheckBoxState::Type IsRadioChecked( ERadioChoice ButtonId ) const
{
    return (CurrentChoice == ButtonId)
        ? ECheckBoxState::Checked
        : ECheckBoxState::Unchecked;
}

...

void OnRadioChanged( ERadioChoice RadioThatChanged, ECheckBoxState::Type NewRadioState )
{
    if (NewRadioState == ECheckBoxState::Checked)
    {
        CurrentChoice = RadioThatChanged;
    }
}

메뉴와 툴바

메뉴

메뉴나 툴바를 생성하기 위해 멀티박스를 사용한다. Slate의 UI_COMMAND 시스템을 사용하지만 동적으로 생성된 버튼,컨트롤로는 불가능하다.
메뉴를 만들려면 FMenuBarBuilder를 생성하여 FUICommandList를 전달한다. 마지막으로 메뉴 바 빌더에서 MakeWidget()을 호출하여 위치를 정한다.

FMenuBarBuilder MenuBarBuilder( CommandList );
{
    MenuBarBuilder.AddPullDownMenu( TEXT("Menu 1"), TEXT("Opens Menu 1"), FNewMenuDelegate::CreateRaw( &FMenus::FillMenu1Entries ) );

    MenuBarBuilder.AddPullDownMenu( TEXT("Menu 2"), TEXT("Opens Menu 2"), FNewMenuDelegate::CreateRaw( &FMenus::FillMenu2Entries ) );
}

return MenuBarBuilder.MakeWidget();

제목, 항목, 구분자, 서브메뉴, 편집가능 텍스트, 커스텀 위젯등을 추가할 수 있다.

static void FillMenu1Entries( FMenuBuilder& MenuBuilder )
{
    MenuBuilder.AddEditableText( TEXT( "Editable Item" ), TEXT( "You can edit this item's text" ), NAME_None, TEXT( "Edit Me!" ) );

    MenuBuilder.AddMenuEntry( FMultiBoxTestCommandList::Get().EighthCommandInfo );

    MenuBuilder.AddMenuSeparator();

    MenuBuilder.AddSubMenu( TEXT("Sub Menu"), TEXT("Opens a submenu"), FNewMenuDelegate::CreateRaw( &FMenus::FillSubMenuEntries ) );

    MenuBuilder.AddWidget(SNew(SVolumeControl), TEXT("Volume"));
}

컨텍스트 메뉴

메뉴 중 하나를 컨텍스트 메뉴로 불러오기 위해서는, FMenuBuilder 에서 생성된 위젯을 구한 다음, 그것을 PushMenu 함수에 다음과 같이 전해준다.

FSlateApplication::Get().PushMenu(
    MenuBuilder.MakeWidget(),
    MouseCursorLocation,
    FPopupTransitionEffect( FPopupTransitionEffect::ContextMenu )
    );

툴바

FToolBarBuilder 를 사용하여 툴바를 생성한다. 자손의 경우 툴바 버튼, 콤보 버튼, 일반 버튼, 풀다운 메뉴 등을 추가할 수 있다.

FToolBarBuilder GameToolBarBuilder( InCommandList );
{
    GameToolBarBuilder.AddToolBarButton( FLevelEditorCommands::Get().Simulate );

    GameToolBarBuilder.AddToolBarButton( 
        FLevelEditorCommands::Get().RepeatLastPlay, 
        LOCTEXT("RepeatLastPlay", "Play").ToString(),
        TAttribute< FString >::Create( TAttribute< FString >::FGetter::CreateRaw( &FLevelEditorActionCallbacks::GetRepeatLastPlayToolTip ) ),
        TAttribute< const FSlateBrush* >::Create( TAttribute< const FSlateBrush* >::FGetter::CreateRaw( &FLevelEditorActionCallbacks::GetRepeatLastPlayIconSlateBrush ) )
        );

    GameToolBarBuilder.AddComboButton(
        SpecialPIEOptionsMenuAction,
        FOnGetContent::CreateRaw( &FLevelEditorToolBar::GeneratePIEMenuContent, InCommandList ),
        FString(),
        LOCTEXT("PIEComboToolTip", "Play-In-Editor options").ToString() );
}

return GameToolBarBuilder.MakeWidget();

아이템 뷰

아이템 뷰는 데이터에 대한 공유 포인터 템플릿 인수를 받는다. Tarray나 TSharedPtr로 채워지고, 그 내부 위젯은 전달된 OnGenerateRow나 OnGenerateTile 로 동적으로 채워지며, 각 열 마다 다양한 위젯으로 생성된다.

리스트 뷰

리스트 뷰는 자손 위젯 목록을 저장하는 위젯이다. SListView<...>로 만든다.

SNew( SListView< TSharedPtr<FTestData> > )
.ItemHeight(24)
.ListItemsSource( &Items )
.OnGenerateRow( this, &STableViewTesting::OnGenerateWidgetForList )
.OnContextMenuOpening( this, &STableViewTesting::GetListContextMenu )
.SelectionMode( this, &STableViewTesting::GetSelectionMode )
.HeaderRow
(
    SNew(SHeaderRow)
    + SHeaderRow::Column("Name")
    [
        SNew(SBorder)
        .Padding(5)
        .Content()
        [
            SNew(STextBlock)
            .Text(TEXT("Name"))
        ]
    ]
    + SHeaderRow::Column("Number") .DefaultLabel(TEXT("Number"))
    + SHeaderRow::Column("TextField") .DefaultLabel(TEXT("Text Field"))
    + SHeaderRow::Column("TextBlock") .DefaultLabel(TEXT("Text Block"))
    + SHeaderRow::Column("AddChild") .DefaultLabel(TEXT("Add Child"))
)

트리 뷰

트리뷰는 STreeView<...> 로 만들고 리스트뷰와 비슷하지만 리스트 내 다른 위젯에 대한 부모 위젯이 지원된다. OnGetChildren 델리게이트를 사용해서 자손 위젯을 전달한다.

SNew( STreeView< TSharedPtr<FTestData> > )
.ItemHeight(24)
.TreeItemsSource( &Items )
.OnGenerateRow( this, &STableViewTesting::OnGenerateWidgetForTree )
.OnGetChildren( this, &STableViewTesting::OnGetChildrenForTree )
.OnContextMenuOpening( this, &STableViewTesting::GetTreeContextMenu )
.SelectionMode( this, &STableViewTesting::GetSelectionMode )
.HeaderRow
(
    SNew(SHeaderRow)
    + SHeaderRow::Column("Name") .DefaultLabel(TEXT("Name"))
    + SHeaderRow::Column("Number") .DefaultLabel(TEXT("Number"))
    + SHeaderRow::Column("TextField") .DefaultLabel(TEXT("Text Field"))
    + SHeaderRow::Column("TextBlock") .DefaultLabel(TEXT("Text Block"))
    + SHeaderRow::Column("AddChild") .DefaultLabel(TEXT("Add Child"))
)

타일 뷰

타일뷰는 STileView<...> 로 만들고 리스트 뷰와 비슷하지만, 자손 위젯이 리스트가 아닌 그리드로 배치된다. 그래서 열과 열 제목을 지원하지 않는다.

SNew( STileView< TSharedPtr<FTestData> > )
.ItemWidth(128)
.ItemHeight(64)
.ListItemsSource( &Items )
.OnGenerateTile( this, &STableViewTesting::OnGenerateWidgetForTileView )
.OnContextMenuOpening( this, &STableViewTesting::GetTileViewContextMenu )
.SelectionMode( this, &STableViewTesting::GetSelectionMode )

문서

https://docs.unrealengine.com/5.1/ko/slate-ui-widget-examples-for-unreal-engine/

[언리얼엔진] 슬레이트 아키텍처

테디슨 — Wed, 3 May 2023 20:11:39 +0900

동기

위젯에서 UI를 만들 때 어려운 부분
- UI 디자인과 반복 작업
- 데이터 흐름 제어 : 위젯과 내재된 데이터끼리 묶어주는것
- UI 기술(description)을 위한 외국어 습득
IMGUI : Immediate Mode Graphics User Interface
- 장점
  - 프로그래머는 UI 기술이 데이터에서 구하기 쉽다는 점에서 코드와 비슷하다는 점을 선호한다.
  - 실효(Invalidation)은 문제가 되지 않고, 그냥 데이터를 직접 폴링(poll)한다.
  - 인터페이스의 절차적 생성이 쉽다.
- 단점
  - 애니메이션과 스타일링 추가가 어려움
  - UI기술이 명령형 코드라서, 데이터 주도형으로 만들기 어려움
목표
- 모델의 코드와 데이터에 쉽게 접근
- UI 절차적 생성 지원
- UI 설명이 꼬이지 않도록
- 애니메이션과 스타일을 반드시 지원

핵심 원리

불투명 캐시와 중복 스테이트를 피함. UI는 스테이트를 캐시에 담고 실효(Invalidation)는 명시적으로 해야한다.
- 폴링
- 투명 캐시
- 불투명 캐시에 드물게(low-grain) 실효(invalidation)
UI 구조가 변할 때, 알림(notification)보다 폴링(Polling)을 선호 (알림을 사용하고자 한다면 빈도가 낮은곳에서 사용하자)
모든 레이아웃은 프로그래머 세팅에서 계산되도록 하여 피드백 루프를 회피하자. 이전 레이아웃 스테이트에 의존하지 않도록.
- 스크롤바가 UI 스테이트를 시각화시키는 경우처럼 UI 스테이트가 모델이 되는 경우는 예외다.
- 퍼포먼스 떄문이라기 보다 프로그래머의 분별을 위해서이다.
많은 양의 난잡한 즉성 UI에 대한 계획을 세우고, 용도를 이해하고 난 후 깔끔한 시스템으로 일반화 하자.

델리게이트와 데이터 흐름 폴링

UI는 Model을 시각화시키고 조작한다. Slate는 Model의 데이터를 읽고 쓸 필요가 있는 위젯의 통로로써 델리게이트(delegate)를 사용한다.
Slate 위젯은 Model의 데이터를 표시할 필요가 있을 때 읽어들인다. 사용자가 동작을 하면, Slate 위젯은 데이터 수정을 위해 write 델리게이트를 부른다(invoke)

특성(Attribute)과 인수(Argument)

델리게이트를 사용하는 것이 항상 바람직한 것은 아니다. 용도에 따라 Slate 위젯에 붙일 인수는 상수값이나 함수일 수도 있다. 이러한 개념은 TAttribute 클래스를 통해 캡슐화시킨다. 이러한 특성은 상수나 델리게이트로 설정 가능하다.

퍼포먼스 고려사항

UI 복잡도는 활성화된 위젯의 갯수에 귀속된다.
콘텐츠의 스크롤 작업은 가능하면 가상화 시킨다.
- 화면 밖에 있는 위젯 수가 많으면 Slate 퍼포먼스를 망칠 수 있다.
큰 화면 사용자는 우월한 사양의 하드웨어를 사용하므로, 다수의 위젯을 처리해 낼 수 있다 가정 (왜?)

실효(invalidation) vs 폴링(polling)

실효의 경우 Model의 구조가 급격히 변하는 상황에서는 보통 기존 UI를 파기하고 재생성 한다. 그러나 스테이트는 잃게 될테니 꼭 필요할 때만 사용하자. 실효는 빈도가 낮은 이벤트에 쓰는것을 규칙으로 삼자

자손 슬롯

모든 Slate 위젯에서 자손은 자손 슬롯에 저장한다. 자손 슬롯은 항상 유효한 위젯이며, 기본적으로 시각화나 상호작용이 없는 위젯인 SNullWidget을 저장한다. 각 위젯 유형은 자체적인 요구를 충족시키는 자손 슬롯 유형을 별도로 선언 할 수 있다. 각 패널 유형은 슬롯을 통해 자손의 배치에 영향을 끼치는 자손별 세팅 집합을 요청할 수 있다.

위젯 규칙

다음 3가지 변종이 있다.

잎 위젯(Leaf Widgets) - 자손 슬롯이 없는 위젯. STextBlock은 텍스트를 표시하기에 더이상 자손슬롯이 필요 없다.
패널 (Panels) - 자손 슬롯의 수가 가변적인 위젯. SVerticlaBox는 몇개의 자손도 수직 배치가 가능하다.
복합 위젯(Compound Widgets) - 명시적으로 이름붙은 자손 슬롯의 갯수가 고정된 위젯. SButton에는 Content라는 슬롯이 있어 버튼 안에 몇 개의 위젯이든 포함 가능하다.

레이아웃

Slate 레이아웃은 두 패스로 이루어 진다.

Pass 1 : Cache Desired Size - 연관된 함수는 SWidget::CacheDesiredSize and SWidget::ComputeDesiredSize
Pass 2 : ArrangeChildren - 연관된 함수는 SWidget::ArrangeChildren

Pass 1 : Cache Desired Size

이 패스의 목표는 각 위젯이 얼마만큼 공간을 차지하려는지 알아내는 것이다. 자손이 없는(잎)위젯같은 경우 내재된(instrinsic) 프로퍼티에 따라 크기를 계산하여 캐시하도록 요청받는다. 다른 위젝과 합쳐지는 위젯(복합 위젯과 패널)은 자손 크기 결정 함수로서 크기를 결정하는데 특수한 로직을 사용한다. ComputeDesiredSize()를 구현할 때만 각 위젯 유형이 필요하다는 점에 유의하고, 캐시나 탐색 로직은 Slate가 구현한다. 위젯에서 ComputeDesiredSize()가 호출될 때, 자손에는 이미 원하는 크기가 계산 및 캐시되어있음을 Slate가 보장해준다. 이건 상향식(bottom up) 패스이다.

Pass 2 : ArrangeChildren

Arrange children은 하향식(Top down) 패스다. Slate는 최상위 창 부터 시작해서 프로그래머가 제공한 제약(Constraint)에 따라 자식을 배치할 것인지 각 창에 묻는다. 각 자손에 할당된 공간이 알려지면 Slate는 재귀를 통해 자손의 자손을 배치할 수 있다.

Slate 그리기 : OnPaint

패인트 패스 도중 Slate는 보이는 모든 위젯에 대해 반복하면서 렌더링 시스템이 소비하게 될 그리기 요소 목록을 만든다. 이 목록은 매프레임 새로 만든다.

최상위 창부터 시작하여 계층구조를 따라 내려오면서, 모든 위젯의 그리기 요소를 그리기 목록에 덧붙인다. 위젯은 페인트 도중 두 가지 작업을 한다. 실제 그리기 요소를 출력하거나, 자손 위젯이 있을 위치를 알아낸 다음 자손 위젯더러 스스로 그리라고 요청한다.

SWidget 해부도

Slate에서 SWidget의 주요 함수

ComputeDesiredSize() - 사이즈 크기를 계산한다.
ArrangeChildren() - 부모 할당 영역 내 자손의 배치를 담당
OnPaint() - 출력을 담당
이벤트 핸들러 - OnSomething 형태의 것으로, 이들은 다양한 시점에서 Slate 가 위젯에서 부를 수 있는 함수들

Composition

Composition 이란 어느 슬롯도 임의의 위젯 내용을 담을 수 있어야 한다는 개념이다. 이로인해 Slate 사용자들은 엄청난 유연성을 확보할 수 있다. Composition 은 가능하면 언제든지, 핵심 Slate 위젯에서 사용된다.
어떤 경우엔 위젯에 특정 유형의 자손을 포함하기도 하는데, 그러한 경우 Composition 조건은 더이상 적용되지 않는다. 이들은 절대 Slate 코어 속 위젯이라기 보다는, 일정 영역 밖에서 재사용되도록 고안되지는 않은 도메인 전용 위젯이다.

선언형 문법

코드에서 Slate를 직접 접근할 필요가 있어서, UI 기술에 선언형(declarative) 언어가 필요했고, C++ 함수 바인딩에 컴파일 시간 검사도 가능하도록 하였다.
그래서 C++ 부분집합으로써 선언형 UI 기술 언어를 만들게 되었다.

문서

https://docs.unrealengine.com/5.1/ko/understanding-the-slate-ui-architecture-in-unreal-engine/

[언리얼엔진] 슬레이트 개요

테디슨 — Wed, 26 Apr 2023 20:45:50 +0900

Slate는 Unreal Editor 또는 게임내 사용자 인터페이스와 같은 도구 및 응용 프로그램용 사용자 인터페이스를 효율적으로 구축하도록 설계된 플랫폼에 구애받지 않는 맞춤형 사용자 인터페이스 프레임워크이다. 서술형(declarative) 문법에 쉬운 디자인, 레이아웃, 스타일 요소가 결합된 Slate를 통해 쉬운 UI제작 및 반복 작업이 가능할 것이다. Slate UI 솔루션으로 툴과 어플리케이션에 사용할 GUI를 매우 쉽게 조합시킬수 있으며, 반복처리도 빠르게 가능하다.

서술형 문법

Slate의 서술형 문법(Declarative syntax)은 프로그래머가 인디렉션(indirection) 레이어를 추가하지 않고도 UI제작을 가능하게 해준다.

SLATE_BEGIN_ARGS( SSubMenuButton )
    : _ShouldAppearHovered( false )
    {}
    /** The label to display on the button */
    SLATE_ATTRIBUTE( FString, Label )
    /** Called when the button is clicked */
    SLATE_EVENT( FOnClicked, OnClicked )
    /** Content to put in the button */
    SLATE_NAMED_SLOT( FArguments, FSimpleSlot, Content )
    /** Whether or not the button should appear in the hovered state */
    SLATE_ATTRIBUTE( bool, ShouldAppearHovered )
SLATE_END_ARGS()

컴포지션

Slate의 컴포지션(Composition) 프레임워크는 프로토타이핑이나 반복처리를 위해 UI요소를 빠르게 재배치하는 작업을 간단하게 만들어 준다.

// 스태틱 메시용 섹션을 새로 추가
ContextualEditingWidget->AddSlot()
.Padding( 2.0f )
[
    SNew( SDetailSection )
    .SectionName("StaticMeshSection")
    .SectionTitle( LOCTEXT("StaticMeshSection", "Static Mesh").ToString() )
    .Content()
    [
        SNew( SVerticalBox )
        + SVerticalBox::Slot()
        .Padding( 3.0f, 1.0f )
        [
            SNew( SHorizontalBox )
            + SHorizontalBox::Slot()
            .Padding( 2.0f )
            [
                SNew( SComboButton )
                .ButtonContent()
                [
                    SNew( STextBlock )
                    .Text( LOCTEXT("BlockingVolumeMenu", "Create Blocking Volume").ToString() ) 
                    .Font( FontInfo )
                ]
                .MenuContent()
                [
                    BlockingVolumeBuilder.MakeWidget()
                ]
            ]
        ]

    ]
];

스타일

스타일은 위젯의 여러 부분에 적용할 수 있다. UI 컴포넌트의 모양을 쉽게 반복하고 스타일 공유 및 재사용도 편해진다.

// 툴바
{
    Set( "ToolBar.Background", FSlateBoxBrush( TEXT("Common/GroupBorder"), FMargin(4.0f/16.0f) ) );

    Set( "ToolBarButton.Normal", FSlateNoResource() );      // 주: 고의적인 투명 배경
    Set( "ToolBarButton.Pressed", FSlateBoxBrush( TEXT("Old/MenuItemButton_Pressed"), 4.0f/32.0f ) );
    Set( "ToolBarButton.Hovered", FSlateBoxBrush( TEXT("Old/MenuItemButton_Hovered"), 4.0f/32.0f ) );

    // Tool bar buttons are sometimes toggle buttons, so they need styles for "checked" state
    Set( "ToolBarButton.Checked", FSlateBoxBrush( TEXT("Old/MenuItemButton_Pressed"),  4.0f/32.0f, FLinearColor( 0.3f, 0.3f, 0.3f ) ) );
    Set( "ToolBarButton.Checked_Hovered", FSlateBoxBrush( TEXT("Old/MenuItemButton_Hovered"),  4.0f/32.0f ) );
    Set( "ToolBarButton.Checked_Pressed", FSlateBoxBrush( TEXT("Old/MenuItemButton_Pressed"),  4.0f/32.0f, FLinearColor( 0.5f, 0.5f, 0.5f ) ) );

    // 툴바 버튼 레이블 폰트
    Set( "ToolBarButton.LabelFont", FSlateFontInfo( TEXT("Roboto-Regular"), 8 ) );
}

컴포지션에 사용된 스타일 예시

SNew( SBorder )
.BorderImage( FEditorStyle::GetBrush( "ToolBar.Background" ) )
.Content()
[
    SNew(SHorizontalBox)

    // 컴파일 버튼 (멀티박스 버튼처럼 보이도록 설정)
    +SHorizontalBox::Slot()
    [
        SNew(SButton)
        .Style(TEXT("ToolBarButton"))
        .OnClicked( InKismet2.ToSharedRef(), &FKismet::Compile_OnClicked )
        .IsEnabled( InKismet2.ToSharedRef(), &FKismet::InEditingMode )
        .Content()
        [
            SNew(SVerticalBox)
            +SVerticalBox::Slot()
            .Padding( 1.0f )
            .HAlign(HAlign_Center)
            [
                SNew(SImage)
                .Image(this, &SBlueprintEditorToolbar::GetStatusImage)
                .ToolTipText(this, &SBlueprintEditorToolbar::GetStatusTooltip)
            ]
            +SVerticalBox::Slot()
            .Padding( 1.0f )
            .HAlign(HAlign_Center)
            [
                SNew(STextBlock)
                .Text(LOCTEXT("CompileButton", "Compile").ToString())
                .Font( FEditorStyle::GetFontStyle( FName( "ToolBarButton.LabelFont" ) ) )
                .ToolTipText(LOCTEXT("CompileButton_Tooltip", "Recompile the blueprint").ToString())
            ]
        ]
    ]
]

입력

Slate에는 마우스와 키보드 입력을 받는 기능이 지원된다. 유연한 키 바인딩 시스템으로 어떤 키조합이든 바인딩 가능하며, 동적으로 변경도 가능하다.

출력

Slate는 타겟에 무관하게 렌더링 프리미티브를 사용하기에 어느 플랫폼에서도 실행 가능하다.

레이아웃 프리미티브

레이아웃 프리미티브로 정적, 동적 레이아웃으로 빌드를 쉽게 할 수 있다.

FString DefaultLayout =
                TEXT( " {" )
                TEXT( "     \"type\": \"tabstack\"," )
                TEXT( "     \"sizecoeff\": 1," )
                TEXT( "     \"children\":" )
                TEXT( "     [" )
                TEXT( "         {" )
                TEXT( "             \"type\": \"tab\"," )
                TEXT( "             \"content\": \"Widget Inspector Tab\"" )
                TEXT( "         }," )
                TEXT( "         {" )
                TEXT( "             \"type\": \"tab\"," )
                TEXT( "             \"content\": \"Plugin Manager Tab\"" )
                TEXT( "         }," )
                TEXT( "         {" )
                TEXT( "             \"type\": \"tab\"," )
                TEXT( "             \"content\": \"Debug Tools\"" )
                TEXT( "         }" )
                TEXT( "     ]" )
                TEXT( " }" );

위 레이아웃 코드는 아래와 같이 표현된다.

[사진 첨부]

사용자 주도형 레이아웃

Slate의 도킹 프레임워크는 자유롭게 탭 패널을 재배치하고 도킹하는 기능이 있다. 사용자가 환경을 커스터마이징할 수 있다면, 원하는 툴을 가지고 원하는 방식으로 작업할 수 있게 된다.

떠다니는 탭

탭을 도킹 타깃에 드래그

도킹된 탭

개발자 툴

Slate 위젯 리플렉터는 UI와 관련 코드를 디버깅하고 분석할 수 있다. 버그와 예상치 못한 행위를 추적하는데 뿐 아니라, 유저 인터페이스의 프로파일링과 최적화하는 데도 도움된다.

엔진 접근

Slate UI 시스템은 프로그래머에게 엔진과 에디터 직접 접근 권한을 제공하여 어떤 요구사항이든 수용할 수 있는 신기능과 툴 구현 작업을 쉽게 만들어 준다.

[게임수학] 17. 캐릭터: 게임에 생기를 불어넣는 기술

테디슨 — Wed, 19 Apr 2023 21:03:07 +0900

17.1 스켈레탈 애니메이션

스켈레탈 애니메이션(Skeletal animation) : 가상의 뼈대인 본(Bone)을 캐릭터 메시에 심은 후, 해당 본의 움직임에 맞춰 캐릭터 메시가 변형되는 방식을 사용

본을 구성하는 3가지 정보

이름 : 본을 식별할 수 있는 고유한 이름
트랜스폼 : 캐릭터 메시에 본이 심어질 때 본의 배치 정보 (현재의 정보)
바인드포즈(Bindpose) : 최초의 배치 정보, 향후 본이 움직일 때 상대적인 변화량을 파악하는데 사용
리깅(Rigging) : 메시에 본 정보를 추가한 후 본의 움직임에 따라 메시의 정점이 움직이도록 본과 정점을 연결하는 작업
웨이트(Weight) : 한 정점에 영향을 주는 본들의 연결 정보
게임 엔진은 시간에 따라 값의 변화를 저장한 키프레임(Keyframe) 데이터를 사용한다.

17-1 실습

스켈레탈 애니메이션의 구현

17.2 트랜스폼 계층 구조

부모 트랜스폼과 자식 트랜스폼이 가져야 하는 규칙

부모가 움직이면 부모의 움직임만큼 자식도 움직인다.
자식이 움직여도 부모는 영향을 받지 않는다.
하나의 부모는 여러 자식을 가질 수 있다.
자식은 하나의 부모만 가질 수 있다.

루트 트랜스폼 (Root Transform) : 계층 구조에서 부모가 없는 최상단 트랜스폼
월드 트랜스폼 (World transform) : 계층 구조와 상관없이 자식이 속한 공간에서의 트랜스폼. 절대 트랜스폼(Absolute transform)
로컬 트랜스폼 (Local transform) : 부모로 부터 상대적인 트랜스폼. 상대 트랜스폼(Relative transform)

트랜스폼 계층 구조의 변환

부모 - 나 - 자식 의 구조에서 사례별 정리

부모의 월드 트랜스폼이 변경된 경우
- 부모의 월드 트랜스폼, 나의 월드 트랜스폼, 자식의 월드 트랜스폼 순서대로 계산
- 나의 로컬 트랜스폼과 자식의 로컬 트랜스폼은 변경되지 않음
나의 로컬 트랜스폼이 변경된 경우
- 나의 로컬 트랜스폼, 나의 원월드 트랜스폼, 자식의 월드 트랜스폼 순서대로 계산
- 부모의 월드 트랜스폼과 자식의 로컬 트랜스폼은 변경되지 않음
나의 월드 트랜스폼이 변경된 경우
- 나의 월드 트랜스폼, 나의 로컬 트랜스폼, 자식의 월드 트랜스폼 순서대로 계산
- 부모의 월드 트랜스폼과 자식의 로컬 트랜스폼은 변경되지 않음
기존에 설정된 부모를 버리고 새로운 부모로 편입하는 경우
- 나의 로컬 트랜스폼을 월드 트랜스 폼으로 변경하고 새로운 부모로 부터의 로컬 트랜스폼을 계산

로컬 트랜스폼으로부터 월드 트랜스폼의 계산

부모의 월드 트랜스폼과 내 로컬 트랜스폼을 사용해 내 월드 트랜스폼을 구하는 방법

크기
S'_world = s-> * s'->

회전
q'_world = q' · q

이동
M_world = M_parent · M_local
t'_world = (q · t'->) * s-> + t

월드 트랜스폼으로부터 로컬 트랜스폼의 계산

부모의 월드 트랜스폼 정보와 나의 월드 트랜스폼 정보를 비교해 나의 로컬 트랜스폼을 계산하는 방법

크기
S^-1-> = (1/s_x, 1/s_y, 1/s_z)

회전
q*

이동
t^-1-> = (q* · t->) * s^-1->

17-2 실습

계층 구조를 활용한 태양계 시스템

캐릭터 메시와 애니메이션

캐릭터를 구성하는 본의 계층 구조

Root
- Plevis
  - Spine
    - LeftArm
    - RightArm
    - Neck
  - LeftLeg
  - RightLeg

17-3 실습

캐릭터 애니메이션의 구현

17.4 정리

스켈레탈 애니메이션의 구현 원리
트랜스폼의 계층구조

[게임수학] 16. 사원수: 4차원 수로 설계한 3차원 회전

테디슨 — Wed, 12 Apr 2023 21:16:21 +0900

사원수(Quaternion) : 4개의 독립된 체계로 구성된 4차원의 수집합, 2차원의 복소평면을 4차원 공간으로 확장한 개념

16.1 사원수 대수

사원수를 구성하는 세 허수

사원수는 3개의 허수부 i,j,k 로 구성되어있지만 허수단위 i와 같은 성질을 가진다.

사원수의 구조

사원수의 덧셈

q1 + q2 = (a1 + a2) + (b1 + b2)i + (c1 + c2)j + (d1 + d2)k

결합법칙 : q1 + (q2 + q3) = (q1 + q2) + q3

      = (a1 + a2 + a3) + (b1 + b2 + b3)i + (c1 + c2 + c3)j + (d1 + d2 + d3)k

교환법칙 : q1 + q2 = q2 + q1 = (a1 + a2) + (b1 + b2)i + (c1 + c2)j + (d1 + d2)k
항등원 : (a + bi + cj + dk) + (0 + 0i + 0j + 0k) = (a + bi + cj + dk)
역원 : (a + bi + cj + dk) + (-a - bi - cj - dk) = (0 + 0i + 0j + 0k)

사원수의 곱셈

q1 · q2 = (a1a2 - b1b2 - c1c2 - d1d2) + (a1b2 + a2b1 + c1d2 - d1c2)i + (a1c2 + a2c1 + b2d1 - b1d2)j + (a1d2 + a2d1 + b1c2 - c1b2)k

결합법칙 : q1 · (q2 · q3) = (q1 · q2) · q3
분배법칙 : q1 · (q2 + q3) = q1 · q2 + q1 · q3
항등원 : (a + bi + cj + dk) · (1 + 0i + 0j + 0k) = (a + bi + cj + dk)
교환법칙은 성립하지 않음

사원수의 크기는 기호 | | 를 사용하여 표기한다 사원수의 크기를 노름(Norm)이라 부른다.

|q| = sqrt(a^2 + b^2 + c^2 + d^2)

사원수와 벡터

q = w + xi + yj + zk = (w, v->)
q1 + q2 = (w1 + w2, v1-> + v2->)

q1·q2 = (w1w2 - (v1->·v2->), w1v2-> + w2v1-> + v1 x v2)

순허수 사원수(Pure imaginary quaternion)

xi + yj + zk = (0, v->)

16.2 사원수의 회전

e^iθ = cos θ + i sin θ = (cos θ, sin θ)

사원수와 오일러 공식

회전 사원수 (Rotation quaternion) : 4차원 공간에서 회전축 n->을 중심으로 회전 변환하는 성질을 가지는 사원수 (cos θ, sin θ)

회전 사원수를 이용한 3차원 공간에서의 회전

회전 사원수와 순허수 사원수 벡터 v->의 곱셈

v'-> = q · v->
= (cos θ, sin θ · n->)·(0, v->)
= (-sin θ(n-> · v->), cos 0 v-> + sin 0(n-> x v->))

16.3 사원수의 변환

오일러 각에서 사원수로의 변환

q = (cos 0/2, sin 0/2·x->) = cos 0/2 + sin 0/2 i

사원수에서 오일러 각으로의 전환

중략

사원수에서 회전 변환 행렬로의 변환

┌ 1-2(y^2+z^2) 2(xy-zw) 2(xz+yw) ┐
│ 2(xy+zw) 1-2(x^2+z^2) 2(yz-xw) |
└ 2(xz-yw) 2(yz+xw) 1-2(x^2+y^2) ┘

회전 변환행렬에서 사원수로의 변환

중략

16.4 사원수의 보간

사원수의 장점

오일러 각과 쉽게 변환이 가능하며 회전행렬 제작이 용이
임의의 축에 대한 회전 표현이 가능하여 짐벌락 현상을 방지
임의의 축에 대한 회전 보간 값을 구할 수 있음
4개의 숫자만 사용하여 저장 공간을 효율적으로 쓸 수 있음
오일러각
- 저장 공간이 가장 작다. 공간의 수 3
- 짐벌락 현상이 발생한다.
- 한 기저 축에 대해서만 회전 보간이 가능하다.
- 직관적이다.
행렬
- 저장 공간이 크다. 공간의 수 9
- 짐벌락 현상이 발생하지 않는다.
- 회전 보간이 불가능하다.
- 직관적이지 않다.
사원수
- 저장 공간이 작다. 공간의 수 4
- 짐벌락 현상이 발생하지 않는다.
- 회전 보간이 임의의 축에 가능하다.
- 직관적이지 않다.

16-1 실습

자유로운 3차원 회전의 구현

정리

사원수의 대수 구조를 설명
사원수를 활용해 3차원 공간의 회전에 사용되는 수학