Python Developer API

Wymaganie Unreal Engine

Interaktywny dostęp do Python Developer API i bezobsługowa automatyzacja Pythona wymagają Unreal Engine 5.6 lub nowszego. Rdzeń Locus, C++, Blueprint i MCP pozostają obsługiwane w Unreal Engine 5.4 i 5.5. Python nie jest obsługiwany w tych wersjach z powodu zweryfikowanego ograniczenia refleksji Unreal Engine w ścieżce wywołań Pythona.

W obsługiwanych wersjach Engine Locus udostępnia wspólną podstawę żądań bezpośrednio pod unreal. Python używa tych żądań zamiast proxy asynchronicznych akcji Blueprint.

Punktem wejścia jest unreal.LocusDeveloperRequestLibrary. Nazwy fabryk i właściwości używają snake case, na przykład create_document, on_succeeded, operation_status i request_id. Wartości enum używają wielkich liter w snake case, na przykład LocusDeveloperRequestState.NOT_STARTED i LocusDeveloperResultCode.STALE_REVISION.

Konstruuj, zachowaj, powiąż, uruchom

Ta kolejność jest częścią kontraktu:

Construct → Retain references → Bind → Start → Completion

Konstrukcja nie wysyła pracy. Zachowaj żądanie, opakowania delegatów i powiązane wywoływalne obiekty Pythona do czasu zakończenia terminalnego. Powiąż sukces i błąd przed start(), ponieważ błąd przyjęcia może zakończyć się synchronicznie. Po zakończeniu usuń powiązania i zwolnij te odwołania.

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")

Przykład tworzy prawdziwy Dokument. Wybierz ścieżkę odpowiednią dla projektu i obsłuż istniejącą tożsamość przez typowany callback błędu.

Inspekcja zakończonego żądania

Zakończone typowane żądanie zachowuje:

• state i succeeded;
• request_id;
• typowany result;
• typowany error;
• operation_status.

Udostępnia także has_started() i is_completed(). Inspekcja sterowana tyknięciami jest prawidłowa. Pętla intensywnego odpytywania nie jest prawidłowa, ponieważ blokuje Game Thread, który musi zakończyć żądanie.

cancel() żąda kooperacyjnego anulowania. Może zapobiec wykonaniu oczekującej pracy, ale nie może przerwać pracy repozytorium ani zamienić zatwierdzonej mutacji w anulowany wynik.

Częściowe aktualizacje

Użyj odzwierciedlonych flag set_*, aby wyrazić zamiar:

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,
)

Nie ma konwencji None właściwej tylko dla Pythona. Zmiany metadanych Pinezki używają tych samych jawnych właściwości set_title, set_description, set_pin_type i set_tags.

Bezobsługowa automatyzacja edytora

Obsługiwanym modelem jest proces Unreal Editor z włączonym PythonScriptPlugin:

External automation
        ↓
UnrealEditor-Cmd full Editor environment
        ↓
PythonScriptPlugin
        ↓
Locus reflected requests

Obsługiwany kształt uruchomienia bezobsługowego pokazano poniżej z UE 5.6; użyj pasującego pliku wykonywalnego edytora dla UE 5.7 lub 5.8:

& "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

Asynchroniczny skrypt bezobsługowy powinien:

1. wywołać unreal.EditorPythonScripting.set_keep_python_script_alive(True);
2. zarejestrować unreal.register_slate_post_tick_callback(...);
3. skonstruować, zachować, powiązać i uruchomić żądanie Locus;
4. pozwolić zwykłym tyknięciom edytora napędzać istniejący wykonawca Locus;
5. obserwować zakończenie terminalne i usunąć powiązania delegatów;
6. wyrejestrować callback tyknięcia;
7. wywołać set_keep_python_script_alive(False) w celu czystego zakończenia.

Nie używaj sleep(), aktywnego oczekiwania, synchronicznego oczekiwania na future ani ręcznego pompowania Game Thread.

Ograniczenia potoku

• Python wymaga procesu Unreal Editor i PythonScriptPlugin.
• Sam Locus nie zależy od PythonScriptPlugin i nadal ładuje się, gdy jest ono wyłączone.
• Samodzielny python.exe nie może importować Locus.
• Pinezki wymagają obsługiwanego zapisanego należącego do projektu świata.
• Commandlet -run=PythonScript nie jest kompletnym obsługiwanym środowiskiem; walidacja otrzymała przejściowy niezapisany świat zamiast zapisanego świata wymaganego przez pełne API.
• Do bezobsługowej automatyzacji używaj pełnej ścieżki -ExecutePythonScript aplikacji edytora.
• Uruchamianie lub uzgadnianie indeksu może wygenerować możliwe do ponowienia Unavailable; wyślij żądanie ponownie przy następnym zwykłym tyknięciu edytora zamiast blokować.

Zobacz Przegląd Developer API — znajdziesz tam tożsamości, rewizje, błędy, stan operacji i macierz możliwości.