Unreal Engine World Partition Convert Fix: Sonsuz Yükleme ve Editor Kilitlenmeleri Nasıl Çözülür?

World Partition menüsünde "Convert" butonuna tıklarsınız ve Unreal Engine editörünüz anında kilitlenir. İlerleme çubuğu %0'da donar, tek bir çekirdekte CPU kullanımı %100'e fırlar ve tek seçeneğiniz Görev Yöneticisi veya terminal aracılığıyla işlemi sonlandırmaya zorlamaktır (force-kill). Harita dönüştürme (map conversion) sırasındaki bu sonsuz yükleme döngüsü (infinite loading loop), eski haritaları veya büyük ölçekli prototipleri Unreal Engine'in modern spatial streaming mimarisine geçiren ekipler için baş belası bir engeldir. Editör arayüzü (editor UI) dönüştürmeyi sadece bir menü tıklaması kadar basit gösterse de, bunu basit olmayan bir seviyede yapmak; editör thread'inin kaldıramayacağı bir dizi senkronize asset yazma, spatial grid tahsisleri ve paket serialization döngülerini tetikler.

Eğer ekibiniz unreal engine world partition convert fix uygulamasını hayata geçirmekte zorlanıyorsa, çözüm editor UI'ını tamamen devre dışı bırakarak harita asset'lerinizi programatik olarak denetlemekten geçiyor. Aşağıda, bu dönüşüm hatalarının ardındaki teknik nedenleri, Unreal'ın commandlet framework'ünü kullanarak dönüşüm sürecini güvenli bir şekilde nasıl çalıştıracağınızı ve saatlerce süren hata ayıklama (debugging) süresinden tasarruf etmek için uçuş öncesi doğrulama (pre-flight validation) kontrollerini nasıl otomatikleştireceğinizi ele alıyoruz.

İşin Arkasında Ne Var? World Partition Dönüşümü Editörünüzü Neden Donduruyor?

Dönüşüm kilitlenmesini çözmek için öncelikle dönüşümü tetiklediğinizde Unreal Engine'in ne yapmaya çalıştığını anlamalısınız. Eski bir seviyede (.umap), tüm actor'ler, özellikler ve component'ler tek ve devasa bir monolithic paket halinde serialize edilir. World Partition ise seviyeyi bir spatial grid'e bölerek ve One File Per Actor (OFPA) sistemini kullanarak her actor'ü kendi ayrı dosyasında saklayarak bunun yerini alır.

Dönüşüm sırasında engine, sıklıkla başarısız olan son derece yoğun üç işlem gerçekleştirir:

1. Spatial Hash Grid Tahsisi ve Sonsuz Koordinat Döngüsü

Unreal Engine, her actor'ün bounding box'ını bir grid hücresine eşler. Varsayılan olarak World Partition, hücre başına 25.600 birimlik (256 metre) bir spatial grid boyutu kullanır. Eğer uç noktalardaki koordinatlara yerleştirilmiş bir actor'ünüz varsa (örneğin, başıboş bir particle system, bir UI helper actor'ü veya yanlış yapılandırılmış bir collision volume; örn. X=2.000.000, Y=-5.000.000), engine başlangıç noktası (origin) ile o actor arasındaki her hücre için hücre metadata'sı oluşturmaya çalışır. Bu durum, milyonlarca boş hücreyi bölümlere ayırmaya çalışırken editörü donduran bir sonsuz bellek tahsisi (memory allocation) döngüsünü tetikler.

2. Disk Throttling ve Dizin Kilitlenmeleri (OFPA)

15.000 actor içeren bir haritayı dönüştürmek, engine'in ExternalActors dizini içinde 15.000 adet bağımsız .uasset dosyası oluşturması gerektiği anlamına gelir. Editörde bu işlem, ana thread (main thread) üzerinde senkronize olarak çalışır. Proje dizinlerinizde aktif bir versiyon kontrol entegrasyonu (Perforce veya Git gibi) veya gerçek zamanlı bir antivirüs tarayıcısı etkinse, her dosya yazma işlemi kesintiye uğrar. İşletim sistemi dosya tanıtıcılarını (file handles) kilitler ve editör thread'ini beklemeye zorlar; bu da kendini sonsuz bir donma (infinite freeze) olarak gösterir.

3. Bellek Tüketimi (Memory Exhaustion) ve Paket Serialization Hataları

Dönüşüm sırasında editör, sınırları (bounds) yeniden hesaplamak ve temiz actor paketleri yazmak için referans verilen tüm blueprint'leri, static mesh'leri ve texture'ları belleğe yükler. Yeterli RAM olmadığında, engine fiziksel belleği tüketir ve büyük ölçüde disk disk belleği dosyasına (disk paging) bağımlı olduğu için durma noktasına gelir. Dahası, çözülmemiş döngüsel bağımlılıklar (circular dependencies) veya bozuk blueprint'ler, serialization worker'ı anında durduran Unreal Package HasValidBlueprint Ensure Crash hatasına benzer ciddi paketleme çökmelerine yol açabilir.

---

Adım Adım Çözüm 1: Commandlet Tabanlı Dönüşüm (Güvenli Yol)

Orta veya büyük ölçekli haritaları asla Unreal Editor UI üzerinden dönüştürmeyin. Bunun yerine WorldPartitionConvertCommandlet kullanın. Dönüşümü komut satırı (command line) üzerinden çalıştırmak, süreci editörün UI thread'inden izole eder, engine'in belleği daha verimli bir şekilde Garbage Collection işlemine tabi tutmasını sağlar ve terminalinizde gerçek zamanlı log çıktısı sunarak hangi actor'ün kilitlenmeye neden olduğunu tam olarak görmenizi sağlar.

Proje klasörünüzün içinde bir bash betiği (convert_map.sh) veya bir Windows batch betiği (convert_map.bat) oluşturun. İşte Windows için geliştiriciler tarafından onaylanmış sağlam bir betik:

@echo off
SET "UNREAL_ENGINE_PATH=C:\Program Files\Epic Games\UE_5.5\Engine\Binaries\Win64\UnrealEditor-Cmd.exe"
SET "PROJECT_PATH=D:\Projects\MyGame\MyGame.uproject"
SET "MAP_NAME=/Game/Maps/Campaign_Main"

echo Starting World Partition Conversion for %MAP_NAME%...

"%UNREAL_ENGINE_PATH%" "%PROJECT_PATH%" ^
    -run=WorldPartitionConvertCommandlet ^
    "%MAP_NAME%" ^
    -AllowCommandletRendering ^
    -Force ^
    -Verbose ^
    -stdout ^
    -unattended ^
    -NoShaderCompile ^
    -LOG=WorldPartitionConversion.log

if %ERRORLEVEL% NEQ 0 (
    echo Conversion failed! Check Saved\Logs\WorldPartitionConversion.log
    exit /b %ERRORLEVEL%
)

echo Conversion completed successfully!

Kritik Commandlet Parametrelerinin (Flags) Açıklaması:

• UnrealEditor-Cmd.exe: Standart UnrealEditor.exe yerine her zaman komut satırı executable dosyasını kullanın. Bu, log'ları doğrudan stdout'a yazdırır ve işlem bittiğinde hemen kapanır.
• -AllowCommandletRendering: Engine'i rendering kaynaklarını başlatmaya zorlar. Haritanızda serialization sırasında GPU bounds hesaplamaları veya material derlemesi gerektiren actor'ler veya component'ler varsa oluşabilecek kilitlenmeleri önler.
• -Force: Dönüştürücüye mevcut tüm external actor asset'lerinin üzerine yazmasını söyler. Bu, önceki bir dönüşüm denemesi yarıda kaldığında ve ExternalActors dizininde bozuk asset'ler bıraktığında kritik bir öneme sahiptir.
• -unattended: Tüm modal açılır pencereleri ve diyalog kutularını engeller. Bu parametre olmadan dönüşüm arka planda sessizce durabilir ve bir asset referansı uyarısında "OK" butonuna tıklamanızı bekleyebilir.
• -NoShaderCompile: Shader derleyicisinin (shader compiler) yeni thread'ler başlatmasını önleyerek dönüşüm sırasında önemli ölçüde CPU ve bellek tasarrufu sağlar.

---

Adım Adım Çözüm 2: Uçuş Öncesi Python Doğrulama Betiği

Haritanızda hatalı veriler varsa dönüşüm betiğini körü körüne çalıştırmak yine de başarısız olabilir. Başarıyı garanti altına almak için, dönüştürücüyü çalıştırmadan önce harita paketinizi denetlemek için aşağıdaki betiği kullanın. Bu Python betiği Unreal Editor içinde çalışır (Python Editor Script Eklentisinin etkinleştirildiğinden emin olun) ve serialization sürecini tıkayan uç koordinatları, null actor'leri ve yüksek yoğunluklu component'leri kontrol eder.

Bu betiği wp_preflight_check.py adıyla kaydedin ve Python konsolu üzerinden veya doğrudan editör penceresine sürükleyerek çalıştırın:

import unreal

def validate_map_for_world_partition(map_path, max_boundary_cm=1000000.0):
    """
    Validates a monolithic map asset before converting it to World Partition.
    Scans for null references, extreme actor coordinates, and component counts.
    """
    # Initialize the asset registry to find the target level
    asset_registry = unreal.AssetRegistryHelpers.get_asset_registry()
    map_asset = asset_registry.get_asset_by_object_path(unreal.SoftObjectPath(map_path))
    
    if not map_asset:
        unreal.log_error(f"[PREFLIGHT] Map asset not found at path: {map_path}")
        return False
        
    unreal.log(f"[PREFLIGHT] Loading map package to analyze: {map_path}")
    world = unreal.EditorLoadingAndSavingUtils.load_map(map_path)
    if not world:
        unreal.log_error("[PREFLIGHT] Failed to load the map package into the editor context.")
        return False
        
    # Query all actors currently present in the persistent level
    actors = unreal.GameplayStatics.get_all_actors_of_class(world, unreal.Actor)
    total_actors = len(actors)
    unreal.log(f"[PREFLIGHT] Analyzing {total_actors} actors for potential conversion hazards...")
    
    invalid_actors = 0
    out_of_bounds_actors = []
    heavy_components_actors = []
    
    for actor in actors:
        if not actor or not actor.is_valid():
            invalid_actors += 1
            continue
            
        actor_name = actor.get_actor_label()
        
        # 1. Coordinate Boundary Checks (Detects spatial grid loops)
        location = actor.get_actor_location()
        if (abs(location.x) > max_boundary_cm or 
            abs(location.y) > max_boundary_cm or 
            abs(location.z) > max_boundary_cm):
            out_of_bounds_actors.append((actor_name, location))
            
        # 2. Check for component bloat that leads to serialization hangs
        components = actor.get_all_child_actors(True)
        if len(components) > 150:
            heavy_components_actors.append((actor_name, len(components)))
            
    # Compile the pre-flight report
    unreal.log("------------------ PRE-FLIGHT REPORT ------------------")
    unreal.log(f"Total Actors Audited: {total_actors}")
    
    success = True
    
    if invalid_actors > 0:
        unreal.log_error(f"[FAIL] Found {invalid_actors} invalid/corrupted actors. Clean up your map hierarchy first.")
        success = False
    else:
        unreal.log("[PASS] No corrupted actors found.")
        
    if out_of_bounds_actors:
        unreal.log_warning(f"[WARN] Found {len(out_of_bounds_actors)} actors at extreme coordinates. These will cause infinite spatial grid loops:")
        for name, loc in out_of_bounds_actors:
            unreal.log_warning(f"  -> Actor: '{name}' is at X={loc.x:.1f}, Y={loc.y:.1f}, Z={loc.z:.1f}")
        success = False
    else:
        unreal.log("[PASS] All actors lie within reasonable spatial boundaries.")
        
    if heavy_components_actors:
        unreal.log_warning(f"[WARN] Found {len(heavy_components_actors)} actors with high child/component density:")
        for name, count in heavy_components_actors:
            unreal.log_warning(f"  -> Actor: '{name}' has {count} children (consider merging or nesting)")
            
    unreal.log("-------------------------------------------------------")
    return success

# Execute validation on your target map path
# Example: validate_map_for_world_partition("/Game/Maps/Campaign_Main")

---

Disk I/O Engellerini ve Versiyon Kontrol Kilitlerini Çözme

Python kontrolü başarılı olur ve commandlet yine de kilitlenirse sorun çevreseldir. World Partition dönüşümü saniyeler içinde dizin yapınızda binlerce fiziksel asset dosyası oluşturur.

Disk engelleme sorunlarını çözmek için:

1. Proje dizinlerini Real-Time Protection kapsamından çıkarın: Windows Güvenliği'ni (veya kurumsal antivirüs yazılımınızı) açın ve proje kök klasörünüzü hariç tutulanlar listesine ekleyin. Gerçek zamanlı antivirüs tarayıcıları, ExternalActors dizinine yazılan her bir .uasset dosyasını incelemeye çalışarak disk sırasını tamamen kilitleyecek ve Unreal asset yazıcısının zaman aşımına uğramasına neden olacaktır.
2. Versiyon kontrol eklentilerini (Plugins) geçici olarak devre dışı bırakın: Dönüşüm betiğini çalıştırmadan önce, .uplugin dosyalarını geçici olarak yeniden adlandırın veya editör yapılandırmanızda Perforce/Git eklentisini kapatın. Harita başarıyla dönüştürüldükten sonra versiyon kontrol eklentisini tekrar etkinleştirebilir, yeni ExternalActors dizinini değişiklik listenize (changelist) ekleyebilir ve commit edebilirsiniz.
3. Yönetici Yetkileriyle Çalıştırın: Bazı kurumsal geliştirici ortamlarında dizin yazma kısıtlamaları, commandlet'lerin anında alt dizinler oluşturmasını engelleyerek sessiz yazma hatalarına ve thread kilitlenmelerine neden olur.

---

Devasa Dünyaları Ölçeklemek: Backend Boyutu

Haritanızı World Partition'a dönüştürmek, devasa koordinatları ve son derece detaylı sahneleri yönetmeye yönelik ilk adımdır. Ancak, büyük dünyaya sahip bir oyun çalıştırmak, multiplayer altyapınıza yeni zorluklar getirir.

Oyun dünyanız birkaç kilometrekareyi kapladığında, tek bir dedicated server instance'ı her oyuncu için replikasyon, collision ve fizik işlemlerini verimli bir şekilde işleyemez. Sunucu performansını korumak için geliştiricilerin sunucu tarafında ihtiyaç duyulmayan asset'leri temizlemesi gerekir; bu süreç dedicated server asset stripping kılavuzumuzda ayrıntılı olarak açıklanmıştır.

Asset stripping yapılsa bile, devasa bir dünya nihayetinde server zoning (sunucu bölgelendirmesi) ve kesintisiz oyuncu geçişleri gerektirir. Dinamik sunucu tahsisi, bölgeler arası matchmaking ve gerçek zamanlı veritabanı senkronizasyonunu yöneten dağıtık bir sunucu backend yapısı oluşturmak devasa bir girişimdir. Geliştiriciler genellikle büyük ölçekli lobileri desteklemek için özel load balancer'lar, session manager'lar ve veritabanı senkronizasyon hatları yazmak için aylar harcarlar.

İşte bu noktada devreye, multiplayer oyun geliştiricileri için özel olarak tasarlanmış, önceden mimarisi oluşturulmuş ve kullanıma hazır bir Backend-as-a-Service sunan horizOn giriyor. Platformumuz oyuncu kalıcılığını (player persistence), düşük gecikmeli session management işlemlerini ve sunucu tarafı durum senkronizasyonunu (state synchronization) otomatik olarak yöneterek ekibinizin altyapı hatalarını ayıklamak yerine oynanış sistemleri oluşturmaya ve istemci (client) performansını optimize etmeye odaklanmasını sağlar.

---

World Partition Dönüşümleri İçin En İyi Pratikler

Sorunsuz harita dönüşümleri sağlamak ve gerilemeleri (regressions) önlemek için savaştan çıkmış bu 4 kuralı takip edin:

1. Öncelikle Belirgin Level Sınırları (Bounds) Tanımlayın: Dönüşümden önce haritanıza her zaman bir ALevelBounds actor'ü yerleştirin. Bu, World Partition builder'a spatial hash için kesin bir bounding box sağlayarak jeneratörün sonsuz koordinatlara yerleştirilmiş başıboş asset'leri ayrıştırmasını engeller.
2. Circular Blueprint Bağımlılıklarını Temizleyin: Seviye blueprint'lerinizin, harici dosyalara dönüştürülen actor'lerle sıkı casting bağımlılıkları (casting dependencies) içermediğinden emin olun. Döngüsel bağımlılıklar (circular dependencies), paketleme aracını serialization ortasında paketleri yeniden yüklemeye zorlayarak sıklıkla memory leak'lere ve dönüşüm kilitlenmelerine neden olur.
3. Dönüşümleri Temiz Bir Engine Durumunda Gerçekleştirin: Devasa seviyeleri dönüştürmeden önce her zaman sisteminizi yeniden başlatın veya shader önbelleğini ve DerivedDataCache (DDC) klasörünü temizleyin. Bu, sistem RAM'ini serbest bırakır ve commandlet'in güncel olmayan önbelleğe alınmış asset'ler nedeniyle tıkanmamasını sağlar.
4. Git/Perforce Üzerinde ExternalActors Dizinini İzole Edin: .gitignore veya .p4ignore dosyalarınızın, ExternalActors dizini altında oluşturulan .uasset dosyalarını takip ederken geçici kilit dosyalarını (lock files) yok sayacak şekilde doğru şekilde yapılandırıldığından emin olun.

---

Multiplayer Backend'inizi Ölçeklemeye Hazır mısınız?

Dönüşümlerinizi commandlet'ler aracılığıyla çalıştırarak ve actor konumlarını programatik olarak doğrulayarak editör kilitlenmelerini kolayca aşabilir ve oyununuzu geliştirmeye devam edebilirsiniz. Devasa seviyeleriniz bölümlere ayrılıp optimize edildikten sonra, bir sonraki adım backend altyapınızın yükü kaldırabileceğinden emin olmaktır.

Özel matchmaking, lobi sistemleri ve player state replication kurmak için haftalar harcamak yerine, zor işleri horizOn'a bırakın. Bugün ücretsiz deneyin veya Unreal Engine projenizi entegre etmenin ne kadar kolay olduğunu görmek için API dokümanlarını okuyun.

---

Kaynak: Convert map to world partition not working unreal engine 5.7.4