1-3. One File Per Actor (OFPA) | World Partition Deep Dive

01

OFPA 개요

각 액터를 개별 파일로 저장

OFPA(One File Per Actor)는 각 액터를 개별 파일로 저장하여 소스 컨트롤 충돌을 최소화하는 시스템입니다. 팀원들이 동시에 같은 월드에서 작업해도 파일 충돌이 발생하지 않습니다.

Content/
├── Maps/
│   └── MyLevel.umap                    # 메인 레벨 파일
├── __ExternalActors__/
│   └── Maps/
│       └── MyLevel/
│           ├── A/
│           │   └── B/
│           │       └── ABC123.uasset   # 개별 액터 파일
│           ├── C/
│           │   └── D/
│           │       └── DEF456.uasset
│           └── ...
└── __ExternalObjects__/
    └── ...                              # 외부 오브젝트

OFPA의 장점

동시 작업 - 같은 레벨에서 여러 팀원이 동시 작업 가능
충돌 최소화 - Git/Perforce에서 병합 작업이 수월
세분화된 버전 관리 - 개별 액터 변경 이력 추적
선택적 로드 - 에디터에서 필요한 액터만 로드

02

FWorldPartitionActorDesc

액터 메타데이터 저장 구조체

Actor Descriptor는 액터의 메타데이터를 저장하여 액터를 로드하지 않고도 정보를 조회할 수 있게 합니다.

                    C++ - WorldPartitionActorDesc.h
// Engine/Source/Runtime/Engine/Public/WorldPartition/WorldPartitionActorDesc.h

struct FWorldPartitionActorDesc
{
    // 기본 정보
    FGuid ActorGuid;
    FName ActorClass;
    FName ActorName;
    FName ActorLabel;

    // 공간 정보
    FBox Bounds;
    FBox EditorBounds;

    // 스트리밍 정보
    bool bIsSpatiallyLoaded;
    TArray<FName> DataLayers;
    FName RuntimeGrid;

    // 레퍼런스
    TArray<FGuid> References;          // 하드 레퍼런스
    TArray<FGuid> EditorReferences;    // 에디터 전용 레퍼런스
};
                

Actor Descriptor 활용

에디터는 Actor Descriptor만 로드하여 전체 월드의 구조를 파악합니다. 실제 액터 데이터는 사용자가 해당 영역을 로드할 때만 메모리에 올립니다.

03

OFPA 활성화 및 변환

프로젝트에 OFPA 적용하기

1. 에디터 설정에서 활성화

                    Editor 설정 경로
// 프로젝트 설정 또는 레벨별 설정
// Edit > Editor Preferences > Experimental > Tools > One File Per Actor

// 또는 레벨별로 설정
// World Settings > World > Advanced > Use External Actors = true
                

2. Commandlet을 통한 변환

                    Command Line
# 레벨과 모든 서브레벨을 OFPA로 변환
UnrealEditor-Cmd.exe "MyProject.uproject" -run=WorldPartitionConvertCommandlet
    "/Game/Maps/MyLevel" -AllowCommandletRendering
                

변환 주의사항

대규모 맵 변환 시 메모리 이슈(E_OUTOFMEMORY)가 발생할 수 있습니다. 반드시 백업 후 변환하고, 필요시 단계적으로 진행하세요.

04

에디터 vs 패키지 빌드

OFPA 동작 차이점

항목	에디터/PIE	패키지 빌드
OFPA	개별 파일에서 직접 스트리밍	레벨 파일에 임베드됨
스트리밍	즉각적 (파일 기반)	최적화된 레벨 스트리밍
Level Instance	즉시 로드	UpdateStreamingState 필요
HLOD	때때로 불안정	일반적으로 안정적
메모리	더 많은 메모리 사용	최적화됨

핵심 포인트

Cook 시 모든 액터는 해당 레벨 파일에 임베드됩니다. OFPA는 에디터 전용 기능입니다. 패키지 빌드에서는 전통적인 레벨 스트리밍 방식으로 동작합니다.

05

OFPA 주의사항

실무에서 알아야 할 제약사항

AutoSave 주의

AutoSave가 활성화되어 있으면 __ExternalActors__ 폴더가 매우 커질 수 있습니다. 대규모 프로젝트에서는 비활성화 고려.

폴더 이름 변경

Maps 폴더 이름 변경 시 레퍼런스 문제가 발생할 수 있습니다. 리디렉터를 통한 이동을 권장합니다.

소스 컨트롤 제출

소스 컨트롤 제출은 에디터 내에서 수행하는 것이 권장됩니다. 외부 도구 사용 시 일부 파일이 누락될 수 있습니다.

디스크 공간

수많은 작은 파일이 생성되므로 SSD 사용을 권장합니다. HDD에서는 에디터 성능이 저하될 수 있습니다.

SUMMARY

핵심 요약

OFPA는 각 액터를 __ExternalActors__ 폴더에 개별 파일로 저장
FWorldPartitionActorDesc가 액터 메타데이터를 저장하여 선택적 로드 가능
Cook 시 모든 액터는 레벨 파일에 임베드 - OFPA는 에디터 전용
WorldPartitionConvertCommandlet으로 기존 레벨 변환 가능
AutoSave, 폴더 이름 변경, 소스 컨트롤 제출 시 주의 필요

PRACTICE

도전 과제

배운 내용을 직접 실습해보세요

실습 1: OFPA 파일 구조 확인

월드에 액터를 배치한 후 __ExternalActors__ 폴더에 생성되는 .uasset 파일을 확인하세요. 액터를 이동/수정하고 Saved Packages에서 어떤 파일만 변경되는지 소스 컨트롤 상태를 관찰합니다.

실습 2: Actor Descriptor 확인

에디터에서 World Partition 창을 열어 FWorldPartitionActorDesc가 표시하는 메타데이터(클래스, 바운드, 데이터 레이어, 그리드 배치)를 확인하세요. 로드하지 않은 액터의 정보가 어떻게 표시되는지 분석합니다.

심화 과제

10명 이상의 레벨 디자이너가 동시 작업하는 시나리오에서 OFPA와 Perforce/Git-LFS를 조합한 최적 워크플로우를 설계하세요. 체크아웃 충돌 최소화, 브랜치 전략, Submit 규칙을 정의합니다.