캐릭터 제작 가이드

📖 개요

Reluv 캐릭터 에디터의 전체 구조와 제작 흐름을 이해합니다.

Reluv 캐릭터 에디터는 7개의 탭으로 구성된 종합 제작 도구입니다. 각 탭은 캐릭터의 서로 다른 측면을 담당합니다.

🚀 빠른 시작

5분 안에 첫 번째 캐릭터를 만들어보세요.

🖥️ 에디터 구조

에디터 화면의 각 영역을 이해합니다.

👤 프로필 탭

캐릭터의 기본 정보와 외형을 설정합니다.

캐릭터 이름

캐릭터의 이름을 입력합니다. 채팅에서 {{char}} 토큰으로 치환됩니다.

최대 50자 필수

썸네일

캐릭터를 대표하는 이미지를 업로드합니다. 카드 목록·상세·채팅 화면 등 곳곳에 노출되므로 첫인상을 결정하는 가장 중요한 에셋입니다.

• 지원 형식: PNG, JPG, WEBP, GIF
• 최대 크기: 15MB
• 권장 비율: 1:1 (정사각형)
• 정적 이미지는 업로드 시 자동 크롭 다이얼로그가 표시됩니다
• 애니메이션 GIF/WebP는 크롭 없이 바로 적용됩니다

한줄 소개 (Tagline)

캐릭터를 한 줄로 설명합니다. 카드 목록에서 이름 아래에 표시됩니다.

최대 100자

태그

캐릭터를 설명하는 태그를 선택합니다. 장르·성향·종족·설정 등이 모두 통합된 태그 라이브러리에서 골라 사용합니다.

최대 10개

태그 선택 버튼을 누르면 카테고리별로 분류된 태그 목록이 다이얼로그로 열립니다. 카테고리는 운영 설정에 따라 다를 수 있으며, 예시는 다음과 같습니다.

성인 컨텐츠

성인 컨텐츠가 포함된 경우 토글을 활성화합니다. 활성화 시 성인 심사를 거칩니다.

💬 시작설정 탭

캐릭터의 시작 상황(시나리오)과 사용 안내를 작성합니다.

시작 상황 (Start Scenarios)

하나의 캐릭터에 여러 개의 시작 상황을 만들 수 있습니다. 각 시작 상황은 제목 · 설명 · 시작 대사로 구성되며, 사용자는 캐릭터 상세 페이지에서 시작 상황을 골라 대화를 시작합니다.

최대 20개 (운영 설정)

시작 상황 항목 구성

*{{char}}이(가) 카페 구석 자리에서 고개를 들어 당신을 바라본다.*

"어, {{user}}? 진짜 왔네. 솔직히 안 올 줄 알았는데."

*커피잔을 가볍게 밀어내며 맞은편 자리를 턱짓한다.*

{{image::1}}

"뭐, 앉아. 할 얘기가 좀 있거든."

플레이 가이드

사용자에게 이 캐릭터와 어떻게 대화하면 좋은지 안내하는 텍스트입니다.

마크다운 지원

플레이 가이드는 기본 마크다운 문법을 지원합니다. 긴 안내문을 구조적으로 쓰고 싶을 때 활용하세요.

# 카페 주인 시아와의 대화

**시아**는 말이 많지 않고 눈치가 빠른 편이에요.
단답형 질문보다는 **상황을 묘사하며 말 거는 방식**을 좋아합니다.

## 추천 대화 스타일

- 커피를 주문하면서 이야기를 시작해 보세요
- 시아가 먼저 질문하면 구체적으로 답하는 것이 좋습니다
- 긴 독백보다 짧은 대사가 어울립니다

## 피하면 좋은 것

1. 갑자기 반말로 돌리는 것
2. 무관심한 답변 ("응", "아니" 등)
3. 시아의 과거를 먼저 캐묻는 것

> 천천히 가까워지는 과정을 즐기세요.

최대 2,000자 (운영 설정)

🧠 프롬프트 탭

캐릭터의 핵심 정체성과 대화 스타일을 정의합니다. 캐릭터 프롬프트와 예시 대화가 AI가 캐릭터처럼 말하는 데 가장 큰 영향을 미칩니다.

상세 설정 (캐릭터 프롬프트)

캐릭터의 핵심 성격·외형·배경·말투를 정의하는 가장 중요한 필드입니다. AI가 캐릭터로서 응답할 때 항상 참조합니다. AI가 알아야 할 모든 정보를 자유롭게 기입하세요.

상세 설정 + 추가 형식·지시 합산 15,000자 (운영 설정) 핵심

추가 형식 및 지시 (Post-History Instructions)

대화 맥락 뒤에 덧붙는 형식·출력 지시 영역입니다. 상세 설정과 함께 합산되어 글자 수 한도(promptCombined)에 포함됩니다.

예시 대화 (Example Dialogues)

AI에게 캐릭터의 대화 스타일과 말투를 학습시키기 위한 짧은 대화 예시입니다. AI는 여기서 캐릭터의 반응 패턴과 어휘 습관을 참고합니다. 실제 채팅창에는 직접 노출되지 않습니다.

최대 5개 · 각 대화당 200 토큰 (운영 설정)

대화 1 — 가벼운 인사
{{user}}: 오늘 뭐 했어?
{{char}}: *어깨를 으쓱한다* 별거 없어. 너는?

대화 2 — 고민 상담
{{user}}: 나 요즘 너무 지쳐...
{{char}}: *잠시 말없이 바라보다가 조용히 손을 잡는다* 무리하지 마. 내가 여기 있잖아.

대화 3 — 장난스러운 반응
{{user}}: 너 귀여운 거 알아?
{{char}}: *볼이 붉어진다* ...그런 거 아니거든.

📚 로어북 탭

캐릭터의 배경 지식과 세계관을 키워드 기반으로 관리합니다.

로어북은 대화에서 특정 키워드가 언급되면 관련 정보를 AI에게 자동으로 주입하는 시스템입니다. 캐릭터의 방대한 세계관이나 복잡한 배경 설정을 메인 프롬프트에 모두 담지 않고 필요할 때만 꺼내 쓰는 방식으로 토큰을 아낄 수 있습니다.

전체 제한

위 값은 운영 설정에 따라 달라질 수 있습니다. 에디터의 실시간 카운터가 우선입니다.

항목 구조

활성화 방식

로어북 항목이 프롬프트에 주입되는 경로는 세 가지입니다.

우선순위 동작

로어북 시스템은 다음 순서로 항목을 처리합니다.

1. 우선순위 내림차순 정렬 — 값이 큰 항목이 맨 앞
2. 토큰 예산 누적 — 앞에서부터 순서대로 예산에 포함. 초과하는 항목은 제외
3. 최종 배치 — 살아남은 항목들이 우선순위 순서대로 프롬프트에 주입

로어북 활용 예시

주요 키워드: 미나, 언니
보조 키워드: 가족
선택적: ON (미나 + 가족 두 키워드가 모두 언급될 때만 활성)
우선순위: 100
지속 턴: 3  (미나 얘기가 시작되면 3턴 유지)
내용: 미나는 {{char}}의 친언니. 26세, 회사원.
동생인 {{char}}을 매우 아끼지만, 과보호하는 경향이 있다.
현재 {{char}}이 집을 나온 것에 대해 걱정하고 있다.

주요 키워드: 카페, 루나, 단골
우선순위: 80  (생략되어도 대화에 큰 지장 없음)
내용: '카페 루나'는 {{char}}의 단골 카페. 대학 근처 골목에 위치.
아메리카노를 항상 주문하며, 창가 자리를 선호한다.
바리스타 진수와는 안면이 있다.

항상 활성화: ON
우선순위: 200  (예산 초과 시에도 반드시 유지)
내용: 이 세계에서 마법은 존재하지 않는다.
현실 기반의 현대 한국 서울 배경.
초자연적 현상에 대한 언급은 비유나 농담으로만 허용.

내 로어북 라이브러리

로어북 탭 우측 상단의 "내 로어북" 버튼으로, 현재 로어북에서 엔트리를 골라 저장하거나 저장해 둔 로어북을 가져오기할 수 있습니다. (자세한 내용은 라이브러리 섹션)

🖼️ 에셋 탭

캐릭터의 이미지를 그룹으로 묶어 관리합니다. 그룹별 코드:설명으로 정리하면, AI가 상황에 맞는 이미지를 자동으로 선택해 대화에 표시합니다.

화면 구성 — 그룹 관리 ↔ 앨범

에셋 탭은 좌우로 분리되어 있습니다.

이미지 등록 — 드래그&드롭 / 파일 선택

🪄 드래그&드롭 업로드 (권장)

• 그룹이 없을 때 — 파일명을 분석해 그룹을 만들고 이미지를 자동 분류합니다.
• 특정 그룹을 선택한 상태 — 그 그룹에 바로 추가됩니다(왼쪽 그룹 창에 떨어뜨리면 항상 자동 분류).
• 같은 이름의 이미지가 이미 있으면 건너뜁니다(중복 방지).
• 드래그 시 하이라이트 박스가 활성화되어 드롭 영역을 안내합니다.

📁 파일 선택 업로드

그룹의 + 이미지 추가 또는 업로드 버튼으로 파일 선택 다이얼로그를 열어 한 번에 여러 장을 올릴 수 있습니다.

그룹 관리

그룹은 이미지를 분류하는 단위입니다. 좌측 그룹 창에서 관리합니다.

앨범 — 이미지 카드

선택한 그룹의 이미지가 카드로 표시됩니다. 각 카드는 다음을 제공합니다.

🧰 일괄 작업

그룹 헤더의 전체 선택 후, 선택한 이미지들을 한 번에 처리합니다.

• 일괄 잠금/해제 · 일괄 공개/비공개
• 일괄 그룹 이동 · 일괄 삭제

설명 — 코드:설명 & 자동 프롬프트

이미지의 설명은 AI가 어떤 이미지인지 이해하는 핵심입니다. 등록된 그룹·코드·설명으로 StageCue 프롬프트가 자동 생성됩니다.

설명 편집 — 설정집(자주 쓰는 설명)

설명 입력창 옆 "설명 추가" 버튼을 누르면 설정집 피커가 열립니다. 감정·상황·배경 등 자주 쓰는 단어를 골라 설명에 빠르게 넣을 수 있고, 나만의 설정집을 직접 꾸밀 수 있습니다.

피커 사용법

• 선택된 설명(상단 고정) — 현재 이미지 설명에 들어간 단어가 표시됩니다. 클릭하면 제거.
• 설명 검색(고정) — 단어를 검색해 빠르게 찾기.
• 사용 가능한 설명(스크롤) — 카테고리별로 단어가 정렬됩니다. 클릭하면 설명에 삽입(선택 순서 유지).
• 각 카테고리 끝의 + 설명 추가 / 목록 하단의 + 카테고리 추가로 인라인 입력 → 새 설명/카테고리 생성.
• 라이브러리에 없는 단어가 설명에 있으면 상황 카테고리에 함께 표시됩니다.

관리 모드 — 수정 · 삭제 · 카테고리 이동

• 우상단 관리 토글 → 각 항목의 라벨 수정, 카테고리 이동(드롭다운), 삭제.
• 드래그&드롭 — 설명 배지를 다른 카테고리로 끌어 이동, 드래그 중 우측에 나타나는 삭제 영역에 놓으면 삭제.
• 기본 단어도 내 설정집 복사본이라 자유롭게 수정/삭제/이동됩니다.

외부 URL & 라이브러리

• 외부 URL 모드 — 직접 업로드 대신 외부 이미지 URL을 사용할 수 있습니다. 외부 이미지 출력 규칙·코드 안내는 프롬프트 탭의 추가 형식 및 지시에 작성하세요.
• 내 에셋 라이브러리 — 자주 쓰는 그룹/이미지를 라이브러리로 저장해 두고, 다른 카드에서 가져오기할 수 있습니다. (자세한 내용은 라이브러리 섹션)

이미지 속성 요약

NSFW 자동 감지 & 배지

NSFW 배지가 붙으면 어떻게 되나요?

• 제작자 확인 요청: 배지가 붙은 이미지가 있는 채로 등록하면, 성인 컨텐츠 토글을 켰는지 한 번 더 확인하라는 안내가 나타납니다.
• 심사 우선순위: 심사 담당자가 해당 이미지를 먼저 검토합니다.
• 카테고리 제한: 캐릭터가 "청소년 이용 가능"으로 등록되어 있다면, NSFW 이미지는 공개가 차단됩니다.
• 오탐(False Positive): 수영복·운동복 같은 일반 노출이 NSFW로 감지되는 경우가 있습니다. 이때는 이미지 가이드라인을 참고해 해당 이미지가 실제로 허용 범위인지 확인하고, 필요하면 정상으로 판정되도록 검토 요청을 제출할 수 있습니다.

이미지 가이드라인

Reluv에 업로드하는 모든 이미지는 아래 가이드라인을 따라야 합니다. 청소년 이용 가능(safety) 콘텐츠와 성인(unsafety) 콘텐츠 각각 허용 기준이 다르며, 어느 쪽에서도 허용되지 않는 금지 항목이 있습니다.

공통 원칙

• 불쾌감을 주는 이미지는 허용되지 않습니다. 폭력, 혐오, 차별적 표현이 포함된 이미지는 모든 카테고리에서 금지됩니다.
• 실사/실존 인물 이미지 표시: 실사로 제작된 이미지이거나 실존 인물로 판단될 수 있는 이미지는, 캐릭터 설명 또는 이미지 안에 AI로 제작된 이미지임이 명확히 표시되어 있어야 합니다.
• 미성년자 표현 금지: 카테고리와 무관하게 모든 등장 인물은 19세 이상 성인이어야 합니다. 설정상 성인이더라도 외형이 어려 보이면 동일하게 제한됩니다.

📗 청소년 이용 가능 (Safety) 콘텐츠

대표 이미지와 앨범 이미지 모두 이 기준을 따릅니다.

• 캐릭터의 성적 행위, 성적 암시를 포함한 모든 표현은 허용되지 않습니다.
• 표정·자세 등으로 성적 요소를 유추할 수 있는 경우도 포함됩니다.

판단 기준은 얼굴 / 체형 / 분위기 / 복장 등을 종합적으로 고려합니다. 단순 노출이 아닌 성적 의도 및 연출을 중심으로 판단합니다.

📕 청소년 이용 불가 (Unsafety) 콘텐츠

🖼️ 대표 이미지 가이드

프로필 탭에서 등록하는 캐릭터 썸네일과, 앨범의 대표로 지정된 이미지에 적용됩니다.

• 다른 사용자에게 불쾌감을 줄 수 있는 내용은 허용되지 않습니다.
• 실사/실존 인물로 오인될 수 있는 이미지는 AI 제작 표시가 필요합니다.
• 이미지 내 캐릭터가 미성년자로 보일 수 있는 경우 제한됩니다. 설정상 성인이더라도 외형이 어려 보이면 동일 적용됩니다.
• 성관계 등 표현 수위가 높은 요소는 허용되지 않습니다.

허용 불가 수위 판단 기준

📷 앨범 이미지 가이드

앨범 갤러리에 표시되는 일반 에셋 이미지에 적용됩니다. 대표 이미지와 공통 원칙을 따르면서, 다음 추가 규정이 있습니다.

• 실사/실존 인물로 오인될 수 있는 이미지는 AI 제작 표시 필요
• 이미지 내 캐릭터가 미성년자로 보이면 제한 (외형 기준)
• 성기·음모·항문·성기 내부 및 인접부 가림 처리가 되어 있지 않은 경우 허용되지 않습니다.
• 실사 캐릭터 움직임 기반 이미지에서 성관계나 과도한 스킨십 표현은 허용되지 않습니다.

가림 처리 상세 규정

🧸 성인 용품 이미지 가이드

🐙 촉수 이미지 가림 처리 가이드

캐릭터 이미지에서 촉수 표현이 성기로 오인되는 사례가 보고되고 있습니다. 다음 기준 중 하나라도 해당하면 가림 처리 대상이 됩니다.

가림 처리 범위: 삽입·접촉이 일어나는 접점 부위부터 성기로 인식되는 시점까지 가림 처리가 필요합니다.

⚡ 인터랙션 탭

스탯, 위젯, AI 호출 추출로 동적인 캐릭터 경험을 만듭니다.

인터랙션 시스템은 Reluv의 가장 강력한 기능입니다. 단순한 텍스트 채팅을 넘어, 게임적 요소와 비주얼 UI를 갖춘 인터랙티브 캐릭터를 만들 수 있습니다.

스탯 (Stats)

캐릭터의 상태를 저장하는 데이터입니다. HP, 호감도, 인벤토리 등 다양한 값을 관리할 수 있습니다.

스탯 타입

제어 주체 (쓰기 권한)

누가 이 스탯의 값을 바꿀 수 있는지 지정합니다. 선택에 따라 AI가 스탯을 관리할지, 사용자가 UI로 직접 조작할지 결정됩니다.

숫자 스탯 검증 & 단계(Stages)

number 타입에는 추가 옵션이 있습니다:

• min / max — 허용 범위 설정 (예: HP는 0~100)
• max_delta — 한 번에 변경 가능한 최대량 (예: HP가 한 턴에 20 이상 감소하지 않도록)
• 단계(Stages) — 값 구간별 라벨 + AI 지시사항(예: 0~30 "경계", 31~70 "보통", 71~100 "호의적")으로 상태에 따른 행동을 안내

위젯 (Widgets)

변수 값을 시각적으로 표현하는 UI 컴포넌트입니다. 채팅 화면에서 상태창, 선택지, 정보 패널 등으로 렌더링됩니다.

표시 위치

위젯을 어디에 표시할지 선택합니다. 위치마다 적합한 용도가 다릅니다.

표시 위치마다 카드 당 허용 개수가 다릅니다. 사이드 1개, 선택지 1개, 시작 1개, 에셋 1개, 정보창 3개, 수동 5개가 일반적인 기본값입니다.

편집 모드 — HTML / JSX 2-way

위젯 편집기 상단의 HTML | JSX 토글로 작성 방식을 고릅니다. 한 위젯은 둘 중 한 모드만 실제 렌더에 사용되고, 다른 모드의 내용은 초안으로 보존됩니다.

기본 제공 템플릿

인터랙션 탭의 템플릿 서브탭에서 아래 템플릿을 바로 적용할 수 있습니다. 적용하면 필요한 변수와 위젯이 자동으로 생성됩니다.

AI 호출 추출

AI의 응답에서 특정 값을 뽑아내 변수에 반영하는 규칙입니다. 예를 들어 "감정을 기쁨으로 표시" 같은 응답을 감지해 emotion 변수를 업데이트할 수 있습니다.

추출 규칙 구조

응답 끝에 현재 감정 상태를 다음 형식으로 표시하세요:
[감정: 기쁨|슬픔|분노|두려움|놀람|평온]

\[감정:\s*(기쁨|슬픔|분노|두려움|놀람|평온)\]

전투가 발생하면 응답 끝에 다음 형식으로 표시:
[HP변동: +N 또는 -N]

\[HP변동:\s*([+-]?\d+)\]

🌐 공개설정 탭

캐릭터의 공개 범위와 상태를 관리합니다.

공개 범위

캐릭터를 누구에게 보여줄지 결정합니다. 언제든 변경할 수 있습니다.

카드 상태 흐름

• 초안 — 작성 중인 상태. 본인만 볼 수 있고 언제든 수정 가능합니다.
• 심사 대기 — 공개 요청을 제출한 상태. 운영진이 가이드라인 위반 여부를 검토합니다.
• 공개됨 — 심사 통과 후 실제로 공개된 상태. 다른 사용자에게 노출됩니다.
• 공개된 카드를 더 이상 노출하고 싶지 않다면 공개 범위를 "비공개"로 변경해 숨기거나, 카드를 삭제하면 됩니다.

캐릭터 상세 소개

카드 상세 페이지 상단에 표시되는 긴 형식의 소개 글입니다. 캐릭터의 배경, 세계관, 플레이 방식, 주의사항 등 사용자가 대화를 시작하기 전 알아야 할 내용을 자유롭게 작성하세요.

마크다운 문법 지원

기본적인 마크다운 문법이 지원됩니다. 플레이 가이드와 동일한 문법을 사용합니다.

수동 위젯 삽입

인터랙션 탭에서 만든 수동 위젯을 캐릭터 상세 소개 안에 삽입할 수 있습니다. 각 위젯 편집기의 "코드 복사" 버튼으로 토큰을 얻은 뒤 본문의 원하는 위치에 붙여넣으세요.

# 🗡️ 모험가 한별

판타지 세계의 신참 모험가와 함께 던전을 탐험하세요!

{{widget::hero_intro_card}}

## 캐릭터 특징

- **직업:** 검사 지망생
- **성격:** 밝고 열정적이지만 가끔 무모함
- **좋아하는 것:** 달콤한 디저트, 강한 상대와의 훈련

## 플레이 팁

당신의 선택이 스토리의 결말을 바꿉니다.
신중하게 대답하면 한별은 진지하게 받아주지만,
무례하게 대하면 바로 토라지니 주의하세요.

> *"함께 가자, 모험의 끝까지."*

📦 라이브러리 (내 로어북 · 에셋 · 위젯)

자주 쓰는 로어북 · 에셋 · 위젯을 라이브러리로 저장해 두고, 다른 캐릭터를 만들 때 가져와 재사용합니다.

어디서 관리하나요?

• 등록(저장) — 카드 편집창의 각 탭(로어북/에셋/위젯)에서 "내 로어북 / 내 에셋 / 내 위젯" 버튼으로 현재 항목을 라이브러리에 저장합니다.
• 관리 — 제작(generate) 페이지의 내 로어북 · 내 에셋 · 내 위젯 탭에서 목록 확인 · 이름 변경 · 삭제 · 미리보기를 합니다.
• 라이브러리는 내 전용(비공개)이며 모든 카드에서 재사용됩니다.

항목별 선택 저장 / 가져오기

저장·가져오기 모두 필요한 항목만 체크해서 처리합니다.

미리보기

• 내 로어북 — 엔트리 목록(이름·키워드·활성 조건·본문)을 정돈된 카드로 미리보기.
• 내 에셋 — 그룹별 앨범 팝업(코드·대표·잠금 표시 + 라이트박스).
• 내 위젯 — 위젯을 실제로 렌더해서 확인(스탯 기본값 적용).

🔧 스탯 심화 가이드

효과적인 변수 설계 패턴과 고급 사용법을 알아봅니다.

스탯 네이밍 규칙

스탯 이름은 한글·영문자·숫자·언더스코어(_)를 사용할 수 있습니다. 한글 이름도 지원합니다(예: 호감도, 현재위치). HTML 위젯에서는 {{스탯명}}으로 값을 참조합니다.

✅ 좋은 예: hp, max_hp, 호감도, 현재위치, is_first_meet
❌ 나쁜 예: my-hp (하이픈), current location (공백), a|b (특수문자)

스탯 설계 패턴

아래 예시의 스탯들은 모두 AI 제어 권한입니다. 사용자가 직접 바꾸지 않고 AI가 내러티브 흐름에 맞춰 업데이트합니다.

hp        (number) — 현재 체력 [0~100, 한 번에 최대 30 변경]
mp        (number) — 현재 마나 [0~50, 한 번에 최대 20 변경]
gold      (number) — 소지금
level     (number) — 레벨 [1~99]
location  (string) — 현재 위치
inventory (string[]) — 보유 아이템
quest     (string) — 현재 퀘스트

affection    (number) — 호감도 [0~100, 한 번에 최대 10 변경]
trust        (number) — 신뢰도 [0~100, 한 번에 최대 5 변경]
mood         (string) — 현재 기분
relationship (string) — 관계 단계
date_count   (number) — 데이트 횟수
secrets_shared (string[]) — 공유한 비밀들

clues      (string[]) — 수집한 단서
suspects   (string[]) — 용의자 목록
location   (string) — 현재 조사 장소
trust_npc  (object) — NPC별 신뢰도
time_phase (string) — 시간대 (아침/낮/밤)
case_progress (number) — 사건 진행도 [0~100]

단계(Stages) 설정

number 타입 스탯에는 단계를 설정할 수 있습니다. 값의 구간마다 라벨과 AI 지시사항을 부여하면, AI가 현재 값이 속한 단계에 맞춰 행동·말투·태도를 조정합니다. (예: 호감도가 낮으면 경계, 높으면 호의적)

단계 구성

스탯: 호감도 (number) — AI 제어, 범위 0~100

단계:
  ┌ 라벨: 경계    | 상한 30  | AI 지시: 차갑고 거리를 둔다. 짧게 답하고 사적인 질문을 피한다.
  ├ 라벨: 보통    | 상한 70  | AI 지시: 무난하게 대한다. 가끔 농담을 섞는다.
  └ 라벨: 호의적  | 상한 100 | AI 지시: 다정하게 대한다. 먼저 말을 걸고 호감을 드러낸다.

AI 쓰기 변수의 설명문 작성법

AI 쓰기 권한 변수의 설명(description)은 매 응답마다 AI에게 전달되는 설명입니다. AI는 이 설명을 보고 "이 변수는 어떤 값을 넣어야 하는지"를 판단합니다.

각 스탯 설명 500자 (운영 설정)

작성 원칙

• 가능한 값의 범위를 명시: number는 min/max, string은 허용 값 나열, boolean은 true/false 판정 기준
• 언제 값을 바꿀지 조건 명시: "어떤 행동/이벤트에서" 값이 변경되는지 구체적으로
• 얼마만큼 바꿀지 크기 명시: 한 번에 증감할 수 있는 수치나 추가/제거 규칙
• 배열(string[])은 전체 배열로 전달: AI는 변경된 전체 배열을 한 번에 보내야 합니다. "추가"/"제거"라는 표현을 쓰되, 결과는 최종 배열임을 명시

실전 예시 — 숫자 변수

이름: affection
타입: number
기본값: 50
validation: { min: 0, max: 100 }
writable: AI 쓰기

{{user}}에 대한 캐릭터의 호감도. 0~100.

증가:
- 친절한 말·배려: +3~5
- 선물/도움: +5~10
- 좋아하는 주제 공감: +5

감소:
- 무례·비꼼: -5~10
- 약속 위반·무시: -10~15
- 배신·편들기: -15~20

값이 실제로 변할 때만 갱신, 아니면 현재 값 유지.

실전 예시 — 문자열 변수 (허용 값 고정)

이름: location
타입: string
기본값: "집"
validation: { allowed_values: ["집", "학교", "카페", "공원", "도서관", "편의점"] }
writable: AI 쓰기

캐릭터의 현재 위치. 다음 중 하나만 사용:
"집", "학교", "카페", "공원", "도서관", "편의점"

캐릭터가 장면 전환이나 이동을 명시할 때마다 업데이트.
이동 중간 상태("이동 중")는 사용하지 말 것 — 반드시
목적지에 도착한 뒤 그 위치로 설정.

값을 변경할 때는 응답 본문에도 자연스러운 이동 묘사를
함께 포함할 것.

실전 예시 — 배열 변수 (가장 까다로움)

이름: inventory
타입: string[]
기본값: []
writable: AI 쓰기

캐릭터의 현재 보유 아이템 목록.

중요: 항상 전체 배열을 그대로 전달.
["검"]에서 "포션" 획득 → ["검","포션"].

허용 아이템 (정확히 이 이름만):
- "검","방패","활","지팡이"
- "빨간 포션","파란 포션","해독제"
- "열쇠","두루마리","보석","금화"

규칙:
- 획득: 배열에 추가
- 사용/분실: 배열에서 제거
- 중복 불가, 최대 15개

실전 예시 — 불리언 변수

이름: is_revealed_secret
타입: boolean
기본값: false
writable: AI 쓰기

캐릭터가 자신의 비밀(과거 사고 이야기)을 {{user}}에게
공개했는지 여부.

true로 바꾸는 조건:
- 호감도(affection)가 80 이상이고
- {{user}}가 캐릭터에게 진지하게 과거를 물어보거나
- 캐릭터가 술에 취해 무의식적으로 언급했을 때

한번 true가 되면 이후 응답에서 다시 false로 돌리지 말 것.

🏗️ 위젯 심화 - 비주얼 모드

코딩 없이 트리 빌더로 위젯을 구성하는 모든 방법을 알아봅니다. 대부분의 위젯은 이 모드에서 완성됩니다.

컨테이너 노드

레이아웃을 구성하는 컨테이너입니다. 다른 노드를 담는 그릇 역할을 합니다.

컴포넌트 노드 — 표시

실제 콘텐츠를 표시하는 UI 요소입니다.

컴포넌트 노드 — 입력 / 상호작용

사용자 입력을 받거나 변수 값을 직접 조작할 수 있는 컴포넌트입니다. 값 필드에 변수를 바인딩하면 자동으로 양방향 동기화됩니다.

입력 컴포넌트의 양방향 동기화

입력 컴포넌트의 value(또는 checked) 필드에 변수를 바인딩하면, 사용자가 컴포넌트를 조작할 때마다 해당 변수에 새 값이 자동으로 기록됩니다. 별도의 액션 코드를 작성할 필요가 없으며, 같은 변수를 표시하는 다른 위젯도 즉시 갱신됩니다.

버튼 액션 타입

Button 컴포넌트의 속성 패널에는 클릭 시 무엇을 할지 정하는 액션 항목이 있습니다. 네 가지 타입 중 하나를 선택합니다.

스타일링 속성

모든 노드에 적용할 수 있는 스타일 속성입니다. 속성 패널 하단에서 설정합니다.

애니메이션 프리셋

아이콘 컴포넌트의 "애니메이션" 속성에서 선택할 수 있습니다.

아이콘 / 아바타 커스텀 크기

아이콘과 아바타는 기본 프리셋(SM/MD/LG/XL) 외에 자유로운 크기를 직접 입력할 수 있습니다. 정사각형 컴포넌트라 하나의 값으로 가로세로 양쪽이 동시에 설정됩니다.

사용 흐름

1. 1 속성 패널에서 크기 드롭다운을 연다
2. 2 "커스텀" 옵션을 선택하면 현재 프리셋에 해당하는 기본 px 값이 자동으로 채워진 텍스트 입력으로 전환된다
3. 3 원하는 값을 입력하면 미리보기에 즉시 반영된다
4. 4 ↺ 리셋 버튼으로 언제든 프리셋(MD)으로 돌아갈 수 있다

지원 포맷

잘못된 값(예: abc, 24xx)을 입력하면 자동으로 MD 프리셋으로 폴백되어 미리보기가 깨지지 않습니다.

여백(패딩 / 마진) 세밀 제어

속성 패널의 Size 섹션에서 패딩과 마진을 4면 개별로 조절할 수 있습니다.

🔗 링크 버튼

PL과 PR 사이, PT와 PB 사이에 있는 🔗 버튼은 두 면의 값을 묶어 동시에 조절합니다.

• 자동 감지: 두 면의 값이 같으면 링크가 자동으로 ON 상태로 표시됩니다.
• 링크 ON 상태: 한쪽을 바꾸면 반대쪽도 같은 값으로 동기화 (CSS의 padding-inline / padding-block 효과)
• 링크 OFF 상태: 각 면을 독립적으로 편집
• 버튼을 클릭해 수동으로 ON/OFF 전환 가능

표(Table) 편의 도구

Table 컨테이너의 속성 패널에는 표 제작을 쉽게 해주는 두 가지 편의 도구가 있습니다.

1. 행·열 자동 생성

원하는 행 수와 열 수를 숫자로 입력하고 생성 버튼을 누르면 빈 셀이 자동으로 만들어집니다. "헤더 행 포함" 옵션을 켜면 첫 행이 헤더로 지정됩니다.

2. CSV 데이터 동기화

쉼표와 줄바꿈으로 표 데이터를 한 번에 입력할 수 있습니다.

헤더: 이름, 나이, 직업
본문:
철수, 25, 개발자
영희, 30, 디자이너
민수, 28, 기획자

셀 개수가 행마다 다르면 가장 긴 행을 기준으로 열 수가 통일되고, 부족한 셀은 빈 값으로 채워집니다. 셀 값에 쉼표나 줄바꿈이 포함된 경우에는 수동 편집이 더 적합합니다.

3. 표 스타일 토글

💻 위젯 심화 - JSX 고급

비주얼 모드로 표현하기 어려운 복잡한 위젯을 JSX 코드로 직접 작성하는 모드입니다. 대부분의 위젯은 비주얼 모드로 충분하므로, 이 섹션은 동적 렌더링·고급 로직·세밀한 제어가 필요할 때만 참고하세요.

언제 JSX 고급 모드가 필요한가

진입 방법과 제약

비주얼 모드로 위젯을 만든 뒤, 속성 패널 상단의 "고급 JSX" 버튼을 클릭하면 JSX 모드로 전환됩니다. 전환 시점에 현재 캔버스 트리가 자동으로 JSX 코드로 변환되어 편집기에 채워집니다.

위젯 실행 컨텍스트

JSX 고급 모드의 위젯은 샌드박스 안에서 실행됩니다. 사용할 수 있는 것과 없는 것을 먼저 이해해야 합니다.

사용 가능

• React 훅: useState, useMemo, useCallback, useRef, useEffect
• shadcn 컴포넌트: Button, Card, Progress, Tabs, Select, Input, Slider, Switch 등 비주얼 모드에서 쓰이는 모든 컴포넌트
• Lucide 아이콘: Heart, Star, Sword, Shield, Loader2 등 화이트리스트 아이콘
• 유틸: cn (className 병합 유틸)
• sendAction(type, payload): 변수 업데이트·채팅 전송·입력창 초안·시작 시나리오 선택
• props: Props 바인딩 편집기로 연결된 변수 값 (상세는 아래)

차단됨

• 브라우저 전역: window, document, globalThis, localStorage, sessionStorage
• 네트워크: fetch, XMLHttpRequest, WebSocket
• 동적 실행: eval, Function, setTimeout, setInterval, import()
• 리플렉션: Proxy, Reflect, Symbol

보안 제약은 서버 컴파일러(AST 검증)와 런타임 샌드박스 두 층에서 적용됩니다. 차단된 식별자를 사용하면 컴파일 에러가 발생하거나 실행 시 undefined가 됩니다.

변수 바인딩 — props로 전달

위젯은 변수에 직접 접근하지 않습니다. 모든 변수는 위젯의 props로 전달되고, 위젯은 React 컴포넌트처럼 props를 통해 값을 읽습니다. 변수와 props 이름을 연결하는 것을 props 바인딩이라고 합니다.

① Props 바인딩 편집기에서 매핑 추가

JSX 고급 모드의 하단 패널에서 "바인딩 추가" 버튼으로 행을 만듭니다.

변수          →   prop 이름
────────────      ────────────
$hp           →   hp
$max_hp       →   maxHp
$location     →   location
$inventory    →   inventory

왼쪽은 변수 목록에서 선택하고($변수명 형태), 오른쪽은 위젯 코드 안에서 사용할 prop 이름을 직접 입력합니다. 두 이름이 달라도 되고, 일반적으로 camelCase로 바꿔 쓰면 JSX 코드에서 자연스럽습니다. 비주얼 모드에서 JSX 고급으로 전환 시 기존에 연결된 바인딩은 자동으로 이 맵에 채워져 있습니다.

② 코드에서 props로 읽기

함수 파라미터에서 destructure하거나 props.xxx로 직접 접근합니다.

function Component(props = {}) {
  const { hp = 0, maxHp = 100, location = '', inventory = [] } = props;

  return (
    <div className="space-y-2">
      <div>HP: {hp} / {maxHp}</div>
      <div>현재 위치: {location}</div>
      <div>
        {inventory.map((item, i) => (
          <span key={i} className="mr-2">{item}</span>
        ))}
      </div>
    </div>
  );
}

③ 타입 변환 주의

변수 값은 내부적으로 문자열 기반으로 저장됩니다. 시스템이 JSON 파싱을 시도하지만, 프리미티브 값(number, boolean)도 문자열로 들어올 수 있습니다. 안전하게 쓰려면 필요 시 명시적으로 변환하세요.

function Component(props = {}) {
  // 숫자는 Number()로 안전하게 변환
  const hp = Number(props.hp) || 0;
  const maxHp = Number(props.maxHp) || 100;
  const percent = Math.round((hp / maxHp) * 100);

  // 배열은 JSON 파싱되어 배열로 오거나, 문자열로 올 수 있음
  const inventory = Array.isArray(props.inventory)
    ? props.inventory
    : [];

  return (
    <div>
      <div>HP: {hp} / {maxHp} ({percent}%)</div>
      <div>아이템 {inventory.length}개</div>
    </div>
  );
}

sendAction API

위젯 안에서 외부 상태를 바꾸려면 sendAction을 호출합니다. 직접 변수를 조작하거나 채팅을 보낼 수 없고, 이 API를 통해서만 가능합니다.

CSS (Global)

고급 JSX 모드에서는 JSX 편집기 아래에 CSS (Global) 편집기가 있습니다. 여기에 작성한 CSS는 모든 위젯이 공유하며, 채팅 화면에서 <style> 태그로 1회 삽입됩니다.

• 색상 변수, 폰트, 공통 애니메이션을 한 곳에서 관리할 수 있습니다.
• 에셋 위젯 + 사이드 위젯 + 선택지 등 여러 위젯이 같은 디자인 언어를 공유할 수 있습니다.
• 위젯 소스 안의 <style>{`...`}</style> 블록은 해당 위젯에만 스코핑되므로, 공통 스타일과 위젯 고유 스타일을 분리할 수 있습니다.

에셋 위젯 — JSX 고급 가이드

출력 위치를 "에셋"으로 설정한 위젯은 대화 중 이미지를 감싸는 래퍼 역할을 합니다. props.src와 props.alt가 런타임에 자동으로 주입되며, Props 바인딩에 등록하지 않아도 됩니다.

자동 주입되는 props

추가로 캐릭터 변수를 바인딩하려면 Props 바인딩 편집기에서 자유롭게 추가할 수 있습니다. 단, src/alt는 런타임 값이 항상 우선하므로 바인딩으로 덮어쓸 수 없습니다.

에셋 위젯 예시

function AssetFrame(props = {}) {
  const { src, alt = '' } = props;
  const [collapsed, setCollapsed] = useState(false);

  if (!src) return null;

  return (
    <div className="asset-frame">
      <div className="asset-header">
        {alt && <span className="asset-alt">{alt}</span>}
        <Button
          variant="ghost"
          className="asset-toggle"
          onClick={() => setCollapsed(v => !v)}
        >
          {collapsed
            ? <ChevronDown size={14} />
            : <ChevronUp size={14} />}
        </Button>
      </div>
      {!collapsed && (
        <img src={src} alt={alt}
          className="asset-image" />
      )}
    </div>
  );
}

위 예시의 스타일(.asset-frame 등)은 CSS (Global) 편집기에 작성하면 모든 에셋 이미지에 일괄 적용됩니다.

JSX 예시

function Component(props = {}) {
  const choices = [
    { icon: '☕', text: '카페로 가자' },
    { icon: '🌳', text: '공원을 산책하자' },
    { icon: '🏠', text: '집에서 쉬자' },
  ];

  return (
    <div className="flex flex-col gap-2">
      {choices.map((c, i) => (
        <Button
          key={i}
          variant="outline"
          onClick={() => sendAction('chat', { text: c.text })}
        >
          {c.icon} {c.text}
        </Button>
      ))}
    </div>
  );
}

function Component(props = {}) {
  const hp = Number(props.hp) || 0;
  const mp = Number(props.mp) || 0;
  const gold = Number(props.gold) || 0;

  return (
    <Card>
      <CardContent className="space-y-2">
        <div className="flex items-center gap-2">
          <span>❤️ HP</span>
          <Progress value={hp} max={100} className="flex-1" />
          <span className="text-xs">{hp}/100</span>
        </div>
        <div className="flex items-center gap-2">
          <span>💙 MP</span>
          <Progress value={mp} max={50} className="flex-1" />
          <span className="text-xs">{mp}/50</span>
        </div>
        <div className="flex items-center gap-2">
          <span>💰</span>
          <span className="font-semibold">{gold} Gold</span>
        </div>
      </CardContent>
    </Card>
  );
}

function Component(props = {}) {
  const inventory = Array.isArray(props.inventory)
    ? props.inventory
    : [];

  const useItem = (item, idx) => {
    const next = inventory.filter((_, i) => i !== idx);
    sendAction('updateVar', { name: 'inventory', value: next });
    sendAction('chat', { text: `${item}을(를) 사용했다.` });
  };

  if (inventory.length === 0) {
    return <Card><CardContent>인벤토리가 비어있습니다.</CardContent></Card>;
  }

  return (
    <Card>
      <CardContent className="space-y-1">
        {inventory.map((item, i) => (
          <Button
            key={i}
            variant="ghost"
            className="w-full justify-between"
            onClick={() => useItem(item, i)}
          >
            <span>{item}</span>
            <span className="text-xs text-muted-foreground">사용</span>
          </Button>
        ))}
      </CardContent>
    </Card>
  );
}

🎭 위젯 심화 - AI 호출

위젯이 AI 응답에서 특정 값을 추출해 변수에 반영하는 방법을 알아봅니다.

추출 방식

정규표현식 기본

AI 응답에서 자주 사용하는 정규식 패턴입니다:

테스트 기능

에디터에 내장된 정규식 테스트 기능으로 실시간 검증이 가능합니다:

• 테스트 텍스트 입력 → 패턴 매칭 결과 즉시 확인
• 캡처 그룹별 추출 결과 미리보기
• 문법 오류 자동 감지

🌍 다국어 지원

캐릭터를 여러 언어로 제공하는 방법을 알아봅니다.

지원 언어

로케일 오버라이드

각 탭 상단의 언어 토글로 다른 언어 버전을 작성할 수 있습니다. 오버라이드하지 않은 필드는 원본 언어(소스 언어)가 사용됩니다.

오버라이드 가능한 필드

• 카드 메타데이터 — 이름, 한줄 소개, 캐릭터 상세 소개, 플레이 가이드
• 버전 콘텐츠 — 캐릭터 프롬프트, 첫 메시지, 대체 인사
• 위젯 코드 — 언어별 JSX 코드
• 에셋 태그 — 이미지 표시 태그의 번역
• 로어북 키워드 — 언어별 키워드 매핑

📏 제한 사항 요약

각 필드의 글자/토큰 제한을 확인합니다.

글자 수 제한

글자/토큰 제한

수량 제한

⌨️ 단축키

에디터에서 사용할 수 있는 키보드 단축키입니다.

💡 제작 팁

더 좋은 캐릭터를 만들기 위한 실전 팁입니다.

❓ FAQ

자주 묻는 질문과 답변입니다.