Unreal Engine’de Python ile editör otomasyonu: adım adım başlangıç rehberi

Bu rehberde ne öğreneceksiniz?

Unreal Editor’daki Python desteği, tekrar eden üretim görevlerini betiklerle yürütmek ve farklı 3D uygulamalar arasındaki üretim hattını desteklemek için kullanılabiliyor. Epic’in belgelerinde örneklenen işler arasında varlık yönetimini otomatikleştirmek, Static Mesh’ler için LOD üretmek ve bir Level içeriğini prosedürel biçimde yerleştirmek bulunuyor. Python ayrıca editör için özel arayüzler hazırlamaya da imkân veriyor.

Bu rehberde önce proje ayarlarını yapacak, ardından kısa bir Python komutunu çalıştıracak ve dosya tabanlı betiklerle otomasyon seçeneklerini karşılaştıracağız. Buradaki yöntemler editör otomasyonuna yöneliktir: Python desteği, Unreal Editor açıkken kullanılabilir; oyun Play In Editor’da, Standalone Game’de veya paketlenmiş çalıştırılabilir dosyada çalışırken kullanılamaz.

Gereksinimler

Python Editor Script Plugin’i açabileceğiniz bir Unreal Engine projesi ve Unreal Editor gerekir. Epic’in rehberine göre eklenti, projeye özel etkinleştirilir; başka bir projede Python kullanmak için orada da ayrıca açılmalıdır. Sık kullanılan editör işlemlerine yönelik sadeleştirilmiş API’ler sağlayan Editor Scripting Utilities eklentisini de etkinleştirmek önerilir.

Python Editor Script Plugin, Python 3.11.8’i Unreal Editor içine gömülü olarak getirir. Bu nedenle rehberdeki kullanım için bilgisayara ayrıca Python kurmak gerekmez. Farklı bir Python sürümünü kullanmak, işletim sisteminde UE_PYTHON_DIR ortam değişkenini ayarlayıp Unreal Engine’i kaynaktan yeniden derlemeyi gerektiriyor.

Epic’in Python API belgeleri Unreal Python 5.8’i “Experimental” olarak işaretliyor. Ana kullanım kılavuzu da özelliğin deneysel olduğuna dikkat çekiyor. Bu nedenle betikleri önce üretim projesinin bir kopyasında veya kontrollü bir test projesinde doğrulamak yerinde olur.

Adım adım: eklentiyi açın ve ilk komutu çalıştırın

1. Unreal Editor’da çalışacağınız projeyi açın. Üst menüden Edit > Plugins yolunu izleyin.

2. Eklentiler penceresinin Scripting bölümünde Python Editor Script Plugin seçeneğini bulun ve Enabled kutusunu işaretleyin.

3. Aynı pencerede Editor Scripting Utilities eklentisini de etkinleştirin. Değişikliklerin ardından editörü yeniden başlatın.

4. Output Log panelini açın ve konsol girişini Python moduna alın. Alternatif olarak ~ tuşuyla konsol giriş çubuğunu açabilirsiniz. Python modunda yazılan kod satırları editörde hemen yürütülür.

5. İlk deneme olarak Python’un print fonksiyonuyla Output Log’a bir mesaj yazdırın:

print("Python etkin")

print çıktısı Output Log paneline yönlendirilir. Konsolda birden fazla satırı çalıştırmak için satırları Shift+Enter ile ayırabilir veya çok satırlı kodu yapıştırabilirsiniz. Bu yöntem, tek tek satır denemek ve basit kontroller yapmak için elverişlidir.

Betik dosyasını çalıştırma seçenekleri

Tekrarlanabilir işlerde kodu bir Python dosyasında tutmak daha düzenli bir çalışma sağlar. Editör konsolunda betik dosyasının yolunu belirterek çalıştırabilirsiniz:

py "C:\MyScripts\my_script.py"

Buradaki yol Epic’in belgesindeki örnektir; kendi betiğinizin konumuyla değiştirin. Alternatif olarak ana penceredeki File > Execute Python Script seçeneğiyle bilgisayardan bir betik seçebilirsiniz. Daha önce çalıştırılan dosyaları Recent Python scripts listesinden yeniden çağırmak da mümkün. Editör dosyayı diskten tekrar okuduğu için dosyada yapılan son değişiklikler de çalıştırılır.

Komut satırından çalıştırma, otomasyon hattına betik eklemek isteyen ekipler için başka bir seçenektir. Tam editör açılıp proje ve varsayılan başlangıç seviyesi yüklendikten sonra betiği çalıştırabilir:

UnrealEditor-Cmd.exe "C:\projects\MyProject.uproject" -ExecutePythonScript="c:\my_script.py"

Bu yaklaşım için projede Python Scripting Plugin ile Editor Scripting Utilities etkinleştirilmiş olmalıdır. İşlem betik tamamlandıktan sonra editörü kapatır.

Daha hızlı, arayüzsüz çalıştırma için pythonscript commandlet’i kullanılabilir:

UnrealEditor-Cmd.exe "C:\projects\MyProject.uproject" -run=pythonscript -script="c:\\my_script.py"

Bu yöntem seviyeleri kendiliğinden yüklemez. Betiğin belirli bir Level içeriğine erişmesi gerekiyorsa, Epic’in belgesinde ilk satır olarak verilen yükleme çağrısı kullanılabilir; içindeki yol örnek projeye aittir ve gerçek projedeki Level yoluna göre düzenlenmelidir:

unreal.get_editor_subsystem(unreal.LevelEditorSubsystem).load_level("/Game/maps/UVlayoutTest.UVlayoutTest")

Yaygın hatalar ve sınırlar

En sık gözden kaçan nokta, eklentinin proje başına etkinleştirilmesidir. Bir projede çalışan betiğin başka bir projede de çalışacağını varsaymayın; önce ilgili eklenti durumunu kontrol edin. Komut satırıyla tam editör yönteminde Editor Scripting Utilities gereksinimini de unutmayın.

Commandlet ile tam editör başlatma aynı davranışı göstermez. Commandlet seviyeyi otomatik yüklemediğinden, seviye içeriğine dayanan betiklerde yükleme adımını açıkça ele almak gerekir. Tam editör yönteminde ise proje açılır ve varsayılan başlangıç seviyesi hazır olduktan sonra betik çalışır.

Python’ı oynanış mantığı için kullanmaya çalışmak da uygun bir kullanım değildir. Epic’in dokümantasyonu Python ortamının Unreal Editor’da bulunduğunu ve çalışma zamanı modlarında kullanılamadığını belirtiyor. Blueprint içinden Python çalıştırma düğümleri de yalnızca Editor Utility Widget ve Editor Utility Blueprint gibi editör odaklı Blueprint sınıflarında kullanılabiliyor; normal çalışma zamanı sınıflarında kullanılamıyor.

Mimarlık, iç mimarlık ve archviz iş akışlarına etkisi

Mimarlık ofisleri ve görselleştirme ekipleri için en doğrudan fayda, editör içinde tekrarlanan varlık işlemlerini betiklerle yönetebilmek. Örneğin projedeki varlık yönetimini düzenlemek, LOD üretimini otomatikleştirmek veya bir seviyeye içerik yerleştirmek, belgelerde açıkça belirtilen kullanım alanları arasında. Birden fazla 3D uygulamanın yer aldığı üretim hatlarında Python’ın ortak betik dili olarak kullanılması da süreçleri birbirine bağlamaya yardımcı olabilir.

Buna karşılık bu rehber, belirli bir archviz eklentisi, donanım gereksinimi, lisans modeli veya belirli bir proje için uyumluluk garantisi sunmuyor. Özellikle deneysel olarak işaretlenen API’lerde, kullanılacak işlevlerin projenin Unreal sürümünde çalıştığı doğrulanmalı. Otomasyonun seviye yükleme davranışını, editör eklentilerini ve ekipteki diğer kullanıcıların proje ayarlarını nasıl etkileyeceğini test etmeden üretim sürecine taşımayın.

Sonraki adımlar

İlk betiği çalıştırdıktan sonra, küçük ve geri alınabilir bir görev seçin: örneğin editör içinden bir komutu doğrulamak veya mevcut bir üretim adımını kontrollü biçimde otomatikleştirmek. Ardından işlemi dosya olarak saklayıp Execute Python Script ya da uygun komut satırı yöntemini deneyin. Birden fazla kişinin kullanacağı projelerde başlangıç betikleri de değerlendirilebilir: init_unreal.py, projenin veya eklentinin Content/Python klasörüne konabilir ve editör tarafından otomatik çalıştırılır. Proje ayarlarında başlangıçta çalıştırılacak betikler de tanımlanabilir.

İş akışı büyüdükçe Unreal Python API belgelerini kullandığınız sürümle birlikte inceleyin; bu belgeler modüller, türler ve API başlıkları için başvuru noktası sağlıyor. Deneysel özelliğin durumunu ve betiklerin yalnızca editör içinde çalıştığını göz önünde tutarak kapsamı adım adım genişletin.

Kaynak ve lisans

Bu rehber, Epic Games’in “Scripting the Unreal Editor Using Python” kılavuzu ve “Unreal Python API Documentation” sayfası temel alınarak Türkçeye uyarlanmıştır. Kaynaklar serbest kullanım olarak işaretlenmiştir; metin ve örnek anlatım yeniden düzenlenmiştir.