# Templates (/start/templates)





You can generate a new project from a template by running:

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm create pixi-vn@latest
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm create pixi-vn
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn create pixi-vn
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bunx create-pixi-vn
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Interactive demo [#interactive-demo]

<Accordions>
  <Accordion title="Visual Novel" id="visual-novel">
    <iframe
      src="https://pixi-vn-visual-novel-example.pages.dev/demo"
      title="Visual Novel"
      style="{
      width: &#x22;100%&#x22;,
      height: &#x22;400px&#x22;,
      border: &#x22;0&#x22;,
      borderRadius: &#x22;4px&#x22;,
      overflow: &#x22;hidden&#x22;,
  }"
      allowFullScreen="true"
    />
  </Accordion>

  <Accordion title="Point & Click" id="point-click-adventure">
    <iframe
      src="https://pixi-vn-point-and-click-example.pages.dev/demo"
      title="Point & Click"
      style="{
      width: &#x22;100%&#x22;,
      height: &#x22;400px&#x22;,
      border: &#x22;0&#x22;,
      borderRadius: &#x22;4px&#x22;,
      overflow: &#x22;hidden&#x22;,
  }"
      allowFullScreen="true"
    />
  </Accordion>
</Accordions>

## How to use a template [#how-to-use-a-template]

If you are reading this page, you likely already have a project generated from a template. The following sections will guide you through the first steps to get it up and running.

### Initial setup [#initial-setup]

Open the project folder with your IDE. The examples below use [Visual Studio Code](https://code.visualstudio.com/).

Once the project is open, VS Code will automatically suggest a few things:

* **Install recommended extensions** — a notification will appear asking you to install the workspace-recommended extensions. It is strongly advised to accept. If the notification does not appear, you can install them manually from the Extensions panel by filtering for [recommended extensions](https://code.visualstudio.com/docs/editor/extension-marketplace#_recommended-extensions).
* **Run startup tasks** — VS Code may prompt you to run the configured startup tasks, which will install all project dependencies. If you prefer to do it manually, run:

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm install
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm install
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn install
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun install
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<CalloutContainer type="warning">
  <CalloutTitle>
    Multi-platform
  </CalloutTitle>

  <CalloutDescription>
    If you selected a template that targets desktop or mobile platforms, you will need to install the additional dependencies required by [Tauri](https://v2.tauri.app/start/prerequisites/) (Rust toolchain and platform-specific build tools). Because Tauri integrates deeply with the system environment, you will likely need to **restart VS Code one or more times** before the project can be launched as a desktop application.
  </CalloutDescription>
</CalloutContainer>

<Accordions>
  <Accordion title="Installing Rust" id="installing-rust">
    The easiest way to install Rust on any platform is via [rustup](https://rustup.rs/), the official Rust toolchain installer.

    <Tabs items="[&#x22;Windows&#x22;, &#x22;macOS&#x22;, &#x22;Linux&#x22;]" groupId="os">
      <Tab>
        Download and run [`rustup-init.exe`](https://win.rustup.rs/), or install it from the terminal with `winget`:

        ```powershell
        winget install --id Rustlang.Rustup
        ```

        After installation, restart your terminal (and VS Code) so the `cargo` command is available on `PATH`.
      </Tab>

      <Tab>
        Open a terminal and run:

        ```bash
        curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
        ```

        Follow the on-screen instructions, then restart your terminal (and VS Code) so the `cargo` command is available on `PATH`. You will also need the Xcode Command Line Tools:

        ```bash
        xcode-select --install
        ```
      </Tab>

      <Tab>
        Open a terminal and run:

        ```bash
        curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
        ```

        Follow the on-screen instructions, then restart your terminal (and VS Code) so the `cargo` command is available on `PATH`. Depending on your distribution, you may also need to install additional system packages required by Tauri (e.g. `webkit2gtk`, `build-essential`, `libssl-dev`) — see the [Tauri Linux prerequisites](https://v2.tauri.app/start/prerequisites/#linux) for the exact packages for your distro.
      </Tab>
    </Tabs>

    Once installed, verify it with:

    ```bash
    rustc --version
    ```
  </Accordion>
</Accordions>

### Run the project [#run-the-project]

The template includes a set of pre-configured **launch configurations** for VS Code. If you are not familiar with them: launch configurations are shortcuts that tell VS Code how to start your project (and optionally attach a debugger), so you do not need to type commands in the terminal every time. You can access them from the **Run and Debug** panel (the play-button icon in the left sidebar, or press `F5`). Select the configuration you want from the dropdown at the top of the panel and press the green play button.

<img alt="Run-and-Debug-panel" src="__img0" />

The following configurations are available:

* **Debug Game**: his is the configuration you will use most often during development — every time you save a file, the browser refreshes automatically. Keep in mind that in this mode animations may not be perfectly smooth and asset loading can be slower than in the final published build.
* **Debug Game Preview**: which closely simulates how the game will behave once published: animations are fluid, loading times are realistic, and optimisations are active. Use this configuration when you want to verify that everything looks and feels correct before publishing.
* **Run as Desktop App (Dev)**: it compiles the Rust/Tauri backend and launches the game as a native desktop window. If your template does not target desktop or mobile platforms, this configuration will not be present.

<Accordions>
  <Accordion title="Command line" id="command-line">
    All commands must be run from the root of the project.

    **Development**

    | Command                     | Description                                                                                             |
    | --------------------------- | ------------------------------------------------------------------------------------------------------- |
    | `npm run dev`               | Start the Vite development server and open the game in the browser.                                     |
    | `npm run tauri:dev`         | Start the game as a **desktop** application (requires the multi-platform template and Tauri installed). |
    | `npm run tauri:android:dev` | Start the game on a connected Android device or emulator.                                               |
    | `npm run tauri:ios:dev`     | Start the game on a connected iOS device or simulator.                                                  |

    **Build & Preview**

    | Command              | Description                                                                              |
    | -------------------- | ---------------------------------------------------------------------------------------- |
    | `npm run build:fast` | Build the web app only (no Tauri). Fast, suitable for web publishing.                    |
    | `npm run build`      | Full build: compiles TypeScript, builds the web app, and packages the Tauri desktop app. |
    | `npm run preview`    | Run `build:fast` and then serve the result locally — simulates the published web game.   |

    **Assets & icons**

    | Command        | Description                                                                                                  |
    | -------------- | ------------------------------------------------------------------------------------------------------------ |
    | `npm run icon` | Generate all icon variants (PWA, desktop, mobile) from `public/icon.png`. Run this after replacing the icon. |

    **UI**

    | Command             | Description                                                                                                                          |
    | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
    | `npm run ui:reinit` | Reinitialize [shadcn/ui](https://ui.shadcn.com/) from scratch (force-reinstall all components) and reformat source files afterwards. |

    **Code quality**

    | Command          | Description                                                    |
    | ---------------- | -------------------------------------------------------------- |
    | `npm run lint`   | Check the code for errors using [Biome](https://biomejs.dev/). |
    | `npm run check`  | Run all Biome checks (lint + format verification).             |
    | `npm run format` | Automatically format all source files.                         |
  </Accordion>
</Accordions>

### Customise the style [#customise-the-style]

The template UI is built entirely with [shadcn/ui](https://ui.shadcn.com/), which means you can customise the colour theme without touching any component code.

Open the [shadcn/ui theme builder](https://ui.shadcn.com/create?template=vite\&base=base\&preset=b1s9eyGkS), adjust the colours to your taste, then navigate to the **Copy** section of the page to copy the generated CSS command. Run that command from the root of your project:

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx shadcn@latest add <paste-the-generated-command-here>
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx shadcn@latest add <paste-the-generated-command-here>
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx shadcn@latest add <paste-the-generated-command-here>
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x shadcn@latest add <paste-the-generated-command-here>
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Once applied, it is recommended to reformat the source files:

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npm run format
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm run format
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn format
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun run format
    ```
  </CodeBlockTab>
</CodeBlockTabs>

For further customisation — fonts, global styles, and more — see <DynamicLink href="/start/interface-font">Styles & font</DynamicLink>.

### Project structure [#project-structure]

<Files>
  <Folder name="project">
    <Folder name="ink">
      <File name="start.ink" />
    </Folder>

    <Folder name="public">
      <File name="icon.png" />
    </Folder>

    <Folder name="src">
      <Folder name="assets">
        <File name="manifest.gen.json" />

        <File name="ink-manifest.gen.json" />

        <File name="index.ts" />
      </Folder>

      <Folder name="components" />

      <Folder name="content">
        <Folder name="ink">
          <File name="hashtag-commands.ts" />

          <File name="text-replaces.ts" />
        </Folder>

        <Folder name="labels">
          <File name="start.label.ts" />
        </Folder>

        <File name="characters.ts" />

        <File name="index.ts" />
      </Folder>

      <Folder name="lib">
        <Folder name="hooks" />

        <Folder name="query" />

        <Folder name="stores" />

        <Folder name="utils" />

        <File name="i18n.ts" />

        <File name="steam.ts" />
      </Folder>

      <Folder name="locales">
        <File name="en.json" />
      </Folder>

      <Folder name="models">
        <File name="Character.ts" />

        <File name="GameSaveData.ts" />
      </Folder>

      <Folder name="routes">
        <Folder name="game">
          <File name="narration.tsx" />
        </Folder>

        <File name="__root.tsx" />

        <File name="game.tsx" />

        <File name="index.tsx" />
      </Folder>

      <File name="constants.ts" />

      <File name="main.tsx" />

      <File name="pixi-vn.keys.gen.ts" />

      <File name="pixi-vn.d.ts" />

      <File name="styles.css" />
    </Folder>

    <Folder name="src-tauri" />
  </Folder>
</Files>

<Accordions>
  <Accordion title="Narration" id="project-structure-narration">
    * `ink/&#x60; — write your story in &#x2A;**ink*** scripts here. The template includes a sample `start.ink` to get you started.
    * `src/content/` — auto-imported at startup; define all game elements here:
      * `ink/hashtag-commands.ts&#x60; — custom hashtag commands from &#x2A;**ink*** scripts. See <DynamicLink href="/ink/hashtag">***ink*** hashtag commands</DynamicLink>.
      * `ink/text-replaces.ts&#x60; — text replacements for &#x2A;**ink*** dialogue. See <DynamicLink href="/ink/replacement">***ink*** text replacements</DynamicLink>.
      * `labels/` — labels defining game flow and scenes (use the `.label.ts` naming convention).
      * `characters.ts` — character definitions.
  </Accordion>

  <Accordion title="Assets" id="project-structure-assets">
    * `src/assets/` — source game assets (images, audio, fonts, etc.). Auto-analysed by [Pixi Asset Pack](https://pixijs.io/assetpack/).
    * `public/assets/` — auto-generated optimized assets used by the project at runtime.
    * `public/icon.png` — source icon. Replace it and run `npm run icon` to regenerate all PWA/desktop/mobile variants.
    * `src/assets/index.ts` — re-exports the auto-generated asset manifest for the engine.
  </Accordion>

  <Accordion title="UI" id="project-structure-ui">
    * `src/components/` — React UI components (screens, menus, dialogue boxes, etc.).
    * `src/routes/` — [TanStack Router](https://tanstack.com/router) route definitions. See <DynamicLink href="/start/interface-navigate">Navigation</DynamicLink>.
    * `src/styles.css` — global stylesheet ([shadcn/ui](https://ui.shadcn.com/)). See <DynamicLink href="/start/interface-font">Fonts & styles</DynamicLink>.
  </Accordion>

  <Accordion title="Translations" id="project-structure-translations">
    * `src/lib/i18n.ts` — internationalisation setup. See <DynamicLink href="/start/translate">Translations</DynamicLink>.
    * `src/locales/` — one translation JSON per language (e.g. `en.json`). See <DynamicLink href="/start/translate">Translations</DynamicLink>.
  </Accordion>

  <Accordion title="Initial setup" id="project-structure-initial-setup">
    * `src/models/` — custom classes and TypeScript types.
    * `src/main.tsx` — application entry point; initialises Pixi’VN.
    * `src/pixi-vn.keys.gen.ts` — auto-generated file with TypeScript types for all keys in the Pixi’VN API (e.g. `PixivnCharacterIds`, `PixivnLabelIds`, etc.). Used for type safety and autocompletion when working with the engine.
    * `src/pixi-vn.d.ts` — TypeScript declaration overrides for `@drincs/pixi-vn`.
  </Accordion>

  <Accordion title="Multi-platform" id="project-structure-multi-platform">
    * `src-tauri/` — Rust/Tauri source (multi-platform templates only); enables native desktop and mobile builds.
  </Accordion>

  <Accordion title="Other" id="project-structure-other">
    * `src/lib/` — utilities and internals:
      * `steam.ts` — Steam API (achievements, cloud saves). See <DynamicLink href="/start/distribution-steam">Steam distribution</DynamicLink>.
    * `src/constants.ts` — project-wide constants (screen sizes, config values, etc.).
  </Accordion>
</Accordions>

### Template screens [#template-screens]

The template comes with a set of pre-built screens that cover the essential parts of a visual novel. Each screen is a React component connected to a route managed by TanStack Router.

* **Main menu** (`/`) — the first screen the player sees when they launch the game. It provides the entry point to start a new game, continue a saved one, and open the settings.
* **Narration screen** (`/game/narration`) — the core gameplay screen where the story is displayed. It renders dialogue, character sprites, backgrounds, and choices.
* **Settings** — the settings panel does not have its own dedicated route. Instead it uses [Search Params](https://tanstack.com/router/latest/docs/framework/react/guide/search-params) to overlay itself on top of whatever screen is currently active. This approach keeps the URL clean while still allowing the player to open settings from anywhere in the game, and to navigate between settings sections (audio, display, language, etc.) without losing track of where they were.
* **Navigation screen** (`/game/navigation`) — *Point & Click* only. It lets the player navigate between rooms and perform the various actions available in the current location.
* **Map screen** (`/game/map`) — *Point & Click* only. It shows the map and lets the player move from one location to another. It also supports managing multiple maps.