Developer API

Locus Developer API를 사용하면 로컬 Unreal Editor 도구가 Locus 노트, 문서 및 핀을 사용할 수 있습니다. C++ 에디터 플러그인, Editor Utility Blueprint와 Widget, Unreal Python 스크립트 및 에디터에서 실행되는 파이프라인 자동화를 대상으로 합니다.

Your Editor tool
       ↓
Locus Developer API
       ↓
Existing Locus application

Developer 작업은 Locus UI와 동일한 검증, 리비전, 영속성, 충돌 보호, 문서 경로 규칙, 소스 컨트롤 라우팅 및 애플리케이션 수명을 사용합니다. Locus 파일을 직접 편집하지 말고 API를 사용하세요.

API 선택

표면	적합한 용도	시작 위치
Native C++	에디터 플러그인, 네이티브 도구, 고급 통합	C++ Developer API
Blueprint	Editor Utility Blueprint, Editor Utility Widget	Blueprint Developer API
Unreal Python	에디터 스크립트, 검증, 일괄 및 비대화형 자동화	Python Developer API

MCP 통합은 AI/에이전트용 별도 외부 클라이언트 표면입니다. C++, Blueprint, Python Developer 도구는 내부적으로 MCP를 사용하지 않습니다.

Engine 호환성

핵심 Locus, C++, Blueprint, MCP는 Unreal Engine 5.4–5.8에서 지원됩니다. 대화형 및 비대화형 Python Developer API에는 Unreal Engine 5.6 이상이 필요합니다.

표면	UE 5.4–5.5	UE 5.6–5.8
C++	지원	지원
Blueprint	지원	지원
Python	지원되지 않음	지원
MCP	지원	지원

현재 작업 표면

지원되는 Engine 버전에서는 선별된 16개 작업을 모두 C++, Blueprint 및 Python에서 사용할 수 있습니다.

콘텐츠	작업
노트	List, Get, Search, Create, Update, Archive
문서	List, Get, Search, Create, Update
핀	List, Get, Create, 메타데이터 Update, 댓글 Add

API는 노트 폴더 변경, 문서 이름 변경/이동/삭제, 핀 위치 변경 또는 전체 앵커 교체, 핀 뷰/표면 조작, 자동화 기능 협상 또는 변경 이벤트, 요청 기한을 의도적으로 노출하지 않습니다.

ID

노트: GUID와 명시적인 공유 또는 개인 범위.
핀: GUID와 명시적인 공유 또는 개인 범위.
문서: ProjectDocuments에 상대적인 정규화된 Markdown 경로.

문서의 표시 루트, 표시 경로, /Game/... 컨텍스트 및 절대 파일 시스템 위치는 다른 ID가 아닙니다.

문서 표시 루트

생성 요청은 하나의 구체적인 루트를 선택합니다. 제공되는 경로는 해당 표시 루트에 상대적입니다.

표시 루트	제공되는 경로	권위 있는 ID
Locus 문서	`Design/Combat.md`	`Design/Combat.md`
콘텐츠 브라우저	`Characters/Hero.md`	`Content/Characters/Hero.md`

콘텐츠 브라우저 아래에서 만들 때 Content/를 앞에 붙이지 마세요. Locus가 해당 매핑을 한 번 적용합니다.

리비전

읽기와 성공한 변경은 불투명한 리비전을 반환합니다. 업데이트 또는 보관 작업은 현재 값을 ExpectedRevision으로 제출해야 합니다.

Get → Snapshot + Revision → Update with ExpectedRevision

리비전을 파싱하거나 만들지 마세요. 결과가 StaleRevision이면 권위 있는 항목을 다시 읽고 변경을 재고합니다. Locus는 자동 재읽기나 재시도로 오래된 쓰기를 숨기지 않습니다.

오류

사람이 읽는 메시지가 아니라 형식화된 오류 코드로 분기하세요.

InvalidInput, NotFound, AlreadyExists, Conflict, StaleRevision, AccessDenied, Unsupported, Busy, Cancelled, Unavailable, ShuttingDown, OperationFailed. None은 오류가 없음을 나타냅니다.

재시도 가능한 Unavailable 쿼리는 이후 정상 Editor tick에서 다시 제출할 수 있습니다. 기다리는 동안 Game Thread를 차단하지 마세요.

성공과 소스 컨트롤 상태는 별개

성공한 로컬 변경은 로컬 영속성을 Committed로 보고하면서 Source Control을 Pending, NotConfigured, Unknown 또는 NotRequired로 보고할 수 있습니다. 이는 Locus 작업으로는 성공한 것입니다. 작업 상태는 사용자가 일반 소스 컨트롤 워크플로를 수행하는 데 필요한 제공자 중립적인 추가 정보입니다.

Locus는 변경 사항을 제출하거나 체인지리스트를 관리하지 않습니다.

신뢰 경계

C++, Blueprint, Python은 신뢰된 로컬 Editor 도구입니다. Private 범위를 명시적으로 요청하는 호출자는 현재 프로젝트의 로컬 Private 콘텐츠에 의도적으로 액세스합니다. MCP의 변경 허용 및 개인 노트 및 핀 허용 설정은 별도의 외부 클라이언트 MCP 경계를 관리하며 프로세스 내 Developer API 호출자에는 적용되지 않습니다.