Python Developer API

Unreal Engine gereksinimi

Etkileşimli Python Developer API erişimi ve kullanıcı etkileşimi gerektirmeyen Python otomasyonu Unreal Engine 5.6 veya daha yeni bir sürüm gerektirir. Temel Locus özellikleri, C++, Blueprint ve MCP; Unreal Engine 5.4 ve 5.5’te desteklenmeye devam eder. Unreal Engine’in reflection sistemindeki doğrulanmış bir sınırlama nedeniyle Python bu sürümlerde desteklenmez.

Desteklenen Engine sürümlerinde Locus, paylaşılan istek temelini doğrudan unreal altında sunar. Python, Blueprint async-action proxy’leri yerine bu istekleri kullanır.

Giriş noktası unreal.LocusDeveloperRequestLibrary’dir. Factory ve property adları create_document, on_succeeded, operation_status ve request_id gibi snake case kullanır. Enum değerleri LocusDeveloperRequestState.NOT_STARTED ve LocusDeveloperResultCode.STALE_REVISION gibi büyük harf snake case kullanır.

Oluştur, referansları sakla, bağla, başlat

Bu sıra sözleşmenin bir parçasıdır:

Construct → Retain references → Bind → Start → Completion

Oluşturma işlemi işi göndermez. Sonlandırıcı tamamlanmaya kadar isteği, delegate wrapper’larını ve bağlı Python callable’larını saklayın. Kabul hatası satır içinde tamamlanabileceği için start() öncesinde başarı ve hata bağlarını kurun. Tamamlanmadan sonra bağları kaldırın ve bu referansları serbest bırakın.

import unreal

input_value = unreal.LocusDeveloperDocumentCreateInput(
    path="DeveloperExamples/PythonGettingStarted.md",
    markdown="# Created from Unreal Python\n",
    presentation_root=unreal.LocusDeveloperDocumentRoot.LOCUS_DOCUMENTS,
)
request = unreal.LocusDeveloperRequestLibrary.create_document(input_value)

def on_succeeded(result):
    unreal.log(f"Created {result.identity.relative_path}")
    release_bindings()

def on_failed(error):
    unreal.log_error(f"Locus failed: {error.code.name}: {error.message}")
    release_bindings()

success_delegate = request.on_succeeded
failure_delegate = request.on_failed

def release_bindings():
    success_delegate.remove_callable(on_succeeded)
    failure_delegate.remove_callable(on_failed)

success_delegate.add_callable(on_succeeded)
failure_delegate.add_callable(on_failed)

if not request.start():
    unreal.log_error("The request had already been started")

Örnek gerçek bir Belge oluşturur. Projeye uygun bir yol seçin ve mevcut kimliği türü belirlenmiş hata callback’i üzerinden işleyin.

Tamamlanmış isteği inceleme

Tamamlanmış, türü belirlenmiş istek şunları saklar:

• state ve succeeded;
• request_id;
• türü belirlenmiş result;
• türü belirlenmiş error;
• operation_status.

Ayrıca has_started() ve is_completed() sunar. Tick güdümlü inceleme geçerlidir. Yoğun yoklama döngüsü geçerli değildir; isteği tamamlaması gereken Game Thread’i engeller.

cancel() iş birliğine dayalı iptal ister. Kuyruktaki işi önleyebilir ancak depo çalışmasını kesemez veya kaydedilmiş bir değişikliği iptal edilmiş sonuca dönüştüremez.

Kısmi güncellemeler

Niyeti belirtmek için reflection sistemine açılan set_* bayraklarını kullanın:

changes = unreal.LocusDeveloperNoteChanges()

changes.set_title = False       # Leave unchanged; title is ignored.
changes.title = "ignored"

changes.set_body = True         # Set a non-empty value.
changes.body = "Updated body"

changes.set_tags = True         # Explicitly clear tags.
changes.tags = []

request = unreal.LocusDeveloperRequestLibrary.update_note(
    note_identity,
    current_revision,
    changes,
)

Python’a özgü bir None kuralı yoktur. Pin meta verisi değişiklikleri aynı açık set_title, set_description, set_pin_type ve set_tags özelliklerini kullanır.

Kullanıcı etkileşimi gerektirmeyen Editor otomasyonu

Desteklenen model, PythonScriptPlugin etkin bir Unreal Editor işlemidir:

External automation
        ↓
UnrealEditor-Cmd full Editor environment
        ↓
PythonScriptPlugin
        ↓
Unreal reflection sistemine açılan Locus istekleri

Kullanıcı etkileşimi gerektirmeyen otomasyon için desteklenen başlatma biçimi aşağıda UE 5.6 ile gösterilmiştir; UE 5.7 veya 5.8 için eşleşen Editor yürütülebilir dosyasını kullanın:

& "C:\Program Files\Epic Games\UE_5.6\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" `
  "C:\Path\To\Project.uproject" `
  "-ExecutePythonScript=C:\Path\To\Script.py" `
  -ScriptErrorsAreFatal -unattended -NullRHI -nosplash

Kullanıcı etkileşimi gerektirmeyen async betik şunları yapmalıdır:

1. unreal.EditorPythonScripting.set_keep_python_script_alive(True) çağırın;
2. unreal.register_slate_post_tick_callback(...) kaydedin;
3. Locus isteğini oluşturun, saklayın, bağlayın ve başlatın;
4. normal Editor tick’lerinin Locus’un mevcut yürütücüsünü çalıştırmasına izin verin;
5. sonlandırıcı tamamlanmayı gözlemleyip delegate bağlarını kaldırın;
6. tick callback kaydını kaldırın;
7. temiz çıkış için set_keep_python_script_alive(False) çağırın.

sleep(), dönerek bekleme, eşzamanlı future beklemesi veya elle Game Thread pompalama kullanmayın.

İşlem hattı sınırları

• Python, Unreal Editor işlemi ve PythonScriptPlugin gerektirir.
• Locus’un kendisi PythonScriptPlugin’e bağlı değildir ve eklenti devre dışıyken de yüklenir.
• Bağımsız python.exe, Locus’u içe aktaramaz.
• Pinler desteklenen, kayıtlı ve projeye ait bir dünya gerektirir.
• -run=PythonScript commandlet’i eksiksiz desteklenen ortam değildir; doğrulamada tam API için gereken kayıtlı dünya yerine geçici, kaydedilmemiş bir dünya alınmıştır.
• Gözetimsiz otomasyon için tam Editor uygulamasının -ExecutePythonScript yolunu kullanın.
• Başlangıç veya dizin uzlaştırması yeniden denenebilir Unavailable üretebilir; engellemek yerine sonraki normal Editor tick’inde yeniden gönderin.

Kimlikler, revizyonlar, hatalar, işlem durumu ve yetenek matrisi için Developer API genel bakışına bakın.