# Quick start (/start)



You can start using Pixi’VN by [initializing a new project](#project-initialization) or [installing the package](#installation) in an existing project.

Prerequisites [#prerequisites]

Before starting, you must have the following tools installed:

* [Node.js](https://nodejs.org/) version 18 or higher.
* Text editor with TypeScript support, such as:
  * [Visual Studio Code](https://code.visualstudio.com/)
  * [Cursor](https://www.cursor.com/)
  * [VSCodium](https://vscodium.com/)
* (Recommended) [Git](https://git-scm.com/)
  * A [GitHub account](https://github.com/) - You will be able to use Copilot (Al assistant), auto-generation of packages to distribute and add comments to the wiki

Project initialization [#project-initialization]

If you want to start from a new project, you can use the following command to initialize a new project with the Pixi’VN templates:

<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>

You can see the list of available templates and interactive demos <DynamicLink href="/start/templates">here</DynamicLink>.

After the project is initialized, open the project directory with your text editor (VSCode is recommended) and start developing your project.

Installation [#installation]

To install the Pixi’VN package in an existing JavaScript project, use one of the following commands:

<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 @drincs/pixi-vn
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm add @drincs/pixi-vn
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn add @drincs/pixi-vn
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun add @drincs/pixi-vn
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Accordions>
  <Accordion title="CDN version" id="cdn-installation">
    You can also use the CDN version of this plugin:

    <CodeBlockTabs defaultValue="script tag">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="script tag">
          script tag
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="map import">
          map import
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="js import">
          js import
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="script tag">
        ```html  title="index.html"
        <script src="https://cdn.jsdelivr.net/npm/@drincs/pixi-vn@<version>/+esm"></script>
        ```
      </CodeBlockTab>

      <CodeBlockTab value="map import">
        ```html  title="index.html"
        <script type="importmap">
            {
                "imports": {
                    "@drincs/pixi-vn@<version>": "https://cdn.jsdelivr.net/npm/@drincs/pixi-vn/+esm"
                }
            }
        </script>
        ```
      </CodeBlockTab>

      <CodeBlockTab value="js import">
        ```js  title="index.js"
        import pixivn from "https://cdn.jsdelivr.net/npm/@drincs/pixi-vn@<version>/+esm";
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <iframe
      src="https://codepen.io/BlackRam-oss/embed/oNrqgNd?default-tab=js%2Cresult"
      height="300"
      style="{
      width: &#x22;100%&#x22;,
  }"
      title="Pixi’VN"
      loading="lazy"
      allowFullScreen="true"
    />
  </Accordion>

  <Accordion title="Vite.js plugin" id="vite-plugin">
    For a better developer experience, use [`vitePluginPixivn`](/jsdoc/pixi-vn/vite/functions/vitePluginPixivn) and [`setupPixivnViteData`](/jsdoc/pixi-vn/vite-listener/functions/setupPixivnViteData).

    <CodeBlockTabs defaultValue="vite.config.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="vite.config.ts">
          vite.config.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="main.ts">
          main.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="vite.config.ts">
        ```ts
        import { defineConfig } from "vite";
        import { vitePluginPixivn } from "@drincs/pixi-vn/vite";
        export default defineConfig({
            // ...
            plugins: [
                // other plugins...
                vitePluginPixivn(),
            ],
        });
        ```
      </CodeBlockTab>

      <CodeBlockTab value="main.ts">
        ```ts
        import { setupPixivnViteData } from "@drincs/pixi-vn/vite-listener"; // [!code focus]

        await Promise.all([import("./values"), import("./labels")]);
        await Promise.all([initializeIndexedDB(), defineAssets(), useI18n()]);
        setupPixivnViteData(); // [!code focus]
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="Error handling" id="error-handling">
    To handle errors in Pixi’VN, you can use the [`Game.addOnError`](/jsdoc/pixi-vn/index/namespaces/Game/functions/addOnError) function. This function takes a callback that will be called whenever an error occurs in the game.
  </Accordion>
</Accordions>

Initialize [#initialize]

Before using the Pixi’VN engine, you must initialize the game. You can do this by calling the [`Game.init`](/jsdoc/pixi-vn/index/namespaces/Game/functions/init) method.

```ts title="src/main.tsx"
import { Game } from "@drincs/pixi-vn";

const body = document.body;
if (!body) {
    throw new Error("body element not found");
}

Game.init(body, {
    height: 1080,
    width: 1920,
    backgroundColor: "#303030",
}).then(() => {
    // ...
    Game.start("start", {});
});

// read more here: https://pixi-vn.com/start/other-narrative-features.html#how-manage-the-end-of-the-game
Game.onEnd(async (props) => {
    Game.clear();
    // navigate to main menu
});

Game.addOnError((error, props) => {
    console.error(`Error occurred`, error);
});

Game.onNavigate((path) => navigateTo(path));
```

```html title="index.html"
<!doctype html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Game</title>
    </head>
    <body>
        <div id="root"></div>
        <script type="module" src="/src/main.ts"></script>
    </body>
</html>
```

```css title="styles.css"
html,
body {
    background-color: #242424;
    height: 100%;
}

body {
    margin: 0;
    min-height: 100vh;
    display: flex;
    overflow: hidden;
}
```