템플릿

다음 명령을 실행하여 템플릿으로부터 새 프로젝트를 생성할 수 있습니다:

npm create pixi-vn@latest

인터랙티브 데모

템플릿 사용 방법

이 페이지를 읽고 있다면, 이미 템플릿으로부터 생성된 프로젝트를 가지고 있을 것입니다. 다음 섹션에서는 프로젝트를 실행하기 위한 첫 단계를 안내합니다.

초기 설정

IDE로 프로젝트 폴더를 여세요. 아래 예시에서는 Visual Studio Code를 사용합니다.

프로젝트를 열면 VS Code가 자동으로 몇 가지를 제안합니다:

• 권장 확장 프로그램 설치 — 워크스페이스에서 권장하는 확장 프로그램을 설치하라는 알림이 표시됩니다. 이를 수락하는 것을 강력히 권장합니다. 알림이 표시되지 않는 경우, 확장 프로그램 패널에서 권장 확장 프로그램을 필터링하여 수동으로 설치할 수 있습니다.
• 시작 작업 실행 — VS Code가 구성된 시작 작업을 실행하라는 메시지를 표시할 수 있으며, 이를 통해 모든 프로젝트 의존성이 설치됩니다. 수동으로 설치하려면 다음을 실행하세요:

npm install

프로젝트 실행

템플릿에는 VS Code용으로 미리 구성된 실행 구성(launch configurations) 세트가 포함되어 있습니다. 익숙하지 않은 분들을 위해 설명하면: 실행 구성은 매번 터미널에 명령을 입력할 필요 없이 VS Code가 프로젝트를 시작하는 방법(그리고 선택적으로 디버거를 연결하는 방법)을 알려주는 바로가기입니다. Run and Debug 패널(왼쪽 사이드바의 재생 버튼 아이콘 또는 F5 키)에서 접근할 수 있습니다. 패널 상단의 드롭다운에서 원하는 구성을 선택하고 초록색 재생 버튼을 누르세요.

다음 구성을 사용할 수 있습니다:

• Debug Game: 개발 중 가장 자주 사용하게 될 구성으로, 파일을 저장할 때마다 브라우저가 자동으로 새로고침됩니다. 이 모드에서는 애니메이션이 완벽하게 부드럽지 않을 수 있고, 에셋 로딩이 최종 게시 빌드보다 느릴 수 있다는 점에 유의하세요.
• Debug Game Preview: 게임이 게시된 후의 동작을 거의 그대로 시뮬레이션하는 구성입니다: 애니메이션이 부드럽고, 로딩 시간이 실제와 유사하며, 최적화가 적용됩니다. 게시하기 전에 모든 것이 올바르게 보이고 작동하는지 확인하고 싶을 때 이 구성을 사용하세요.
• Run as Desktop App (Dev): Rust/Tauri 백엔드를 컴파일하고 게임을 네이티브 데스크톱 창으로 실행합니다. 템플릿이 데스크톱 또는 모바일 플랫폼을 대상으로 하지 않는 경우 이 구성은 존재하지 않습니다.

스타일 사용자 지정

템플릿 사용자 인터페이스(UI)는 전적으로 shadcn/ui로 구축되어 있으므로, 컴포넌트 코드를 건드리지 않고도 색상 테마를 사용자 지정할 수 있습니다.

shadcn/ui 테마 빌더를 열고 원하는 색상으로 조정한 다음, 페이지의 Copy 섹션으로 이동하여 생성된 CSS 명령을 복사하세요. 해당 명령을 프로젝트 루트에서 실행하세요:

npx shadcn@latest add <paste-the-generated-command-here>

적용한 후에는 소스 파일을 다시 포맷하는 것을 권장합니다:

npm run format

추가적인 사용자 지정 — 폰트, 전역 스타일 등 — 에 대해서는 Styles & font을 참고하세요.

프로젝트 구조

템플릿 화면

템플릿에는 비주얼 노벨의 필수적인 부분을 다루는 사전 제작된 화면 세트가 포함되어 있습니다. 각 화면은 TanStack Router가 관리하는 라우트에 연결된 React 컴포넌트입니다.

• Main menu (/) — 플레이어가 게임을 실행할 때 처음 보게 되는 화면입니다. 새 게임을 시작하거나, 저장된 게임을 계속하거나, 설정을 여는 진입점을 제공합니다.
• Narration screen (/game/narration) — 스토리가 표시되는 핵심 게임플레이 화면입니다. 대화, 캐릭터 스프라이트, 배경, 선택지를 렌더링합니다.
• Settings — 설정 패널은 자체적인 전용 라우트를 가지고 있지 않습니다. 대신 Search Params를 사용하여 현재 활성화된 화면 위에 오버레이됩니다. 이 방식은 URL을 깔끔하게 유지하면서도 플레이어가 게임 어디에서든 설정을 열 수 있게 하고, 있던 위치를 잃지 않으면서 설정 섹션(오디오, 디스플레이, 언어 등) 간을 이동할 수 있게 해줍니다.
• Navigation screen (/game/navigation) — Point & Click 전용입니다. 플레이어가 방 사이를 이동하고 현재 위치에서 이용 가능한 다양한 행동을 수행할 수 있게 해줍니다.
• Map screen (/game/map) — Point & Click 전용입니다. 맵을 보여주고 플레이어가 한 위치에서 다른 위치로 이동할 수 있게 해줍니다. 또한 여러 맵을 관리하는 기능도 지원합니다.