YAVN (야븐)

Type your story. Play your novel.

YAVN은 YAML 기반 비주얼노벨 엔진입니다. 현재 DSL은 YAML V3이며, 전역/공통/챕터 선언을 분리합니다.

기여 가이드 · 게임 목록에 작품 추가하기 · English contribution guide

이야기 지도

• 플레이 중 HUD의 이야기 지도 또는 사망·엔딩 화면의 이야기 지도 펼치기로 진입합니다.
• 챕터 YAML 전체의 장면·선택·합류·반복·결말을 읽어 실제 배경과 인물 에셋이 붙은 분기 지도로 보여 줍니다. 누적 방문 기록이 있는 장·장면만 표시하고 실제로 지나온 연결선은 금색으로 표시합니다. 미방문 장면과 미선택 경로는 표시하지 않습니다.
• 열 때마다 생존·사망 여부와 관계없이 현재 장면을 화면 중앙에 맞춥니다. 선택지별 번호와 방향 화살표로 합류와 되돌아가는 길을 구분하며, 발견한 경로의 도착 지점을 상세 패널에서 확인할 수 있습니다. 같은 장면으로 합류해도 관계·소지품 결과까지 같다는 뜻은 아닙니다.
• 드래그/스크롤, 확대·축소, 현재 위치 찾기, 챕터 이동을 지원합니다. 사망하지 않아도 이 시점으로 돌아가기로 이전 지점을 당시 소지품·관계·기록 상태에서 다시 플레이할 수 있습니다. 이전 버전 저장도 선택 기록을 바탕으로 과거 복원점을 복구합니다.
• 탐색 기록은 게임별로 분리되며 새 회차와 되돌리기 이후에도 남습니다. 저장 공간이 부족하면 세션 안에서 유지합니다. 작품 버전이 바뀌어도 지도는 지우지 않고 이전 버전 기록으로 표시합니다.
• 챕터의 선택 필드 chapterTitle, 장면의 선택 필드 title로 지도 제목을 지정합니다. 기존 YAML은 그대로 실행됩니다.

chapterTitle: 모란이 피기 전에
script: [{scene: opening}]
scenes:
  opening:
    title: 먼저 쓰인 사망 기록
    actions:
      - say: {text: 종이에서 내 이름을 찾았다.}

Quick Start

pnpm install
pnpm test
pnpm dev

• Node: 22.13+ (배포·CI 권장: 22.x)
• 기본 주소: http://localhost:5173

AI에게 게임 맡기기

시놉시스만 있으면 다른 AI에게 기획부터 YAML까지 맡길 수 있습니다. 복사해서 쓰는 프롬프트(기획 → 제작 → 다듬기 3단계)는 docs/AI_GAME_WRITING_PROMPT.ko.md에 있습니다. AI 같은 내레이션, 밋밋한 인물, 튀는 장면 전환을 처음부터 막는 규칙이 들어 있습니다.

이야기 서재

책장 모티프의 로고와 아이보리·딥그린 디자인으로 작품을 둘러보고 바로 플레이할 수 있습니다. 대표작 쇼케이스, 검색·태그 필터, PC·태블릿·휴대폰에 맞춘 작품 목록, ZIP 실행과 제작 안내를 제공합니다.

플레이 편의

• 플레이어 이름: 정답 없이 쓰는 input(자유 입력)으로 이름을 받아 {{player_name}}처럼 대사·선택지·이름표에 넣을 수 있습니다. {{player_name|은}}은 받침에 맞춰 은/는, 이/가, 을/를 등을 고릅니다. 무원은 시작할 때 주인공 이름을 받습니다.
• 수동 저장 칸 3개: 저장·설정에서 세 칸에 따로 저장하고 불러옵니다.
• 서재 진행 표시: 작품 카드에 이어서 읽을 저장과 발견한 결말 수가 보입니다.
• 읽은 대사 건너뛰기: 대화창의 건너뛰기를 켜면 이 게임에서 이미 읽은 대사를 빠르게 넘깁니다. 처음 보는 대사, 선택지, 입력, 영상, 게임오버, 엔딩에서 자동으로 멈춥니다. 읽은 기록은 게임별로 브라우저에 남아 새 회차와 되돌리기 이후에도 유지됩니다.
• 빠른 첫 장면: 챕터를 열 때 시작 장면과 그 장면에서 두 단계 안에 이어지는 장면의 그림만 기다리고, 나머지 그림은 장면이 시작된 뒤 계속 받습니다.
• 조사 장면 안내: 배경 위 조사 지점이 있는 선택에서는 화면에서 살펴볼 곳을 누르세요를 표시하고, 목록형 선택지 번호는 실제로 보이는 순서대로 매깁니다.
• 읽기 쉬운 글자: 게임 화면·시작 화면·이야기 지도의 글자는 12px 이상으로 표시하고, 설정 화면 소제목은 한국어로 보여 줍니다.
• 이용 통계 선택: 동의 창은 시작 화면 위에 표시하고, 게임 중에는 떠 있는 이용 통계 버튼이 대화창을 가리지 않도록 숨깁니다. 선택은 저장 · 설정 → 권리·출처 → 이용 통계 설정에서 바꿀 수 있습니다.

설치·오프라인

야븐은 설치형 웹앱(PWA)입니다. Chrome·Edge에서는 주소창의 설치 버튼으로, iPhone·iPad Safari에서는 공유 → 홈 화면에 추가로 앱처럼 띄울 수 있습니다.

• 오프라인 저장: 서재 대표작 카드의 오프라인 저장 · 4.9MB를 누르면 그 게임의 YAML·그림·소리를 기기에 받아 둡니다. 저장 중 n% → 오프라인 가능으로 바뀌며 지우기로 비울 수 있습니다. 배포된 파일이 바뀌면 업데이트 있음과 함께 바뀐 파일만 다시 받는 버튼이 나옵니다. 47MB인 Live2D 테스트처럼 20MB를 넘는 게임은 저장을 제공하지 않습니다.
• 연결이 끊겼을 때: 서재 위에 오프라인 · 저장한 게임만 열 수 있어요가 뜨고, 저장하지 않은 게임은 흐리게 바뀌어 열리지 않습니다. 저장한 게임은 배경·음악까지 그대로 플레이되고, 진행 저장은 원래대로 브라우저(localStorage)에 남습니다. 온라인으로 한 번 플레이한 게임도 본 장면의 파일은 기기에 쌓입니다.
• 새 버전: 새 배포가 나오면 늘 보던 새 버전이 나왔어요. 지금 반영할까요? 안내 하나만 뜹니다. 지금 반영을 눌러야 자동 저장을 마친 뒤 새 버전으로 넘어가며, 저절로 새로고침되지 않습니다.
• 작동 방식(서비스 워커, 캐시 규칙)은 개발 가이드의 2026-11-13 PWA 변경 기록에 있습니다.

장면 연출

• 자동 인물 배치와 상반신 구도: 기본 scene.layout: auto는 보이는 1·2·3명에 맞춰 재정렬하고, 빈자리를 유지할 장면만 fixed로 지정합니다. char.position은 생략하거나 auto로 지정할 수 있습니다. framings.cropBottom으로 전신 원화의 얼굴을 크게 보여 주면서 같은 이미지·DOM을 유지합니다.

• 대화·전환 렌더링 최적화: 전신↔상반신 확대는 이미지 높이 대신 transform으로 보간합니다. 대사 타이핑의 레이아웃 계산은 크기가 정해진 대화창 내부로 제한하고, 마지막 글자 효과에는 재사용하는 글자 분리기로 필요한 글자만 찾습니다. 기존 YAML에 자동 적용됩니다.

• 끊기지 않는 무대 객체: 같은 아이템·캐릭터의 DOM을 유지하고 그림·표정·좌표만 갱신합니다. 족보 같은 증거물은 대사마다 숨기지 않으며, 두 캐릭터가 자리를 바꿔도 이동과 표정 전환이 이어집니다. 기존 YAML과 저장에 자동 적용됩니다.

• 주인공 시점 플레이: thought/action으로 속마음과 감각을 구분하고, continueLabel 행동 버튼 앞에서 AUTO가 기다립니다. choice.presentation: explore와 options[].at로 장면 속 물건을 살펴본 뒤 조건부 추론으로 이어갑니다. 조사한 내용은 기존 저장에 보존됩니다.

• 이미지 리소스 재사용: 프리로드와 화면 표시가 같은 디코딩 이미지 요소를 공유합니다. 반복 등장·표정·배경의 재준비를 줄이고, 다음 챕터는 이미지 바이트만 미리 받아 현재 장면의 디코딩과 경쟁하지 않습니다.

• 인게임 플레이어 UI: 잘리지 않는 안쪽 포커스 테두리, 테마별 대화·선택·입력, 기록·소지품·저장/설정과 결과 화면 통일. 메뉴 키보드 탐색·초점 복귀·이야기 시간 일시 정지 지원.

• 비주얼노벨 인물 연출: 디코드 후 등장, 표정 크로스디졸브, 제자리 퇴장·교체, 안정적인 대화 구도와 카메라 유지. 화자는 색을 바꾸지 않고 살짝 앞으로 확대.

• 타이틀 장면 엔진: 카메라·다층 이미지·마우스 시차·비/불티/눈/반딧불·안개/조명·영상과 시작 전환을 YAML로 구성. 로딩 중 이야기 시간을 보존. 모바일 세로 메뉴는 제목·버튼·고지를 실제 높이대로 쌓고 안전영역 안에서 스크롤.

• 장소 전환: 디졸브·암전·좌우 와이프·컷, 장면별 길이와 디코드/전환 완료 대기.

• 공격 연출: 공격자·대상·방향을 지정하면 접근→타격→반응에 맞춰 인물, 화면 효과, 효과음이 함께 움직입니다. attack.image로 무기·표정이 보이는 전용 장면 컷도 지정할 수 있습니다.

• 게임오버·엔딩: 마지막 장면에서 결말을 읽은 뒤 선택 복구나 크레딧으로 이동합니다. 개별 엔딩의 배경·음악·후일담·분위기를 지정할 수 있습니다.

• 플레이 감각: 모션 감소 설정, SFX 음소거, 연속 클릭 보호, 복구 시 남은 연출 정리. 기존 YAML 축약형도 유지합니다.

# chapter.yaml — courtyard, guard, heroine은 base.yaml 에셋 ID
- bg: { id: courtyard, transition: fade, duration: 900 }
- say: { channel: narration, text: "발소리가 멎었다. 칼집이 짧게 울렸다." }
- attack:
    attacker: guard
    target: heroine
    from: right
    style: slash
    strength: heavy
    anticipation: 650
    impact: 160
    recovery: 750
    caption: "대답보다 칼이 먼저 움직였다."
- say: { char: heroine, delivery: nervous, text: "아직… 끝나지 않았어." }

# config.yaml
endings:
  dawn:
    title: "새벽까지 살아남다"
    message: "두 사람은 함께 성문을 빠져나왔습니다."
    epilogue: "다음 날에도 그 문은 열려 있었습니다."
    background: courtyard
    tone: hopeful

공격의 실제 결과는 set/branch/gameOver로 작성합니다. 세부 옵션과 저장·접근성 동작은 개발 가이드를 참고하세요.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗