Python Developer API

지원되는 Engine 버전에서 Locus는 공유 요청 기반을 unreal 아래에 직접 노출합니다. Python은 Blueprint 비동기 작업 프록시 대신 이 요청을 사용합니다.

진입점은 unreal.LocusDeveloperRequestLibrary입니다. 팩토리와 속성 이름은 create_document, on_succeeded, operation_status, request_id처럼 snake case입니다. 열거형 값은 LocusDeveloperRequestState.NOT_STARTED 및 LocusDeveloperResultCode.STALE_REVISION처럼 대문자 snake case를 사용합니다.

생성, 보관, 바인딩, 시작

이 순서는 계약의 일부입니다.

Construct → Retain references → Bind → Start → Completion

종료 완료까지 요청, 델리게이트 래퍼 및 바인딩된 Python 호출 가능 객체에 대한 참조를 유지합니다. start() 전에 성공과 실패를 바인딩하세요. 수락 실패가 인라인으로 완료될 수 있기 때문입니다. 완료 후 바인딩을 제거하고 참조를 해제합니다.

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

이 예제는 실제 문서를 생성합니다. 프로젝트에 적합한 경로를 선택하고, 형식화된 실패 콜백을 통해 이미 존재하는 ID를 처리하세요.

완료된 요청 검사

완료된 형식화 요청은 다음을 유지합니다.

state 및 succeeded
request_id
형식화된 result
형식화된 error
operation_status

has_started() 및 is_completed()도 노출합니다. tick 기반 검사는 유효하지만 바쁜 폴링 루프는 사용하면 안 됩니다. 요청을 완료해야 하는 Game Thread를 차단하기 때문입니다.

cancel()은 협력적 취소를 요청합니다. 대기열에 있는 작업은 막을 수 있지만 리포지토리 작업을 중단하거나 이미 영속화가 확정된 변경을 취소된 결과로 바꿀 수는 없습니다.

부분 업데이트

리플렉션된 set_* 플래그를 사용해 의도를 표현합니다.

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 전용 None 규칙은 없습니다. 핀 메타데이터 변경에는 동일하게 명시적인 set_title, set_description, set_pin_type, set_tags 속성을 사용합니다.

비대화형 Editor 자동화

지원되는 모델은 PythonScriptPlugin이 활성화된 Unreal Editor 프로세스입니다.

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

지원되는 비대화형 시작 형식은 UE 5.6을 사용해 아래와 같이 표시합니다. UE 5.7 또는 5.8에는 일치하는 Editor 실행 파일을 사용하세요.

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

비동기 비대화형 스크립트는 다음을 수행해야 합니다.

unreal.EditorPythonScripting.set_keep_python_script_alive(True)를 호출합니다.
unreal.register_slate_post_tick_callback(...)을 등록합니다.
Locus 요청을 구성하고, 보관하고, 바인딩하고, 시작합니다.
일반 Editor tick이 Locus의 기존 실행기를 구동하게 합니다.
종료 완료를 관찰하고 델리게이트 바인딩을 제거합니다.
tick 콜백을 등록 해제합니다.
정상 종료를 위해 set_keep_python_script_alive(False)를 호출합니다.

sleep(), 스핀 대기, 동기 future 대기 또는 수동 Game Thread 펌핑을 사용하지 마세요.

파이프라인 제한

Python에는 Unreal Editor 프로세스와 PythonScriptPlugin이 필요합니다.
Locus 자체는 PythonScriptPlugin에 의존하지 않으며 비활성화되어도 로드됩니다.
독립 실행형 python.exe에서는 Locus를 가져올 수 없습니다.
핀에는 지원되는 저장된 프로젝트 소유 월드가 필요합니다.
-run=PythonScript commandlet은 완전한 지원 환경이 아닙니다. 검증에서는 전체 API에 필요한 저장된 월드가 아니라 일시적인 저장되지 않은 월드를 받았습니다.
비대화형 자동화에는 전체 Editor 애플리케이션의 -ExecutePythonScript 경로를 사용하세요.
시작 또는 인덱스 조정에서 재시도 가능한 Unavailable이 발생할 수 있습니다. 차단하지 말고 이후 정상 Editor tick에서 다시 제출하세요.

ID, 리비전, 오류, 작업 상태 및 기능 매트릭스는 Developer API 개요를 참조하세요.