# 엔티티 참조와 @

> 참조 기능은 불변의 엔티티를 기록합니다. 본문 우클릭 연결, 긴 텍스트의 @ 멘션, 자동 감지와 정식 참조의 차이를 설명합니다.

Source: https://loomworld.ai/ko/docs/references

## 참조 데이터에 보관되는 정보

프로젝트 전체에서 단 하나의 참조 문법을 사용합니다. 하나의 참조에는 프로토콜 버전, 유효 범위(Scope), 객체 유형, 고유 ID(Stable ID), 표시 텍스트가 저장됩니다. 따라서 "이것이 누구를 가리키는가"는 각본, 세계관 설정, 타임라인, 복선 및 어시스턴트 메시지 전반에서 항상 동일한 답을 갖습니다. 화면마다 서로 다른 다섯 가지 방언을 익힐 필요가 없습니다.

객체의 이름을 변경하더라도 모든 참조는 원래의 카드를 계속 가리킵니다. 동명 객체는 유형과 고유 ID로 명확히 구분되며, 별칭(Alias)은 검색을 도울 뿐 결코 객체의 고유 식별자가 되지 않습니다. 프로젝트에 인물 "월화"와 세계관 설정 "월화"가 동시에 존재하더라도, 후보 목록에는 서로 다른 유형으로 표시되어 잘못 연결될 염려가 없습니다.

## 참조를 생성해야 하는 시점

본문의 텍스트가 프로젝트에 실제로 존재하는 특정 카드를 가리키고 있을 때 생성합니다. 참조의 가치는 단어에 색을 입히는 데 있지 않습니다. 작가와 AI 모두 "여기서 말하는 대상이 어느 카드인가"를 명확히 아는 데 있습니다. 그래야 이어 쓰기 시 정확한 자료가 조합되고, 통계 집계 시 올바르게 귀속되며, 클릭 한 번으로 해당 카드로 바로 이동할 수 있습니다. 반대로, 아직 정리되지 않았거나 지나가는 말로 가볍게 언급된 대상은 굳이 연결할 필요가 없습니다.

## 각본 본문에서: 우클릭 메뉴 "Connect to…"(연결)

본문 텍스트를 드래그하여 선택한 뒤 우클릭합니다. 메뉴의 상단에는 Rewrite / Expand / Condense / Polish(개작 / 확장 / 축약 / 윤문)와 추가 지시어 입력창이 위치하며, 하단에는 "Connect to…"(연결)가 자리합니다. 이 검색창을 통해 인물, 장소, 소품, 세계관 설정, 챕터, 씬, 시공간 설정, 각본 행, 타임라인 항목, 복선, 모듈 입구 등 프로젝트의 모든 항목을 검색할 수 있습니다. 연결 가능한 대상이 없으면 "연결 가능한 대상 없음"으로 표시되며, 검색어에 일치하는 결과가 없으면 검색 결과가 없다는 안내가 나타납니다.

새로운 카드를 생성하려는 경우, 목록에서 "+ Create character…"(+ 인물 생성) 및 "+ Create item…"(+ 소품 생성)과 같은 명시적인 생성 및 연결 항목을 선택할 수 있습니다. 이는 시스템의 임의 추측이 아닌, 사용자가 직접 내린 명확한 결정입니다.

## 긴 텍스트 본문에서: @ 멘션의 두 가지 경로

- **2단계 선택**세계관 설정 설명, 복선 메모, 타임라인 설명 등 긴 텍스트 입력창에서 `@`를 입력하고 카테고리(인물 / 장소 및 지도 / 소품 / 세계관 설정 / 각본 구조 / 타임라인 / 복선 / 모듈 입구)를 선택한 다음, 구체적인 대상을 지정합니다. 카테고리 내의 후보 목록은 도중에 잘리지 않으므로 전체를 스크롤하여 확인하거나 계속 입력하여 필터링할 수 있습니다.

- **직접 검색**이름을 이미 알고 있다면 @키워드를 바로 입력하여 모든 유형을 한 번에 검색할 수 있습니다. 두 경로 모두 최종적으로 동일한 고유 참조를 기록합니다.

- **본문 내 즉시 표시**대상을 선택하면 입력한 위치에 식별 가능한 태그 형태로 즉시 삽입되며, 클릭 시 해당 카드로 이동합니다. 아래에 별도의 미리보기 상자가 추가로 열리지 않습니다.

검색은 정식 명칭과 별칭을 모두 지원하며, 완전 일치 항목이 접두사 및 부분 일치 항목보다 우선적으로 표시됩니다. 이름과 소속 경로는 구분되어 매칭되므로, 특정 씬의 제목을 검색하더라도 해당 씬 내부의 모든 각본 본문 행이 결과로 쏟아져 나오지 않습니다.

## 참조 연결 후 나타나는 효과

- 각본 내의 인물, 소품, 장소 연결은 기존의 등장 횟수 및 사용 빈도 통계에 지속적으로 반영됩니다. 그 외의 대상은 빠른 이동과 AI의 맥락 파악을 돕는 정보성 링크이며 대상 모듈을 역으로 변경하지 않습니다.
- 참조를 생성한다고 해서 존재하지 않는 카드가 자동으로 생성되지 않으며, 모듈 입구를 참조했다고 해서 모듈 전체 데이터가 AI 컨텍스트에 한꺼번에 쏟아져 들어가지도 않습니다. 모듈 참조는 순수한 네비게이션 역할을 합니다.
- 참조 자체는 어떠한 쓰기 권한도 부여하지 않습니다. AI의 모든 수정 작업은 예외 없이 제안 카드의 승인 절차를 거칩니다.

## 자동 감지와 정식 참조의 구별

에디터는 본문에서 인물, 장소, 소품, 세계관 설정의 명칭을 자동으로 인식하지만, 매우 옅은 점선 밑줄로만 표시합니다. 마우스를 올리면 일반 선택 영역보다 옅은 배경색이 표시되며, 클릭하더라도 상세 창이 바로 열리지 않습니다. 인물과 소품의 경우 클릭 시 \"turn into a link\"(링크로 전환) 옵션이 제공되며, 이를 확인해야 비로소 정식 참조로 등록됩니다. 화자 행은 이미 발언자가 명시되어 있으므로 이 인식 단계를 건너뜁니다.

정식으로 연결된 참조만이 통계 집계와 AI 자료 조합에 반영됩니다. 옅은 점선 표시는 \"이곳에 언급되었을 수 있음\"을 알려주는 가벼운 안내일 뿐입니다.

## 제한 사항 및 문제 해결

- 기존의 [[이름]] 문법과 이전 버전의 인물/소품 표기법도 정상적으로 읽어옵니다. 이전 명칭이 단 하나의 객체와 대응될 때는 문제없이 표시되며, 동명 다의 객체가 존재할 경우 임의로 첫 번째를 선택하지 않고 모호함 플래그를 표시합니다. 대상 객체를 찾을 수 없는 경우 유효하지 않음으로 표시됩니다.
- 객체가 삭제된 후에도 참조에는 원래의 표시 텍스트가 그대로 유지되며, 다른 내용으로 임의 대체되지 않습니다.
- 이번 버전에서는 프로젝트 간 교차 참조를 지원하지 않습니다. 다른 프로젝트로 데이터를 이동하려면 프로젝트 팩을 활용해 내보내고 가져오시기 바랍니다.
- 입력 필드 안에서 Tab 키를 눌러도 각본의 유형 메뉴가 열리지 않습니다. 이는 일반 입력 필드의 고유한 동작 방식입니다.

연동 방향과 파급 효과에 관한 자세한 내용은 [모듈 간 연동](https://loomworld.ai/ko/docs/cross-sync) 문서를 참고하시기 바랍니다.