문서

문서는 긴 형식의 프로젝트 지식을 위한 프로젝트 소유 Markdown 파일입니다. .md 파일이 항상 권위 있는 파일이며 외부 텍스트 에디터와 호환됩니다.

소유권 및 저장소

모든 문서는 <Project>/ProjectDocuments/ 아래에 있습니다. 공유 또는 개인 문서 범위는 없습니다. /Game/... 아래의 콘텐츠 브라우저 폴더는 ProjectDocuments/Content/... 아래의 해당 경로에 매핑됩니다. Developers 폴더도 프로젝트 컨텍스트이며 개인 소유권을 의미하지 않습니다.

문서는 UAsset, 패키지, 리디렉터, 런타임 오브젝트 또는 쿠킹 데이터의 소유자가 아닙니다. Locus는 Markdown을 다른 권위 형식으로 감싸지 않습니다.

Locus 문서 및 콘텐츠 브라우저 루트

문서 트리에는 하나의 물리적 리포지토리 위에 두 개의 표시 루트가 있습니다.

Locus 문서에는 예약된 Content/ 하위 트리 바깥에 저장된 일반 프로젝트 소유 문서가 들어 있습니다. 이 문서는 Locus에만 존재하며 Unreal 콘텐츠 브라우저로 프로젝션되지 않습니다.
콘텐츠 브라우저에는 권위 있는 상대 경로가 Content/로 시작하는 문서만 들어 있습니다. Locus는 트리에서 내부 저장소 접두사를 숨기므로 ProjectDocuments/Content/Blueprints/AI/Behavior.md가 콘텐츠 브라우저 > Blueprints > AI > Behavior로 표시되고 /Game/Blueprints/AI로 프로젝션됩니다.

콘텐츠 브라우저 루트는 희소하며 문서 중심입니다. 프로젝션된 Locus 문서를 직접 포함하는 폴더와 해당 폴더에 도달하는 데 필요한 상위 폴더만 표시합니다. 관련 없는 /Game 폴더를 미러링하지 않으며 파생된 표시 폴더를 제거해도 해당 Unreal 폴더를 삭제하거나 수정하지 않습니다.

프로젝션은 파일을 만든 UI가 아니라 권위 있는 상대 경로를 따릅니다. 시작 시 검색된 매핑 문서, Locus에서 만든 문서, Add > Locus > Locus 문서로 만든 문서, 가져온 문서 또는 MCP로 만든 문서는 동일한 인덱스 ID와 프로젝션 동작을 가집니다.

문서 만들기 및 찾기

Locus 전용 문서는 Locus 문서 아래에 만듭니다. 해당 /Game 컨텍스트로 프로젝션되는 매핑 문서는 콘텐츠 브라우저 아래에 만듭니다. 지원되는 콘텐츠 브라우저 폴더에서 Add > Locus > Locus 문서를 사용하면 같은 매핑 ID가 생성됩니다. Locus는 실제 외부 .md 파일을 만들고 일반 UI에서는 확장자를 숨긴 뒤 전용 에디터 탭을 엽니다. Markdown 가져오기와 MCP로 만든 문서는 동일한 로컬 추적되지 않음 생성 정책을 따릅니다.

소스 컨트롤에 추가하기 전에 새 문서를 정리하세요.

생성 → 이름 변경, 이동, 편집 → 경로가 확정되면 추가 대상으로 표시

작업 공간은 실제 폴더를 탐색하며 제목/경로 검색, 상태 필터, 새로 고침, 열기, 이름 변경, 이동, 삭제, 체크아웃, 추가 대상으로 표시, 가져오기 및 내보내기를 지원합니다. 여러 문서 탭을 동시에 열 수 있으며 이미 열린 경로를 열면 기존 탭에 포커스합니다.

가져오려면 콘텐츠 브라우저 Locus 작업을 사용하고 유효한 UTF-8 .md 파일 하나를 선택합니다. Locus는 원본 바이트와 줄 끝을 보존하며 대상이 이미 존재하면 안전한 번호가 붙은 이름을 사용합니다.

문서 도구 모음은 한 행으로 유지됩니다. 우선순위가 낮은 작업은 점진적으로 추가 작업로 이동합니다. 내보내기 및 새로 고침는 그대로 유지됩니다. 공급자가 구성되지 않은 경우 소스 제어 작업이 없습니다.

편집 및 저장

새 문서 또는 빈 문서는 편집 모드로 열리고 내용이 있는 문서는 읽기 모드로 열립니다. Ctrl+E로 편집 모드, Ctrl+R로 읽기 모드, Ctrl+S로 저장합니다. 문서는 노트처럼 자동 저장하지 않고 명시적으로 저장합니다.

소스 에디터는 제목, 강조, 인라인 및 펜스 코드, 순서 있는 목록과 순서 없는 목록, 작업 목록, 인용, 링크, 표, 가로줄, 애셋 참조 및 핀 참조 명령을 제공합니다. 분할 미리 보기는 짧은 업데이트 지연 후 현재 저장되지 않은 버퍼를 소스 옆에 표시합니다. 미리 보기를 열거나 업데이트해도 파일이 저장되지는 않습니다.

편집에서 컴팩트 도구 모음은 제목, 굵게, 기울임꼴, 인라인 코드, 순서 없는 목록, 순서 있는 목록, 외부 링크, 애셋 참조 및 핀 참조를 제공합니다. 다른 명령은 서식에 남아 있습니다. 미리 보기 분할는 저장하지 않고 짧은 디바운스 후에 소스 옆에 현재 버퍼를 렌더링합니다. 구분선, 열린 상태 및 비율은 개인 취향입니다.

읽기 모드 및 Markdown 지원

읽기 모드는 네이티브 Unreal UI를 사용합니다. 에디터 툴바에 필요한 Markdown 구문인 제목, 단락, 강조, 굵은 텍스트, 목록, 표시 전용 작업 항목, 인용, 코드, 링크, 정렬이 있는 표, 가로줄 및 취소선을 지원합니다.

Locus는 브라우저와 동일하거나 완전한 Markdown 렌더링을 보장하지 않습니다. 원시 HTML은 실행되지 않는 소스 텍스트로 유지되고 JavaScript는 실행되지 않으며 안전하지 않은 URL 스킴은 활성화되지 않고 원격 콘텐츠는 자동으로 가져오지 않습니다. HTTP 및 HTTPS 링크는 운영 체제 브라우저에서 사용자가 명시적으로 작업한 후에만 열립니다.

제목, 목록, 표가 있는 프로젝트 Markdown 문서를 읽기 모드로 표시하는 Locus 문서 에디터 — 문서는 Markdown을 소스로 유지하고 읽기 모드에서는 지원되는 구조를 네이티브 Editor UI로 표시합니다.

애셋 및 핀 참조는 표시할 때 읽기 쉬운 레이블을 사용합니다. 현재 맵의 핀은 포커스할 수 있고, 다른 맵의 핀은 자동으로 로드하지 않고 소유 레벨을 찾을 수 있습니다. 누락된 참조는 비활성 상태로 진단할 수 있게 유지됩니다.

해결된 자산, 핀, 노트, 문서 및 Actor 참조는 읽을 수 있는 레이블을 사용합니다. Actor 참조는 편집 모드에서 적격 로드된 World Outliner Actor 하나를 문서에 놓아서만 작성됩니다. 참조 삽입 또는 @에서는 제공되지 않습니다. 원시 HTML 및 JavaScript는 실행되지 않으며 원격 콘텐츠를 가져오지 않습니다.

이름 변경, 이동, 삭제

이름 변경 및 이동은 문서 루트 안에서 이루어집니다. 이름을 변경할 수 있는 추적되지 않은 문서에서는 툴바나 컨텍스트 메뉴의 이름 변경, F2, 툴바의 이동을 사용하거나 유효한 기존 폴더로 드래그할 수 있습니다. 이름 변경 또는 이동의 권위 있는 위치는 Locus 문서 작업 공간입니다. 콘텐츠 브라우저 항목은 프로젝션이며 콘텐츠 브라우저에서 직접 이름을 변경하는 것은 지원되지 않습니다.

추가 대상으로 표시한 후에는 이름 변경과 이동을 의도적으로 사용할 수 없습니다. 관리되는 문서에서도 마찬가지입니다. Locus가 제공자 중립적인 트랜잭션 소스 컨트롤 이동을 보장할 수 없기 때문입니다. 이 안전 경계는 파일 시스템 변경으로 문서와 소스 컨트롤의 동기화가 풀리는 것을 막습니다. 저장되지 않았거나 충돌 중인 문서를 열어 둔 경우에도 작업 공간의 이름 변경, 이동, 삭제가 차단됩니다.

삭제는 영구적이며 확인이 필요하고 Unreal을 통해 실행 취소할 수 없습니다. 추적된 파일의 경우 Locus가 상태를 확인한 뒤 로컬 정리 전에 활성 제공자를 통해 삭제를 전달합니다.

경로 변경은 로컬 또는 Untracked 문서에만 사용할 수 있습니다. Locus는 공급자 중립 저장소 이동을 수행하지 않거나 경로 간에 열린 상태를 전송하지 않기 때문에 추가 대상으로 표시 또는 공급자 제어 후에는 이름 바꾸기 및 이동이 비활성화됩니다.

내보내기

선택한 문서, 폴더, 모든 문서 또는 에디터 복사본을 내보낼 수 있습니다. 내보내기는 현재 소스를 유지하며 복사본을 내보낼 때 저장되지 않은 에디터 버퍼도 포함할 수 있습니다. 폴더 구조도 유지할 수 있습니다. 대상은 ProjectDocuments 안에 있을 수 없으며 충돌 시 덮어쓰기, 건너뛰기, 번호가 붙은 복사본 중에서 선택합니다. 내보내기는 원본 문서, 문서 탭 또는 소스 컨트롤 상태를 변경하지 않습니다.

복구 및 외부 편집

Locus는 문서 복구 데이터를 <Project>/Saved/Locus/Recovery/문서/ 아래에 저장합니다. 저장에 성공하면 해당 스냅샷을 제거합니다. 외부에서 변경되었지만 깨끗한 상태라면 다시 로드하고, 외부 변경이 저장되지 않은 로컬 텍스트와 충돌하면 안전한 해결을 선택할 때까지 저장을 차단합니다.

.md가 권위 있는 형식이므로 외부 에디터를 지원합니다. 외부 파일 작업 후 작업 공간이 즉시 업데이트되지 않으면 검색 결과를 새로 고칩니다. Unreal Editor를 다시 시작해도 에디터 탭은 자동으로 복원되지 않습니다.

새로운 Locus 문서는 활성 또는 가장 최근 활성 Locus 문서 탭 스택을 선호합니다. 동일한 정규화된 경로는 기존 탭에 초점을 맞춥니다. 탭은 자유롭게 도킹 가능한 상태로 유지되지만 에디터를 다시 시작한 후에는 복원되지 않습니다.

선택한 문서 미리 보기

문서를 선택하면 작업 공간 세부 정보 패널에 읽기 전용 Markdown 미리 보기가 표시됩니다. 저장된 권위 파일을 보여 주므로 내용을 읽거나 편집하려면 전용 문서 에디터를 사용하세요. 일반적인 짧은 선택 전환 중에는 선택한 콘텐츠가 준비될 때까지 미리 보기가 중립적으로 유지됩니다. 약 1초보다 오래 기다린 경우에만 오래된 콘텐츠가 아니라 간결한 네이티브 로딩 설명이 표시됩니다.

문서 파일 이름과 경로가 작업 공간 ID를 제공합니다. Markdown 제목은 콘텐츠이므로 파일 이름을 바꾸면 표시 파일 이름은 바뀌지만 # My Title 같은 제목은 다시 쓰지 않습니다.

문서 편집기 보기 메뉴에서 소스 글꼴 크기는 소스 편집기에 영향을 주고 읽기 글꼴 크기는 전체 읽기 및 분할 미리 보기에 영향을 줍니다. Ctrl+mouse wheel는 해당 뷰를 조정합니다.

소스 컨트롤

문서는 프로젝트 소유입니다. 새 문서는 추가 대상으로 표시를 명시적으로 선택할 때까지 추적되지 않음 상태이므로 경로가 바뀌는 동안 정리할 수 있습니다. 로컬 또는 추적되지 않은 문서는 로컬 모드에서 정상적으로 편집할 수 있습니다. 추가 대상으로 표시가 실패해도 유효한 Markdown이 남아 다시 시도할 수 있습니다.

기존 디포 관리 문서는 읽을 수 있지만 명시적 체크아웃이 성공할 때까지 권위 있는 편집 모드나 저장에 들어갈 수 없습니다. 문서가 깨끗하게 체크아웃되지 않았거나, 다른 사용자 또는 클라이언트가 체크아웃했거나, 오래되었거나, 제공자에서 연결 해제된 경우 Locus는 이러한 작업을 사용할 수 없게 유지합니다. 쓰기 가능 우회 방법은 제공하지 않으며 해당되는 경우 읽기 모드와 복사본 내보내기를 계속 사용할 수 있습니다.

소스 컨트롤에 다시 연결한 뒤 새로 고치면 관리 상태가 복원됩니다. 체크아웃이 성공할 때까지 문서는 읽기 전용입니다. Locus는 제출, 동기화, 체인지리스트 관리 또는 typemap 변경을 수행하지 않습니다. 소스 컨트롤, 프로젝트 영향 및 종속성, 문제 해결을 참조하세요.

구성된 공급자가 없으면 문서에는 소스 제어 관련 상태, 지침, 도구 설명 또는 작업이 표시되지 않습니다. 구성되었지만 사용할 수 없는 공급자는 알려진 제어 파일을 보호합니다.