# Assets management (/start/assets-management)



To load and manipulate assets (images, gifs, videos, etc.) you will need to use `Assets`. `Assets` is a class with many features and comes from the PixiJS library. For more information, read [here](https://pixijs.com/8.x/guides/components/assets).

In all Pixi’VN functions, you can directly use the image URL, even if it is not defined in `Assets`.

```ts
let alien1 = await showImage("alien", "https://pixijs.com/assets/eggHead.png");
```

This method has some drawbacks:

* Changing the URL of an asset from one version to another may cause incompatibilities.
* The player will have to wait for a short loading time every time they press "continue" and a <DynamicLink href="/start/labels">`step`</DynamicLink> is started that uses assets.
* Writing the entire URL in code will increase its length and make it less readable.

For these reasons, it is recommended to handle assets in the following ways.

Initialize the asset matrix at project start [#initialize-the-asset-matrix-at-project-start]

Initializing the asset matrix at the beginning of the project allows you to reference assets by a unique alias without having to use the URL/path. Using the alias you can change the URL of an asset without having to worry about version compatibility.

To do this, it is recommended to create an asynchronous function `defineAssets` that will be called at the start of the project.
In the `defineAssets` function, use `Assets` (e.g. `Assets.add`, `Assets.addBundle`, and `Assets.init`) to assign aliases to URLs. You can find more information about them [here](https://pixijs.com/8.x/guides/components/assets) to assign an alias to each asset.

<CodeBlockTabs defaultValue="utils/defineAssets.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="utils/defineAssets.ts">
      utils/defineAssets.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="utils/defineAssets.ts">
    ```ts
    import { Assets, sound } from "@drincs/pixi-vn";
    import manifest from "../assets/manifest";

    export async function defineAssets() {
        // manifest
        await Assets.init({ manifest });
        // single asset
        Assets.add({ alias: 'eggHead', src: "https://pixijs.com/assets/eggHead.png" })
        Assets.add({ alias: 'flowerTop', src: "https://pixijs.com/assets/flowerTop.png" })
        Assets.add({ alias: 'video', src: "https://pixijs.com/assets/video.mp4" })
        sound.add('bird', 'https://pixijs.io/sound/examples/resources/bird.mp3');
        sound.add('musical', 'https://pixijs.io/sound/examples/resources/musical.mp3');
        // bundle
        Assets.addBundle('liam', {
            "liam-head": 'liam_head.png',
            "liam-body": 'liam_body.png',
            "liam-arms": 'liam_arms.png',
        });
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            // screens
            {
                name: "main_menu",
                assets: [
                    {
                        alias: "background_main_menu",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/main-menu.png",
                    },
                ],
            },
            // labels
            {
                name: "start",
                assets: [
                    {
                        alias: "bg01-hallway",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/bg01-hallway.webp",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Load assets [#load-assets]

By default, assets are loaded only when needed.

But **if the assets are not saved locally**, but in an <DynamicLink href="/start/assets#assets-hosting">"assets hosting"</DynamicLink>, their loading may take some time. This means that starting a `step` may not be immediate. So, after starting the execution of the <DynamicLink href="/start/labels-flow#continue">next `step`</DynamicLink> (for example with the "next" button), the player may have to wait some time to "view" the changes and be able to run another `step`.

Performing these loadings at each `step` may be annoying to the player, even if they are very short.

To solve this problem, the developer can group multiple loadings at a certain stage of the game. In this way, the player will not have continuous loadings, but fewer, even if longer.

Here are various ways to load the assets:

<Accordions>
  <Accordion title="load_assets_at_project_start" id="load-assets-at-project-start">
    It is possible to load assets at project startup before the player can interact with the project, for example during the startup loading screen. It is suggested to use this procedure only for assets used in the main page or for assets used frequently, and not to exceed 100MB.

    To do this, you must use the `Assets.load` function and wait for it to finish (with `await`) when the project starts. You can learn more about the `Assets.load` function [here](https://pixijs.com/8.x/guides/components/assets).

    <CodeBlockTabs defaultValue="utils/defineAssets.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="utils/defineAssets.ts">
          utils/defineAssets.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="utils/defineAssets.ts">
        ```ts
        import { Assets, sound } from "@drincs/pixi-vn";
        import manifest from "../assets/manifest";

        export async function defineAssets() {
            // manifest
            await Assets.init({ manifest });
            // single asset
            Assets.add({ alias: 'eggHead', src: "https://pixijs.com/assets/eggHead.png" })
            Assets.add({ alias: 'flowerTop', src: "https://pixijs.com/assets/flowerTop.png" })
            Assets.add({ alias: 'video', src: "https://pixijs.com/assets/video.mp4" })
            sound.add('bird', 'https://pixijs.io/sound/examples/resources/bird.mp3');
            sound.add('musical', 'https://pixijs.io/sound/examples/resources/musical.mp3');
            // bundle
            Assets.addBundle('liam', {
                "liam-head": 'liam_head.png',
                "liam-body": 'liam_body.png',
                "liam-arms": 'liam_arms.png',
            });

            // The game will not start until these assets are loaded. // [!code focus]
            await Assets.load('eggHead') // [!code focus]
            await Assets.loadBundle('liam') // [!code focus]
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                // screens
                {
                    name: "main_menu",
                    assets: [
                        {
                            alias: "background_main_menu",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/main-menu.png",
                        },
                    ],
                },
                // labels
                {
                    name: "start",
                    assets: [
                        {
                            alias: "bg01-hallway",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/bg01-hallway.webp",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="load_assets_in_the_background_at_project_start" id="load-assets-in-the-background-at-project-start">
    It is possible to load assets in the background when the project starts, reducing loading times when your project starts. It is recommended not to exceed 2GB.

    To do this, you can use the `Assets.backgroundLoad` function when the project starts. You can learn more about the `Assets.backgroundLoad` function [here](https://pixijs.com/8.x/guides/components/assets).

    <CodeBlockTabs defaultValue="utils/defineAssets.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="utils/defineAssets.ts">
          utils/defineAssets.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="utils/defineAssets.ts">
        ```ts
        import { Assets, sound } from "@drincs/pixi-vn";
        import manifest from "../assets/manifest";

        export async function defineAssets() {
            // manifest
            await Assets.init({ manifest });
            // single asset
            Assets.add({ alias: 'eggHead', src: "https://pixijs.com/assets/eggHead.png" })
            Assets.add({ alias: 'video', src: "https://pixijs.com/assets/video.mp4" })
            sound.add('bird', 'https://pixijs.io/sound/examples/resources/bird.mp3');
            sound.add('musical', 'https://pixijs.io/sound/examples/resources/musical.mp3');
            // bundle
            Assets.addBundle('liam', {
                "liam-head": 'liam_head.png',
                "liam-body": 'liam_body.png',
                "liam-arms": 'liam_arms.png',
            });

            // The game will not start until these assets are loaded.
            await Assets.load('eggHead')

            // The game will start immediately, but these assets will be loaded in the background. // [!code focus]
            Assets.backgroundLoadBundle(['liam']); // [!code focus]
            // Load an individual asset in the background // [!code focus]
            Assets.backgroundLoad({ alias: 'flowerTop', src: 'https://pixijs.com/assets/flowerTop.png' }); // [!code focus]
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                // screens
                {
                    name: "main_menu",
                    assets: [
                        {
                            alias: "background_main_menu",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/main-menu.png",
                        },
                    ],
                },
                // labels
                {
                    name: "start",
                    assets: [
                        {
                            alias: "bg01-hallway",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/bg01-hallway.webp",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="load_assets_at_label_start" id="load-assets-at-label-start">
    <Callout title="ink" type="info">
      You can use this method with the *ink* syntax. See more <DynamicLink href="/ink/assets">here</DynamicLink>.
    </Callout>

    To group the loadings from one `step` to another of a `label` into a single loading, it is possible to load all or part of the assets used by the `label` before it starts. Since this does not reduce the waiting times for the player, but adds them to a single loading, it is recommended to [load them in the background](#load-assets-in-the-background-at-label-start).

    To do this, you must use the `Assets.load` function and wait for it to finish (with `await`) when the `label` starts. You will use the <DynamicLink href="/start/labels-advanced#onloadinglabel">`onLoadingLabel`</DynamicLink> function.

    For cleaner code, it is recommended to define a bundle in your manifest with the id corresponding to the `label` id and define within it the assets that will be used in that `label`.

    ```ts title="labels/startLabel.ts"
    import { newLabel, showImage, Assets } from "@drincs/pixi-vn";

    const startLabel = newLabel("start", [
        () => {
            await showImage("eggHead")
        },
        () => {
            await showImage("flowerTop")
        },
    ], {
        onLoadingLabel: async (_stepId, label) => { // [!code focus]
            // The label will not start until these assets are loaded. // [!code focus]
            await Assets.loadBundle(label.id) // [!code focus]
        } // [!code focus]
    })
    export default startLabel;
    ```

    <CodeBlockTabs defaultValue="assets/manifest.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";
        import startLabel from "../labels/startLabel";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                // labels
                {
                    name: startLabel.id,
                    assets: [
                        {
                            alias: "eggHead",
                            src: "https://pixijs.com/assets/eggHead.png",
                        },
                        {
                            alias: "flowerTop",
                            src: "https://pixijs.com/assets/flowerTop.png",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="load_assets_in_the_background_at_label_start" id="load-assets-in-the-background-at-label-start">
    <Callout title="Already present in the templates" type="info">
      In all templates, when a `label` is started, the background loading of the bundle (if it exists) with the id corresponding to the `label` will be started. So, it is enough to &#x2A;*create a manifest with a bundle for each `label`**. Here is the implementation used to allow this:

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

      Game.onLoadingLabel((_stepId, { id }) => Assets.backgroundLoadBundle(id));
      ```
    </Callout>

    To make the game smoother by trying to remove asset loading times from one `step` to another, it is possible to start a "loading group" at the beginning of a `label`. This means that you may potentially not feel any loading, especially in the later `steps` of the `label`.

    To do this, you can use the `Assets.backgroundLoad` function when the `label` starts. You can learn more about the `Assets.backgroundLoad` function [here](https://pixijs.com/8.x/guides/components/assets). And, you will use the <DynamicLink href="/start/labels-advanced#onloadinglabel">`onLoadingLabel`</DynamicLink> function.

    For cleaner code, it is recommended to define a bundle in your manifest with the id corresponding to the `label` id and define within it the assets that will be used in that `label`.

    ```ts title="labels/startLabel.ts"
    import { newLabel, showImage, Assets } from "@drincs/pixi-vn";

    const startLabel = newLabel("start", [
        () => {
            await showImage("eggHead")
        },
        () => {
            await showImage("flowerTop")
        },
    ], {
        onLoadingLabel: async (_stepId, label) => { // [!code focus]
            // The label will start immediately, but these assets will be loaded in the background. // [!code focus]
            Assets.backgroundLoadBundle(label.id) // [!code focus]
        } // [!code focus]
    })
    export default startLabel;
    ```

    <CodeBlockTabs defaultValue="assets/manifest.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";
        import startLabel from "../labels/startLabel";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                // labels
                {
                    name: startLabel.id,
                    assets: [
                        {
                            alias: "eggHead",
                            src: "https://pixijs.com/assets/eggHead.png",
                        },
                        {
                            alias: "flowerTop",
                            src: "https://pixijs.com/assets/flowerTop.png",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>
</Accordions>


# Assets (/start/assets)









**What are assets?** Assets are all files that are not code, such as images, sounds, and videos.

You can use assets saved locally in the project or online (for the second option, you need to make sure that the cloud service you are using allows *CORS requests*). If your assets are online, your game will require an internet connection. You should notify the user and block the game if there is no connection.

If you are creating a visual novel, it is recommended to keep frequently used assets locally. For assets used only once in the game, it is better to publish them online.

To load and manipulate assets (images, gifs, videos, etc.) you will need to use `Assets`. `Assets` is a class with many features and comes from the PixiJS library. For more information, read [here](https://pixijs.com/8.x/guides/components/assets). It is also very important that you read this documentation to better <DynamicLink href="/start/assets-management">organize the uploading of your assets</DynamicLink>.

You mainly have two choices for where to save your assets: locally or online.

Local assets [#local-assets]

To save and use assets locally, you can use any folder—there are no restrictions. However, it is recommended to use the `assets` folder. Inside this folder, you can create subfolders to better organize your assets.

Here is an example of how to import and load an asset into your project:

```ts title="utils/assets.ts"
import { Assets } from "@drincs/pixi-vn";
import bg01hallway from "../assets/images/bg01-hallway.webp";

Assets.add({
    alias: "bg01-hallway",
    src: bg01hallway,
});
```

<Accordions>
  <Accordion title="pixijs_assetpack" id="pixijs-assetpack">
    AssetPack is a tool for optimizing local assets for the web. It can be used to transform, combine, and compress assets.

    If you want to use AssetPack, you can find the documentation [here](https://pixijs.io/assetpack).
  </Accordion>
</Accordions>

Assets hosting [#assets-hosting]

You can save your assets online. This is a good option if you want to save space on your computer. You can use any cloud service that allows you to upload files and generate a public URL (CORS enabled).

Here is an example of how to import and load an asset into your project:

```ts title="utils/assets.ts"
import { Assets } from "@drincs/pixi-vn";

Assets.add({
    alias: "bg01-hallway",
    src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/bg01-hallway.webp",
});
```

You can save your assets as you like, with complete freedom. If you plan to save your assets online, here are some of the options:

<Accordions>
  <Accordion title="github" id="github">
    You can use Github to host your assets. You can use the raw link of the file in your project. The link will be in the following format:

    ```text
    https://raw.githubusercontent.com/[repository]/raw/refs/heads/main/[file path]
    ```

    * **Price**: Completely free.
    * **Space limits**: No space limits, but each single file must not exceed 100 MB.
    * **Type of files**: You can upload any type of file.
    * **Traffic**: Speed is not the best.
    * **Edit assets**: You can edit the file while keeping the same URL.
  </Accordion>

  <Accordion title="image_hosting" id="image-hosting">
    Image hosting is a service that allows you to upload images. There are many sites to upload images for free, for example [imgbb](https://imgbb.com/), [imgix](https://www.imgix.com/), [imgur](https://imgur.com/). You can use the link of the image in your project.

    * **Price**: Completely free, but you can pay for more features.
    * **Space limits**: No space limits, but each single file can have a maximum size.
    * **Type of files**: You can upload only images.
    * **Traffic**: Speed is good.
    * **Edit assets**: You can't edit the file while keeping the same URL.
  </Accordion>

  <Accordion title="cloud_storage" id="Cloud-storage">
    Cloud storage is a service that allows you to upload files online.

    * **Price**: Usually paid or with a free version with limits.
    * **Space limits**: Monthly cost based on space used (usually free if you do not exceed a certain threshold).
    * **Type of files**: You can upload any type of file.
    * **Traffic**: Speed is good.
    * **Edit assets**: You can edit the file while keeping the same URL.

    Here is a list of some of the most popular cloud storage services:

    * <img alt="firebase-text" src="__img0" /> **Firebase Storage** is a cloud service that is very easy to use. Firebase has two plans: Spark (free) and Blaze (pay as you go). You can find more information [here](https://firebase.google.com/pricing).\
      **Solving Firebase Storage CORS Issue**:
      * Install [gcloud CLI](https://cloud.google.com/sdk/docs/install)
      * Read this [documentation](https://medium.com/@we.viavek/setting-cors-in-firebase-19a2cce2fe28) to solve the CORS issue.
    * <img alt="aws-text" src="__img1" /> **Amazon S3** is a cloud service. Compared to its competitors, it has many settings, but it may be more difficult to use. There is a payment plan to use Amazon S3. You can find more information [here](https://aws.amazon.com/s3/pricing/).
    * <img alt="supabase-text" src="__img2" /> **Supabase** is an open-source Firebase alternative. Supabase has two plans: Free and Pay as you go. You can find more information [here](https://supabase.io/pricing).
    * **Convex** is a cloud service that allows you to store and serve user-generated content, such as photos, videos, or other files. Convex has two plans: Free and Pay as you go. You can find more information [here](https://www.convex.dev/pricing).
  </Accordion>
</Accordions>

Other features [#other-features]

<Accordions>
  <Accordion title="caching_assets" id="caching-assets">
    <Callout title="Templates" type="info">
      In all templates, a service worker is included to cache external assets (images, sounds, videos, etc.) used in your game. This improves performance and reduces loading times for players.
    </Callout>

    For assets hosted online, the service worker caches them locally on the user's device after the first download. This means that subsequent requests for the same asset will be served from the cache, resulting in faster load times and reduced data usage.

    <CodeBlockTabs defaultValue="public/service-worker.js">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="public/service-worker.js">
          public/service-worker.js
        </CodeBlockTabsTrigger>

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

      <CodeBlockTab value="public/service-worker.js">
        ```js
        const CACHE_NAME = "external-assets-v1";
        const MAX_AGE_DAYS = 7;
        const MAX_AGE_MS = MAX_AGE_DAYS * 24 * 60 * 60 * 1000;

        const lastUsed = {};

        // The fetch event handler below implements a simple cache-for-host strategy:
        // - It only attempts to cache responses for requests whose hostname is explicitly allowed in the switch below.
        // - Cached entries are kept in the "external-assets-v1" cache and tracked via `lastUsed` timestamps.
        // - If a cached response exists and is not older than MAX_AGE_DAYS, it is served directly.
        // - Otherwise the service worker fetches from the network, caches the successful response, and returns it.
        // - If the network fails and a cached response exists, the cached response is returned as a fallback.
        // NOTE: Add the hostnames of external asset providers you want to cache (CDNs, raw asset hosts, etc.) in the switch below.
        self.addEventListener("fetch", (event) => {
            const request = event.request;
            const url = new URL(request.url);

            switch (url.hostname) {
                case "raw.githubusercontent.com":
                    break;
                // Add asset hostnames here to enable caching for them.
                // Examples:
                // case "raw.githubusercontent.com":
                // case "cdn.jsdelivr.net":
                // case "your.cdn.domain.com":
                //     break;
                default:
                    return;
            }

            event.respondWith(
                (async () => {
                    const cache = await caches.open(CACHE_NAME);
                    const now = Date.now();
                    const cached = await cache.match(request);

                    if (cached && lastUsed[url.href]) {
                        const age = now - lastUsed[url.href];
                        if (age < MAX_AGE_MS) {
                            lastUsed[url.href] = now;
                            return cached;
                        }
                        await cache.delete(request);
                        delete lastUsed[url.href];
                    }

                    try {
                        const response = await fetch(request);
                        if (response && response.type === "cors" && response.status < 400) {
                            await cache.put(request, response.clone());
                            lastUsed[url.href] = now;
                        }
                        return response;
                    } catch (err) {
                        if (cached) return cached;
                        return fetch(request);
                    }
                })()
            );
        });
        ```
      </CodeBlockTab>

      <CodeBlockTab value="main.ts">
        ```ts
        // Register service worker
        if ("serviceWorker" in navigator) {
            window.addEventListener("load", () => {
                navigator.serviceWorker.register("/service-worker.js").catch(console.error);
            });
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>
</Accordions>


# Canvas component aliases (/start/canvas-alias)





Each component added into the canvas must be assigned an alias. An alias is a way to refer to a component by a unique string.

If a component is added by assigning an existing alias, the new component will replace the old one.

The alias corresponds to `PixiJSComponent.label`, so do not change the `label`, but use the <DynamicLink href="/start/canvas-functions">methods provided by Pixi’VN</DynamicLink> to change the alias.

Heredity factor [#heredity-factor]

If a component is added using an existing alias, the new component, in addition to replacing the old one, will inherit the properties, the `zIndex`, and the <DynamicLink href="/start/canvas-tickers">tickers</DynamicLink> of the old component.

<HeredityFactorExample />

Edit canvas component alias [#edit-canvas-component-alias]

To edit the alias of a canvas component, you can use `canvas.editAlias`. If the alias has one or more <DynamicLink href="/start/canvas-tickers">tickers</DynamicLink> associated, it will be automatically updated in the ticker.

The `editAlias` method has the following parameters:

* `oldAlias`: The old alias of the component to edit.
* `newAlias`: The new alias of the component.

```typescript
import { canvas } from '@drincs/pixi-vn'

canvas.editAlias('sprite1', 'sprite2')
```

Game layer alias [#game-layer-alias]

In Pixi’VN, the game layer is a special component that represents the main game area where all the game elements are rendered.

This component has been assigned a special alias, `const CANVAS_APP_GAME_LAYER_ALIAS = "__game_layer__"`, which is used to reference the game layer in the script.

This is very useful if you want to run some <DynamicLink href="/start/canvas-animations-effects">animations or effects</DynamicLink> on the entire layer. Some features are not allowed on this item, such as deletion.

```typescript
import { CANVAS_APP_GAME_LAYER_ALIAS, shakeEffect } from '@drincs/pixi-vn'

shakeEffect(CANVAS_APP_GAME_LAYER_ALIAS)
```


# Animations and transitions (/start/canvas-animations-effects)



Animations are a key part of any video game, helping to create a more engaging and immersive experience. In Pixi’VN, animations are managed using tickers and the `animate` function.

The <DynamicLink href="/start/canvas-motion">`animate`</DynamicLink> function is a wrapper around the [`motion`](https://motion.dev/) library, providing a simple yet powerful way to animate canvas components. You can define animations with properties such as duration, `easing`, and more.

Pixi’VN also provides several functions to perform <DynamicLink href="/start/canvas-transition">transitions</DynamicLink> between `steps`. All transitions are built on top of the `animate` function, making it easy to create custom transitions as well.

All animations in Pixi’VN are triggered by <DynamicLink href="/start/canvas-tickers">tickers</DynamicLink>, which are classes that run on every frame and execute functions leveraging PixiJS.


# Articulated animations (/start/canvas-articulated-animations-effects)





Articulated animations are functions that use the <DynamicLink href="/start/canvas-alias">`canvas.animate`</DynamicLink> function to create animations that can be applied to canvas components. These functions are typically used to create effects like shaking, bouncing, or other complex animations that involve multiple steps or components.

Shake [#shake]

The `shakeEffect` function is an articulated animation that shakes a component.
This function has the following parameters:

* `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component.
* `options` (Optional): Animation options, matching the <DynamicLink href="/start/canvas-motion">`options` of animate function</DynamicLink>. Additional properties:
  * `shocksNumber` (Optional): The number of shocks.
  * `shakeType` (Optional): The type of shake effect. Possible values are `vertical` and `horizontal`.
  * `maxShockSize` (Optional): The maximum size of the shock.
* `priority` (Optional): The priority of the PixiJS ticker. This parameter sets the ticker's priority. The default is `UPDATE_PRIORITY.NORMAL`.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { CANVAS_APP_GAME_LAYER_ALIAS, newLabel, shakeEffect, showImage } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            await showImage("bg", "bg", { scale: 1.3 });
            await showImage("alien", "alien", { align: 0.5 });
            shakeEffect("alien"); // [!code focus]
        },
        async () => {
            shakeEffect(CANVAS_APP_GAME_LAYER_ALIAS); // [!code focus]
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "alien",
                        src: "https://pixijs.com/assets/eggHead.png",
                    },
                    {
                        alias: "bg",
                        src: "https://pixijs.com/assets/bg_grass.jpg",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<ShakeExample />


# Canvas components (/start/canvas-components)



Pixi’VN provides a set of canvas components. These components extend the [Pixi.js](https://pixijs.com/) components, adding various features, such as the ability to save their current state.

**What are canvas components?** Components are reusable building blocks for canvas apps, allowing app makers to create custom controls to use inside an app or across apps using a component library. Components can use advanced features such as custom properties and enable complex capabilities.

Base components [#base-components]

The available components are:

* `Sprite` corresponds to the component [`PixiJS.Sprite`](https://pixijs.com/8.x/guides/components/sprites).
* `Container` corresponds to the component [`PixiJS.Container`](https://pixijs.com/8.x/guides/components/containers).
* <DynamicLink href="/start/canvas-image">ImageSprite</DynamicLink> is a component introduced by Pixi’VN.
* <DynamicLink href="/start/canvas-image-container">ImageContainer</DynamicLink> is a component introduced by Pixi’VN.
* <DynamicLink href="/start/canvas-video">VideoSprite</DynamicLink> is a component introduced by Pixi’VN.
* <DynamicLink href="/start/canvas-text">Text</DynamicLink> is a component introduced by Pixi’VN.

Custom components [#custom-components]

You can create custom components by extending the base components. To do this, you need to use the decorator `@canvasComponentDecorator`.

`@canvasComponentDecorator` is a decorator that saves the canvas component in memory (<DynamicLink href="/faq#enable-typescript-decorators">How to enable decorators in TypeScript?</DynamicLink>). This function has the following parameters:

* `name`: The id used by Pixi’VN to refer to this class (must be unique). If you don't pass the id, the class name will be used as the id.
* `getInstance`: A function that returns an instance of the canvas component. This function is used when the canvas state is reset.
* `copyProperty`: A function that copies the properties of the canvas component. This function is used when copying the properties of the canvas component into another instance of the same canvas component.

It is necessary to override the `memory` property to store the custom component properties.
In `get memory()`, it is very important to return the `className` property; this property must be equal to the id used in the decorator.

For example, you can create an `AlienTinting` class that extends the `Sprite` class to manage the direction and speed of each individual alien in an animation.

```ts title="canvas/components/AlienTinting.ts"
const ALIEN_TINTING_TEST_ID = "AlienTintingTest"
@canvasComponentDecorator({
    name: ALIEN_TINTING_TEST_ID,
})
class AlienTintingTest extends Sprite<IAlienTintingMemory> {
    readonly pixivnId: string = CANVAS_SPINE_ID;
    override get memory() {
        return {
            ...super.memory,
            pixivnId: CANVAS_SPINE_ID,
            direction: this.direction,
            turningSpeed: this.turningSpeed,
            speed: this.speed,
        }
    }
    override async setMemory(memory: IAlienTintingMemory) {
        await super.setMemory(memory)
        this.direction = memory.direction
        this.turningSpeed = memory.turningSpeed
        this.speed = memory.speed
    }
    direction: number = 0
    turningSpeed: number = 0
    speed: number = 0
    static override from(source: Texture | TextureSourceLike, skipCache?: boolean) {
        let sprite = Sprite.from(source, skipCache)
        let mySprite = new AlienTintingTest()
        mySprite.texture = sprite.texture
        return mySprite
    }
}
```


# Filters (/start/canvas-filters)



<Callout title="This page is under construction" type="warn">
  Currently, this functionality is not available in Pixi’VN, but we plan to implement it. If you are interested, feel free to write in the chat below!
</Callout>

Having the ability to filter the entire canvas or a specific component can be very useful in many cases.

<img alt="image" src="https://filters.pixijs.download/main/screenshots/shockwave.gif?v=3" width="280" height="140" />

The [PixiJS Filters](https://pixijs.io/filters/docs/) library provides this capability to PixiJS.


# Components functions (/start/canvas-functions)





Add [#add]

To add a component to the game canvas, you can use `canvas.add`.
This function has the following parameters:

* `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component.
* `component`: The component to add.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { Assets, canvas, newLabel, Sprite } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            const sprite = new Sprite();
            const texture = await Assets.load("egg_head");
            sprite.texture = texture;
            canvas.add("sprite", sprite); // [!code focus]
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "egg_head",
                        src: "https://pixijs.com/assets/eggHead.png",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<AddCanvasComponents />

Get [#get]

To get a component from the game canvas, you can use `canvas.find`. If the component does not exist, it will return `undefined`.
This function has the following parameters:

* `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { Assets, canvas, newLabel, Sprite } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            const sprite = new Sprite();
            const texture = await Assets.load("egg_head");
            sprite.texture = texture;
            canvas.add("sprite", sprite);
        },
        () => {
            const sprite = canvas.find("sprite"); // [!code focus]
            if (sprite) {
                sprite.x = 100;
                sprite.y = 100;
            }
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "egg_head",
                        src: "https://pixijs.com/assets/eggHead.png",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<GetCanvasComponents />

Remove [#remove]

To remove a component from the game canvas, you can use `canvas.remove`.
This function has the following parameters:

* `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { Assets, canvas, newLabel, Sprite } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            const sprite = new Sprite();
            const texture = await Assets.load("egg_head");
            sprite.texture = texture;
            canvas.add("sprite", sprite);
        },
        () => {
            canvas.remove("sprite"); // [!code focus]
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "egg_head",
                        src: "https://pixijs.com/assets/eggHead.png",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<RemoveCanvasComponents />

Remove all [#remove-all]

To remove all components from the game canvas, you can use `canvas.removeAll`.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { Assets, canvas, newLabel, Sprite } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            const texture = await Assets.load("egg_head");
            for (let i = 0; i < 3; i++) {
                const sprite = new Sprite();
                sprite.texture = texture;
                sprite.x = i * 150;
                canvas.add(`sprite${i}`, sprite);
            }
        },
        () => {
            canvas.removeAll(); // [!code focus]
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "egg_head",
                        src: "https://pixijs.com/assets/eggHead.png",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<RemoveAllCanvasComponents />

Add a listener to an event [#add-a-listener-to-an-event]

<Callout type="info">
  If possible, try using <DynamicLink href="/start/interface">HTML and PixiJS UI</DynamicLink> to add buttons or other elements with events.
</Callout>

In Pixi’VN, compared to PixiJS, you can use a [listener with the `on` method](https://pixijs.com/8.x/examples/events/click) (for example to make it clickable), but if you don't use the `@eventDecorator` decorator, the event will not be registered in the Pixi’VN event system, so if you load a save where that event was used, it will be lost.

`@eventDecorator` is a decorator that saves the event in memory (<DynamicLink href="/faq#enable-typescript-decorators">How to enable decorators in TypeScript?</DynamicLink>). This function has the following parameters:

* `name`: The id used by Pixi’VN to refer to this function (must be unique). If you don't pass the id, the function name will be used as the id.

<CodeBlockTabs defaultValue="canvas/events.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="canvas/events.ts">
      canvas/events.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="canvas/events.ts">
    ```ts
    import { eventDecorator, FederatedEvent, Sprite } from "@drincs/pixi-vn";

    export default class Events {
        @eventDecorator()
        static buttonEvent(event: FederatedEvent, sprite: Sprite): void {
            switch (event.type) {
                case "pointerdown":
                sprite.scale.x *= 1.25;
                sprite.scale.y *= 1.25;
                break;
            }
        }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { newLabel, showImage } from "@drincs/pixi-vn";
    import Events from "../canvas/events";

    export const startLabel = newLabel("start_label", [
        async () => {
            const bunny = await showImage("bunny", "bunny", {
                align: 0.5,
                anchor: 0.5,
            });
            // Opt-in to interactivity
            bunny.eventMode = "static";
            // Shows hand cursor
            bunny.cursor = "pointer";
            // Pointers normalize touch and mouse (good for mobile and desktop)
            bunny.on("pointerdown", Events.buttonEvent);
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [{ alias: "bunny", src: "https://pixijs.com/assets/bunny.png" }],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<AddListenerGivenEvent />

<Comments>
  TODO ### access to PIXI.Application
</Comments>


# ImageContainer (/start/canvas-image-container)





The `ImageContainer` component extends the [`PixiJS.Container`](https://pixijs.com/8.x/guides/components/containers) component, so you can use all the methods and properties of `PixiJS.Container`. It allows you to group multiple images into a single component and manipulate them as one.

The children of the `ImageContainer` are <DynamicLink href="/start/canvas-image">`ImageSprite`</DynamicLink> components.

To initialize this component, you must pass the following parameters:

* `options` (Optional): The options for the component.
* `imageUrls` (Optional): An array of image URLs or paths. If you have initialized the <DynamicLink href="/start/assets-management#initialize-the-asset-matrix-at-project-start">asset matrix</DynamicLink>, you can use the alias of the texture.

```ts
import { canvas, ImageContainer } from "@drincs/pixi-vn"

let james = new ImageContainer({
    anchor: { x: 0.5, y: 0.5 },
    x: 100,
    y: 100,
}, [
    'https://image.com/body.webp',
    'https://image.com/head.webp',
    'https://image.com/eyes.webp',
])

await james.load()
canvas.add("james", james)
```

Compared to the `Container` component, `ImageContainer` adds the following features:

* `load()`: Loads all image URLs and sets the resulting textures in the children.
* Additional positioning: <DynamicLink href="/start/canvas-position">align and position with percentage</DynamicLink>.

Show [#show]

The simplest way to show a group of images on the canvas is to use the `showImageContainer` function. This function combines `load` and <DynamicLink href="/start/canvas-functions#add-a-canvas-component">`canvas.add`</DynamicLink>.

This function returns an `ImageContainer` that you can use to manipulate the component. This function has the following parameters:

* `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component.
* `imageUrls` (Optional): An array of image URLs or paths. If you have initialized the <DynamicLink href="/start/assets-management#initialize-the-asset-matrix-at-project-start">asset matrix</DynamicLink>, you can use the alias of the texture.
* `options` (Optional): The options for the component.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { canvas, ImageContainer, newLabel, showImageContainer } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            let james = await showImageContainer("james", ["m01-body", "m01-eyes", "m01-mouth"], { // [!code focus]
                xAlign: 0.5, // [!code focus]
                yAlign: 1, // [!code focus]
            }); // [!code focus]
        },
        () => {
            canvas.removeAllTickers();
            let tickerId = canvas.animate<ImageContainer>("james", { xAlign: 0, yAlign: 1 });
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "m01-body",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-body.webp",
                    },
                    {
                        alias: "m01-eyes",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-eyes-smile.webp",
                    },
                    {
                        alias: "m01-mouth",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-smile00.webp",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<ShowImageContainerExample />

Add [#add]

To add a group of images to the canvas, use the `addImageCointainer` function. This function only adds the component to the canvas; it does **not** show it or load its texture. It uses <DynamicLink href="/start/canvas-functions#add-a-canvas-component">`canvas.add`</DynamicLink> to add the component to the canvas.

This function returns an `ImageContainer` that you can use to manipulate the component. This function has the following parameters:

* `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component.
* `imageUrls` (Optional): An array of image URLs or paths. If you have initialized the <DynamicLink href="/start/assets-management#initialize-the-asset-matrix-at-project-start">asset matrix</DynamicLink>, you can use the alias of the texture.
* `options` (Optional): The options for the component.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { addImageCointainer, canvas, ImageContainer, newLabel } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        () => {
            let james = await addImageCointainer("james", ["m01-body", "m01-eyes", "m01-mouth"], { // [!code focus]
                xAlign: 0.5, // [!code focus]
                yAlign: 1, // [!code focus]
            }); // [!code focus]
        },
        async () => {
            let james = canvas.find<ImageContainer>("james");
            james && (await james.load());
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "m01-body",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-body.webp",
                    },
                    {
                        alias: "m01-eyes",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-eyes-smile.webp",
                    },
                    {
                        alias: "m01-mouth",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-smile00.webp",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<AddImageContainerExample />

Remove [#remove]

As with other canvas components, you can remove this component using the <DynamicLink href="/start/canvas-functions#remove-a-canvas-component">`canvas.remove`</DynamicLink> function.


# ImageSprite (/start/canvas-image)





The `ImageSprite` component extends the [`PixiJS.Sprite`](https://pixijs.com/8.x/guides/components/sprites) component, so you can use all the methods and properties of `PixiJS.Sprite`. It is used to display a single image on the canvas.

To initialize this component, you must pass the following parameters:

* `options` (Optional): The options for the component.
* `imageUrl` (Optional): The URL or path. If you have initialized the <DynamicLink href="/start/assets-management#initialize-the-asset-matrix-at-project-start">asset matrix</DynamicLink>, you can use the alias of the texture.

```ts
import { canvas, ImageSprite } from "@drincs/pixi-vn"

let alien = new ImageSprite({
    anchor: { x: 0.5, y: 0.5 },
    x: 100,
    y: 100,
}, 'https://pixijs.com/assets/eggHead.png')

await alien.load()
canvas.add("alien", alien)
```

Compared to the `Sprite` component, `ImageSprite` adds the following features:

* `load()`: Loads the image URL and sets the resulting texture to the component.
* Additional positioning: <DynamicLink href="/start/canvas-position">align and position with percentage</DynamicLink>.

Show [#show]

The simplest way to show an image on the canvas is to use the `showImage` function. This function combines `load` and <DynamicLink href="/start/canvas-functions#add-a-canvas-component">`canvas.add`</DynamicLink>.

This function returns an `ImageSprite` that you can use to manipulate the component. This function has the following parameters:

* `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component.
* `imageUrl` (Optional): The URL or path. If you have initialized the <DynamicLink href="/start/assets-management#initialize-the-asset-matrix-at-project-start">asset matrix</DynamicLink>, you can use the alias of the texture. If you don't provide the URL, then the alias is used as the URL.
* `options` (Optional): The options for the component.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { newLabel, showImage } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            let alien1 = await showImage("alien"); // [!code focus]
            let alien2 = await showImage("alien2", "alien", { // [!code focus]
                xAlign: 0.5, // [!code focus]
            }); // [!code focus]
            let alien3 = await showImage("alien3", "https://pixijs.com/assets/eggHead.png", { // [!code focus]
                xAlign: 1, // [!code focus]
            }); // [!code focus]
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "alien",
                        src: "https://pixijs.com/assets/eggHead.png",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<ImageSpriteShow />

Add [#add]

To add an image to the canvas, use the `addImage` function. This function only adds the component to the canvas; it does **not** show it or load its texture. It uses <DynamicLink href="/start/canvas-functions#add-a-canvas-component">`canvas.add`</DynamicLink> to add the component to the canvas.

This function returns an `ImageSprite` that you can use to manipulate the component. This function has the following parameters:

* `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component.
* `imageUrl` (Optional): The URL or path. If you have initialized the <DynamicLink href="/start/assets-management#initialize-the-asset-matrix-at-project-start">asset matrix</DynamicLink>, you can use the alias of the texture. If you don't provide the URL, then the alias is used as the URL.
* `options` (Optional): The options for the component.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { addImage, canvas, ImageSprite, newLabel } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        () => {
            let alien1 = addImage("alien"); // [!code focus]
            let alien2 = addImage("alien2", "alien", { // [!code focus]
                xAlign: 0.5, // [!code focus]
            }); // [!code focus]
            let alien3 = addImage("alien3", "https://pixijs.com/assets/eggHead.png", { // [!code focus]
                xAlign: 1, // [!code focus]
            }); // [!code focus]
        },
        async () => {
            let alien1 = canvas.find<ImageSprite>("alien");
            let alien2 = canvas.find<ImageSprite>("alien2");
            let alien3 = canvas.find<ImageSprite>("alien3");
            // Load the textures
            alien1 && (await alien1.load());
            alien2 && (await alien2.load());
            alien3 && (await alien3.load());
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "alien",
                        src: "https://pixijs.com/assets/eggHead.png",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<ImageSpriteAdd />

Remove [#remove]

As with other canvas components, you can remove this component using the <DynamicLink href="/start/canvas-functions#remove-a-canvas-component">`canvas.remove`</DynamicLink> function.


# Lights (/start/canvas-lights)



<Callout title="This page is under construction" type="warn">
  Currently, this functionality is not available in Pixi’VN, but we plan to implement it. If you are interested, feel free to write in the chat below!
</Callout>

Having the ability to create light and shadow effects can be very useful in many cases.

<img alt="357854550-af5a80c0-6996-4b74-a8b8-36b63c8b825c" src="https://github.com/user-attachments/assets/1ce47130-322e-4a62-96c0-b5513615545c" width="1026" height="762" />

The [PixiJS Lights](https://userland.pixijs.io/lights/docs/index.html) library provides this capability to PixiJS.


# Animate (motion) (/start/canvas-motion)





Pixi’VN allows developers to animate canvas components using a function called `animate`. This function is a re-implementation of the [`animate` function from the `motion` library](https://motion.dev/docs/animate), adapted to use PixiJS tickers for triggering animation events.

**What is `motion`?**\
`motion` is a popular JavaScript library that provides a simple and powerful way to create animations. You can read more about it [here](https://motion.dev/).

There are two variants of this function:

* `animate`: Intended for animating PixiJS or Pixi’VN elements used for <DynamicLink href="/start/interface-pixijs">UI</DynamicLink>. Pixi’VN does not save the current state of animations created with this function. Since it is identical to [motion’s animate function](https://motion.dev/docs/animate), it will not be explained further here.
* `canvas.animate`: Designed for animating Pixi’VN canvas components. It saves the current state of animations, allowing you to restore the state of an animation from a save. This function has some differences from the original `animate` function, which will be explained in detail below.

Use [#use]

The `canvas.animate` function works as follows:
The developer defines a component state to be reached (for example, its x-y position). Once the animation starts, an event is continuously triggered to update the component until it reaches the desired state. You can further customize the animation with various options.

This function has the following parameters:

* `components`: The PixiJS component(s) to animate. This can be a single component, an array of components, or a string representing the <DynamicLink href="/start/canvas-alias">component's alias</DynamicLink>.
* `keyframes`: This is an object containing the properties to animate and the values to reach.
* `options` (Optional): [`motion` options](https://motion.dev/docs/animate#options) for the animation, including duration, `easing`, and ticker. The following options extend those from `motion`:
  * `aliasToRemoveAfter` (Optional): An array of strings containing the aliases of the <DynamicLink href="/start/canvas-components">canvas components</DynamicLink> to remove after the animation completes.
  * `tickerIdToResume` (Optional): A string containing the ticker ID to resume after the animation completes.
  * `tickerAliasToResume` (Optional): If you want to resume tickers that were previously paused, provide the aliases of the canvas components whose tickers should be resumed.
  * `completeOnContinue` (Optional): A boolean indicating whether the animation must complete before the next `step` of the game. If `true`, the game will force the animation to finish before proceeding.
* `priority` (Optional): The priority of the PixiJS ticker. This parameter sets the ticker's priority. The default is `UPDATE_PRIORITY.NORMAL`.

The function returns the ID of the ticker created to animate the component(s).

Here are some examples:

<Accordions>
  <Accordion title="move" id="move">
    <CodeBlockTabs defaultValue="labels/startLabel.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="labels/startLabel.ts">
          labels/startLabel.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="labels/startLabel.ts">
        ```ts
        import { canvas, ImageSprite, newLabel, showImage } from "@drincs/pixi-vn";

        export const startLabel = newLabel("start_label", [
            async () => {
                const alien = await showImage("alien"); // [!code focus]
                canvas.animate(alien, { xAlign: 1, yAlign: 0 }, { ease: "easeOut" }); // [!code focus]
            },
            () => canvas.animate<ImageSprite>("alien", { xAlign: 1, yAlign: 1 }, { ease: "backOut" }), // [!code focus]
            () => canvas.animate<ImageSprite>("alien", { xAlign: 0, yAlign: 1 }, { ease: "circIn" }), // [!code focus]
            () => canvas.animate<ImageSprite>("alien", { xAlign: 0, yAlign: 0 }, { ease: "linear" }), // [!code focus]
        ]);
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        {
                            alias: "alien",
                            src: "https://pixijs.com/assets/eggHead.png",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <MoveExample />
  </Accordion>

  <Accordion title="rotate" id="rotate">
    <CodeBlockTabs defaultValue="labels/startLabel.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="labels/startLabel.ts">
          labels/startLabel.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="labels/startLabel.ts">
        ```ts
        import { canvas, newLabel, showImage } from "@drincs/pixi-vn";

        export const startLabel = newLabel("start_label", [
            async () => {
                const alien = await showImage("alien", "alien", { align: 0.5, anchor: 0.5 }); // [!code focus]
                canvas.animate(alien, { angle: 360 }, { duration: 1, type: "spring", repeat: Infinity, repeatDelay: 0.2 }); // [!code focus]
            },
        ]);
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        {
                            alias: "alien",
                            src: "https://pixijs.com/assets/eggHead.png",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <RotateExample />
  </Accordion>

  <Accordion title="fade" id="fade">
    <CodeBlockTabs defaultValue="labels/startLabel.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="labels/startLabel.ts">
          labels/startLabel.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="labels/startLabel.ts">
        ```ts
        import { canvas, newLabel, showImage } from "@drincs/pixi-vn";

        export const startLabel = newLabel("start_label", [
          async () => {
            const alien = await showImage("alien", "alien", { align: 0.5, anchor: 0.5, alpha: 0 }); // [!code focus]
            canvas.animate(alien, { alpha: 1 }, { ease: "linear", duration: 1 }); // [!code focus]
          },
        ]);
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        {
                            alias: "alien",
                            src: "https://pixijs.com/assets/eggHead.png",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <FadeExample />
  </Accordion>

  <Accordion title="zoom" id="zoom">
    <CodeBlockTabs defaultValue="labels/startLabel.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="labels/startLabel.ts">
          labels/startLabel.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="labels/startLabel.ts">
        ```ts
        import { canvas, newLabel, showImage } from "@drincs/pixi-vn";

        export const startLabel = newLabel("start_label", [
            async () => {
                const alien = await showImage("alien", "alien", { align: 0.5, anchor: 0.5, scale: 0 }); // [!code focus]
                canvas.animate(alien, { scaleX: 1, scaleY: 1 }, { ease: "circInOut", duration: 1 }); // [!code focus]
            },
        ]);
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        {
                            alias: "alien",
                            src: "https://pixijs.com/assets/eggHead.png",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ZoomExample />
  </Accordion>

  <Accordion title="mirror" id="mirror">
    <CodeBlockTabs defaultValue="labels/startLabel.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="labels/startLabel.ts">
          labels/startLabel.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="labels/startLabel.ts">
        ```ts
        import { canvas, newLabel, showImage } from "@drincs/pixi-vn";

        export const startLabel = newLabel("start_label", [
            async () => {
                const alien = await showImage("alien", "alien", { align: 0.5, anchor: 0.5 }); // [!code focus]
                canvas.animate(alien, { scaleX: -1 }); // [!code focus]
            },
            () => canvas.animate("alien", { scaleX: 1 }), // [!code focus]
        ]);
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        {
                            alias: "alien",
                            src: "https://pixijs.com/assets/eggHead.png",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <MirrorExample />
  </Accordion>
</Accordions>

Sequence [#sequence]

The `canvas.animate` function can also be used to create sequences of animations.

To create a sequence, you can pass arrays as properties values in the keyframes object. In this case, you can use the [`times` property](https://motion.dev/docs/animate#times) to specify the timing of each keyframe.

For example:

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { canvas, newLabel, showImage } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            const alien = await showImage("alien"); // [!code focus]
            canvas.animate( // [!code focus]
                alien, // [!code focus]
                { // [!code focus]
                    xAlign: [0, 1, 1, 0, 0], // [!code focus]
                    yAlign: [0, 0, 1, 1, 0], // [!code focus]
                }, // [!code focus]
                { repeat: Infinity, duration: 10 } // [!code focus]
            ); // [!code focus]
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "alien",
                        src: "https://pixijs.com/assets/eggHead.png",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<SequenceExample />

Timeline sequences [#timeline-sequences]

<Callout type="warn">
  This method has some limitations compared to the previous one, such as restrictions on the `repeat` property due to the original \`motion' library.
</Callout>

Another way to create animation sequences with `canvas.animate` is by using a [timeline](https://motion.dev/docs/animate#timeline-sequences). This is useful when you want to chain multiple animations that are not strictly linear. You can provide an array of keyframes, where each keyframe is an object with the properties to animate and their values, along with optional animation options.

For example:

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { canvas, newLabel, showImage } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            const alien = await showImage("alien"); // [!code focus]
            canvas.animate( // [!code focus]
                alien, // [!code focus]
                [ // [!code focus]
                    [{ xAlign: 0, yAlign: 0 }, { ease: "circInOut" }], // [!code focus]
                    [{ xAlign: 1, yAlign: 0 }, { ease: "backInOut" }], // [!code focus]
                    [{ xAlign: 1, yAlign: 1 }, { ease: "linear" }], // [!code focus]
                    [{ xAlign: 0, yAlign: 1 }, { ease: "anticipate" }], // [!code focus]
                    [{ xAlign: 0, yAlign: 0 }, { ease: "easeOut" }], // [!code focus]
                ], // [!code focus]
                { repeat: 10, duration: 10 } // [!code focus]
            ); // [!code focus]
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "alien",
                        src: "https://pixijs.com/assets/eggHead.png",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<MotionSequenceExample />

Methods [#methods]

The `canvas.animate` function is built on Pixi’VN Tickers, so you can use all the <DynamicLink href="/start/canvas-tickers-functions">functions available to control Pixi’VN Tickers</DynamicLink>.


# Properties for positioning (/start/canvas-position)





<Callout title="References and citations" type="info">
  Most of the texts and images on this page were copied from Position Properties – [Pos and Anchor](https://feniksdev.com/renpy-position-properties-pos-and-anchor/) and [align, xycenter, and offset](https://feniksdev.com/renpy-position-properties-align-xycenter-and-offset/). Feniks in these two pages explained very well the properties of Ren'Py positioning, common to many other canvases including Pixi’VN.
</Callout>

Before we get into the different positioning properties, note that Pixi’VN considers the default for all position properties to be `{ x: 0, y: 0 }`, which corresponds to the top-left of the element you’re positioning.

Positive numbers move the element to the right and down. So, something at a position of `{ x: 200, y: 300 }` in the game will be 200 pixels from the left edge of the screen and 300 pixels from the top edge of the screen. Negative numbers move the element left and up relative to their starting position.

[Position](#position-pixel) and [anchor](#anchor-and-pivot) are the main properties you use to move elements around on the screen. It’s important to understand how they work, because most other positioning properties act as some combination of these two.

Position (pixel) [#position-pixel]

Position is used to position the component using pixel units.

You can modify it with these properties:

* `x`: moves the component left-to-right (along the x-axis)
* `y`: moves the component top-to-bottom (along the y-axis)
* `position`: an object `{ x: number, y: number }`. You can also set both x and y to the same value, e.g. `component.position = 200`.

Anchor and pivot [#anchor-and-pivot]

The pivot is an offset, expressed in pixels, from the top-left corner of the component. If you have a component whose texture is 100px x 50px, and want to set the pivot point to the center of the image, you'd set your pivot to (50, 25) - half the width, and half the height.

Anchors are specified in percentages, from 0.0 to 1.0, in each dimension. It has the same utility as the pivot, but to deduce the point where it is located it calculates the percentage of the height and width of the texture. For example, to rotate around the center point of a texture using anchors, you'd set your component's anchor to (0.5, 0.5) - 50% in width and height. Anchors compared to Pivot are easier to use.

You can modify it with these properties:

* `anchor`: an object `{ x: number, y: number }`. You can also set both x and y to the same value, e.g. `conponent.anchor = 0.5`.
* `pivot`: is an object that corresponds to `{ x: number, y: number }`.

***

**What, exactly, is anchor/pivot?** Let’s think of it in terms of something you may be more familiar with. Instead of positioning an element on a screen, you are trying to pin a photo onto a cork board. You have three things:

* a cork board
* a push pin
* a photograph

Let’s pretend that 1mm is equal to 1 pixel on a computer screen.

<img alt="17351596389764883495402859713640" src="https://github.com/user-attachments/assets/becfa6ac-1156-49ad-8ceb-17b06627be7c" width="876" height="532" />

* The cork board is the screen, or the container you’re trying to position the element inside.
* The photograph is the element.
* Where you put the pin on the photo is the anchor/pivot of the photograph.
* Where you push the pin into on the cork board is the position of the photograph.

By default in Pixi’VN, the push pin always starts in the top left corner of the photo, so to speak. If you want the top-left corner of the photo 200mm from the left side of the cork board, you will put it at x 200. If you also want the top-left corner 300mm down from the top of the board, you will put it at y 300.

<img alt="17351597056618553068745888144175" src="https://github.com/user-attachments/assets/c6955336-1c30-4518-8f05-edd950a1227e" width="876" height="532" />

What if you want the center of the photo at 200mm x 300mm?

This means you need to move where the pin is relative to the photo. The pin will stay at the point (200, 300) on the cork board – you just need to center the photo around that point as well. This means you need to change the anchor/pivot of the photo.

To set the anchor point of the photo to the center of the photo, you can use anchor (0.5, 0.5) or pivot (100, 150)

Position with percentage [#position-with-percentage]

Pixi’VN introduces the ability to position a component by percentage. Its operation is very similar to that of html.

In practice, the percentage will be multiplied by the height or width of the parent component to calculate the position in pixels.

You can modify it with these properties:

* `percentageX`: for moving things left-to-right (along the x-axis)
* `percentageY`: for moving things top-to-bottom (along the y-axis).
* `percentagePosition`: an object `{ x: number, y: number }`. You can also set both x and y to the same value, e.g. `conponent.align = 0.5`.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { newLabel, showImage } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            await showImage("egg_head", "egg_head", {
                percentagePosition: 0.5,
                anchor: 0.5,
            });
            await showImage("flower_top", "flower_top", {
                percentagePosition: 0,
            });
            await showImage("panda", "panda", {
                percentageX: 1,
                percentageY: 0,
                anchor: { x: 1, y: 0 },
            });
            await showImage("skully", "skully", {
                percentageX: 0,
                percentageY: 1,
                anchor: { x: 0, y: 1 },
            });
            await showImage("helmlok", "helmlok", {
                percentagePosition: 1,
                anchor: 1,
            });
            await showImage("bunny", "bunny", {
                percentageX: 0.5,
                percentageY: 1,
                anchor: { x: 0.5, y: 1 },
            });
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    { alias: "egg_head", src: "https://pixijs.com/assets/eggHead.png" },
                    { alias: "flower_top", src: "https://pixijs.com/assets/flowerTop.png" },
                    { alias: "panda", src: "https://pixijs.com/assets/panda.png" },
                    { alias: "skully", src: "https://pixijs.com/assets/skully.png" },
                    { alias: "helmlok", src: "https://pixijs.com/assets/helmlok.png" },
                    { alias: "bunny", src: "https://pixijs.com/assets/bunny.png" },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<PositionwithpercentageExample />

Align [#align]

Until now we have seen positioning methods influenced by [anchor/pivot](#anchor-and-pivot). The disadvantage of these methods is that if for example you want to add your component to the center of the screen you will first have to set the anchor to 0.5 and then set the position to half the width and height of the screen. This is where the align property comes in.

Align is a feature originally created for &#x2A;**Ren'Py***, which was also introduced in Pixi’VN. Align combines [position](#position-pixel) and [anchor/pivot](#anchor-and-pivot) to give you a more intuitive way to position your components at the beginning, in the center or in the end of the screen.

Align are specified in percentages, from 0.0 to 1.0, in each dimension. For example if you use 0.25 as a percentage, your component will be positioned at 25% of the screen with anchor at 0.25.

The calculation that is used to calculate the location is the following:

```ts
myComponent.x = (align * (fatherComponent.width - myComponent.width)) + myComponent.pivot + (myComponent.anchor * myComponent.width)
myComponent.y = (align * (fatherComponent.height - myComponent.height)) + myComponent.pivot + (myComponent.anchor * myComponent.height)
```

You can modify it with these properties:

* `xAlign`: for moving things left-to-right (along the x-axis)
* `yAlign`: for moving things top-to-bottom (along the y-axis).
* `align`: an object `{ x: number, y: number }`. You can also set both x and y to the same value, e.g. `conponent.align = 0.5`.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { newLabel, showImage } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            await showImage("egg_head", "egg_head", { align: 0.5 });
            await showImage("flower_top", "flower_top", { align: 0 });
            await showImage("panda", "panda", { xAlign: 1, yAlign: 0 });
            await showImage("skully", "skully", { xAlign: 0, yAlign: 1 });
            await showImage("helmlok", "helmlok", { align: 1 });
            await showImage("bunny", "bunny", { xAlign: 0.5, yAlign: 1 });
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    { alias: "egg_head", src: "https://pixijs.com/assets/eggHead.png" },
                    { alias: "flower_top", src: "https://pixijs.com/assets/flowerTop.png" },
                    { alias: "panda", src: "https://pixijs.com/assets/panda.png" },
                    { alias: "skully", src: "https://pixijs.com/assets/skully.png" },
                    { alias: "helmlok", src: "https://pixijs.com/assets/helmlok.png" },
                    { alias: "bunny", src: "https://pixijs.com/assets/bunny.png" },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<AlignExample />


# Spine 2D (/start/canvas-spine2d)





<Callout title="This page is under construction" type="warn">
  This library is currently in **testing phase**, so it may change significantly between versions.
</Callout>

**What is Spine 2D?** Spine 2D is a powerful 2D animation software specifically designed for game development. It uses a skeletal animation system, meaning that characters and objects are animated through a hierarchy of **bones** that control the movement of attached parts.

You can learn more about Spine 2D on the [official Spine 2D website](https://it.esotericsoftware.com/).

Within your **Pixi’VN** project, you can use the Spine 2D integration to create complex and smooth animations for your characters and objects.\
This integration is essentially a wrapper around the official [Spine 2D runtime for PixiJS](https://it.esotericsoftware.com/spine-pixi), allowing you to use all Spine 2D features directly inside your Pixi’VN project.

Why? [#why]

By using the Spine 2D integration in Pixi’VN, you can easily add animated components while taking advantage of both Pixi’VN and Spine 2D features, such as:

* Saving the current animation state within game save files.
* Using the <DynamicLink href="/start/canvas-position">additional Pixi’VN positioning properties</DynamicLink>.
* Starting animation sequences quickly and easily.
* Accessing additional features shared with other Pixi’VN components.

Installation [#installation]

To install the Spine 2D package in an existing JavaScript project, use one of the following commands:

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

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

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

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

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

  <CodeBlockTab value="npm">
    ```sh
    npm install @drincs/pixi-vn-spine
    ```
  </CodeBlockTab>

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

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

  <CodeBlockTab value="bun">
    ```sh
    bun add @drincs/pixi-vn-spine
    ```
  </CodeBlockTab>

  <CodeBlockTab value="deno">
    ```sh
    deno install npm:@drincs/pixi-vn-spine
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Initialize [#initialize]

Due to compatibility issues with Lazy components, the library must be imported when the game is initialized, so that it can be used inside Lazy components.

```ts title="main.ts"
import "@drincs/pixi-vn-spine"; // [!code focus]

Game.init(body, {
    // ...
})
```

Usage [#usage]

You can use the `Spine` component just like any other Pixi’VN component.\
However, you must first load the Spine 2D assets (**skeleton** and **atlas**) before using it.

This component has two required properties: `skeleton` and `atlas`, which must match the names of the loaded assets.

For example:

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

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="main.ts">
    ```ts
    import { Assets, canvas } from "@drincs/pixi-vn";
    import { Spine } from "@drincs/pixi-vn-spine";

    await Assets.load(["spineboySkeleton", "spineboyAtlas"]);
    const spine = new Spine({ atlas: "spineboyAtlas", skeleton: "spineboySkeleton" });
    canvas.add("spine", spine);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "spineboySkeleton",
                        src: "https://raw.githubusercontent.com/pixijs/spine-v8/main/examples/assets/spineboy-pro.skel",
                    },
                    {
                        alias: "spineboyAtlas",
                        src: "https://raw.githubusercontent.com/pixijs/spine-v8/main/examples/assets/spineboy-pma.atlas",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Animation [#animation]

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { Assets, canvas, newLabel } from "@drincs/pixi-vn";
    import { Spine } from "@drincs/pixi-vn-spine";

    export const startLabel = newLabel("start", [
        async () => {
            await Assets.load(["spineboySkeleton", "spineboyAtlas"]);
            const spine = new Spine({ atlas: "spineboyAtlas", skeleton: "spineboySkeleton", xAlign: 0.5, yAlign: 1 });
            spine.addAnimation("idle", { loop: true });
            canvas.add("spine", spine);
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "spineboySkeleton",
                        src: "https://raw.githubusercontent.com/pixijs/spine-v8/main/examples/assets/spineboy-pro.skel",
                    },
                    {
                        alias: "spineboyAtlas",
                        src: "https://raw.githubusercontent.com/pixijs/spine-v8/main/examples/assets/spineboy-pma.atlas",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<AnimationExample />

Spine + motion.js animations [#spine--motionjs-animations]

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { Assets, canvas, newLabel } from "@drincs/pixi-vn";
    import { Spine } from "@drincs/pixi-vn-spine";

    export const startLabel = newLabel("start", [
        async () => {
            await Assets.load(["spineboySkeleton", "spineboyAtlas"]);
            const spine = new Spine({ atlas: "spineboyAtlas", skeleton: "spineboySkeleton", xAlign: 0, yAlign: 1 });
            spine.addAnimation("walk", { loop: true });
            canvas.add("spine", spine);
            canvas.animate(
                spine,
                [
                    [{ xAlign: 1 }, { duration: 1, ease: "linear" }],
                    [{ scaleX: -1 }, { duration: 0.2 }],
                    [{ xAlign: 0 }, { duration: 1, ease: "linear" }],
                    [{ scaleX: 1 }, { duration: 0.2 }],
                ],
                { repeat: Infinity },
            );
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "spineboySkeleton",
                        src: "https://raw.githubusercontent.com/pixijs/spine-v8/main/examples/assets/spineboy-pro.skel",
                    },
                    {
                        alias: "spineboyAtlas",
                        src: "https://raw.githubusercontent.com/pixijs/spine-v8/main/examples/assets/spineboy-pma.atlas",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<MotionExample />

Animations sequence [#animations-sequence]

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { Assets, canvas, newLabel } from "@drincs/pixi-vn";
    import { Spine } from "@drincs/pixi-vn-spine";

    export const startLabel = newLabel("start", [
        async () => {
            await Assets.load(["spineboySkeleton", "spineboyAtlas"]);
            const spine = new Spine({ atlas: "spineboyAtlas", skeleton: "spineboySkeleton", xAlign: 0.5, yAlign: 1 });
            spine.playSequence([
                ["idle", { loop: true, duration: 2 }],
                "jump",
            ], {
                repeat: Infinity,
            });
            canvas.add("spine", spine);
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "spineboySkeleton",
                        src: "https://raw.githubusercontent.com/pixijs/spine-v8/main/examples/assets/spineboy-pro.skel",
                    },
                    {
                        alias: "spineboyAtlas",
                        src: "https://raw.githubusercontent.com/pixijs/spine-v8/main/examples/assets/spineboy-pma.atlas",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<AnimationSequenceExample />


# Text (/start/canvas-text)





The `Text` component extends the [`PixiJS.Text`](https://pixijs.com/8.x/guides/components/scene-objects/text) component, so you can use all the methods and properties of `PixiJS.Text`. It is used to display text on the canvas.

To initialize this component, you must pass the following parameters:

* `options`: The options for the component, the `text` property is required.

```ts
import { canvas, Text } from "@drincs/pixi-vn";

const basicText = new Text({ text: "Basic text in pixi", align: 0.5 });

canvas.add("text", basicText);
```

Compared to the `PixiJS.Text` component, `Text` adds the following features:

* Additional positioning: <DynamicLink href="/start/canvas-position">align and position with percentage</DynamicLink>.

Show [#show]

The simplest way to show text on the canvas is to use the `showText` function.

This function returns a `Text` that you can use to manipulate the component. This function has the following parameters:

* `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component.
* `text`: The text to display.
* `options` (Optional): The options for the component.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { newLabel, showText } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            let text = await showText("text", "Hello World!", { // [!code focus]
                xAlign: 0.5, // [!code focus]
                yAlign: 0.5, // [!code focus]
            }); // [!code focus]
            text.style.fontSize = 30; // [!code focus]
        },
    ]);
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<TextCanvas />

Remove [#remove]

As with other canvas components, you can remove this component using the <DynamicLink href="/start/canvas-functions#remove-a-canvas-component">`canvas.remove`</DynamicLink> function.

Style [#style]

To style the text, use `TextStyle`. This class allows you to customize font family, size, color, stroke, shadow, and more.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { canvas, newLabel, Text, TextStyle } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        () => {
            const skewStyle = new TextStyle({ // [!code focus]
                fontFamily: "Arial", // [!code focus]
                dropShadow: { // [!code focus]
                    alpha: 0.8, // [!code focus]
                    angle: 2.1, // [!code focus]
                    blur: 4, // [!code focus]
                    color: "0x111111", // [!code focus]
                    distance: 10, // [!code focus]
                }, // [!code focus]
                fill: "#ffffff", // [!code focus]
                stroke: { color: "#004620", width: 12, join: "round" }, // [!code focus]
                fontSize: 60, // [!code focus]
                fontWeight: "lighter", // [!code focus]
            }); // [!code focus]

            const skewText = new Text({ // [!code focus]
                text: "SKEW IS COOL", // [!code focus]
                style: skewStyle, // [!code focus]
                align: 0.5, // [!code focus]
                skew: { x: 0.65, y: -0.3 }, // [!code focus]
            }); // [!code focus]

            canvas.add("text", skewText); // [!code focus]
        },
    ]);
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<TextCanvasStyle />


# Three.js (/start/canvas-threejs)



<Callout title="This page is under construction" type="warn">
  Currently, this functionality is not available in Pixi’VN, but we plan to implement it. If you are interested, feel free to write in the chat below!
</Callout>

**What is Three.js?** Three.js is a JavaScript library that makes it easy to render 3D graphics in a web browser. It uses WebGL to render 3D graphics in the browser. Three.js is a popular choice for creating 3D graphics on the web.

You can learn more about Three.js on the [Three.js website](https://threejs.org/).

Having the ability interact with 3D elements can be very useful in many cases.

The [three-pixi](https://pixijs.com/8.x/guides/advanced/mixing-three-and-pixi#example-combining-3d-and-2d-elements) library provides this capability to PixiJS.


# Tickers functions (/start/canvas-tickers-functions)



To play, pause, or stop a ticker, you must use the functions of the `canvas`.

It is important to keep the following behaviors in mind:

* If a ticker does not have any canvas components associated with it, it will be deleted.
* If you <DynamicLink href="/start/canvas-functions#remove-a-canvas-component">remove a canvas component</DynamicLink>, your alias will be unlinked from the ticker.
* If you add a canvas component with an alias that already exists, the new component will replace the old one. The new component will inherit the tickers of the old component.

Find a ticker [#find-a-ticker]

To find a ticker, you must use the `canvas.findTicker` function. This function receives the following parameters:

* `tickerId`: The id of the ticker to be found.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="utils/defineAssets.ts">
      utils/defineAssets.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { canvas, newLabel, RotateTicker, showImage } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            await showImage("egg_head", "egg_head", { yAlign: 0.5, xAlign: 0.25, anchor: 0.5 });
            await showImage("flower_top", "flower_top", { yAlign: 0.5, xAlign: 0.75, anchor: 0.5 });
            let tikerId = canvas.addTicker(["egg_head", "flower_top"], new RotateTicker({}));
            let ticker = canvas.findTicker(tikerId); // [!code focus]
            console.log(ticker);
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="utils/defineAssets.ts">
    ```ts
    import { Assets } from "@drincs/pixi-vn";

    export async function defineAssets() {
        Assets.add({ alias: "egg_head", src: "https://pixijs.com/assets/eggHead.png" });
        Assets.add({ alias: "flower_top", src: "https://pixijs.com/assets/flowerTop.png" });
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Remove a ticker [#remove-a-ticker]

To remove a ticker, you must use the `canvas.removeTicker` function. This function receives the following parameters:

* `tikerId`: The id or an array of ids of the ticker to be removed.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="utils/defineAssets.ts">
      utils/defineAssets.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { canvas, newLabel, RotateTicker, showImage, storage } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            await showImage("egg_head", "egg_head", { yAlign: 0.5, xAlign: 0.25, anchor: 0.5 });
            await showImage("flower_top", "flower_top", { yAlign: 0.5, xAlign: 0.75, anchor: 0.5 });
            let tikerId = canvas.addTicker(["egg_head", "flower_top"], new RotateTicker({}));
            storage.set("tiker_id", tikerId);
        },
        () => {
            let tikerId = storage.get<string>("tiker_id");
            tikerId && canvas.removeTicker(tikerId); // [!code focus]
        },
    ]);

    ```
  </CodeBlockTab>

  <CodeBlockTab value="utils/defineAssets.ts">
    ```ts
    import { Assets } from "@drincs/pixi-vn";

    export async function defineAssets() {
        Assets.add({ alias: "egg_head", src: "https://pixijs.com/assets/eggHead.png" });
        Assets.add({ alias: "flower_top", src: "https://pixijs.com/assets/flowerTop.png" });
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Sandbox template="zglj8q" entry="/src/labels/startLabel.ts,/src/utils/assets-utility.ts" />

Pause and resume a ticker [#pause-and-resume-a-ticker]

To pause a ticker, you must use the `canvas.pauseTicker` function. This function receives the following parameters:

* `alias`: The alias of the canvas element that will use the ticker.
* `tickerIdsExcluded`: The tickers that will not be paused.

To resume a paused ticker, you must use the `canvas.resumeTicker` function. This function receives the following parameters:

* `alias`: The alias of the canvas element that will use the ticker.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="utils/defineAssets.ts">
      utils/defineAssets.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { canvas, narration, newLabel, RotateTicker, showImage } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            await showImage("egg_head", "egg_head", { align: 0.5, anchor: 0.5 });
            let tikerId = canvas.addTicker(["egg_head"], new RotateTicker({}));
            narration.dialogue = "start";
        },
        () => {
            canvas.pauseTicker("egg_head"); // [!code focus]
            narration.dialogue = "pause";
        },
        () => {
            canvas.resumeTicker("egg_head"); // [!code focus]
            narration.dialogue = "resume";
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="utils/defineAssets.ts">
    ```ts
    import { Assets } from "@drincs/pixi-vn";

    export async function defineAssets() {
        Assets.add({ alias: "egg_head", src: "https://pixijs.com/assets/eggHead.png" });
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Sandbox template="ns726n" entry="/src/labels/startLabel.ts,/src/utils/assets-utility.ts" />

Force completion of the transition at the end of the step [#force-completion-of-the-transition-at-the-end-of-the-step]

When the animation has a goal to reach, such as a destination, we sometimes need the animation to reach the goal before the current `step` ends.

To do this, you can use the `canvas.completeTickerOnStepEnd` function. This function receives the following parameters:

* `step`: The `step` that the ticker must be completed before the next `step`. It receives an object with the following properties:
  * `id`: The id of the `step`.
  * `alias`: If it is a sequence of tickers, the alias of the [sequence of tickers](#sequence-of-tickers).

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="utils/defineAssets.ts">
      utils/defineAssets.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { canvas, narration, newLabel, showImage } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            await showImage("egg_head", "egg_head", { yAlign: 0, xAlign: 0, anchor: 0 });
            let tikerId = canvas.addTicker(["egg_head"],
                new MoveTicker({
                    destination: { x: 1, y: 0, type: "align" },
                    speed: 1,
                })
            );
            tikerId && canvas.completeTickerOnStepEnd({ id: tikerId }); // [!code focus]
        },
        () => {
            narration.dialogue = "complete";
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="utils/defineAssets.ts">
    ```ts
    import { Assets } from "@drincs/pixi-vn";

    export async function defineAssets() {
        Assets.add({ alias: "egg_head", src: "https://pixijs.com/assets/eggHead.png" });
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Sandbox template="7zgqr6" entry="/src/labels/startLabel.ts,/src/utils/assets-utility.ts" />


# Ticker (/start/canvas-tickers)



Pixi’VN allows you to animate canvas components using tickers.

**What is a ticker?**\
A ticker is a class that runs on every frame and executes a function. Tickers can be used to animate components, perform transitions, or run any logic that needs to update regularly.

Compared to `PixiJS.tickers`, Pixi’VN tickers are classes with a `fn` method that is called every frame. This method is used to animate canvas components. Pixi’VN manages all running tickers, detects when they are no longer needed, and lets you pause, resume, or delete them using <DynamicLink href="/start/canvas-tickers-functions">various methods</DynamicLink>.

Create your own ticker [#create-your-own-ticker]

Creating your own ticker is simple: extend the <DynamicLink href="/start/canvas-tickers-functions">TickerBase</DynamicLink> class, override the `fn` method, and implement your logic.

Then, decorate the class with the `@tickerDecorator` decorator. The decorator can take a string as the ticker's alias; if not provided, the class name is used.

For example:

```typescript title="canvas/tickers/RotateTicker.ts"
import { canvas, Container, TickerBase, tickerDecorator, TickerValue } from "@drincs/pixi-vn";

@tickerDecorator() // or @tickerDecorator('RotateTicker')
export default class RotateTicker extends TickerBase<{ speed?: number; clockwise?: boolean }> {
    fn(
        t: TickerValue,
        args: {
            speed?: number;
            clockwise?: boolean;
        },
        aliases: string[]
    ): void {
        let speed = args.speed === undefined ? 0.1 : args.speed;
        let clockwise = args.clockwise === undefined ? true : args.clockwise;
        aliases.forEach((alias) => {
            let component = canvas.find(alias);
            if (component && component instanceof Container) {
                if (clockwise) component.rotation += speed * t.deltaTime;
                else component.rotation -= speed * t.deltaTime;
            }
        });
    }
}
```

Run a ticker [#run-a-ticker]

To add a ticker you must use the `canvas.addTicker` function. This function receives the following parameters:

* `canvasElementAlias`: The alias of the canvas element that will use the ticker. You can pass a string or an array of strings. If you pass an array of strings, the ticker will be associated with all canvas components.
* `ticker`: The <DynamicLink href="/start/canvas-tickers">ticker</DynamicLink> instance to be run.

The function returns the id of the ticker that was added.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="utils/defineAssets.ts">
      utils/defineAssets.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { canvas, newLabel, RotateTicker, showImage } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            await showImage("egg_head", "egg_head", { yAlign: 0.5, xAlign: 0.25, anchor: 0.5 });
            await showImage("flower_top", "flower_top", { yAlign: 0.5, xAlign: 0.75, anchor: 0.5 });
            let tikerId = canvas.addTicker(["egg_head", "flower_top"], new RotateTicker({})); // [!code focus]
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="utils/defineAssets.ts">
    ```ts
    import { Assets } from "@drincs/pixi-vn";

    export async function defineAssets() {
        Assets.add({ alias: "egg_head", src: "https://pixijs.com/assets/eggHead.png" });
        Assets.add({ alias: "flower_top", src: "https://pixijs.com/assets/flowerTop.png" });
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Sandbox template="vfqzch" entry="/src/labels/startLabel.ts,/src/utils/assets-utility.ts" />

Sequence of tickers [#sequence-of-tickers]

If you want to run a sequence of tickers, you can use the `canvas.addTickersSequence` function. This function receives the following parameters:

* `canvasElementAlias`: The alias of the canvas element that will use the ticker. Please note that a component alias can only have one sequence sequence of tickers to it. If you add a new sequence of tickers to the same alias, the new sequence will replace the old one.
* `tickers`: An array of tickers to be run in sequence.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="utils/defineAssets.ts">
      utils/defineAssets.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { canvas, newLabel, RotateTicker, showImage } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
    async () => {
        await showImage("egg_head", "egg_head", { anchor: 0.5 });
        let tikerId = canvas.addTickersSequence("egg_head", [ // [!code focus]
            new MoveTicker({ // [!code focus]
                destination: { x: 0.5, y: 0.5, type: "align" }, // [!code focus]
            }), // [!code focus]
            new RotateTicker({ speed: 2, clockwise: false }, 2), // [!code focus]
        ]); // [!code focus]
    },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="utils/defineAssets.ts">
    ```ts
    import { Assets } from "@drincs/pixi-vn";

    export async function defineAssets() {
        Assets.add({ alias: "egg_head", src: "https://pixijs.com/assets/eggHead.png" });
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Sandbox template="k3wj6d" entry="/src/labels/startLabel.ts,/src/utils/assets-utility.ts" />

Pause [#pause]

If you want to pause the steps for a while, you can use the `Pause` token. The `Pause` token receives the time in seconds to pause.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="utils/defineAssets.ts">
      utils/defineAssets.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { canvas, newLabel, Pause, RotateTicker, showImage } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            await showImage("egg_head", "egg_head", { anchor: 0.5, align: 0.5 });
            let tikerId = canvas.addTickersSequence("egg_head", [ // [!code focus]
                new RotateTicker({ speed: 1, clockwise: true }, 2), // [!code focus]
                Pause(1), // [!code focus]
                new RotateTicker({ speed: 1, clockwise: false }, 2), // [!code focus]
            ]); // [!code focus]
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="utils/defineAssets.ts">
    ```ts
    import { Assets } from "@drincs/pixi-vn";

    export async function defineAssets() {
        Assets.add({ alias: "egg_head", src: "https://pixijs.com/assets/eggHead.png" });
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Sandbox template="y25tgn" entry="/src/labels/startLabel.ts,/src/utils/assets-utility.ts" />

Repeat [#repeat]

If you want to repeat the steps, you can use the `Repeat` token.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="utils/defineAssets.ts">
      utils/defineAssets.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { canvas, newLabel, Repeat, RotateTicker, showImage } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            await showImage("egg_head", "egg_head", {
                anchor: 0.5,
                align: 0.5,
            });
            let tikerId = canvas.addTickersSequence("egg_head", [ // [!code focus]
                new RotateTicker({ speed: 1, clockwise: true }, 2), // [!code focus]
                new RotateTicker({ speed: 2, clockwise: false }, 2), // [!code focus]
                Repeat, // [!code focus]
            ]); // [!code focus]
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="utils/defineAssets.ts">
    ```ts
    import { Assets } from "@drincs/pixi-vn";

    export async function defineAssets() {
        Assets.add({ alias: "egg_head", src: "https://pixijs.com/assets/eggHead.png" });
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Sandbox template="d3f7gv" entry="/src/labels/startLabel.ts,/src/utils/assets-utility.ts" />


# Transitions (/start/canvas-transition)





Pixi’VN provides various transition effects to show or remove a <DynamicLink href="/start/canvas-components">canvas component</DynamicLink>, as well as the ability to [create your own transitions](#custom-functionality).

<Accordions>
  <Accordion title="dissolve" id="dissolve">
    The dissolve transition:

    * When showing a component, gradually increases its `alpha`. If a component with the same alias exists, it will be removed when the new component's transition is complete.
    * When removing a component, gradually decreases its `alpha`.

    The `showWithDissolve` function displays a canvas element with a dissolve transition. This function has the following parameters:

    * `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component.
    * `image` (Optional): The image to show. If not provided, the alias is used as the URL. It can be:
      * a URL/path (video: <DynamicLink href="/start/canvas-video">VideoSprite</DynamicLink>, otherwise <DynamicLink href="/start/canvas-image">ImageSprite</DynamicLink>)
      * an array of URLs/paths (<DynamicLink href="/start/canvas-image">ImageContainer</DynamicLink>)
      * `{ value: string, options: ImageSpriteOptions }` (video: <DynamicLink href="/start/canvas-video">VideoSprite</DynamicLink>, otherwise <DynamicLink href="/start/canvas-image">ImageSprite</DynamicLink>)
      * `{ value: string[], options: ImageContainerOptions }` (<DynamicLink href="/start/canvas-image">ImageContainer</DynamicLink>)
      * a <DynamicLink href="/start/canvas-components">canvas component</DynamicLink>
    * `options` (Optional): Animation options, matching the <DynamicLink href="/start/canvas-motion">`options` of `animate` function</DynamicLink>.
    * `priority` (Optional): The priority of the PixiJS ticker. This parameter sets the ticker's priority. The default is `UPDATE_PRIORITY.NORMAL`.

    The `removeWithDissolve` function removes a canvas element with a dissolve transition. This function has the following parameters:

    * `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> of the component to remove.
    * `options` (Optional): Animation options, matching the <DynamicLink href="/start/canvas-motion">`options` of `animate` function</DynamicLink>.
    * `priority` (Optional): The priority of the PixiJS ticker. This parameter sets the ticker's priority. The default is `UPDATE_PRIORITY.NORMAL`.

    <CodeBlockTabs defaultValue="labels/startLabel.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="labels/startLabel.ts">
          labels/startLabel.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="labels/startLabel.ts">
        ```ts
        import { newLabel, removeWithDissolve, showWithDissolve } from "@drincs/pixi-vn";

        export const startLabel = newLabel("start_label", [
            async () => {
                await showWithDissolve("alien", "egg_head"); // [!code focus]
                await showWithDissolve("human", { // [!code focus]
                    value: ["m01-body", "m01-eyes", "m01-mouth"], // [!code focus]
                    options: { scale: 0.5, xAlign: 0.7 }, // [!code focus]
                }); // [!code focus]
            },
            async () => {
                await showWithDissolve("alien", "flower_top"); // [!code focus]
                removeWithDissolve("human"); // [!code focus]
            },
        ]);
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        {
                            alias: "egg_head",
                            src: "https://pixijs.com/assets/eggHead.png",
                        },
                        {
                            alias: "flower_top",
                            src: "https://pixijs.com/assets/flowerTop.png",
                        },
                        {
                            alias: "m01-body",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-body.webp",
                        },
                        {
                            alias: "m01-eyes",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-eyes-smile.webp",
                        },
                        {
                            alias: "m01-mouth",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-smile00.webp",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <DissolveTransitionExample />
  </Accordion>

  <Accordion title="fade" id="fade">
    The fade transition:

    * When showing a component, gradually increases its `alpha`. If a component with the same alias exists, the existing component will be removed with a fade-out effect before the new component is shown.
    * When removing a component, gradually decreases its `alpha`.

    The `showWithFade` function displays a canvas element with a fade transition. This function has the following parameters:

    * `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component.
    * `image` (Optional): The image to show. If not provided, the alias is used as the URL. It can be:
      * a URL/path (video: <DynamicLink href="/start/canvas-video">VideoSprite</DynamicLink>, otherwise <DynamicLink href="/start/canvas-image">ImageSprite</DynamicLink>)
      * an array of URLs/paths (<DynamicLink href="/start/canvas-image">ImageContainer</DynamicLink>)
      * `{ value: string, options: ImageSpriteOptions }` (video: <DynamicLink href="/start/canvas-video">VideoSprite</DynamicLink>, otherwise <DynamicLink href="/start/canvas-image">ImageSprite</DynamicLink>)
      * `{ value: string[], options: ImageContainerOptions }` (<DynamicLink href="/start/canvas-image">ImageContainer</DynamicLink>)
      * a <DynamicLink href="/start/canvas-components">canvas component</DynamicLink>
    * `options` (Optional): Animation options, matching the <DynamicLink href="/start/canvas-motion">`options` of `animate` function</DynamicLink>.
    * `priority` (Optional): The priority of the PixiJS ticker. This parameter sets the ticker's priority. The default is `UPDATE_PRIORITY.NORMAL`.

    The `removeWithFade` function removes a canvas element with a fade transition. This function has the following parameters:

    * `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> of the component to remove.
    * `options` (Optional): Animation options, matching the <DynamicLink href="/start/canvas-motion">`options` of `animate` function</DynamicLink>.
    * `priority` (Optional): The priority of the PixiJS ticker. This parameter sets the ticker's priority. The default is `UPDATE_PRIORITY.NORMAL`.

    <CodeBlockTabs defaultValue="labels/startLabel.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="labels/startLabel.ts">
          labels/startLabel.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="labels/startLabel.ts">
        ```ts
        import { newLabel, removeWithFade, showWithFade } from "@drincs/pixi-vn";

        export const startLabel = newLabel("start_label", [
            async () => {
                await showWithFade("alien", "egg_head", { duration: 5 }); // [!code focus]
                await showWithFade("human", { // [!code focus]
                    value: ["m01-body", "m01-eyes", "m01-mouth"], // [!code focus]
                    options: { scale: 0.5, xAlign: 0.7 }, // [!code focus]
                }); // [!code focus]
            },
            async () => {
                await showWithFade("alien", "flower_top"); // [!code focus]
                removeWithFade("human"); // [!code focus]
            },
        ]);
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        {
                            alias: "egg_head",
                            src: "https://pixijs.com/assets/eggHead.png",
                        },
                        {
                            alias: "flower_top",
                            src: "https://pixijs.com/assets/flowerTop.png",
                        },
                        {
                            alias: "m01-body",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-body.webp",
                        },
                        {
                            alias: "m01-eyes",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-eyes-smile.webp",
                        },
                        {
                            alias: "m01-mouth",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-smile00.webp",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <FadeTransitionExample />
  </Accordion>

  <Accordion title="move_in_out" id="move-in-out">
    The move in/out transition:

    * When showing a component, moves it from outside (right, left, top, or bottom) to its position on the canvas. If a component with the same alias exists, the existing component will be removed with a move-out effect before the new component is shown.
    * When removing a component, moves it from its position to outside the canvas.

    The `moveIn` function displays a canvas element with a move-in transition. This function has the following parameters:

    * `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component.
    * `image` (Optional): The image to show. If not provided, the alias is used as the URL. It can be:
      * a URL/path (video: <DynamicLink href="/start/canvas-video">VideoSprite</DynamicLink>, otherwise <DynamicLink href="/start/canvas-image">ImageSprite</DynamicLink>)
      * an array of URLs/paths (<DynamicLink href="/start/canvas-image">ImageContainer</DynamicLink>)
      * `{ value: string, options: ImageSpriteOptions }` (video: <DynamicLink href="/start/canvas-video">VideoSprite</DynamicLink>, otherwise <DynamicLink href="/start/canvas-image">ImageSprite</DynamicLink>)
      * `{ value: string[], options: ImageContainerOptions }` (<DynamicLink href="/start/canvas-image">ImageContainer</DynamicLink>)
      * a <DynamicLink href="/start/canvas-components">canvas component</DynamicLink>
    * `options` (Optional): Animation options, matching the <DynamicLink href="/start/canvas-motion">`options` of `animate` function</DynamicLink>. Additional properties:
      * `direction`: Direction of the move (`right`, `left`, `top`, `bottom`). Default: `right`.
      * `removeOldComponentWithMoveOut` (Optional): If true, removes the existing component with a move-out effect after the new component transition. Default: `false`.
    * `priority` (Optional): The priority of the PixiJS ticker. This parameter sets the ticker's priority. The default is `UPDATE_PRIORITY.NORMAL`.

    The `moveOut` function removes a canvas element with a move-out transition. This function has the following parameters:

    * `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> of the component to remove.
    * `options` (Optional): Animation options, matching the <DynamicLink href="/start/canvas-motion">`options` of `animate` function</DynamicLink>. Additional properties:
      * `direction`: Direction of the move (`right`, `left`, `top`, `bottom`). Default: `right`.
    * `priority` (Optional): The priority of the PixiJS ticker. This parameter sets the ticker's priority. The default is `UPDATE_PRIORITY.NORMAL`.

    <CodeBlockTabs defaultValue="labels/startLabel.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="labels/startLabel.ts">
          labels/startLabel.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="labels/startLabel.ts">
        ```ts
        import { moveIn, moveOut, newLabel } from "@drincs/pixi-vn";

        export const startLabel = newLabel("start_label", [
            async () => {
                await moveIn("alien", "egg_head", { direction: "up" }); // [!code focus]
                await moveIn("human", { // [!code focus]
                    value: ["m01-body", "m01-eyes", "m01-mouth"], // [!code focus]
                    options: { scale: 0.5, xAlign: 0.7 }, // [!code focus]
                }); // [!code focus]
            },
            async () => {
                await moveIn("alien", "flower_top", { direction: "up" }); // [!code focus]
                moveOut("human"); // [!code focus]
            },
        ]);
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        {
                            alias: "egg_head",
                            src: "https://pixijs.com/assets/eggHead.png",
                        },
                        {
                            alias: "flower_top",
                            src: "https://pixijs.com/assets/flowerTop.png",
                        },
                        {
                            alias: "m01-body",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-body.webp",
                        },
                        {
                            alias: "m01-eyes",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-eyes-smile.webp",
                        },
                        {
                            alias: "m01-mouth",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-smile00.webp",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <MoveinTransitionExample />
  </Accordion>

  <Accordion title="push_in_out" id="push-in-out">
    The push in/out transition:

    * When showing a component, moves it from outside (right, left, top, or bottom) to its position on the canvas. If a component with the same alias exists, the existing component will be removed with a push-out effect while the new component is moving in.
    * When removing a component, moves it from its position to outside the canvas.

    The `pushIn` function displays a canvas element with a push-in transition. This function has the following parameters:

    * `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component.
    * `image` (Optional): The image to show. If not provided, the alias is used as the URL. It can be:
      * a URL/path (video: <DynamicLink href="/start/canvas-video">VideoSprite</DynamicLink>, otherwise <DynamicLink href="/start/canvas-image">ImageSprite</DynamicLink>)
      * an array of URLs/paths (<DynamicLink href="/start/canvas-image">ImageContainer</DynamicLink>)
      * `{ value: string, options: ImageSpriteOptions }` (video: <DynamicLink href="/start/canvas-video">VideoSprite</DynamicLink>, otherwise <DynamicLink href="/start/canvas-image">ImageSprite</DynamicLink>)
      * `{ value: string[], options: ImageContainerOptions }` (<DynamicLink href="/start/canvas-image">ImageContainer</DynamicLink>)
      * a <DynamicLink href="/start/canvas-components">canvas component</DynamicLink>
    * `options` (Optional): Animation options, matching the <DynamicLink href="/start/canvas-motion">`options` of `animate` function</DynamicLink>. Additional properties:
      * `direction`: Direction of the move (`right`, `left`, `top`, `bottom`). Default: `right`.
    * `priority` (Optional): The priority of the PixiJS ticker. This parameter sets the ticker's priority. The default is `UPDATE_PRIORITY.NORMAL`.

    The `pushOut` function removes a canvas element with a push-out transition. This function has the following parameters:

    * `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> of the component to remove.
    * `options` (Optional): Animation options, matching the <DynamicLink href="/start/canvas-motion">`options` of `animate` function</DynamicLink>. Additional properties:
      * `direction`: Direction of the move (`right`, `left`, `top`, `bottom`). Default: `right`.
    * `priority` (Optional): The priority of the PixiJS ticker. This parameter sets the ticker's priority. The default is `UPDATE_PRIORITY.NORMAL`.

    <CodeBlockTabs defaultValue="labels/startLabel.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="labels/startLabel.ts">
          labels/startLabel.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="labels/startLabel.ts">
        ```ts
        import { newLabel, pushIn, pushOut } from "@drincs/pixi-vn";

        export const startLabel = newLabel("start_label", [
            async () => {
                await pushIn("alien", "egg_head"); // [!code focus]
                await pushIn("human", { // [!code focus]
                    value: ["m01-body", "m01-eyes", "m01-mouth"], // [!code focus]
                    options: { scale: 0.5, xAlign: 0.7 }, // [!code focus]
                }); // [!code focus]
            },
            async () => {
                await pushIn("alien", "flower_top", { direction: "up" }); // [!code focus]
                pushOut("human"); // [!code focus]
            },
        ]);
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        {
                            alias: "egg_head",
                            src: "https://pixijs.com/assets/eggHead.png",
                        },
                        {
                            alias: "flower_top",
                            src: "https://pixijs.com/assets/flowerTop.png",
                        },
                        {
                            alias: "m01-body",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-body.webp",
                        },
                        {
                            alias: "m01-eyes",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-eyes-smile.webp",
                        },
                        {
                            alias: "m01-mouth",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-smile00.webp",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <PushinTransitionExample />
  </Accordion>

  <Accordion title="zoom_in_out" id="zoom-in-out">
    The zoom in/out transition:

    * When showing a component, scales it from 0 (from outside the canvas) to its original scale and position. If a component with the same alias exists, the existing component will be removed when the new component's transition is complete.
    * When removing a component, scales it from its original size to 0, moving it outside the canvas.

    The `zoomIn` function displays a canvas element with a zoom-in transition. This function has the following parameters:

    * `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component.
    * `image` (Optional): The image to show. If not provided, the alias is used as the URL. It can be:
      * a URL/path (video: <DynamicLink href="/start/canvas-video">VideoSprite</DynamicLink>, otherwise <DynamicLink href="/start/canvas-image">ImageSprite</DynamicLink>)
      * an array of URLs/paths (<DynamicLink href="/start/canvas-image">ImageContainer</DynamicLink>)
      * `{ value: string, options: ImageSpriteOptions }` (video: <DynamicLink href="/start/canvas-video">VideoSprite</DynamicLink>, otherwise <DynamicLink href="/start/canvas-image">ImageSprite</DynamicLink>)
      * `{ value: string[], options: ImageContainerOptions }` (<DynamicLink href="/start/canvas-image">ImageContainer</DynamicLink>)
      * a <DynamicLink href="/start/canvas-components">canvas component</DynamicLink>
    * `options` (Optional): Animation options, matching the <DynamicLink href="/start/canvas-motion">`options` of `animate` function</DynamicLink>. Additional properties:
      * `direction`: Direction of the move (`right`, `left`, `top`, `bottom`). Default: `right`.
      * `removeOldComponentWithZoomOut` (Optional): If true, removes the existing component with a zoom-out effect after the new component transition. Default: `false`.
    * `priority` (Optional): The priority of the PixiJS ticker. This parameter sets the ticker's priority. The default is `UPDATE_PRIORITY.NORMAL`.

    The `zoomOut` function removes a canvas element with a zoom-out transition. This function has the following parameters:

    * `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> of the component to remove.
    * `options` (Optional): Animation options, matching the <DynamicLink href="/start/canvas-motion">`options` of `animate` function</DynamicLink>. Additional properties:
      * `direction`: Direction of the move (`right`, `left`, `top`, `bottom`). Default: `right`.
    * `priority` (Optional): The priority of the PixiJS ticker. This parameter sets the ticker's priority. The default is `UPDATE_PRIORITY.NORMAL`.

    <CodeBlockTabs defaultValue="labels/startLabel.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="labels/startLabel.ts">
          labels/startLabel.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="labels/startLabel.ts">
        ```ts
        import { newLabel, zoomIn, zoomOut } from "@drincs/pixi-vn";

        export const startLabel = newLabel("start_label", [
            async () => {
                await zoomIn("alien", "egg_head"); // [!code focus]
                await zoomIn("human", { // [!code focus]
                    value: ["m01-body", "m01-eyes", "m01-mouth"], // [!code focus]
                    options: { scale: 0.5, xAlign: 0.7 }, // [!code focus]
                }); // [!code focus]
            },
            async () => {
                await zoomIn("alien", "flower_top"); // [!code focus]
                zoomOut("human"); // [!code focus]
            },
        ]);
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        {
                            alias: "egg_head",
                            src: "https://pixijs.com/assets/eggHead.png",
                        },
                        {
                            alias: "flower_top",
                            src: "https://pixijs.com/assets/flowerTop.png",
                        },
                        {
                            alias: "m01-body",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-body.webp",
                        },
                        {
                            alias: "m01-eyes",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-eyes-smile.webp",
                        },
                        {
                            alias: "m01-mouth",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-smile00.webp",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ZoominTransitionExample />
  </Accordion>
</Accordions>

Custom functionality [#custom-functionality]

<Callout type="info">
  The Pixi’VN Team welcomes new proposals and contributions to make this library even more complete. Feel free to share or propose your transition in the chat below!
</Callout>

Creating your own transition is simple: use <DynamicLink href="/start/canvas-motion">`canvas.animate`</DynamicLink> to define custom effects.

To help you get started, here is a simplified version of [`showWithDissolve`](#dissolve):

```ts title="canvas/transitions/showWithDissolve.ts"
import { canvas, ImageSprite, UPDATE_PRIORITY } from "@drincs/pixi-vn";
import { AnimationOptions } from "@drincs/pixi-vn/motion";

export default async function showWithDissolve(
    alias: string,
    component: ImageSprite,
    props: AnimationOptions = {},
    priority?: UPDATE_PRIORITY,
): Promise<string[] | undefined> {
    let { completeOnContinue = true, ...options } = props;
    // add the new component
    canvas.add(alias, component)
    // edit the properties of the new component
    component.alpha = 0;
    // create the ticker and play it
    let id = canvas.animate(
        alias,
        {
            alpha: 1,
        },
        {
            ...options,
            completeOnContinue,
        },
        priority,
    );
    // load the image if the image is not loaded
    if (component.haveEmptyTexture) {
        await component.load();
    }
    // return the ids of the tickers
    if (id) {
        return [id];
    }
}
```

Replace or remove the previous component [#replace-or-remove-the-previous-component]

If a component with the same alias already exists, you can let it be replaced, or:

<Accordions>
  <Accordion title="remove_the_previous_component_after_completion" id="remove-the-previous-component-after-completion">
    To remove the previous component when the new component's transition is complete, use the <DynamicLink href="/start/canvas-motion">`aliasToRemoveAfter` property</DynamicLink>.

    ```ts title="canvas/transitions/showWithDissolve.ts"
    import { canvas, ImageSprite, UPDATE_PRIORITY } from "@drincs/pixi-vn";
    import { AnimationOptions } from "@drincs/pixi-vn/motion";

    export default async function showWithDissolve(
        alias: string,
        component: ImageSprite,
        props: AnimationOptions = {},
        priority?: UPDATE_PRIORITY,
    ): Promise<string[] | undefined> {
        let { completeOnContinue = true, ...options } = props;
        // check if the alias is already exist // [!code ++]
        let oldComponentAlias: string | undefined = undefined; // [!code ++]
        let oldComponent = canvas.find(alias); // [!code ++]
        if (oldComponent) { // [!code ++]
            oldComponentAlias = alias + "_temp_disolve"; // [!code ++]
            canvas.editAlias(alias, oldComponentAlias); // [!code ++]
        } // [!code ++]
        // add the new component and transfer the properties of the old component to the new component
        canvas.add(alias, component);
        oldComponent?.parent?.setChildIndex(oldComponent, oldComponent.parent.getChildIndex(oldComponent) - 0.1); // [!code ++]
        oldComponentAlias && canvas.copyCanvasElementProperty(oldComponentAlias, alias); // [!code ++]
        oldComponentAlias && canvas.transferTickers(oldComponentAlias, alias, "duplicate"); // [!code ++]
        // edit the properties of the new component
        component.alpha = 0;
        // create the ticker and play it
        let id = canvas.animate(
            alias,
            {
                alpha: 1,
            },
            {
                ...options,
                completeOnContinue,
            },
            priority,
        );
        // load the image if the image is not loaded
        if (component.haveEmptyTexture) {
            await component.load();
        }
        // return the ids of the tickers
        if (id) {
            return [id];
        }
    }
    ```
  </Accordion>

  <Accordion title="remove_the_previous_component_with_a_transition" id="remove-the-previous-component-with-a-transition">
    To remove the previous component with a transition, run another animation with <DynamicLink href="/start/canvas-motion">`canvas.animate`</DynamicLink> and use the <DynamicLink href="/start/canvas-motion">`tickerIdToResume` property</DynamicLink>.

    ```ts title="canvas/transitions/showWithFade.ts"
    import { canvas, ImageSprite, UPDATE_PRIORITY } from "@drincs/pixi-vn";
    import { AnimationOptions } from "@drincs/pixi-vn/motion";

    export default async function showWithDissolve(
        alias: string,
        component: ImageSprite,
        props: AnimationOptions = {},
        priority?: UPDATE_PRIORITY,
    ): Promise<string[] | undefined> {
        let { completeOnContinue = true, ...options } = props;
        // check if the alias is already exist // [!code ++]
        let oldComponentAlias: string | undefined = undefined; // [!code ++]
        let oldComponent = canvas.find(alias); // [!code ++]
        if (oldComponent) { // [!code ++]
            return showWithDissolve(alias, component, props, priority); // [!code ++]
        } // [!code ++]
        let oldComponentAlias = alias + "_temp_fade"; // [!code ++]
        canvas.editAlias(alias, oldComponentAlias); // [!code ++]
        // add the new component and transfer the properties of the old component to the new component // [!code ++]
        canvas.add(alias, component);
        oldComponent?.parent?.setChildIndex(oldComponent, oldComponent.parent.getChildIndex(oldComponent) - 0.1); // [!code ++]
        oldComponentAlias && canvas.copyCanvasElementProperty(oldComponentAlias, alias); // [!code ++]
        oldComponentAlias && canvas.transferTickers(oldComponentAlias, alias, "duplicate"); // [!code ++]
        // edit the properties of the new component
        component.alpha = 0;
        // create the ticker and play it
        let id = canvas.animate(
            alias,
            {
                alpha: 1,
            },
            {
                ...options,
                completeOnContinue,
            },
            priority,
        );
        if (id) { // [!code ++]
            // pause the ticker // [!code ++]
            canvas.pauseTicker({ id: id }); // [!code ++]
            // remove the old component // [!code ++]
            canvas.animate( // [!code ++]
                alias, // [!code ++]
                { // [!code ++]
                    alpha: 0, // [!code ++]
                }, // [!code ++]
                { // [!code ++]
                    ...options, // [!code ++]
                    tickerIdToResume: id, // [!code ++]
                    aliasToRemoveAfter: oldComponentAlias, // [!code ++]
                    completeOnContinue, // [!code ++]
                }, // [!code ++]
                priority // [!code ++]
            ); // [!code ++]
        } // [!code ++]
        // load the image if the image is not loaded
        if (component.haveEmptyTexture) {
            await component.load();
        }
        // return the ids of the tickers
        if (id) {
            return [id];
        }
    }
    ```
  </Accordion>
</Accordions>


# VideoSprite (/start/canvas-video)





The `VideoSprite` component extends the <DynamicLink href="/start/canvas-image">`ImageSprite`</DynamicLink> component, so you can use all the methods and properties of `ImageSprite`. It is used to display a single video on the canvas.

To initialize this component, you must pass the following parameters:

* `options` (Optional): The options for the component.
* `videoUrl` (Optional): The URL or path. If you have initialized the <DynamicLink href="/start/assets-management#initialize-the-asset-matrix-at-project-start">asset matrix</DynamicLink>, you can use the alias of the texture.

```ts
import { canvas, VideoSprite } from "@drincs/pixi-vn"

let video = new VideoSprite({
    anchor: { x: 0.5, y: 0.5 },
    x: 100,
    y: 100,
}, 'https://pixijs.com/assets/video.mp4')

await video.load()
canvas.add("my_video", video)
```

Compared to the `Sprite` component, `ImageSprite` adds the following features:

* `loop`: Indicates if the video should loop after it finishes.
* `paused`: Indicates if the video is paused.
* `pause()`: Pause the video.
* `play()`: Play the video.
* `currentTime`: The current time of the video.
* `restart()`: Restart the video.

Show [#show]

The simplest way to show a video on the canvas is to use the `showVideo` function. This function combines `load` and <DynamicLink href="/start/canvas-functions#add-a-canvas-component">`canvas.add`</DynamicLink>.

This function returns a `VideoSprite` that you can use to manipulate the component. This function has the following parameters:

* `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component.
* `videoUrl` (Optional): The URL or path. If you have initialized the <DynamicLink href="/start/assets-management#initialize-the-asset-matrix-at-project-start">asset matrix</DynamicLink>, you can use the alias of the texture. If you don't provide the URL, then the alias is used as the URL.
* `options` (Optional): The options for the component.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { newLabel, showVideo } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            let video1 = await showVideo("video"); // [!code focus]
            let video2 = await showVideo("video2", "video", { // [!code focus]
                xAlign: 0.5, // [!code focus]
            }); // [!code focus]
            let video3 = await showVideo("video3", "https://pixijs.com/assets/video.mp4", { // [!code focus]
                xAlign: 1, // [!code focus]
            }); // [!code focus]
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "video",
                        src: "https://pixijs.com/assets/video.mp4",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<VideoSpriteShow />

Add [#add]

To add an video to the canvas, use the `addVideo` function. This function only adds the component to the canvas; it does **not** show it or load its texture. It uses <DynamicLink href="/start/canvas-functions#add-a-canvas-component">`canvas.add`</DynamicLink> to add the component to the canvas.

This function returns a `VideoSprite` that you can use to manipulate the component. This function has the following parameters:

* `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component.
* `videoUrl` (Optional): The URL or path. If you have initialized the <DynamicLink href="/start/assets-management#initialize-the-asset-matrix-at-project-start">asset matrix</DynamicLink>, you can use the alias of the texture. If you don't provide the URL, then the alias is used as the URL.
* `options` (Optional): The options for the component.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { addVideo, canvas, VideoSprite, newLabel } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        () => {
            let video1 = addVideo("video"); // [!code focus]
            let video2 = addVideo("video2", "video", { // [!code focus]
                xAlign: 0.5, // [!code focus]
            }); // [!code focus]
            let video3 = addVideo("video3", "https://pixijs.com/assets/video.mp4", { // [!code focus]
                xAlign: 1, // [!code focus]
            }); // [!code focus]
        },
        async () => {
            let video1 = canvas.find<VideoSprite>("video");
            let video2 = canvas.find<VideoSprite>("video2");
            let video3 = canvas.find<VideoSprite>("video3");
            // Load the textures
            video1 && (await video1.load());
            video2 && (await video2.load());
            video3 && (await video3.load());
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "video",
                        src: "https://pixijs.com/assets/video.mp4",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<VideoSpriteAdd />

Remove [#remove]

As with other canvas components, you can remove this component using the <DynamicLink href="/start/canvas-functions#remove-a-canvas-component">`canvas.remove`</DynamicLink> function.

Play and pause [#play-and-pause]

Use `play()` and `pause()` methods, or set the `paused` property.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { canvas, narration, newLabel, showVideo, VideoSprite } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            narration.dialogue = "add video";
            await showVideo("video");
        },
        async () => {
            narration.dialogue = "pause video";
            let video = canvas.find<VideoSprite>("video");
            if (video) {
                video.pause(); // [!code focus]
                // or: video.paused = true // [!code focus]
            }
        },
        async () => {
            narration.dialogue = "resume video";
            let video = canvas.find<VideoSprite>("video");
            if (video) {
                video.play(); // [!code focus]
                // or: video.paused = false // [!code focus]
            }
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "video",
                        src: "https://pixijs.com/assets/video.mp4",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<VideoSpritePlayPause />

Looping [#looping]

Set the `loop` property to make the video repeat.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { newLabel, showVideo } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            let video = await showVideo("video");
            video.loop = true; // [!code focus]
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "video",
                        src: "https://pixijs.com/assets/video.mp4",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<VideoSpriteLooping />

Restart [#restart]

Use the `restart()` method to restart playback.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { canvas, narration, newLabel, showVideo, VideoSprite } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            narration.dialogue = "add video";
            await showVideo("video");
        },
        async () => {
            narration.dialogue = "restart video";
            let video = canvas.find<VideoSprite>("video");
            if (video) {
                video.restart(); // [!code focus]
            }
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "video",
                        src: "https://pixijs.com/assets/video.mp4",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<VideoSpriteRestart />


# Canvas (WebGL/WebGPU) (/start/canvas)







Pixi’VN uses [PixiJS](https://pixijs.com/8.x/guides/basics/what-pixijs-is) for rendering. You can use the Pixi’VN API to add images, text, and animations to the PixiJS canvas (or, more precisely, to the 2D WebGL/WebGPU rendering engine).

<Accordions>
  <Accordion title="what_is_pixijs" id="what-is-pixijs">
    PixiJS is the fastest, most lightweight 2D library available for the web, working across all devices and allowing you to create rich, interactive graphics and cross-platform applications using WebGL and WebGPU. It is fast, flexible, and easy to use. PixiJS is used in games like [Good Pizza, Great Pizza](https://www.goodpizzagreatpizza.com/) and [The Enchanted Cave 2](https://store.steampowered.com/app/368610/The_Enchanted_Cave_2/).

    You can learn more about PixiJS on the [PixiJS website](https://www.pixijs.com/).
  </Accordion>
</Accordions>

Use [#use]

<Callout title="ink" type="info">
  You can use this method with the *ink* syntax. See more <DynamicLink href="/ink/canvas">here</DynamicLink>.
</Callout>

To interact with the PixiJS application, you can use the `canvas` element, which acts as a wrapper. With it, you can add the set of <DynamicLink href="/start/canvas-components">components</DynamicLink> provided by Pixi’VN and start <DynamicLink href="/start/canvas-animations-effects">animations</DynamicLink>.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { canvas, Sprite } from "@drincs/pixi-vn" // [!code focus]

    export const startLabel = newLabel("start_label",
        [
            () => {
                let sprite = new Sprite({}); // [!code focus]
                canvas.add("sprite", sprite); // [!code focus]
            },
        ]
    )
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Other features [#other-features]

<Accordions>
  <Accordion title="use_pixijs_directly" id="use-pixijs-directly">
    <Callout title="CDN" type="info">
      In CDN-based environments like CodePen, you cannot install pixi.js, but you will have to use the `@drincs/pixi-vn/pixi.js` submodule.

      ```ts
      import { Graphics } from "@drincs/pixi-vn/pixi.js";
      ```
    </Callout>

    If you are using build tools such as Vite.js or similar systems, you can directly install and use the `pixi.js` package.

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

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

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

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

      <CodeBlockTab value="npm">
        ```sh
        npm install pixi.js
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```sh
        yarn add pixi.js
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```sh
        pnpm add pixi.js
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```sh
        bun add pixi.js
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    This is useful when creating <DynamicLink href="/start/interface#adding-pixijs-ui-layers">UI layers with PixiJS</DynamicLink> or for <DynamicLink href="/start/minigames">creating minigames</DynamicLink>.

    ```ts
    import { canvas } from "@drincs/pixi-vn";
    import { Graphics } from "pixi.js";

    const graphic = new Graphics().rect(0, 0, 200, 100).fill(0xff0000);

    const container = canvas.addLayer("ui");
    container.addChild(graphic);
    ```

    Although not recommended, you can use `canvas.app` to directly access the PixiJS application used by Pixi’VN.

    ```ts
    import { canvas } from "@drincs/pixi-vn";
    import { Graphics } from "pixi.js";

    const graphic = new Graphics().rect(0, 0, 200, 100).fill(0xff0000);

    canvas.app.stage.addChild(graphic);
    ```
  </Accordion>

  <Accordion title="pixijs_differences" id="pixijs-differences">
    Rendering in Pixi’VN is very similar to PixiJS, with the following differences:

    * All components added to the canvas are linked to an <DynamicLink href="/start/canvas-alias">alias</DynamicLink> of your choice. This alias is used to identify and manipulate the component.
    * Pixi’VN saves the current canvas state at each <DynamicLink href="/start/labels">`step`</DynamicLink>.
      &#x2A;*Note:** Only components linked to an alias are saved. If you add components directly to `PixiJS.Application`, they will not be included in the saved state.
    * Pixi’VN provides <DynamicLink href="/start/canvas-functions">various functions</DynamicLink> to add, remove, find, and manipulate components in the canvas.
    * Pixi’VN offers <DynamicLink href="/start/canvas-components">custom components</DynamicLink>, some of which correspond to PixiJS components, while others add new features.
    * Tickers are managed by Pixi’VN. If you use a PixiJS ticker, its state will not be saved.
    * To add event listeners and save their state in saves, it is recommended to read <DynamicLink href="/start/canvas-functions#add-a-listener-for-a-given-event">here</DynamicLink>.
  </Accordion>

  <Accordion title="pixijs_devtools" id="pixijs-devtools">
    [**PixiJS DevTools**](https://pixijs.io/devtools/) is a [Chrome extension](https://chromewebstore.google.com/detail/pixijs-devtools/dlkffcaaoccbofklocbjcmppahjjboce) that allows you to inspect and debug PixiJS applications. You can use it to view the display list, inspect textures, and debug your PixiJS application. PixiJS DevTools works with Pixi’VN, allowing you to inspect the canvas.

        <img alt="devtools" src="__img0" />

    After installing PixiJS DevTools, open Chrome DevTools (F12) and go to the `PixiJS` tab.

        <img alt="image" src="__img1" />
  </Accordion>

  <Accordion title="renderer" id="renderer">
    PixiJS supports various rendering backends, including WebGL and WebGPU. Pixi’VN detects the best available renderer for the user's device and uses it by default. However, you can specify a preferred renderer in the `Game.init` method.

    For example:

    ```ts
    Game.init({
        // ...
        preference: "webgpu"
    });
    ```
  </Accordion>

  <Accordion title="error_handling" id="error-handling">
    To handle errors related to the canvas, you can use the `drawCanvasErrorHandler` handler provided by Pixi’VN. This handler will draw an error message on the canvas when an error linked to the canvas component occurs. You can use it in the `Game.addOnError` function.

    ```ts title="main.ts"
    import { Game, drawCanvasErrorHandler } from '@drincs/pixi-vn'

    Game.addOnError(drawCanvasErrorHandler());
    ```
  </Accordion>
</Accordions>


# Characters (/start/character)



**What are `characters`?** Characters are the actors that appear in a visual novel. In Pixi’VN, characters are created using the `CharacterBaseModel` class or a [custom class](#custom-class).

Initialize [#initialize]

To initialize a character, create a new instance of the `CharacterBaseModel` class (or your [custom class](#custom-class)) and add it to the game character dictionary when the game is initialized.

<Callout type="info">
  It is recommended to import the instances at project startup.
</Callout>

To create a new instance of `CharacterBaseModel`, you need the following parameters:

* `id`: A unique identifier (string). It is used to reference the character in the game (must be unique). If you want to create a [character with an "emotion", you can pass an object](#character-emotions).
* `props`: An object with the character's properties:
  * `name`: The character's name.
  * `surname` (Optional): The character's surname.
  * `age` (Optional): The character's age.
  * `icon` (Optional): The character's icon image URL.
  * `color` (Optional): The character's color.

<CodeBlockTabs defaultValue="content/characters.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="content/characters.ts">
      content/characters.ts
    </CodeBlockTabsTrigger>

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

  <CodeBlockTab value="content/characters.ts">
    ```ts
    import { CharacterBaseModel, RegisteredCharacters } from "@drincs/pixi-vn";

    export const liam = new CharacterBaseModel('liam', {
        name: 'Liam',
        surname: 'Smith',
        age: 25,
        icon: "https://example.com/liam.png",
        color: "#9e2e12"
    });

    export const emma = new CharacterBaseModel('emma', {
        name: 'Emma',
        surname: 'Johnson',
        age: 23,
        icon: "https://example.com/emma.png",
        color: "#9e2e12"
    });

    RegisteredCharacters.add([liam, emma]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="main.ts">
    ```ts
    import "@/content";

    // ...
    ```
  </CodeBlockTab>
</CodeBlockTabs>

`RegisteredCharacters.add` is **required** to save the characters in the game.

You can also create a function to load characters. The important thing is that it is called at least once before the characters are used in the game, otherwise they will not be available.

Get [#get]

To get a character by its `id`, use the `RegisteredCharacters.get` function.

```typescript
import { RegisteredCharacters } from "@drincs/pixi-vn";

const liam = RegisteredCharacters.get('liam');
```

Get all [#get-all]

To get all characters, use the `RegisteredCharacters.values` function.

```typescript
import { RegisteredCharacters } from "@drincs/pixi-vn";

const characters = RegisteredCharacters.values();
```

Use [#use]

<Callout title="ink" type="info">
  You can use this method with the *ink* syntax. See more <DynamicLink href="/ink/character#use">here</DynamicLink>.
</Callout>

You can use a game character, for example, to <DynamicLink href="/start/dialogue#set-the-current-dialogue">link it to the current dialogue</DynamicLink>. You can use the character's `id` or the character's instance, but it is recommended to use the instance.

```ts title="content/characters.ts"
export const liam = new CharacterBaseModel('liam_id', {
    name: 'Liam',
    surname: 'Smith',
    age: 25,
    icon: "https://example.com/liam.png",
    color: "#9e2e12"
});
RegisteredCharacters.add([liam]);
```

```typescript
narration.dialogue = { character: liam, text: "Hello" }
// or
narration.dialogue = { character: "liam_id", text: "Hello" }
```

Edit [#edit]

<Callout title="ink" type="info">
  You can use this method with the *ink* syntax. See more <DynamicLink href="/ink/character#edit">here</DynamicLink>.
</Callout>

`CharacterBaseModel` is a <DynamicLink href="/start/stored-classes">stored class</DynamicLink>, which means its properties are saved in <DynamicLink href="/start/storage">game storage</DynamicLink>.

If the character's name is changed during the game, the new name will be saved in the game storage and linked to its `id`.

If the **character's `id` is changed** from one version to another, the system will **not** move the data linked from the previous `id` to the new `id`.

The properties of the `CharacterBaseModel` that are stored in the game storage are:

* `name`: The character's name.
* `surname`: The character's surname.
* `age`: The character's age.

To get the properties used when instantiating the class, you can use:

* `defaultName`: The character's name.
* `defaultSurname`: The character's surname.
* `defaultAge`: The character's age.

Here's a simplified implementation of the `CharacterBaseModel` class for better understanding of the properties that are stored in the game storage:

```typescript title="CharacterBaseModel.ts"
export default class CharacterBaseModel extends StoredClassModel implements CharacterBaseModelProps {
    constructor(id: string, props: CharacterBaseModelProps) {
        super(
            // ...
        )
        this.defaultName = props.name
        this.icon = props.icon
        // ...
    }

    // name property is stored in the game storage
    private defaultName: string = ""
    get name(): string {
        return this.getStorageProperty<string>("name") || this.defaultName
    }
    set name(value: string) {
        this.setStorageProperty<string>("name", value)
    }

    // icon property is not stored in the game storage
    icon: string = ""

    // ...
}
```

Character emotions [#character-emotions]

<Callout title="ink" type="info">
  You can use this method with the *ink* syntax. See more <DynamicLink href="/ink/character#character-emotions">here</DynamicLink>.
</Callout>

It is often useful to have multiple types of the same character. For example, a character "Alice" and a subtype related to her emotional state, like "Angry Alice". The character and the subtype have the same characteristics, except for one or more properties, such as the icon.

With Pixi’VN, you can create a "character with an emotion" by passing an object instead of the id, with the following properties:

* `id`: The id of an existing character.
* `emotion`: The character's subcategory (e.g. the character's emotion).

```ts title="content/characters.ts"
import { CharacterBaseModel, RegisteredCharacters } from "@drincs/pixi-vn";

export const alice = new CharacterBaseModel('alice', {
    name: 'Alice',
    icon: "https://example.com/alice.png",
    color: "#9e2e12"
});

export const angryAlice = new CharacterBaseModel({ id: 'alice', emotion: 'angry' }, {
    icon: "https://example.com/angryAlice.png",
});

RegisteredCharacters.add([alice, angryAlice]);
```

```typescript
console.log(alice.name); // Alice

alice.name = "Eleonora";
console.log(alice.name); // Eleonora
console.log(angryAlice.name); // Eleonora

angryAlice.name = "Angry Eleonora";
console.log(alice.name); // Eleonora
console.log(angryAlice.name); // Angry Eleonora
```

Custom class [#custom-class]

<Callout title="Templates" type="info">
  In all templates, the `Character` class is already defined in the file `models/Character.ts`. You can use it directly or modify it to suit your needs.
</Callout>

It is recommended to create your own class `Character` that extends `CharacterStoredClass` and "override" the interface `CharacterInterface` to add, edit, or remove properties or methods.

For example, if you want to create a class `Character`, you must "override" the interface `CharacterInterface` to use your properties or methods. (See the file `pixi-vn.d.ts`)

Now you can create a class `Character` that extends `CharacterStoredClass` and implements the `CharacterInterface`. (For more information on how to create a class in TypeScript, read [the official documentation](https://www.typescriptlang.org/docs/handbook/2/classes.html))

To create a property that stores its value in the game storage, you can create [Getters/Setters](https://www.typescriptlang.org/docs/handbook/2/classes.html#getters--setters) and use the `this.getStorageProperty()`/`this.setStorageProperty()` methods. (See the file `Character.ts`)

<CodeBlockTabs defaultValue="models/Character.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="models/Character.ts">
      models/Character.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pixi-vn.d.ts">
      pixi-vn.d.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="models/Character.ts">
    ```ts
    import { CharacterInterface, CharacterStoredClass } from "@drincs/pixi-vn";

    export class Character extends CharacterStoredClass implements CharacterInterface {
        constructor(id: string | { id: string, emotion: string }, props: CharacterProps) {
            super(typeof id === "string" ? id : id.id, typeof id === "string" ? "" : id.emotion)
            this._icon = props.icon
            this._color = props.color
            this.defaultName = props.name
            this.defaultSurname = props.surname
            this.defaultAge = props.age
        }

        // Not stored properties
        
        readonly icon?: string;
        readonly color?: string | undefined;

        // Stored properties

        private defaultName?: string
        get name(): string {
            return this.getStorageProperty<string>("name") || this.defaultName || this.id
        }
        set name(value: string | undefined) {
            this.setStorageProperty<string>("name", value)
        }
        private defaultSurname?: string
        get surname(): string | undefined {
            return this.getStorageProperty<string>("surname") || this.defaultSurname
        }
        set surname(value: string | undefined) {
            this.setStorageProperty<string>("surname", value)
        }
        private defaultAge?: number | undefined
        get age(): number | undefined {
            return this.getStorageProperty<number>("age") || this.defaultAge
        }
        set age(value: number | undefined) {
            this.setStorageProperty<number>("age", value)
        }
    }

    interface CharacterProps {
        /**
         * The name of the character.
         */
        name?: string;
        /**
         * The surname of the character.
         */
        surname?: string;
        /**
         * The age of the character.
         */
        age?: number;
        /**
         * The icon of the character.
         */
        icon?: string;
        /**
         * The color of the character.
         */
        color?: string;
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pixi-vn.d.ts">
    ```ts
    declare module '@drincs/pixi-vn' {
        interface CharacterInterface {
            /**
             * The name of the character.
             * If you set undefined, it will return the default name.
             */
            name: string;
            /**
             * The surname of the character.
             * If you set undefined, it will return the default surname.
             */
            surname?: string;
            /**
             * The age of the character.
             * If you set undefined, it will return the default age.
             */
            age?: number;
            /**
             * The icon of the character.
             */
            readonly icon?: string;
            /**
             * The color of the character.
             */
            readonly color?: string;
        }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>


# Choice menus (/start/choices)





<Callout title="UI screen" type="info">
  You can find an example of the choice menu UI screen in the <DynamicLink href="/start/interface-examples#choice-menu">interface examples</DynamicLink> section.
</Callout>

<Callout title="ink" type="info">
  You can use this method with the *ink* syntax. See more <DynamicLink href="/ink/choices">here</DynamicLink>.
</Callout>

In visual novels, choice menus allow the player to make decisions that affect the story.

In Pixi’VN, you can prompt the player to make a choice. Each choice can either start a `label` or close the choice menu.

Require the player to make a choice [#require-the-player-to-make-a-choice]

To require the player to make a choice, set `narration.choices` to an array of `StoredChoiceInterface`. To create a `StoredChoiceInterface` object, use:

<Accordions>
  <Accordion title="newchoiceoption" id="newchoiceoption">
    In Pixi’VN, you can create a choice menu option using the `newChoiceOption` function.
    This function has the following parameters:

    * `text`: The text displayed in the choice menu.
    * `label`: The <DynamicLink href="/start/labels#label">`label`</DynamicLink> to call when the player selects the option.
    * `props`: The properties passed to the `label`. If the `label` does not require parameters, pass an empty object `{}`.
    * `options` (Optional): An object with the `choice`'s options:
      * `type`: How the <DynamicLink href="/start/labels-flow#run-a-label">label will be performed</DynamicLink>. Can be `call` or `jump`. Default is `call`.
      * `oneTime`: If `true`, the choice can only be made once.
      * `onlyHaveNoChoice`: If `true`, the choice is shown only if there are no other choices.
      * `autoSelect`: If `true` and it is the only choice, it will be selected automatically.
  </Accordion>

  <Accordion title="newclosechoiceoption" id="newclosechoiceoption">
    In addition to `newChoiceOption`, you can use `newCloseChoiceOption` to create a closing option. This closes the choice menu and continues with the <DynamicLink href="/start/labels">steps</DynamicLink>, without calling any <DynamicLink href="/start/labels#label">label</DynamicLink>.
    This function has the following parameters:

    * `text`: The text displayed in the choice menu.
    * `options` (Optional): An object with the `choice`'s options:
      * `closeCurrentLabel`: If `true`, the current `label` will be closed. Default is `false`.
      * `oneTime`: If `true`, the choice can only be made once.
      * `onlyHaveNoChoice`: If `true`, the choice is shown only if there are no other choices.
      * `autoSelect`: If `true` and it is the only choice, it will be selected automatically.
  </Accordion>
</Accordions>

```ts title="labels/startLabel.ts"
import { newChoiceOption, newCloseChoiceOption, narration, newLabel } from "@drincs/pixi-vn"

export const startLabel = newLabel("start_label",
    [
        async () => {
            narration.dialogue = "Choose a fruit:"
            narration.choices = [ // [!code focus]
                newChoiceOption("Orange", orangeLabel, {}), // by default, the label will be called with "call" // [!code focus]
                newChoiceOption("Banana", bananaLabel, {}, { type: "jump" }), // [!code focus]
                newChoiceOption("Apple", appleLabel, { quantity: 5 }, { type: "call" }), // [!code focus]
                newCloseChoiceOption("Cancel"), // [!code focus]
            ] // [!code focus]
        },
        () => { narration.dialogue = "Restart" },
        async (props) => await narration.jump("start_label", props)
    ],
)
```

<ChoiceMenus />

Get [#get]

To get the current choice menu, use `narration.choices`. This returns an array of `StoredChoiceInterface`.

```typescript
const menuOptions: StoredChoiceInterface[] = narration.choices;
```

Request [#request]

To select a choice, use `narration.selectChoice`.

```typescript
const item = narration.choices![0]; // get the first item

narration.selectChoice(item, {
    // Add StepLabelProps here
    navigate: navigate, // example
    // And the props to pass to the label
    ...item.props
})
    .then(() => {
        // ...
    })
    .catch((e) => {
        // ...
    })
```

Remove [#remove]

To clear the choice options, set `narration.choices = undefined`.

```typescript
narration.choices = undefined;
```

Custom class [#custom-class]

You can customize a choice menu option by adding properties to the `ChoiceInterface` interface. For example, add an `icon` property to display an icon.

Override the `ChoiceInterface` interface in your `.d.ts` file:

<CodeBlockTabs defaultValue="pixi-vn.d.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="pixi-vn.d.ts">
      pixi-vn.d.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="screens/ChoiceMenu.tsx">
      screens/ChoiceMenu.tsx
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="pixi-vn.d.ts">
    ```ts
    declare module '@drincs/pixi-vn' {
        interface ChoiceInterface {
            icon?: string
        }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    narration.choices = [
        newChoiceOption("Orange", orangeLabel, {}, { icon: "orange.png" }),
        newChoiceOption("Banana", bananaLabel, {}, { icon: "banana.png" }),
        newChoiceOption("Apple", appleLabel, {}, { icon: "apple.png" }),
    ]
    ```
  </CodeBlockTab>

  <CodeBlockTab value="screens/ChoiceMenu.tsx">
    ```tsx
    function ChoiceMenu({ choices }: { choices: StoredIndexedChoiceInterface[] }) {
        return (
            <div>
                {choices.map((choice, index) => (
                    <div key={index}>
                        {choice.icon && <img src={choice.icon} alt={choice.text} />}
                        <button onClick={() => narration.selectChoice(choice)}>{choice.text}</button>
                    </div>
                ))}
            </div>
        )
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Other features [#other-features]

<Accordions>
  <Accordion title="choices_already_made" id="choices-already-made">
    To get the choices already made in the current `step`, use `narration.alreadyCurrentStepMadeChoices`.

    <CodeBlockTabs defaultValue="hooks/useQueryInterface.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="hooks/useQueryInterface.ts">
          hooks/useQueryInterface.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="screens/ChoiceMenu.tsx">
          screens/ChoiceMenu.tsx
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="hooks/useQueryInterface.ts">
        ```ts
        import { narration } from "@drincs/pixi-vn";
        import { useQuery } from "@tanstack/react-query";

        export const INTERFACE_DATA_USE_QUEY_KEY = "interface_data_use_quey_key";

        const CHOICE_MENU_OPTIONS_USE_QUEY_KEY = "choice_menu_options_use_quey_key";
        export function useQueryChoiceMenuOptions() {
            return useQuery({
                queryKey: [INTERFACE_DATA_USE_QUEY_KEY, CHOICE_MENU_OPTIONS_USE_QUEY_KEY],
                queryFn: async () =>
                    narration.choices?.map((option) => ({
                        ...option,
                        text: typeof option.text === "string" ? option.text : option.text.join(" "),
                        alreadyChosen: // [!code ++]
                            narration.alreadyCurrentStepMadeChoices?.find((index) => index === option.choiceIndex) !== // [!code ++]
                            undefined, // [!code ++]
                    })) || [],
            });
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="screens/ChoiceMenu.tsx">
        ```tsx
        import useNarrationFunctions from "../hooks/useNarrationFunctions";
        import { useQueryChoiceMenuOptions } from "../hooks/useQueryInterface";

        export default function ChoiceMenu() {
            const { data: menu = [] } = useQueryChoiceMenuOptions();
            const { selectChoice } = useNarrationFunctions();

            return (
                <div
                    style={{
                        display: "flex",
                        flexDirection: "column",
                        justifyContent: "center",
                        alignItems: "center",
                        width: "100%",
                        height: "100%",
                        overflow: "auto",
                        gap: "8px",
                        maxHeight: "100%",
                        margin: 0,
                        pointerEvents: menu?.length > 0 ? "auto" : "none",
                    }}
                >
                    {menu?.map((item, index) => (
                        <button
                            key={"choice-" + index}
                            style={{
                                justifyContent: "center",
                                alignItems: "center",
                            }}
                            onClick={() => selectChoice(item)}
                        >
                            {item.alreadyChosen ? "✓ " : ""} // [!code ++]
                            {item.text}
                        </button>
                    ))}
                </div>
            );
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ChoicesAlreadyMade />
  </Accordion>
</Accordions>


# Dialogue (/start/dialogue)





<Callout title="UI screen" type="info">
  You can find the example of the narrative dialogue UI screen in the <DynamicLink href="/start/interface-examples#narrative-dialogue">interface examples</DynamicLink> section.
</Callout>

**What is dialogue?** A written composition in which two or more characters are represented as conversing.

In Pixi’VN, `dialogue` is an object that contains information about *who* and *what* is currently being said. Its functionality can be broader, as it can also be used for other purposes, such as monologues, soliloquies, or to display a message to the player. For this reason, it is more appropriate to consider it as a text that can be linked to a <DynamicLink href="/start/character#use-characters-in-the-game">character</DynamicLink>.

Set [#set]

To set the current dialogue, you can use `narration.dialogue`.

```ts title="labels/startLabel.ts"
import { narration, newLabel } from "@drincs/pixi-vn"
import { eggHead } from "../values/characters"

// What is a Label? https://pixi-vn.web.app/start/labels.html
export const startLabel = newLabel("start_label",
    [
        () => {
            // in this example, not exists a character with id 'Alice' // [!code focus]
            // so when you get the current dialogue, the character is a fake character with the name 'Alice' // [!code focus]
            narration.dialogue = { // [!code focus]
                character: "Alice", // [!code focus]
                text: "Hello, world!" // [!code focus]
            } // [!code focus]
        },
        () => {
            // in this example, exists a character with id 'egg-head' // [!code focus]
            // so when you get the current dialogue, the character is the character with id 'egg-head' // [!code focus]
            narration.dialogue = { // [!code focus]
                character: 'egg-head', // [!code focus]
                text: "Hello, world!" // [!code focus]
            } // [!code focus]
            // or better // [!code focus]
            narration.dialogue = { // [!code focus]
                character: eggHead, // [!code focus]
                text: "Hello, world!" // [!code focus]
            } // [!code focus]
        },
        // if don't want to set a character, you can set a string // [!code focus]
        () => narration.dialogue = "Hello, world!", // [!code focus]
    ],
)
```

<CurrentDialogueExample />

Get [#get]

To get the current dialogue, use `narration.dialogue`. The return value is a `DialogueInterface`.

```typescript
const currentDialogue: DialogueInterface = narration.dialogue;
```

Delete [#delete]

To clear the current dialogue, set `narration.dialogue = undefined`.

```typescript
narration.dialogue = undefined;
```

Custom class [#custom-class]

You can customize the dialogue interface by adding additional properties to the `DialogueInterface`. For example, you can add a `color` property to change the color of the text.

To do this, "override" the `DialogueInterface` interface in your `.d.ts` file:

<CodeBlockTabs defaultValue="pixi-vn.d.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="pixi-vn.d.ts">
      pixi-vn.d.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="pixi-vn.d.ts">
    ```ts
    declare module '@drincs/pixi-vn' {
        interface DialogueInterface {
            color?: string
        }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    narration.dialogue = {
        character: "Alice",
        text: "Hello, world!",
        color: "#ff0000"
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Other features [#other-features]

<Accordions>
  <Accordion title="glue" id="dialogue-glue">
    <Callout type="info">
      Dialogue glue is a feature originally created for &#x2A;**ink***, which was also introduced in Pixi’VN.
    </Callout>

    When "glue" is enabled, the next dialogue will be appended after the current dialogue.

    ```ts title="labels/startLabel.ts"
    import { narration, newLabel } from "@drincs/pixi-vn";

    const startLabel = newLabel("start", [
        () => {
            narration.dialogue = `Hello, my name is Alice and ...` // [!code focus]
        },
        () => {
            narration.dialogGlue = true // [!code focus]
            narration.dialogue = `I am a character in this game.` // [!code focus]
        },
    ])
    ```

    <DialogueGlueExample />
  </Accordion>
</Accordions>


# Desktop & mobile devices (/start/distribution-desktop-mobile)





There are several ways to distribute your game for desktop and mobile platforms. Common choices include [Tauri](https://v2.tauri.app/), [Ionic](https://ionicframework.com/), [Electron](https://www.electronjs.org/), [NW.js](https://nwjs.io/), and [React Native for Windows + Mac](https://microsoft.github.io/react-native-windows/).

If you don't want to manage a heavily customized native project, consider using the <DynamicLink href="/start#project-initialization">multi-device templates</DynamicLink>. Those templates include Tauri so you can develop a web app and also build desktop and mobile apps from the same codebase.

<img alt="tauri-h2" src="__img0" />

Distributing your game with Tauri [#distributing-your-game-with-tauri]

<Accordions>
  <Accordion title="what_is_tauri" id="what-is-tauri">
    Tauri is a framework for building desktop and mobile applications with web technologies. It leverages **Rust** to produce secure, lightweight, and fast native binaries, while a WebView renders your HTML, CSS, and JavaScript.

    Learn more on the [Tauri website](https://v2.tauri.app/).
  </Accordion>
</Accordions>

Creating releases manually for every platform is difficult: it requires many tools to be installed, and building iOS apps requires a Mac. For these reasons, manual release generation is generally not recommended.

Tauri supports using GitHub Actions to automate release builds. GitHub Actions runs jobs on virtual machines (runners) that you configure with YAML workflow files. In a workflow you define the events that trigger the pipeline (for example, pushing a tag) and the list of commands the runner should execute.

<Callout title="Mobile" type="warn">
  Currently, mobile builds via GitHub Actions are experimental.
</Callout>

The <DynamicLink href="/start#project-initialization">multi-device templates</DynamicLink> include the file `/.github/workflows/tauri.yml`. That workflow builds release artifacts (installation packages) for multiple operating systems.

```yml title=".github/workflows/tauri.yml"
# https://tauri.app/distribute/pipelines/github/
name: 'publish'

on:
  push:
    tags:
      - 'v*'

jobs:
  publish-tauri:
    permissions:
      contents: write
    strategy:
      fail-fast: false
      matrix:
        include:
          - platform: 'macos-latest' # for Arm based macs (M1 and above).
            args: '--target aarch64-apple-darwin'
          - platform: 'macos-latest' # for Intel based macs.
            args: '--target x86_64-apple-darwin'
          - platform: 'ubuntu-22.04'
            args: ''
          - platform: 'windows-latest'
            args: ''
          - platform: 'macos-latest' # iOS
            args: '--target x86_64-apple-darwin'
            mobile: "ios"
          - platform: 'ubuntu-22.04' # Android
            args: ''
            mobile: "android"

    runs-on: ${{ matrix.platform }}
    steps:
      - uses: actions/checkout@v4

      - name: install dependencies (ubuntu only)
        if: matrix.platform == 'ubuntu-22.04' # This must match the platform value defined above.
        run: |
          sudo apt-get update
          sudo apt-get install -y libwebkit2gtk-4.1-dev libappindicator3-dev librsvg2-dev patchelf

      - name: setup node
        uses: actions/setup-node@v6
        with:
          node-version: lts/*

      - name: Update Java (only for Android builds)
        if: matrix.mobile == 'android'
        uses: actions/setup-java@v5
        with:
          distribution: 'temurin'
          java-version: '21'

      - name: setup Android SDK (only for Android builds)
        if: matrix.mobile == 'android'
        uses: android-actions/setup-android@v3

      - name: install Rust stable
        uses: dtolnay/rust-toolchain@stable # Set this to dtolnay/rust-toolchain@nightly
        with:
          # Those targets are only used on macos runners so it's in an `if` to slightly speed up windows and linux builds.
          targets: ${{ matrix.platform == 'macos-latest' && 'aarch64-apple-darwin,x86_64-apple-darwin' || '' }}

      - name: install frontend dependencies
        # If you don't have `beforeBuildCommand` configured you may want to build your frontend here too.
        run: yarn install # change this to npm or pnpm depending on which one you use.

      - name: Upload Tauri icons
        run: npm run tauri icon public/pwa-512x512.png

      - name: Rust cache
        uses: swatinem/rust-cache@v2
        with:
          workspaces: './src-tauri -> target'

      - uses: tauri-apps/tauri-action@v0
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tagName: app-v__VERSION__ # the action automatically replaces \_\_VERSION\_\_ with the app version.
          releaseName: 'App v__VERSION__'
          releaseBody: 'See the assets to download this version and install.'
          releaseDraft: true
          prerelease: false
          args: ${{ matrix.args }}
          mobile: ${{ matrix.mobile || null }}
```

To trigger this workflow you need a GitHub repository for your project and a Git tag that starts with `v`. For example:

```bash
git tag v1.0.0
git push origin v1.0.0
```

You can follow the workflow runs in the repository's Actions tab.

<img alt="Actions section" src="https://github.com/user-attachments/assets/b39055a9-02a7-472b-930f-daf0a9c6c78b" width="904" height="57" />

At the end of a successful run a GitHub Release will be created. Read more about GitHub Releases [here](https://docs.github.com/repositories/releasing-projects-on-github/viewing-your-repositorys-releases-and-tags).


# itch.io (/start/distribution-itchio)



You can distribute your game on [itch.io](https://itch.io/). It is a platform that allows you to upload your game and distribute it to the public. It is a great platform to distribute your game and get feedback from the community.

Game playable in browser [#game-playable-in-browser]

On itch.io you can enable the "This file will be played in the browser" flag for an uploaded file to make it playable in the browser.

But only a single html or js file can be executed and not a directory. For example, if you upload a zip of the generated folder after a build, you will see a result of something like this:

<img alt="image" src="https://github.com/user-attachments/assets/0482a6fa-8c21-4fa6-b4e1-04f05bc4315d" width="1148" height="646" />

The solution is to <DynamicLink href="/start/distribution-website#hosting-and-deploying">host the game on a server</DynamicLink> and then create an iframe on itch.io to show the game.

For example, after hosting the game on a server, you can create a index.html file with the following content:

```html title="index.html"
<!doctype html>
<html lang="en" style="height: 100%; width: 100%;">
  <head></head>
  <body
    style="height: 100%; width: 100%; display: flex; overflow: hidden; margin: 0; background-color: #242424;"
  >
    <div id="root"
      style="height: 100%; width: 100%;"
    >
      <iframe
        src="https://pixi-vn-react-template.web.app/"
        style="height: 100%; width: 100%; border: none;"
        allowfullscreen
      >
      </iframe>
    </div>
  </body>
</html>
```

Then you can upload the index.html file to itch.io.


# Website (/start/distribution-website)





Your Pixi’VN game can be distributed as a website, allowing players to access it directly in their web browsers. This is a great way to reach a wider audience, as no downloads or installations are required.\
To do this, you need to [host the game on a server](#hosting-and-deploying).

Hosting and deploying [#hosting-and-deploying]

You can use various hosting services like [Firebase](https://firebase.google.com/), [Vercel](https://vercel.com/), or [Netlify](https://www.netlify.com/). These platforms offer free plans and have similar setup processes.

<Accordions>
  <Accordion title="firebase" id="firebase">
    This guide uses Firebase as an example for hosting.\
    Firebase offers additional features such as database hosting and authentication, and is a reliable Google product.

    1. [Create a Firebase project](https://console.firebase.google.com/) if you haven't already.
    2. Install the Firebase CLI:

    ```bash
    npm install -g firebase-tools
    ```

    1. Log in to your Google account (if first time):

    ```bash
    firebase login
    ```

    1. Initialize Firebase in your project directory:

    ```bash
    firebase init
    ```

    Follow the CLI prompts:

    * **Features**: Choose `Hosting: Configure files for Firebase Hosting and (optionally) set up GitHub Action deploys`.
    * **Default project**: Select your Firebase project.
    * **Detected Vite codebase**: Enter `no`.
    * **Use a web framework?**: Enter `no`.
    * **Public directory**: Enter `dist`.
    * **Single-page app?**: Enter `yes` (ensures routing and deep linking work).
    * **Overwrite dist/index.html?**: Enter `no`.
    * **Set up GitHub deploys?**: Enter `no` (Optional).

    A `firebase.json` config file will be generated.

    Example `firebase.json`:

    ```json title="firebase.json"
    {
      "hosting": {
        "public": "dist",
        "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
        "rewrites": [
          {
            "source": "**",
            "destination": "/index.html"
          }
        ]
      }
    }
    ```

    See the [Firebase documentation](https://firebase.google.com/docs/hosting/full-config#section-firebase-json) for more details.

    To deploy your app:

    ```bash
    npm run build
    firebase deploy
    ```
  </Accordion>
</Accordions>

Enable "Add to Home Screen" (PWA Plugin) [#enable-add-to-home-screen-pwa-plugin]

<img alt="image" src="__img0" />

Enabling installation as a "browser application" allows users to use your game as a standalone app on their device.

If you use [Vite js](https://vitejs.dev/) as your build tool, you can add the [PWA Vite Plugin](https://vite-pwa-org.netlify.app/). See this [example](https://vite-pwa-org.netlify.app/guide/pwa-minimal-requirements.html#web-app-manifest).

Otherwise, create a `manifest.json` file according to your framework's requirements.


# Distribution (/start/distribution)



A very important point to take into account before developing a game is the distribution of the game. It is important to know how the game will be distributed and how it will be played by the users.

Potentially all JavaScript/Typescript projects can be distributed in **all platforms**. For example, Discord is a JavaScript/Typescript project that have a desktop app, a web app and a mobile app.

* <DynamicLink href="/start/distribution-website">
    Website (native support)
  </DynamicLink>
  * <DynamicLink href="/start/distribution-itchio">
      itch.io
    </DynamicLink>
* <DynamicLink href="/start/distribution-desktop-mobile">
    Desktop & Mobile devices
  </DynamicLink>


# Flags management (/start/flags)



Pixi’VN provides functions to manage "game flags". Game flags are boolean values used to control the flow of the game or to store other boolean value in the game storage.

This mechanic has much less impact on save size than <DynamicLink href="/start/storage#set-a-variable-in-the-game-storage">saving a boolean in game storage</DynamicLink>.

Set [#set]

To set a flag, use the `storage.setFlag` function.
This function has the following parameters:

* `name`: The flag name.
* `value`: The flag value.

```typescript
import { storage } from '@drincs/pixi-vn'

storage.setFlag('flag1', true)
```

Get [#get]

To get a flag, use the `storage.getFlag` function.
This function has the following parameters:

* `name`: The flag name.

```typescript
import { storage } from '@drincs/pixi-vn'

const flag1 = storage.getFlag('flag1')
```

Other features [#other-features]

<Accordions>
  <Accordion title="class_boolean_property" id="class-boolean-property">
    If you are creating a class with a boolean property, you can connect it to a flag. This way, the property will automatically reflect the flag's value.

    This can simplify your code and make it more readable.

    ```typescript
    import { storage } from '@drincs/pixi-vn'

    class ButtonClass {
        private _disabled: boolean | string
        get disabled() {
            if (typeof this._disabled === 'string') {
                return storage.getFlag(this._disabled)
            }
            return this._disabled
        }
        set disabled(value: boolean | string) {
            this._disabled = value
        }
    }
    ```

    ```typescript
    // Button to go to school
    const goToSchoolButton = new ButtonClass()
    goToSchoolButton.disabled = 'weekend'

    function afterNewDay() {
        storage.setFlag('weekend', 
            // Check if it is Saturday or Sunday
        )
    }
    ```
  </Accordion>
</Accordions>


# History (/start/history)



<Callout title="UI screen" type="info">
  You can find an example of the history UI screen in the <DynamicLink href="/start/interface-examples#history">interface examples</DynamicLink> section.
</Callout>

Pixi’VN saves all dialogues, choices, responses and more, at every `step` executed during the game.

Get [#get]

The narration timeline is a list of all dialogues and choices shown to the player.\
To get the narrative history, use `stepHistory.narrativeHistory`. It returns a list of `NarrativeHistory<T>[]`.

```typescript
const dialogues: NarrativeHistory[] = stepHistory.narrativeHistory;
```

Remove [#remove]

To delete all narrative history, use `stepHistory.removeNarrativeHistory()`.

```typescript
stepHistory.removeNarrativeHistory();
```

To delete part of the narrative history, pass a number to remove the first N elements:

```typescript
// Delete the first 2 elements
stepHistory.removeNarrativeHistory(2);
```

Other features [#other-features]

<Accordions>
  <Accordion title="limit_saved_steps" id="limit-saved-steps">
    At each `step`, all information about the current game state is saved.

    To prevent the save file from growing too large, there is a limit on the number of `steps` saved. By default, only the last 20 `steps` are saved, but you can increase this limit (e.g., to 100). When the limit is reached, only essential information from older `steps` is kept. This allows you to display the full <DynamicLink href="/start/history">narrative history</DynamicLink>, but you cannot <DynamicLink href="/start/labels-flow#go-back">return</DynamicLink> to a specific `step` beyond the limit.

    You can change the `step` save limit by setting the `stepLimitSaved` property in the `stepHistory` object.

    ```typescript
    import { stepHistory } from '@drincs/pixi-vn'

    stepHistory.stepLimitSaved = 100
    ```

    To disable the `step` save limit, set `stepLimitSaved` to `Infinity`.

    ```typescript
    import { stepHistory } from '@drincs/pixi-vn'

    stepHistory.stepLimitSaved = Infinity
    ```
  </Accordion>
</Accordions>


# 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/)

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="yarn">
      yarn
    </CodeBlockTabsTrigger>

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

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

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

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

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

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

  <CodeBlockTab value="bun">
    ```sh
    bun create pixi-vn
    ```
  </CodeBlockTab>

  <CodeBlockTab value="deno">
    ```sh
    deno init --npm 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.

All templates include a `README.md` file with more information about the 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="yarn">
      yarn
    </CodeBlockTabsTrigger>

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

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

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

  <CodeBlockTab value="npm">
    ```sh
    npm install @drincs/pixi-vn
    ```
  </CodeBlockTab>

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

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

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

  <CodeBlockTab value="deno">
    ```sh
    deno install npm:@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 the Vite plugin.

    This plugin provides the following features:

    * Endpoints to manage characters, `labels`, and assets manifest.
      * `GET /pixi-vn/characters` - Retrieve the list of registered characters.
      * `POST /pixi-vn/characters` - Update the list of registered characters.
      * `GET /pixi-vn/labels` - Retrieve the list of registered `labels`.
      * `POST /pixi-vn/labels` - Update the list of registered `labels`.
      * `GET /pixi-vn/assets/manifest` - Retrieve the assets manifest.
      * `POST /pixi-vn/assets/manifest` - Update the assets manifest.

    <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` function. This function takes a callback that will be called whenever an error occurs in the game.

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

    Game.addOnError((error, { notify }) => {
        notify("An error occurred")
        // Optionally send the error to GlitchTip, Sentry, etc.
    })
    ```

    You can also check if the error is an instance of `PixiError` to handle specific errors related to Pixi’VN.

    ```ts title="main.ts"
    import { PixiError } from '@drincs/pixi-vn'

    Game.addOnError((error, { notify }) => {
        if (error instanceof PixiError) {
            // ...
        }
    })
    ```
  </Accordion>
</Accordions>

Initialize [#initialize]

Before using the Pixi’VN engine, you must initialize the game. You can do this by calling the `Game.init` method.

This function has the following parameters:

* `element`: The HTML element to append the canvas to.
* `options`: Equivalent to the options you can use when initializing a [PixiJS Application](https://pixijs.com/8.x/guides/components/application). Additionally, it supports the following options:
  * `id`: The ID to assign to the canvas element.
  * `resizeMode`: The resize mode to use. Possible values are:
    * `none`: No resizing.
    * `contain`: The canvas will be resized to fit within the parent element while maintaining its aspect ratio. (default)
* `devtoolsOptions`: Equivalent to the options you can use when initializing the <DynamicLink href="/start/canvas#use-pixijs-devtools-with-pixivn">PixiJS Devtools</DynamicLink>.

```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.web.app/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);
});
```

```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;
}
```


# Input prompt (/start/input)





<Callout title="UI screen" type="info">
  You can find an example of the input prompt dialog UI in the <DynamicLink href="/start/interface-examples#input-prompt">interface examples</DynamicLink> section.
</Callout>

<Callout title="ink" type="info">
  You can use this method with the *ink* syntax. See more <DynamicLink href="/ink/input">here</DynamicLink>.
</Callout>

In visual novels, you may need to ask the player to enter text, numbers, dates, or other values.

Pixi’VN provides functions to handle input prompts. The developer can require the player to enter a value (the game will not continue until a value is provided), while the <DynamicLink href="/start/interface">UI</DynamicLink> is responsible for displaying the prompt.

Request [#request]

To prompt the player for input, use the `narration.requestInput()` function.
This function has the following parameters:

* `props`: An object with input prompt properties:
  * `type` (Optional): The type of input prompt (string).
* `defaultValue` (Optional): The default value to display in the input field.

```ts title="labels/startLabel.ts"
import { narration, newLabel } from "@drincs/pixi-vn";

export const startLabel = newLabel("start_label", [
    () => {
        narration.dialogue = "Hello";
    },
    () => {
        narration.dialogue = "What is your name?";
        narration.requestInput({ type: "string" });
    },
    () => {
        narration.dialogue = `My name is ${narration.inputValue}`;
    },
    () => {
        narration.dialogue = "How old are you?";
        narration.requestInput({ type: "number" }, 18);
    },
    () => {
        narration.dialogue = `I am ${narration.inputValue} years old`;
    },
    () => {
        narration.dialogue = "Describe who you are:";
        narration.requestInput({ type: "html textarea" });
    },
    () => {
        narration.dialogue = `${narration.inputValue}`;
    },
    () => {
        narration.dialogue = "Restart";
    },
]);
```

<InputPrompt />

Get [#get]

To get input prompt information, use:

* `narration.isRequiredInput`: Returns `true` if the player must enter a value.
* `narration.inputType`: Returns the type of input prompt requested.

```typescript
if (narration.isRequiredInput) {
    openInputModal(narration.inputType)
}
```

Remove [#remove]

To remove the input prompt request, use `narration.removeInputRequest()`.

```typescript
narration.removeInputRequest()
```


# Connect the UI components with the game variables (/start/interface-connect-storage)





<img alt="usequery" src="__img0" />

The best way to connect the UI with the game variables is to use the TanStack Query library.

**What is TanStack Query?** TanStack Query is a library that allows you to manage the state of your application in a simple and efficient way. It is based on the concept of queries, mutations and subscriptions. This library is very useful and is compatible with React, Vue, Angular, Svelte, etc.

You can learn more about TanStack Query on the [TanStack website](https://tanstack.com/query/latest).

Here is an example:

In our example we have two variables, `text1` and `text2`, stored in the <DynamicLink href="/start/storage">game storage</DynamicLink>. These variables are updated either by a UI input or by a <DynamicLink href="/start/labels">`label`</DynamicLink> or during a `step`.

Because storage variables can only be changed during a <DynamicLink href="/start/labels#continue-and-go-back">next `step` / go back</DynamicLink>, when you <DynamicLink href="/start/labels#run-a-label">run a `label`</DynamicLink>, or when <DynamicLink href="/start/save#load">loading a save</DynamicLink> (outside the interface), we'll create `useQueryText1` and `useQueryText2` hooks and invalidate them after each of those events.

```typescript
import { useQuery } from "@tanstack/react-query";
import { getLastSaveFromIndexDB } from "../utilities/save-utility";

// parent key used to invalidate all related queries
export const INTERFACE_DATA_USE_QUERY_KEY = "interface_data_use_query_key";

const TEXT1_USE_QUERY_KEY = "text1_save_use_query_key";
export function useQueryText1() {
    return useQuery({
        queryKey: [INTERFACE_DATA_USE_QUERY_KEY, TEXT1_USE_QUERY_KEY],
        queryFn: async () => {
            return storage.get<string>("text1") || "";
        },
    });
}

const TEXT2_USE_QUERY_KEY = "text2_save_use_query_key";
export function useQueryText2() {
    return useQuery({
        queryKey: [INTERFACE_DATA_USE_QUERY_KEY, TEXT2_USE_QUERY_KEY],
        queryFn: async () => {
            return storage.get("text2") || "";
        },
    });
}
```

To invalidate queries, use the `queryClient.invalidateQueries` function.

In this example, to update all queries that depend on the `INTERFACE_DATA_USE_QUERY_KEY`, use:

```ts
const queryClient = useQueryClient()
queryClient.invalidateQueries({ queryKey: [INTERFACE_DATA_USE_QUERY_KEY] })
```

To update only the `text1` or `text2` query, use:

```ts
const queryClient = useQueryClient()
queryClient.invalidateQueries({ queryKey: [INTERFACE_DATA_USE_QUERY_KEY, TEXT1_USE_QUERY_KEY] })
queryClient.invalidateQueries({ queryKey: [INTERFACE_DATA_USE_QUERY_KEY, TEXT2_USE_QUERY_KEY] })
```

```typescript
const queryClient = useQueryClient()

narration.continue({})
    .then((result) => {
        queryClient.invalidateQueries({ queryKey: [INTERFACE_DATA_USE_QUERY_KEY] })
    });

stepHistory.back({})
    .then((result) => {
        queryClient.invalidateQueries({ queryKey: [INTERFACE_DATA_USE_QUERY_KEY] })
    });

Game.restoreGameState(jsonString, navigate)
    .then(() => {
        queryClient.invalidateQueries({ queryKey: [INTERFACE_DATA_USE_QUERY_KEY] })
    })

// only if you are not in a label step
narration.call("myLabel", {})
    .then((result) => {
        queryClient.invalidateQueries({ queryKey: [INTERFACE_DATA_USE_QUERY_KEY] })
    });
```

In the UI, call the `useQueryText1` and `useQueryText2` hooks to access the stored `text1` and `text2` values.

```tsx title="src/components/MyComponent.tsx"
export function MyComponent() {
    const { data: text1 = "" } = useQueryText1()
    const { data: text2 = "" } = useQueryText2()
    const queryClient = useQueryClient()

    return (
        <>
            <Input
                sx={{
                    pointerEvents: "auto",
                }}
                value={text1}
                onChange={(e) => {
                    storage.set("text1", e.target.value);
                    queryClient.invalidateQueries({ queryKey: [INTERFACE_DATA_USE_QUERY_KEY, TEXT1_USE_QUEY_KEY] })
                }}
            />
            <Input
                sx={{
                    pointerEvents: "auto",
                }}
                value={text2}
                onChange={(e) => {
                    storage.set("text2", e.target.value);
                    queryClient.invalidateQueries({ queryKey: [INTERFACE_DATA_USE_QUERY_KEY, TEXT2_USE_QUEY_KEY] })
                }}
            />
        </>
    );
}
```


# UI screen examples (/start/interface-examples)



<Callout type="info" name="AI">
  You can use the button above to create your own AI UI screen.
</Callout>

<Callout type="info">
  All examples were created using basic HTML elements, you will need to replace them with UI components from your favorite library to improve the graphics.
</Callout>

<Accordions>
  <Accordion title="ui_narrative_dialogue" id="narrative-dialogue">
    <CodeBlockTabs defaultValue="React">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="React">
          React
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="Vue">
          Vue
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="hooks/useQueryInterface.ts">
          hooks/useQueryInterface.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="React">
        ```tsx
        import Markdown from "react-markdown";
        import rehypeRaw from "rehype-raw";
        import remarkGfm from "remark-gfm";
        import { useQueryDialogue } from "../hooks/useQueryInterface";
        import ChoiceMenu from "./ChoiceMenu";

        export default function NarrationScreen() {
            const { data: { text, character } = {} } = useQueryDialogue();

            return (
                <div
                    style={{
                        position: "absolute",
                        display: "flex",
                        flexDirection: "column",
                        height: "100%",
                        width: "100%",
                    }}
                >
                    <div style={{ flex: 1, minHeight: 0 }}>
                        <ChoiceMenu />
                    </div>
                    {text && (
                        <div
                            style={{
                                flex: "0 0 auto",
                                height: "30%",
                                minHeight: 0,
                                pointerEvents: "auto",
                                backgroundColor: "white",
                                display: "flex",
                                flexDirection: "column",
                                overflow: "hidden",
                            }}
                        >
                            {character && character.name && <b>{`${character?.name || ""} ${character?.surname || ""}`}</b>}
                            <div
                                style={{
                                    display: "flex",
                                    flexDirection: "row",
                                    height: "100%",
                                    minHeight: 0,
                                    overflow: "hidden",
                                }}
                            >
                                {character?.icon && (
                                    <img
                                        src={character?.icon}
                                        loading='lazy'
                                        alt=''
                                        style={{
                                            maxWidth: "30%",
                                            height: "auto",
                                            objectFit: "contain",
                                            display: "block",
                                        }}
                                    />
                                )}
                                <div style={{ flex: 1, minHeight: 0, overflow: "auto", height: "100%" }}>
                                    <Markdown remarkPlugins={[remarkGfm]} rehypePlugins={[rehypeRaw]}>
                                        {text}
                                    </Markdown>
                                </div>
                            </div>
                        </div>
                    )}
                </div>
            );
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="Vue">
        ```vue
        <template>
            <div style="position: absolute; display: flex; flex-direction: column; height: 100%; width: 100%;">
                <div style="flex: 1; min-height: 0;">
                    <ChoiceMenu />
                </div>
                <div
                    v-if="text"
                    style="flex: 0 0 auto; height: 30%; min-height: 0; pointer-events: auto; background-color: white; display: flex; flex-direction: column; overflow: hidden;"
                >
                    <b v-if="character && (character.name || character.surname)">{{ character?.name || '' }} {{ character?.surname || '' }}</b>
                    <div style="display: flex; flex-direction: row; height: 100%; min-height: 0; overflow: hidden;">
                        <img
                            v-if="character && character.icon"
                            :src="character.icon"
                            loading="lazy"
                            alt=""
                            style="max-width: 30%; height: auto; object-fit: contain; display: block;"
                        />
                        <div style="flex: 1; min-height: 0; overflow: auto; height: 100%;">
                            <Markdown v-if="text" :source="text" />
                        </div>
                    </div>
                </div>
            </div>
        </template>

        <script setup>
        import { computed } from 'vue'
        import Markdown from 'vue3-markdown-it'
        import { useQueryDialogue } from '../hooks/useQueryInterface'
        import ChoiceMenu from './ChoiceMenu.vue'

        const { data } = useQueryDialogue()
        const text = computed(() => data.value?.text)
        const character = computed(() => data.value?.character)
        </script>

        ```
      </CodeBlockTab>

      <CodeBlockTab value="hooks/useQueryInterface.ts">
        ```ts
        import { CharacterBaseModel, narration } from "@drincs/pixi-vn";
        import { useQuery } from "@tanstack/react-query";

        export const INTERFACE_DATA_USE_QUEY_KEY = "interface_data_use_quey_key";

        const DIALOGUE_USE_QUEY_KEY = "dialogue_use_quey_key";
        export function useQueryDialogue() {
            return useQuery({
                queryKey: [INTERFACE_DATA_USE_QUEY_KEY, DIALOGUE_USE_QUEY_KEY],
                queryFn: async ({ queryKey }) => {
                    let dialogue = narration.dialogue;
                    let text = dialogue?.text;
                    if (Array.isArray(text)) {
                        text = text.join(" ");
                    }
                    let character = dialogue?.character as string | CharacterBaseModel | undefined;
                    if (typeof character === "string") {
                        character = new CharacterBaseModel(character, {
                            name: character,
                        });
                    }

                    return {
                        text,
                        character,
                    };
                },
            });
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="ui_choice_menu" id="choice-menu">
    <CodeBlockTabs defaultValue="React">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="React">
          React
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="Vue">
          Vue
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="hooks/useQueryInterface.ts">
          hooks/useQueryInterface.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="hooks/useNarrationFunctions.ts">
          hooks/useNarrationFunctions.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="React">
        ```tsx
        import useNarrationFunctions from "../hooks/useNarrationFunctions";
        import { useQueryChoiceMenuOptions } from "../hooks/useQueryInterface";

        export default function ChoiceMenu() {
            const { data: menu = [] } = useQueryChoiceMenuOptions();
            const { selectChoice } = useNarrationFunctions();

            return (
                <div
                    style={{
                        display: "flex",
                        flexDirection: "column",
                        justifyContent: "center",
                        alignItems: "center",
                        width: "100%",
                        height: "100%",
                        overflow: "auto",
                        gap: "8px",
                        maxHeight: "100%",
                        margin: 0,
                        pointerEvents: menu?.length > 0 ? "auto" : "none",
                    }}
                >
                    {menu?.map((item, index) => (
                        <button
                            key={"choice-" + index}
                            style={{
                                justifyContent: "center",
                                alignItems: "center",
                            }}
                            onClick={() => selectChoice(item)}
                        >
                            {item.text}
                        </button>
                    ))}
                </div>
            );
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="Vue">
        ```vue
        <template>
            <div
                :style="{
                    display: 'flex',
                    flexDirection: 'column',
                    justifyContent: 'center',
                    alignItems: 'center',
                    width: '100%',
                    height: '100%',
                    overflow: 'auto',
                    gap: '8px',
                    maxHeight: '100%',
                    margin: 0,
                }"
                :pointer-events="menu.length > 0 ? 'auto' : 'none'">
                <button
                    v-for="(item, index) in menu"
                    :key="'choice-' + index"
                    :style="{ justifyContent: 'center', alignItems: 'center' }"
                    @click="selectChoice(item)"
                >
                    {{ item.text }}
                </button>
            </div>
        </template>

        <script setup>
        import { computed } from 'vue'
        import useNarrationFunctions from '../hooks/useNarrationFunctions'
        import { useQueryChoiceMenuOptions } from '../hooks/useQueryInterface'

        const { data } = useQueryChoiceMenuOptions()
        const menu = computed(() => data.value || [])
        const { selectChoice } = useNarrationFunctions()
        </script>

        ```
      </CodeBlockTab>

      <CodeBlockTab value="hooks/useQueryInterface.ts">
        ```ts
        import { CharacterBaseModel, narration } from "@drincs/pixi-vn";
        import { useQuery } from "@tanstack/react-query";

        export const INTERFACE_DATA_USE_QUEY_KEY = "interface_data_use_quey_key";

        const CHOICE_MENU_OPTIONS_USE_QUEY_KEY = "choice_menu_options_use_quey_key";
        export function useQueryChoiceMenuOptions() {
            return useQuery({
                queryKey: [INTERFACE_DATA_USE_QUEY_KEY, CHOICE_MENU_OPTIONS_USE_QUEY_KEY],
                queryFn: async () =>
                    narration.choices?.map((option) => ({
                        ...option,
                        text: typeof option.text === "string" ? option.text : option.text.join(" "),
                    })) || [],
            });
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="hooks/useNarrationFunctions.ts">
        ```ts
        import { narration, StoredIndexedChoiceInterface } from "@drincs/pixi-vn";
        import { useQueryClient } from "@tanstack/react-query";
        import { useCallback } from "react";
        import { INTERFACE_DATA_USE_QUEY_KEY } from "./useQueryInterface";

        export default function useNarrationFunctions() {
            const queryClient = useQueryClient();
            const gameProps = {};

            const selectChoice = useCallback(
                async (item: StoredIndexedChoiceInterface) => {
                return narration
                    .selectChoice(item, gameProps)
                    .then(() => queryClient.invalidateQueries({ queryKey: [INTERFACE_DATA_USE_QUEY_KEY] }))
                    .catch((e) => console.error(e));
                },
                [gameProps, queryClient]
            );

            return {
                selectChoice,
            };
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="ui_go_next" id="go-next">
    <CodeBlockTabs defaultValue="React">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="React">
          React
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="Vue">
          Vue
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="hooks/useQueryInterface.ts">
          hooks/useQueryInterface.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="hooks/useNarrationFunctions.ts">
          hooks/useNarrationFunctions.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="React">
        ```tsx
        import { useState } from "react";
        import useNarrationFunctions from "../hooks/useNarrationFunctions";
        import { useQueryCanGoNext } from "../hooks/useQueryInterface";

        export default function NextButton() {
            const { data: canGoNext = false } = useQueryCanGoNext();
            const [loading, setLoading] = useState(false);
            const { goNext } = useNarrationFunctions();

            if (!canGoNext) {
                return null;
            }

            return (
                <button
                    onClick={() => {
                        setLoading(true);
                        goNext()
                            .then(() => setLoading(false))
                            .catch(() => setLoading(false));
                    }}
                    disabled={loading}
                    style={{
                        width: 40,
                        height: 20,
                        pointerEvents: "auto",
                    }}
                >
                    Next
                </button>
            );
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="Vue">
        ```vue
        <template>
            <button
                v-if="canGoNext"
                :disabled="loading"
                :style="{ width: '40px', height: '20px', pointerEvents: 'auto' }"
                @click="handleClick"
            >
                Next
            </button>
        </template>

        <script setup>
        import { ref, computed } from 'vue'
        import useNarrationFunctions from '../hooks/useNarrationFunctions'
        import { useQueryCanGoNext } from '../hooks/useQueryInterface'

        const { data } = useQueryCanGoNext()
        const canGoNext = computed(() => data.value ?? false)
        const loading = ref(false)
        const { goNext } = useNarrationFunctions()

        function handleClick() {
            loading.value = true
            goNext()
                .then(() => (loading.value = false))
                .catch(() => (loading.value = false))
        }
        </script>

        ```
      </CodeBlockTab>

      <CodeBlockTab value="hooks/useQueryInterface.ts">
        ```ts
        import { narration } from "@drincs/pixi-vn";
        import { useQuery } from "@tanstack/react-query";

        export const INTERFACE_DATA_USE_QUEY_KEY = "interface_data_use_quey_key";

        const CAN_GO_NEXT_USE_QUEY_KEY = "can_go_next_use_quey_key";
        export function useQueryCanGoNext() {
            return useQuery({
                queryKey: [INTERFACE_DATA_USE_QUEY_KEY, CAN_GO_NEXT_USE_QUEY_KEY],
                queryFn: async () => narration.canContinue && !narration.isRequiredInput,
            });
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="hooks/useNarrationFunctions.ts">
        ```ts
        import { narration } from "@drincs/pixi-vn";
        import { useQueryClient } from "@tanstack/react-query";
        import { useCallback } from "react";
        import { INTERFACE_DATA_USE_QUEY_KEY } from "./useQueryInterface";

        export default function useNarrationFunctions() {
            const queryClient = useQueryClient();
            const gameProps = {};

            const goNext = useCallback(async () => {
                try {
                    if (!narration.canContinue) {
                        return;
                    }
                    return narration
                        .continue(gameProps)
                        .then(() => queryClient.invalidateQueries({ queryKey: [INTERFACE_DATA_USE_QUEY_KEY] }))
                        .catch((e) => console.error(e));
                } catch (e) {
                    console.error(e);
                    return;
                }
            }, [gameProps, queryClient]);

            return {
                goNext,
            };
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="ui_go_back" id="go-back">
    <CodeBlockTabs defaultValue="React">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="React">
          React
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="Vue">
          Vue
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="hooks/useQueryInterface.ts">
          hooks/useQueryInterface.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="hooks/useNarrationFunctions.ts">
          hooks/useNarrationFunctions.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="React">
        ```tsx
        import { useState } from "react";
        import useNarrationFunctions from "../hooks/useNarrationFunctions";
        import { useQueryCanGoBack } from "../hooks/useQueryInterface";

        export default function BackButton() {
            const { data: canGoBack = false } = useQueryCanGoBack();
            const [loading, setLoading] = useState(false);
            const { goBack } = useNarrationFunctions();

            if (!canGoBack) {
                return null;
            }

            return (
                <button
                    onClick={() => {
                        setLoading(true);
                        goBack()
                            .then(() => setLoading(false))
                            .catch(() => setLoading(false));
                    }}
                    disabled={loading}
                    style={{
                        width: 40,
                        height: 20,
                        pointerEvents: "auto",
                    }}
                >
                    Back
                </button>
            );
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="Vue">
        ```vue
        <template>
            <button
                v-if="canGoBack"
                :disabled="loading"
                :style="{ width: '40px', height: '20px', pointerEvents: 'auto' }"
                @click="handleClick"
            >
                Back
            </button>
        </template>

        <script setup>
        import { ref, computed } from 'vue'
        import useNarrationFunctions from '../hooks/useNarrationFunctions'
        import { useQueryCanGoBack } from '../hooks/useQueryInterface'

        const { data } = useQueryCanGoBack()
        const canGoBack = computed(() => data.value ?? false)
        const loading = ref(false)
        const { goBack } = useNarrationFunctions()

        function handleClick() {
            loading.value = true
            goBack()
                .then(() => (loading.value = false))
                .catch(() => (loading.value = false))
        }
        </script>

        ```
      </CodeBlockTab>

      <CodeBlockTab value="hooks/useQueryInterface.ts">
        ```ts
        import { stepHistory } from "@drincs/pixi-vn";
        import { useQuery } from "@tanstack/react-query";

        export const INTERFACE_DATA_USE_QUEY_KEY = "interface_data_use_quey_key";

        const CAN_GO_BACK_USE_QUEY_KEY = "can_go_back_use_quey_key";
        export function useQueryCanGoBack() {
            return useQuery({
                queryKey: [INTERFACE_DATA_USE_QUEY_KEY, CAN_GO_BACK_USE_QUEY_KEY],
                queryFn: async () => stepHistory.canGoBack,
            });
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="hooks/useNarrationFunctions.ts">
        ```ts
        import { stepHistory } from "@drincs/pixi-vn";
        import { useQueryClient } from "@tanstack/react-query";
        import { useCallback } from "react";
        import { INTERFACE_DATA_USE_QUEY_KEY } from "./useQueryInterface";

        export default function useNarrationFunctions() {
            const queryClient = useQueryClient();
            const gameProps = {};

            const goBack = useCallback(async () => {
                return stepHistory
                    .back(gameProps)
                    .then(() => queryClient.invalidateQueries({ queryKey: [INTERFACE_DATA_USE_QUEY_KEY] }))
                    .catch((e) => console.error(e));
            }, [gameProps, queryClient]);

            return {
                goBack,
            };
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="ui_input_prompt" id="input-prompt">
    <CodeBlockTabs defaultValue="React">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="React">
          React
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="Vue">
          Vue
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="hooks/useQueryInterface.ts">
          hooks/useQueryInterface.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="React">
        ```tsx
        import { narration } from "@drincs/pixi-vn";
        import { useQueryClient } from "@tanstack/react-query";
        import { useState } from "react";
        import { INTERFACE_DATA_USE_QUEY_KEY, useQueryDialogue, useQueryInputValue } from "../../hooks/useQueryInterface";

        export default function TextInput() {
            const { data: { text } = {} } = useQueryDialogue();
            const {
                data: { isRequired: open, currentValue } = {
                    currentValue: undefined,
                    isRequired: false,
                },
            } = useQueryInputValue<string | number>();
            const [tempValue, setTempValue] = useState<string | number>();
            const queryClient = useQueryClient();

            return (
                <dialog
                    open={open}
                    style={{
                        pointerEvents: "auto",
                    }}
                >
                    <p>{text}</p>
                    {open && (
                        <input
                            defaultValue={currentValue || ""}
                            onChange={(e) => {
                                if (e && e.target && "value" in e.target) {
                                    let value: any = e.target.value;
                                    if ("type" in e.target && e.target.type === "number" && "valueAsNumber" in e.target) {
                                        value = e.target.valueAsNumber;
                                    }
                                    setTempValue(value);
                                }
                            }}
                        />
                    )}
                    <button
                        onClick={() => {
                            narration.inputValue = tempValue || currentValue;
                            setTempValue(undefined);
                            queryClient.invalidateQueries({
                                queryKey: [INTERFACE_DATA_USE_QUEY_KEY],
                            });
                        }}
                    >
                        Confirm
                    </button>
                </dialog>
            );
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="Vue">
        ```vue
        <template>
            <dialog :open="open" style="pointer-events: auto;">
                <p>{{ text }}</p>
                <input
                    v-if="open"
                    :value="currentValue || ''"
                    @input="onInput"
                />
                <button @click="confirm">Confirm</button>
            </dialog>
        </template>

        <script setup>
        import { ref, computed } from 'vue'
        import { useQueryClient } from '@tanstack/vue-query'
        import { narration } from '@drincs/pixi-vn'
        import { INTERFACE_DATA_USE_QUEY_KEY, useQueryDialogue, useQueryInputValue } from '../../hooks/useQueryInterface'

        const { data: dialogueData } = useQueryDialogue()
        const text = computed(() => dialogueData.value?.text)

        const { data: inputData } = useQueryInputValue()
        const open = computed(() => inputData.value?.isRequired ?? false)
        const currentValue = computed(() => inputData.value?.currentValue)

        const tempValue = ref(undefined)
        const queryClient = useQueryClient()

        function onInput(e) {
            tempValue.value = e.target?.value
        }

        function confirm() {
            narration.inputValue = tempValue.value ?? currentValue.value
            tempValue.value = undefined
            queryClient.invalidateQueries({ queryKey: [INTERFACE_DATA_USE_QUEY_KEY] })
        }
        </script>

        ```
      </CodeBlockTab>

      <CodeBlockTab value="hooks/useQueryInterface.ts">
        ```ts
        import { CharacterBaseModel, narration } from "@drincs/pixi-vn";
        import { useQuery } from "@tanstack/react-query";

        export const INTERFACE_DATA_USE_QUEY_KEY = "interface_data_use_quey_key";

        const INPUT_VALUE_USE_QUEY_KEY = "input_value_use_quey_key";
        export function useQueryInputValue<T>() {
            return useQuery({
                queryKey: [INTERFACE_DATA_USE_QUEY_KEY, INPUT_VALUE_USE_QUEY_KEY],
                queryFn: async () => ({
                    isRequired: narration.isRequiredInput,
                    type: narration.inputType,
                    currentValue: narration.inputValue as T | undefined,
                }),
            });
        }

        const DIALOGUE_USE_QUEY_KEY = "dialogue_use_quey_key";
        export function useQueryDialogue() {
            return useQuery({
                queryKey: [INTERFACE_DATA_USE_QUEY_KEY, DIALOGUE_USE_QUEY_KEY],
                queryFn: async ({ queryKey }) => {
                    let dialogue = narration.dialogue;
                    let text = dialogue?.text;
                    if (Array.isArray(text)) {
                        text = text.join(" ");
                    }
                    let character = dialogue?.character as string | CharacterBaseModel | undefined;
                    if (typeof character === "string") {
                        character = new CharacterBaseModel(character, {
                            name: character,
                        });
                    }

                    return {
                        text,
                        character,
                    };
                },
            });
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="ui_history" id="history">
    <CodeBlockTabs defaultValue="React">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="React">
          React
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="Vue">
          Vue
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="hooks/useQueryInterface.ts">
          hooks/useQueryInterface.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="React">
        ```tsx
        import { Box, Stack } from "@mui/system";
        import React from "react";
        import { useQueryNarrativeHistory } from "../use_query/useQueryInterface";

        export default function HistoryScreen() {
            const { data = [] } = useQueryNarrativeHistory();

            return (
                <dialog
                    open={true}
                    style={{
                        height: "80%",
                    }}
                >
                    <Box
                        sx={{
                            display: "flex",
                            flex: 1,
                            minHeight: 0,
                            px: 2,
                            py: 3,
                            overflowY: "scroll",
                            flexDirection: "column-reverse",
                            pointerEvents: "auto",
                            overflow: "auto",
                            height: "80%",
                        }}
                    >
                        <Stack spacing={2} justifyContent="flex-end">
                        {data.map((data, index) => {
                            return (
                            <React.Fragment key={"history" + index}>
                                <Stack direction="row" spacing={1.5}>
                                    <img
                                        src={data.icon}
                                        loading="lazy"
                                        alt=""
                                        style={{
                                            verticalAlign: "middle",
                                            maxWidth: "50px",
                                            maxHeight: "50px",
                                            borderRadius: "50%",
                                        }}
                                    />
                                    <Box sx={{ flex: 1 }}>
                                        {data.character && data.character}
                                        <div />
                                        {data.text}
                                    </Box>
                                </Stack>
                                <Stack direction="row" spacing={0.5}>
                                    <Box sx={{ flex: 1 }}>
                                        {data.choices &&
                                        data.choices.map((choice, index) => {
                                            if (choice.hidden) {
                                                return null;
                                            }
                                            if (choice.isResponse) {
                                                return (
                                                    <div
                                                        key={"choices-success" + index}
                                                        style={{
                                                            display: "inline-block",
                                                            padding: "5px 5px",
                                                            fontSize: "12px",
                                                            borderRadius: "25px",
                                                            backgroundColor: "#21ff3e",
                                                        }}
                                                    >
                                                        {choice.text}
                                                    </div>
                                                );
                                            }
                                            return (
                                                <div
                                                    key={"choices" + index}
                                                    style={{
                                                        display: "inline-block",
                                                        padding: "5px 5px",
                                                        fontSize: "12px",
                                                        borderRadius: "25px",
                                                        backgroundColor: "#bcfdff",
                                                    }}
                                                >
                                                    {choice.text}
                                                </div>
                                            );
                                        })}
                                        {data.inputValue && (
                                            <div
                                                key={"choices-success" + index}
                                                style={{
                                                    display: "inline-block",
                                                    padding: "5px 5px",
                                                    fontSize: "12px",
                                                    borderRadius: "25px",
                                                    backgroundColor: "#b0c2b2",
                                                }}
                                            >
                                                {data.inputValue.toString()}
                                            </div>
                                        )}
                                    </Box>
                                </Stack>
                            </React.Fragment>
                            );
                        })}
                        </Stack>
                    </Box>
                </dialog>
            );
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="Vue">
        ```vue
        <template>
            <dialog open style="height: 80%;">
                <div
                    style="display:flex;flex:1;min-height:0;padding:0 16px;overflow-y:scroll;flex-direction:column-reverse;pointer-events:auto;height:80%;"
                >
                    <div v-for="(item, index) in data" :key="'history' + index" style="margin-bottom: 12px;">
                        <div style="display:flex;gap:12px;align-items:center;">
                            <img :src="item.icon" loading="lazy" alt="" style="vertical-align:middle;max-width:50px;max-height:50px;border-radius:50%;" />
                            <div style="flex:1;">
                                <div>{{ item.character }}</div>
                                <div />
                                <div>{{ item.text }}</div>
                            </div>
                        </div>
                        <div style="display:flex;gap:8px;margin-top:8px;">
                            <div style="flex:1;">
                                <template v-if="item.choices">
                                    <template v-for="(choice, i) in item.choices" :key="'choice-' + i">
                                        <span v-if="!choice.hidden" :style="choice.isResponse ? responseStyle : choiceStyle">{{ choice.text }}</span>
                                    </template>
                                </template>
                                <div v-if="item.inputValue" :style="inputStyle">{{ item.inputValue.toString() }}</div>
                            </div>
                        </div>
                    </div>
                </div>
            </dialog>
        </template>

        <script setup>
        import { computed } from 'vue'
        import { useQueryNarrativeHistory } from '../use_query/useQueryInterface'

        const { data } = useQueryNarrativeHistory()
        const responseStyle = { display: 'inline-block', padding: '5px 5px', fontSize: '12px', borderRadius: '25px', backgroundColor: '#21ff3e' }
        const choiceStyle = { display: 'inline-block', padding: '5px 5px', fontSize: '12px', borderRadius: '25px', backgroundColor: '#bcfdff' }
        const inputStyle = { display: 'inline-block', padding: '5px 5px', fontSize: '12px', borderRadius: '25px', backgroundColor: '#b0c2b2' }
        </script>

        ```
      </CodeBlockTab>

      <CodeBlockTab value="hooks/useQueryInterface.ts">
        ```ts
        import {
            CharacterBaseModel,
            getCharacterById,
            narration,
        } from "@drincs/pixi-vn";
        import { useQuery } from "@tanstack/react-query";

        export const INTERFACE_DATA_USE_QUEY_KEY = "interface_data_use_quey_key";

        const NARRATIVE_HISTORY_USE_QUEY_KEY = "narrative_history_use_quey_key";
        export function useQueryNarrativeHistory() {
            return useQuery({
                queryKey: [INTERFACE_DATA_USE_QUEY_KEY, NARRATIVE_HISTORY_USE_QUEY_KEY],
                queryFn: () => {
                    return narration.narrativeHistory.map((step) => {
                        let character = step.dialoge?.character
                            ? getCharacterById(step.dialoge?.character) ??
                                new CharacterBaseModel(step.dialoge?.character, {
                                    name: step.dialoge?.character,
                                })
                            : undefined;
                        return {
                            character: character?.name
                                ? character.name +
                                (character.surname ? " " + character.surname : "")
                                : undefined,
                            text: step.dialoge?.text || "",
                            icon: character?.icon,
                            choices: step.choices,
                            inputValue: step.inputValue,
                        };
                    });
                },
            });
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>
</Accordions>


# Change UI font and text size (/start/interface-font)



This page explains how to change the UI font and text size in a Pixi’VN project.

<Callout title="Templates" type="info">
  Pixi’VN templates use Vite and Tailwind CSS, so the instructions below are tuned for that setup.
</Callout>

Import the font [#import-the-font]

To import a font you can use a service such as [Google Fonts](https://fonts.google.com/) or host fonts locally. For Google Fonts, add an `@import` to your `index.css`.

Example:

```css title="index.css"
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap');
```

For local fonts, copy the files to `public/fonts/` and declare an `@font-face` in `index.css`.

Example:

```css title="index.css"
@font-face {
  font-family: 'MyCustomFont';
  src: url('/fonts/MyCustomFont-Regular.woff2') format('woff2'),
       url('/fonts/MyCustomFont-Regular.woff') format('woff');
  font-weight: 400;
  font-style: normal;
}
```

Set the global font and sizes [#set-the-global-font-and-sizes]

In `index.css` (or your global stylesheet) set the font family and — if desired — CSS variables for sizes.

Example:

```css title="index.css"
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "tailwindcss-motion";

:root {
  --ui-font-family: 'Inter', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto; /* [!code ++] */
  --ui-font-size: 16px; /* [!code ++] */
}

html,
body {
  background-color: #242424;
  height: 100%;
}

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

@layer base { /* [!code ++] */
  html { font-size: 16px; } /* [!code ++] */
  body { font-family: var(--ui-font-family); } /* [!code ++] */
  .ui-text { font-size: var(--ui-font-size); } /* [!code ++] */
} /* [!code ++] */
```

Use Tailwind utilities in components [#use-tailwind-utilities-in-components]

Prefer Tailwind classes for consistency.

Example:

* React: `<div className="font-sans text-ui-base">UI text</div>`
* Vue: `<div class="font-sans text-ui-base">UI text</div>`

For UI parts that need a custom look (dialog box, choice menu) add classes like `font-display text-ui-lg`.


# Navigate/switch between UI screens (/start/interface-navigate)



To navigate between different UI screens, it is necessary to use a routing system. A routing system allows you to define routes (or paths) for different screens and manage navigation between them. There are several routing systems available, including:

* [TanStack Router](https://tanstack.com/router/latest)
* [React Router](https://reactrouter.com/)
* [Vue Router](https://router.vuejs.org/)
* [Angular Router](https://angular.io/guide/router)

TanStack Router [#tanstack-router]

<Callout title="Templates" type="info">
  All templates generated with version 2.0.0 of `create-pixi-vn` use TanStack Router as the routing system.
</Callout>

TanStack Router is a routing system for web applications that allows you to manage navigation between different pages or components in a simple and efficient way. It is designed to be flexible and easy to use, offering advanced features such as support for dynamic parameters, router state management, and integration with rendering libraries like React, Vue, and Angular.

The main advantage of TanStack Router is its ability to automatically generate route handling using `createFileRoute`. With `createFileRoute`, you can define your routes simply by creating files in a specific folder structure. For example, if you create a file `about.tsx` in the `src/routes` folder, TanStack Router will automatically generate a route for `/about` that renders the component defined in `about.tsx`.

```ts title="src/routes/about.tsx"
import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/about")({ // [!code focus]
    component: About, // [!code focus]
}); // [!code focus]

function About() {
    return (
        <main className="page-wrap px-4 py-12">
            <section className="island-shell rounded-2xl p-6 sm:p-8">
                <p className="island-kicker mb-2">About</p>
                <h1 className="display-title mb-3 text-4xl font-bold text-[var(--sea-ink)] sm:text-5xl">
                    A small starter with room to grow.
                </h1>
                <p className="m-0 max-w-3xl text-base leading-8 text-[var(--sea-ink-soft)]">
                    TanStack Start gives you type-safe routing, server functions, and modern SSR defaults. Use this as a
                    clean foundation, then layer in your own routes, styling, and add-ons.
                </p>
            </section>
        </main>
    );
}
```

How to navigate between routes? [#how-to-navigate-between-routes]

To navigate between routes, use the navigation function provided by your routing system.

<Callout title="Templates" type="info">
  In all templates, the `StepLabelProps` interface is already extended to include a `navigate` function. You can find it in the `pixi-vn.d.ts` file.
</Callout>

In pixi-vn projects, it's very common to need to navigate between routes while narrating. To enable this, the navigation function must be included in the <DynamicLink href="/start/labels#steplabelprops">`StepLabelProps` interface</DynamicLink>.

<CodeBlockTabs defaultValue="pixi-vn.d.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="pixi-vn.d.ts">
      pixi-vn.d.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="hooks/useGameProps.ts">
      hooks/useGameProps.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="pixi-vn.d.ts">
    ```ts
    import { narration } from '@drincs/pixi-vn'

    declare module '@drincs/pixi-vn' {
        interface StepLabelProps {
            navigate: (route: string) => void,
        }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="hooks/useGameProps.ts">
    ```ts
    import { StepLabelProps } from "@drincs/pixi-vn";
    import useMyNavigate from "./useMyNavigate";

    export default function useGameProps(): StepLabelProps {
        const navigate = useMyNavigate();

        return {
            navigate,
        };
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Callout title="ink" type="info">
  In all *ink* templates, a <DynamicLink href="/ink/hashtag">custom hashtag command</DynamicLink> has been introduced to navigate between routes. To do this, you need to use the following syntax:

  ```ink title="ink"
  # navigate [route]
  ```

  * `route`: The destination route/path. For example, `# navigate /new-route`.
</Callout>

So, when you create a new label, you can use the `navigate` function to switch between routes:

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    export const startLabel = newLabel("start_label",
        [
            ({ navigate }) => { // [!code focus]
                navigate("/new-route") // [!code focus]
            }, // [!code focus]
        ]
    )
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Accordions>
  <Accordion title="block_back_forward" id="block-back-forward">
    Using the browser's back and forward buttons can cause the game to be in an inconsistent state. This is because those keys allow the player to navigate between routes, not between narrative `steps`.

    It is recommended to prevent the path from changing when the browser's back button is pressed. There are many ways to do this, but the following approach is suggested:

    Intercept the `popstate` event, which is triggered after the browser's back button is pressed, and call `history.forward()` to cancel the navigation. To allow users to navigate back if they press the back button twice in succession, we can push a new state to the history stack on each route change.

    For example:

    ```ts title="hooks/useConfirmBackNavigation.ts"
    import { useLocation } from "@tanstack/react-router";
    import { useEffect } from "react";

    /**
     * useConfirmBackNavigation
     *
     * Prevent accidental browser "back" navigation.
     * Behavior:
     * - On each `href` change it pushes a history state (`pushState`).
     * - Listens for `popstate` and calls `history.forward()` to cancel a single
     *   press of the browser back button.
     * - If the user presses back twice in succession (i.e. the second press occurs
     *   before the first is handled), the browser will navigate back.
     *
     * Usage: call this hook at the app root to avoid unintended back navigations
     * (e.g. accidental taps or gestures). Returns `null`.
     */
    export default function useConfirmBackNavigation() {
        const { href } = useLocation();

        useEffect(() => {
            const isInIframe = typeof window !== "undefined" && window.self !== window.top;
            if (isInIframe) return;
            const listener = () => {
                window.history.forward();
            };
            window.addEventListener("popstate", listener);

            return () => {
                window.removeEventListener("popstate", listener);
            };
        }, []);

        useEffect(() => {
            window.history.pushState(null, href, href);
        }, [href]);
    }
    ```
  </Accordion>
</Accordions>


# PixiJS UI (/start/interface-pixijs)



As explained in more detail <DynamicLink href="/start/canvas#pixijs-differences">here</DynamicLink>, the entire rendering part of Pixi’VN is based on PixiJS. By taking advantage of <DynamicLink href="/start/interface#adding-pixijs-ui-layers">PixiJS Layers</DynamicLink>, you can use PixiJS to create custom UI screens.

<Callout title="Templates" type="info">
  In all templates, a PixiJS Layer called "ui" is created on startup. You can use this layer to create your UI screens.
</Callout>

You can also combine HTML Layer components with PixiJS Layer ones. To do this, add the PixiJS components during the first rendering of an HTML screen and clean up the PixiJS Layer when the screen is closed.

For example:

```tsx title="React"
import { useEffect } from "react";
import { Assets, canvas } from "@drincs/pixi-vn";
import { Sprite } from "pixi.js";

export default function MyScreen() {
    useEffect(() => {
        let layer = canvas.getLayer("ui");
        if (layer) {
            const texture = await Assets.load('https://pixijs.com/assets/bunny.png');
            const bunny = new Sprite(texture);
            layer.addChild(bg);
        }

        return () => {
            canvas.getLayer("ui")?.removeChildren();
        };
    });

    return null;
}
```

Best PixiJS component libraries [#best-pixijs-component-libraries]

To create a beautiful user interface, you can use some of the best PixiJS component libraries:

* [PixiJS](https://pixijs.com/)
* [PixiUI](https://github.com/pixijs/ui)
* [PixiLayout](https://github.com/pixijs/layout)


# React UI (/start/interface-react)



**What is React?** React is a JavaScript library for building user interfaces (UIs) for websites, apps, and more. It's free, open-source, and maintained by Meta (formerly Facebook) and a large community.

You can learn more about React on the [React website](https://react.dev/).

How to add Pixi’VN to a React application [#how-to-add-pixivn-to-a-react-application]

<Callout title="React template" type="info">
  There are Pixi’VN templates available that use React. You can read more about them in the <DynamicLink href="/start#project-initialization">templates</DynamicLink> section.

  If you want to add Pixi’VN to an existing React application, follow the steps below.
</Callout>

First, you need a React application and to <DynamicLink href="/start#installation">install pixi-vn</DynamicLink>. It is recommended to use [Vite](https://vite.dev/guide/#scaffolding-your-first-vite-project) to create a new React application.

Now you can replace the content of the following files with the code below:

<CodeBlockTabs defaultValue="src/main.tsx">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="src/main.tsx">
      src/main.tsx
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="src/index.css">
      src/index.css
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="src/App.tsx">
      src/App.tsx
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="src/main.tsx">
    ```tsx
    import { Assets, canvas, Container, drawCanvasErrorHandler, Game, showImage, sound } from "@drincs/pixi-vn"; // [!code ++]
    import { StrictMode } from "react";
    import { createRoot } from "react-dom/client";
    import App from "./App.tsx";
    import "./index.css";

    createRoot(document.getElementById("root")!).render( // [!code --]
    const body = document.body; // [!code ++]
    if (!body) { // [!code ++]
        throw new Error("body element not found"); // [!code ++]
    } // [!code ++]

    Game.init(body, { // [!code ++]
        height: 1080, // [!code ++]
        width: 1920, // [!code ++]
        backgroundColor: "#303030", // [!code ++]
        resizeMode: "contain", // [!code ++]
    }).then(() => { // [!code ++]
        showImage( // [!code ++]
            "juliette", // [!code ++]
            "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/icon.webp", // [!code ++]
            { xAlign: 0.9, yAlign: 0.1, anchor: 0.5 }, // [!code ++]
        ).then(() => { // [!code ++]
            canvas.animate("juliette", { angle: 360 }, { repeat: Infinity, duration: 5 }); // [!code ++]
        }); // [!code ++]

        // Pixi.JS UI Layer // [!code ++]
        canvas.addLayer("ui", new Container()); // [!code ++]

        // Sound setup // [!code ++]
        sound.addChannel("bgm", { background: true }); // [!code ++]
        sound.addChannel("sfx"); // [!code ++]
        sound.defaultChannelAlias = "sfx"; // [!code ++]

        // React setup with ReactDOM // [!code ++]
        const root = document.getElementById("root"); // [!code ++]
        if (!root) { // [!code ++]
            throw new Error("root element not found"); // [!code ++]
        } // [!code ++]

        const htmlLayout = canvas.addHtmlLayer("ui", root); // [!code ++]
        if (!htmlLayout) { // [!code ++]
            throw new Error("htmlLayout not found"); // [!code ++]
        } // [!code ++]
        const reactRoot = createRoot(htmlLayout); // [!code ++]

        reactRoot.render(
            <StrictMode>
                <App />
            </StrictMode>,
        )
    }); // [!code ++]

    Game.onEnd(async (props) => { // [!code ++]
        Game.clear(); // [!code ++]
        // Navigate to the main menu after the game ends // [!code ++]
    }); // [!code ++]

    Game.addOnError(drawCanvasErrorHandler()); // [!code ++]
    Game.addOnError((error, props) => { // [!code ++]
        console.error(`Error occurred`, error); // [!code ++]
    }); // [!code ++]

    Game.onLoadingLabel((_stepId, { id }) => Assets.backgroundLoadBundle(id)); // [!code ++]
    ```
  </CodeBlockTab>

  <CodeBlockTab value="src/index.css">
    ```css
    :root {
      --text: #6b6375;
      --text-h: #08060d;
      --bg: #fff;
      --border: #e5e4e7;
      --code-bg: #f4f3ec;
      --accent: #aa3bff;
      --accent-bg: rgba(170, 59, 255, 0.1);
      --accent-border: rgba(170, 59, 255, 0.5);
      --social-bg: rgba(244, 243, 236, 0.5);
      --shadow:
        rgba(0, 0, 0, 0.1) 0 10px 15px -3px, rgba(0, 0, 0, 0.05) 0 4px 6px -2px;

      --sans: system-ui, 'Segoe UI', Roboto, sans-serif;
      --heading: system-ui, 'Segoe UI', Roboto, sans-serif;
      --mono: ui-monospace, Consolas, monospace;

      font: 18px/145% var(--sans);
      letter-spacing: 0.18px;
      color-scheme: light dark;
      color: var(--text);
      background: var(--bg);
      font-synthesis: none;
      text-rendering: optimizeLegibility;
      -webkit-font-smoothing: antialiased;
      -moz-osx-font-smoothing: grayscale;

      @media (max-width: 1024px) {
        font-size: 16px;
      }
    }

    @media (prefers-color-scheme: dark) {
      :root {
        --text: #9ca3af;
        --text-h: #f3f4f6;
        --bg: #16171d;
        --border: #2e303a;
        --code-bg: #1f2028;
        --accent: #c084fc;
        --accent-bg: rgba(192, 132, 252, 0.15);
        --accent-border: rgba(192, 132, 252, 0.5);
        --social-bg: rgba(47, 48, 58, 0.5);
        --shadow:
          rgba(0, 0, 0, 0.4) 0 10px 15px -3px, rgba(0, 0, 0, 0.25) 0 4px 6px -2px;
      }

      #social .button-icon {
        filter: invert(1) brightness(2);
      }
    }

    #root {
      width: 1126px;
      max-width: 100%;
      margin: 0 auto;
      text-align: center;
      border-inline: 1px solid var(--border);
      min-height: 100svh;
      display: flex;
      flex-direction: column;
      box-sizing: border-box;
    }

    html, /* [!code ++] */
    body { /* [!code ++] */
      background-color: #242424; /* [!code ++] */
      height: 100%; /* [!code ++] */
    } /* [!code ++] */

    body {
      margin: 0;
      min-height: 100vh; /* [!code ++] */
      display: flex; /* [!code ++] */
      overflow: hidden; /* [!code ++] */
    }

    h1,
    h2 {
      font-family: var(--heading);
      font-weight: 500;
      color: var(--text-h);
    }

    h1 {
      font-size: 56px;
      letter-spacing: -1.68px;
      margin: 32px 0;
      @media (max-width: 1024px) {
        font-size: 36px;
        margin: 20px 0;
      }
    }
    h2 {
      font-size: 24px;
      line-height: 118%;
      letter-spacing: -0.24px;
      margin: 0 0 8px;
      @media (max-width: 1024px) {
        font-size: 20px;
      }
    }
    p {
      margin: 0;
    }

    code,
    .counter {
      font-family: var(--mono);
      display: inline-flex;
      border-radius: 4px;
      color: var(--text-h);
    }

    code {
      font-size: 15px;
      line-height: 135%;
      padding: 4px 8px;
      background: var(--code-bg);
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="src/App.tsx">
    ```tsx
    import { useState } from 'react'
    import './App.css'
    import heroImg from './assets/hero.png'
    import reactLogo from './assets/react.svg'
    import viteLogo from './assets/vite.svg'

    function App() {
      const [count, setCount] = useState(0)

      return (
        <>
          <section id="center">
            <div className="hero">
              <img src={heroImg} className="base" width="170" height="179" alt="" />
              <img src={reactLogo} className="framework" alt="React logo" />
              <img src={viteLogo} className="vite" alt="Vite logo" />
            </div>
            <div>
              <h1>Get started</h1>
              <p>
                Edit <code>src/App.tsx</code> and save to test <code>HMR</code>
              </p>
            </div>
            <button
              className="counter"
              onClick={() => setCount((count) => count + 1)}
              // Read here: https://pixi-vn.web.app/start/interface#how-to-enable-ui-interaction // [!code ++]
              style={{ pointerEvents: "auto" }} // [!code ++]
            >
              Count is {count}
            </button>
          </section>

          <div className="ticks"></div>

          <section id="next-steps">
            <div id="docs">
              <svg className="icon" role="presentation" aria-hidden="true">
                <use href="/icons.svg#documentation-icon"></use>
              </svg>
              <h2>Documentation</h2>
              <p>Your questions, answered</p>
              <ul>
                <li>
                  <a href="https://vite.dev/" target="_blank"
                    // Read here: https://pixi-vn.web.app/start/interface#how-to-enable-ui-interaction // [!code ++]
                    style={{ pointerEvents: "auto" }} // [!code ++]
                  >
                    <img className="logo" src={viteLogo} alt="" />
                    Explore Vite
                  </a>
                </li>
                <li>
                  <a href="https://react.dev/" target="_blank"
                    // Read here: https://pixi-vn.web.app/start/interface#how-to-enable-ui-interaction // [!code ++]
                    style={{ pointerEvents: "auto" }} // [!code ++]
                  >
                    <img className="button-icon" src={reactLogo} alt="" />
                    Learn more
                  </a>
                </li>
              </ul>
            </div>
            <div id="social">
              <svg className="icon" role="presentation" aria-hidden="true">
                <use href="/icons.svg#social-icon"></use>
              </svg>
              <h2>Connect with us</h2>
              <p>Join the Vite community</p>
              <ul>
                <li>
                  <a href="https://github.com/vitejs/vite" target="_blank"
                    // Read here: https://pixi-vn.web.app/start/interface#how-to-enable-ui-interaction // [!code ++]
                    style={{ pointerEvents: "auto" }} // [!code ++]
                  >
                    <svg
                      className="button-icon"
                      role="presentation"
                      aria-hidden="true"
                    >
                      <use href="/icons.svg#github-icon"></use>
                    </svg>
                    GitHub
                  </a>
                </li>
                <li>
                  <a href="https://chat.vite.dev/" target="_blank"
                    // Read here: https://pixi-vn.web.app/start/interface#how-to-enable-ui-interaction // [!code ++]
                    style={{ pointerEvents: "auto" }} // [!code ++]
                  >
                    <svg
                      className="button-icon"
                      role="presentation"
                      aria-hidden="true"
                    >
                      <use href="/icons.svg#discord-icon"></use>
                    </svg>
                    Discord
                  </a>
                </li>
                <li>
                  <a href="https://x.com/vite_js" target="_blank"
                    // Read here: https://pixi-vn.web.app/start/interface#how-to-enable-ui-interaction // [!code ++]
                    style={{ pointerEvents: "auto" }} // [!code ++]
                  >
                    <svg
                      className="button-icon"
                      role="presentation"
                      aria-hidden="true"
                    >
                      <use href="/icons.svg#x-icon"></use>
                    </svg>
                    X.com
                  </a>
                </li>
                <li>
                  <a href="https://bsky.app/profile/vite.dev" target="_blank"
                    // Read here: https://pixi-vn.web.app/start/interface#how-to-enable-ui-interaction // [!code ++]
                    style={{ pointerEvents: "auto" }} // [!code ++]
                  >
                    <svg
                      className="button-icon"
                      role="presentation"
                      aria-hidden="true"
                    >
                      <use href="/icons.svg#bluesky-icon"></use>
                    </svg>
                    Bluesky
                  </a>
                </li>
              </ul>
            </div>
          </section>

          <div className="ticks"></div>
          <section id="spacer"></section>
        </>
      )
    }

    export default App
    ```
  </CodeBlockTab>
</CodeBlockTabs>


# Vue UI (/start/interface-vue)



**What is Vue?** Vue is a progressive framework for building user interfaces. It is designed to be incrementally adoptable and can easily scale between a library and a full-featured framework.

You can learn more about Vue on the [Vue website](https://vuejs.org/).

How to add Pixi’VN to a Vue application [#how-to-add-pixivn-to-a-vue-application]

<Callout title="Vue template" type="info">
  I am looking for someone to help me develop Vue templates. Are you available to help?

  If you are interested or available to help, feel free to write in the chat below!
</Callout>

First, you need a Vue application and to <DynamicLink href="/start#installation">install pixi-vn</DynamicLink>. Is recommended to use [Vite](https://vite.dev/guide/#scaffolding-your-first-vite-project) to create a new Vue application.

Now you can replace the content of the following files with the code below:

<CodeBlockTabs defaultValue="src/main.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="src/main.ts">
      src/main.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="src/style.css">
      src/style.css
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="src/components/HelloWorld.vue">
      src/components/HelloWorld.vue
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="index.html">
      index.html
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="src/main.ts">
    ```tsx
    import { canvas, Container, Game, RotateTicker, showImage } from '@drincs/pixi-vn'
    import { createApp } from 'vue'
    import './style.css'
    import App from './App.vue'

    createApp(App).mount('#app') // [!code --]
    const body = document.body; // [!code ++]
    if (!body) { // [!code ++]
      throw new Error("body element not found"); // [!code ++]
    } // [!code ++]
     // [!code ++]
    Game.init(body, { // [!code ++]
        height: 1080, // [!code ++]
        width: 1920, // [!code ++]
        backgroundColor: "#303030", // [!code ++]
      }) // [!code ++]
      .then(() => { // [!code ++]
     // [!code ++]
        // Pixi.JS UI Layer [!code ++]
        canvas.addLayer("ui", new Container()); // [!code ++]
        showImage( // [!code ++]
          "juliette", // [!code ++]
          "https://firebasestorage.googleapis.com/v0/b/pixi-vn.appspot.com/o/public%2Fcharacters%2Fjuliette-icon.webp?alt=media&token=cbcdd613-12e4-48b5-b7b3-16443b4e125e", // [!code ++]
          { xAlign: 0.9, yAlign: 0.1, anchor: 0.5 } // [!code ++]
        ); // [!code ++]
        canvas.addTicker("juliette", new RotateTicker({ speed: 1 })); // [!code ++]
     // [!code ++]
        // Vue setup [!code ++]
        const app = document.getElementById("app"); // [!code ++]
        if (!app) { // [!code ++]
          throw new Error("app element not found"); // [!code ++]
        } // [!code ++]
     // [!code ++]
        const htmlLayer = canvas.addHtmlLayer("ui", app, { // [!code ++]
          position: "absolute", // [!code ++]
          pointerEvents: "none" // [!code ++]
        }); // [!code ++]
        if (!htmlLayer) { // [!code ++]
          throw new Error("htmlLayer not found"); // [!code ++]
        } // [!code ++]
        createApp(App).mount(htmlLayer) // [!code ++]
      } // [!code ++]
    ) // [!code ++]
    ```
  </CodeBlockTab>

  <CodeBlockTab value="src/style.css">
    ```css
    :root {
      font-family: system-ui, Avenir, Helvetica, Arial, sans-serif;
      line-height: 1.5;
      font-weight: 400;

      color-scheme: light dark;
      color: rgba(255, 255, 255, 0.87);

      font-synthesis: none;
      text-rendering: optimizeLegibility;
      -webkit-font-smoothing: antialiased;
      -moz-osx-font-smoothing: grayscale;
    }

    a {
      font-weight: 500;
      color: #646cff;
      text-decoration: inherit;
    }
    a:hover {
      color: #535bf2;
    }

    html, /* [!code ++] */
    body { /* [!code ++] */
      background-color: #242424; /* [!code ++] */
      height: 100%; /* [!code ++] */
    } /* [!code ++] */

    body {
      margin: 0;
      display: flex;
      min-height: 100vh;
      place-items: center; /* [!code --] */
      min-width: 320px; /* [!code --] */
      overflow: hidden; /* [!code ++] */
    }

    h1 {
      font-size: 3.2em;
      line-height: 1.1;
    }

    button {
      border-radius: 8px;
      border: 1px solid transparent;
      padding: 0.6em 1.2em;
      font-size: 1em;
      font-weight: 500;
      font-family: inherit;
      background-color: #1a1a1a;
      cursor: pointer;
      transition: border-color 0.25s;
    }
    button:hover {
      border-color: #646cff;
    }
    button:focus,
    button:focus-visible {
      outline: 4px auto -webkit-focus-ring-color;
    }

    .card {
      padding: 2em;
    }

    #app {
      max-width: 1280px;
      margin: 0 auto;
      padding: 2rem; /* [!code --] */
      text-align: center;
    }

    @media (prefers-color-scheme: light) {
      :root {
        color: #213547;
        background-color: #ffffff;
      }
      a:hover {
        color: #747bff;
      }
      button {
        background-color: #f9f9f9;
      }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="src/components/HelloWorld.vue">
    ```vue
    <script setup lang="ts">
    import { ref } from 'vue'

    defineProps<{ msg: string }>()

    const count = ref(0)
    </script>

    <template>
      <h1>{{ msg }}</h1>

      <div class="card">
        <!-- Read here: https://pixi-vn.web.app/start/interface#how-to-enable-ui-interaction -->
        <button type="button" @click="count++">count is {{ count }}</button> <!-- [!code --] -->
        <button type="button" @click="count++" :style="{ pointerEvents: 'auto' }">count is {{ count }}</button> <!-- [!code ++] -->
        <p>
          Edit
          <code>components/HelloWorld.vue</code> to test HMR
        </p>
      </div>

      <p>
        Check out
        <a href="https://vuejs.org/guide/quick-start.html#local" target="_blank"
          >create-vue</a
        >, the official Vue + Vite starter
      </p>
      <p>
        Learn more about IDE Support for Vue in the
        <a
          href="https://vuejs.org/guide/scaling-up/tooling.html#ide-support"
          target="_blank"
          >Vue Docs Scaling up Guide</a
        >.
      </p>
      <p class="read-the-docs">Click on the Vite and Vue logos to learn more</p>
    </template>

    <style scoped>
    .read-the-docs {
      color: #888;
    }
    </style>
    ```
  </CodeBlockTab>

  <CodeBlockTab value="index.html">
    ```html
    <!doctype html>
    <html lang="en">
      <head>
        <meta charset="UTF-8" />
        <link rel="icon" type="image/svg+xml" href="/vite.svg" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Vite + Vue</title> <!-- [!code --] -->
        <title>Vite + Vue + Pixi’VN</title> <!-- [!code ++] -->
      </head>
      <body>
        <div id="app"></div>
        <script type="module" src="/src/main.ts"></script>
      </body>
    </html>
    ```
  </CodeBlockTab>
</CodeBlockTabs>


# User Interface (UI) with JavaScript Framework (/start/interface)





**What is UI?** UI stands for User Interface. It refers to the visual elements and interactive components through which a user interacts with a digital device, application, or website. The UI includes everything that users interact with, such as buttons, menus, icons, text fields, and layout. The goal of UI design is to create an interface that is both aesthetically pleasing and functional, providing a seamless and intuitive experience for users.

Pixi’VN does not provide built-in components to create the game UI. Instead, you should use external JavaScript frameworks to build your UI. This allows you to leverage systems such as React, Vue, etc., to create complex and high-performance **UI screens**.

* <DynamicLink href="/start/interface-react">
    React
  </DynamicLink>
* <DynamicLink href="/start/interface-vue">
    Vue
  </DynamicLink>
* <DynamicLink href="/start/interface-pixijs">
    PixiJS
  </DynamicLink>

Pixi’VN offers features to improve compatibility with other JavaScript frameworks:

<Accordions>
  <Accordion title="adding_html_ui_layers" id="adding-html-ui-layers">
    **What is an HTML UI Layer?** An HTML UI Layer is an HTML element that is added above the PixiJS canvas and has the same dimensions as the canvas. This allows you to create a UI with a JavaScript framework such as React or Vue.

    To add an HTML UI Layer, you can use the `canvas.addHtmlLayer` function. This function has the following parameters:

    * `id`: A unique identifier (string). It is used to reference the layer (must be unique).
    * `element`: the HTML element to add as a layer.
    * `style`: An object with the style properties to apply to the layer. The default style is `{ position: "absolute", pointerEvents: "none", userSelect: "none" }`.

    For example:

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

        <CodeBlockTabsTrigger value="index.html">
          index.html
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="main.ts">
        ```ts
        const root = document.getElementById("root");
        if (!root) {
            throw new Error("root element not found");
        }
        const htmlLayer = canvas.addHtmlLayer("ui", root, {
            position: "absolute",
            pointerEvents: "none",
            userSelect: "none"
        });
        ```
      </CodeBlockTab>

      <CodeBlockTab value="index.html">
        ```html
        <!doctype html>
        <html lang="en">
          <body>
            <div id="root"></div>
            <script type="module" src="/src/main.ts"></script>
          </body>
        </html>
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    To get the HTML element of the layer, you can use the `canvas.getHtmlLayer` function. This function has the following parameters:

    * `id`: The id of the layer.

    To remove an HTML UI Layer, you can use the `canvas.removeHtmlLayer` function. This function has the following parameters:

    * `id`: The id of the layer.
  </Accordion>

  <Accordion title="how_to_enable_ui_interaction" id="how-to-enable-ui-interaction">
    By default, all HTML elements of the HTML UI Layers have the `pointer-events: none` style. This means that the HTML elements will not intercept any mouse or touch events, allowing the PixiJS canvas to receive all events. This is useful when you want to display an image or a video in the canvas and you don't want the UI to interfere with it.

    So you must set the `pointer-events: auto` style only for the conponent that you want to interact with the user.

    For example:

    <CodeBlockTabs defaultValue="Shadcn - Tailwind CSS">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="Shadcn - Tailwind CSS">
          Shadcn - Tailwind CSS
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="React">
          React
        </CodeBlockTabsTrigger>

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

      <CodeBlockTab value="Shadcn - Tailwind CSS">
        ```ts
        import { Button as ButtonPrimitive } from "@base-ui/react/button";
        import { cva, type VariantProps } from "class-variance-authority";

        import { cn } from "@/lib/utils";

        const buttonVariants = cva(
            "pointer-events-auto ...",
            {
                // ...
            }
        );
        ```
      </CodeBlockTab>

      <CodeBlockTab value="React">
        ```tsx
        export default function NextButton() {
            return (
                <button
                    style={{
                        pointerEvents: "auto",
                    }}
                >
                    Next
                </button>
            );
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="Vue">
        ```vue
        <template>
            <button style="pointer-events: auto;">
                Next
            </button>
        </template>
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="adding_pixijs_ui_layers" id="adding-pixijs-ui-layers">
    **What is an PixiJS UI Layer?** It is PixiJS Container. Unlike the main Container dedicated only for Pixi’VN features:

    * The current state of the Ul will not be included in saves.
    * It has better performance. Pixi’VN will not do any checks on it.
    * You can't use Pixi’VN features.
    * Being a core PixiJS component, you can add all PixiJS compatible components.

    To add a PixiJS UI Layer, you can use the `canvas.addLayer` function. This function has the following parameters:

    * `label`: The PixiJS Container label, it must be unique.

    For example:

    ```ts title="src/main.ts"
    const container = canvas.addLayer("ui");
    ```

    To get the PixiJS Container of the layer, you can use the `canvas.getLayer` function. This function has the following parameters:

    * `label`: The PixiJS Container label.

    To remove a PixiJS UI Layer, you can use the `canvas.removeLayer` function. This function has the following parameters:

    * `label`: The PixiJS Container label.
  </Accordion>
</Accordions>

<img alt="Architecture" src="__img0" />

Differences between the UI and the canvas [#differences-between-the-ui-and-the-canvas]

As Pixi’VN was designed and conceived, the UI and the canvas are two distinct and independent elements. The UI is above the canvas and is used to create buttons, forms, etc. The canvas is used to display images, videos, etc.

All information about the current state of the canvas is included in the save and it is possible to restore the state of a previous step. The current state of the UI will not be included in the saves. So you have to <DynamicLink href="/start/interface-connect-storage">manage it yourself by saving the information</DynamicLink> you need to <DynamicLink href="/start/storage">game storage</DynamicLink> or browser storage.

In the canvas you can add components during each step. In the UI you can't do that, you can create several <DynamicLink href="/start/interface-connect-storage">"screens" and navigate between them</DynamicLink>.

In the canvas you can only add Pixi’VN components. In the UI you can add any HTML/PixiJS component or use any UI component library, so you can create much more complex interfaces.


# Advanced label features (/start/labels-advanced)





This section covers advanced <DynamicLink href="/start/labels">label</DynamicLink> features. These are not required to create a basic game, but can help you build more complex and interactive experiences.

<Accordions>
  <Accordion title="onloadinglabel" id="onloadinglabel">
    `onLoadingLabel` is a function executed in `onStepStart` if the `step` index is 0, and also when the user loads a save file.

    When a save file is loaded, all `onLoadingLabel` functions of the `narration.openedLabels` (the current `label` and all `labels` in the stack) are executed.

    This is useful, for example, to ensure all images used in the `label` are cached before the `label` starts.

    You can set this function by passing it to the `onLoadingLabel` property in the `label` options. This function has the following parameters:

    * `stepIndex`: The index of the `step` being executed
    * `label`: The `label` being executed

    ```ts title="labels/startLabel.ts"
    const startLabel = newLabel("start", [
        async () => {
            await showImage("image1", "path/to/image1.png")
            await showImage("image2", "path/to/image2.png")
        }
    ], {
        onLoadingLabel: async (stepIndex, label) => { // [!code focus]
            await Assets.load("path/to/image1.png") // [!code focus]
            await Assets.load("path/to/image2.png") // [!code focus]
        } // [!code focus]
    })
    ```

    You can also use `Game.onLoadingLabel` to intercept the loading of all `labels` globally.

    ```ts
    import { Game } from "@drincs/pixi-vn"

    Game.onLoadingLabel((_stepId, label) => { // [!code focus]
        Assets.backgroundLoadBundle(label.id); // [!code focus]
    }); // [!code focus]
    ```
  </Accordion>

  <Accordion title="onstepstart" id="onstepstart">
    `onStepStart` is a function executed before each `step` of a `label`. Set it via the `onStepStart` property in the `label` options. This function has the following parameters:

    * `stepIndex`: The index of the `step` being executed
    * `label`: The `label` containing the `step`

    ```ts title="labels/startLabel.ts"
    const startLabel = newLabel("start", [
        () => {
            narration.dialogue = "Step 1"
        },
        () => {
            narration.dialogue = "Step 2"
        }
    ], {
        onStepStart: (stepIndex, label) => { // [!code focus]
            console.log(`Step ${stepIndex} started`) // [!code focus]
        } // [!code focus]
    })
    ```

    You can also use `Game.onStepStart` to intercept the start of any `step` in any `label`.

    ```ts
    import { Game } from "@drincs/pixi-vn"

    Game.onStepStart((stepIndex, label) => { // [!code focus]
        console.log(`Step ${stepIndex} started`) // [!code focus]
    }) // [!code focus]
    ```
  </Accordion>

  <Accordion title="onstepend" id="onstepend">
    `onStepEnd` is a function executed after each `step` of a `label`. Set it via the `onStepEnd` property in the `label` options. This function has the following parameters:

    * `stepIndex`: The index of the `step` that ended
    * `label`: The `label` containing the `step`

    ```ts title="labels/startLabel.ts"
    const startLabel = newLabel("start", [
        () => {
            narration.dialogue = "Step 1"
        },
        () => {
            narration.dialogue = "Step 2"
        }
    ], {
        onStepEnd: (stepIndex, label) => { // [!code focus]
            console.log(`Step ${stepIndex} ended`) // [!code focus]
        } // [!code focus]
    })
    ```

    You can also use `Game.onStepEnd` to intercept the end of any `step` in any `label`.

    ```ts
    import { Game } from "@drincs/pixi-vn"

    Game.onStepEnd((stepIndex, label) => { // [!code focus]
        console.log(`Step ${stepIndex} ended`) // [!code focus]
    }) // [!code focus]
    ```
  </Accordion>

  <Accordion title="dynamic_step_list" id="dynamic-step-list">
    When creating a new `label`, you can pass a function that returns the `steps` for that `label`. This allows you to change the `step` list dynamically based on a condition.

    ```ts title="labels/startLabel.ts"
    import { storage, narration, newLabel } from "@drincs/pixi-vn"

    export const startLabel = newLabel("start_label",
        () => {
            let condition = storage.getFlag("condition")
            if (condition) {
                return [
                    () => {
                        narration.dialogue = "Step 2"
                    },
                    () => {
                        narration.dialogue = "Restart";
                    },
                ]
            } else {
                return [
                    () => {
                        narration.dialogue = "Step 1"
                    },
                    async (props, { labelId }) => {
                        storage.setFlag("condition", true)
                        return await narration.jump(labelId, props)
                    }
                ]
            }
        }
    )
    ```

    <ReturningDifferentStepLists />
  </Accordion>
</Accordions>


# Manage narration flow with labels (/start/labels-flow)



The narration flow is managed by functions such as `call`, `jump`, `continue`, `back`, and `closeLabel`, all available in the `narration` object.

Run a label [#run-a-label]

<Callout title="ink" type="info">
  You can use this method with the *ink* syntax. See more <DynamicLink href="/ink/labels#run-a-knot">here</DynamicLink>.
</Callout>

<Accordions>
  <Accordion title="call" id="call-a-label">
    To call a `label`, use the `narration.call` function.
    This function has the following parameters:

    * `label`: the `label` to be called
    * `props`: the properties to pass to the `label`. The interface corresponds to <DynamicLink href="/start/labels#steplabelprops">`StepLabelProps`</DynamicLink>.

    When you call a `label`, the first `step` of that `label` is executed. If another `label` was running before the call, the remaining `steps` of that previous `label` will resume after the called `label` finishes.

    For example, if the game is running `step` 5 of `label` A and you **call** `label` B, after all `steps` of `label` B are executed, the game continues with `step` 6 of `label` A.

    `narration.call` returns the <DynamicLink href="/start/labels#all-steps-result">result of the first `step` of the called `label`</DynamicLink>.

    ```ts
    import { narration } from '@drincs/pixi-vn'

    narration.call(startLabel, {})
    ```

    If you execute `narration.call` inside a `step`, you should return the result of `narration.call` and use `await`. This ensures the history is managed correctly.

    ```ts title="labels/startLabel.ts"
    import { narration, newLabel } from '@drincs/pixi-vn'

    export const startLabel = newLabel("start_label",
        [
            async (props) => {
                return await narration.call(TestLabel, props)
            },
            async (props) => await narration.call(TestLabel, props),
        ]
    )
    ```
  </Accordion>

  <Accordion title="jump" id="jump-to-a-label">
    To jump to a `label`, use the `narration.jump` function.
    This function has the following parameters:

    * `label`: the `label` to jump to
    * `props`: the properties to pass to the `label`. The interface corresponds to <DynamicLink href="/start/labels#steplabelprops">`StepLabelProps`</DynamicLink>.

    When you jump to a `label`, the current `label`'s `steps` are stopped and the new `label`'s `steps` begin.

    For example, if the game is running `step` 5 of `label` A, and you **call** `label` B, but then **jump** to `label` C, after `label` C finishes, the game continues with `step` 6 of `label` A. When you jump to `label` C, `label` B is closed.

    `narration.jump` returns the <DynamicLink href="/start/labels#all-steps-result">result of the first `step` of the called `label`</DynamicLink>.

    ```ts
    import { narration } from '@drincs/pixi-vn'

    narration.jump(startLabel, {})
    ```

    If you execute `narration.jump` inside a `step`, you should return the result of `narration.jump` and use `await`. This ensures the first `step` of the new `label` is awaited.

    ```ts title="labels/startLabel.ts"
    import { narration } from '@drincs/pixi-vn'

    export const startLabel = newLabel("start_label",
        [
            async (props) => {
                return await narration.jump(TestLabel, props)
            },
            async (props) => await narration.jump(TestLabel, props),
        ]
    )
    ```
  </Accordion>

  <Accordion title="start_game" id="start-game">
    To start the game, use the `Game.start` function. This function is equivalent to calling a `label`, but it is recommended to use it for a cleaner startup.

    ```ts title="labels/startLabel.ts"
    import { Game } from '@drincs/pixi-vn'

    Game.start(startLabel, gameProps);
    ```
  </Accordion>
</Accordions>

Continue and go back in steps [#continue-and-go-back-in-steps]

Continue [#continue]

<Callout title="UI screen" type="info">
  You can find the example of the "continue" button in the <DynamicLink href="/start/interface-examples#go-next">interface examples</DynamicLink> section.
</Callout>

To execute the next `step`, use the `narration.continue()` function.
This function has the following parameters:

* `props`: the properties to pass to the `label`. The interface corresponds to <DynamicLink href="/start/labels#steplabelprops">`StepLabelProps`</DynamicLink>.

```ts
import { narration } from '@drincs/pixi-vn'

await narration.continue({})
```

`narration.continue()` is asynchronous, so you can use `.then` to, for example, disable a "Next" button until the `step` is complete.

```ts
import { narration } from '@drincs/pixi-vn'

// disable next button
narration.continue({})
    .then((result) => {
        // enable next button
    })
```

<Accordions>
  <Accordion title="call_continue_inside_step" id="call-continue-inside-a-step">
    If you call `narration.continue()` inside a `step`, the "continue" request will be queued and executed when the queue is empty.

    ```ts title="labels/startLabel.ts"
    import { narration, newLabel } from '@drincs/pixi-vn'

    export const startLabel = newLabel("start_label", [
        async (props) => {
            narration.continue(props)
        },
    ])
    ```

    Here is an example to illustrate how the queue works:

    ```ts title="labels/startLabel.ts"
    import { narration, newLabel } from '@drincs/pixi-vn'

    export const startLabel = newLabel("start_label", [
        async (props) => {
            await narration.call(label2, props);
            console.log(1);
        },
        () => {
            console.log(3);
        },
    ])

    const label2 = newLabel("label_02", [
        async (props) => {
            await narration.continue(props);
            console.log(2);
        },
    ])
    ```

    In this example, the output will be `2`, `1`, `3`. The steps are:

    1. `await narration.call(label2, props)` calls label2 and awaits its first `step`. (1 item in the queue)
    2. The first `step` of label2 executes `await narration.continue(props)`, but the continue request is queued because the queue is not empty. (2 items in the queue)
    3. `console.log(2)` runs, finishing the first `step` of label2. (1 item in the queue)
    4. `console.log(1)` runs, finishing the first `step` of startLabel. (0 items in the queue)
    5. Now the continue request is executed, and the second `step` of startLabel runs. (1 item in the queue)
    6. `console.log(3)` runs, finishing the second `step` of startLabel. (0 items in the queue)
  </Accordion>

  <Accordion title="check_can_go_next_step" id="can-go-next">
    You can use the `narration.canContinue` property to check if the next `step` can be executed.

    `narration.canContinue` is `false` when:

    * A `step` is running
    * The player must <DynamicLink href="/start/choices">make a choice</DynamicLink>
    * The player must <DynamicLink href="/start/input">enter a value</DynamicLink>

    ```tsx title="components/NextButton.tsx"
    import { narration } from '@drincs/pixi-vn'

    function NextButton() {
        return (
            <button disabled={!narration.canContinue} onClick={() => {
                narration.continue({})
            }}>
                Next
            </button>
        )
    }
    ```
  </Accordion>
</Accordions>

Go back [#go-back]

<Callout title="UI screen" type="info">
  You can find the example of the go back button in the <DynamicLink href="/start/interface-examples#go-back">interface examples</DynamicLink> section.
</Callout>

At every `step`, the system saves the current state of the game. To go back to the previous `step`, use the `stepHistory.back()` function.

You must pass a function `navigate: (path: string) => void` as a parameter. This function will be called with the <DynamicLink href="/start/start/interface-navigate">URL Path or Route</DynamicLink> of the previous `step`, so you can <DynamicLink href="/start/interface-navigate">navigate to the previous UI screen</DynamicLink>.

```ts title="React Router Dom"
import { stepHistory } from '@drincs/pixi-vn'
import { useNavigate } from 'react-router-dom';

const navigate = useNavigate();

if (stepHistory.canGoBack) {
    stepHistory.back(navigate).then(() => {
        // ...
    })
}
```

<Accordions>
  <Accordion title="can_go_back" id="can-go-back">
    You can use the `stepHistory.canGoBack` property to check if going back is possible.

    `stepHistory.canGoBack` is `false` when there are no `steps` in the history to restore.

    ```tsx title="components/BackButton.tsx"
    import { stepHistory } from '@drincs/pixi-vn'

    function BackButton() {
        return (
            <button disabled={!stepHistory.canGoBack} onClick={() => {
                stepHistory.back({})
            }}>
                Back
            </button>
        )
    }
    ```
  </Accordion>

  <Accordion title="block_the_possibility_of_going_back" id="block-the-possibility-of-going-back">
    You can block the "go back" by calling `stepHistory.blockGoBack()`.

    ```typescript
    import { stepHistory } from '@drincs/pixi-vn'

    stepHistory.blockGoBack()
    ```
  </Accordion>
</Accordions>

Close labels [#close-labels]

<Accordions>
  <Accordion title="close_current_label" id="close-current-label">
    To close the current `label`, use the `narration.closeCurrentLabel()` function.

    ```typescript
    import { narration } from '@drincs/pixi-vn'

    narration.closeCurrentLabel()
    ```
  </Accordion>

  <Accordion title="close_all_labels" id="close-all-labels">
    To close all `labels`, use the `narration.closeAllLabels()` function.\
    &#x2A;*If you call this function and do not call any `label` afterwards, the <DynamicLink href="/start/other-narrative-features#how-manage-the-end-of-the-game">game will end</DynamicLink>.**

    ```typescript
    import { narration } from '@drincs/pixi-vn'

    narration.closeAllLabels()
    ```
  </Accordion>
</Accordions>

Other features [#other-features]

<Accordions>
  <Accordion title="rollback_rollforward" id="rollback-rollforward">
    <Callout title="Templates" type="info">
      In all templates, this implementation is already included.
    </Callout>

    If you execute multiple `stepHistory.back()` and `narration.continue()` requests synchronously, the system will internally queue them and calculate the delta to execute only the necessary processes.

    So you can implement rollback and rollforward features using the `stepHistory.back()` and `narration.continue()` functions.

    ```tsx title="hooks/useWheelActions.tsx"
    import { stepHistory, StepLabelProps } from "@drincs/pixi-vn";
    import { narration } from "@drincs/pixi-vn/narration";
    import { useQueryClient } from "@tanstack/react-query";
    import { throttle } from "es-toolkit";
    import { useCallback, useEffect, useRef } from "react";
    import useStepStore from "../stores/useStepStore";
    import useGameProps from "./useGameProps";
    import { INTERFACE_DATA_USE_QUEY_KEY } from "./useQueryInterface";

    export function useWheelActions({
        throttleMs = 300,
        minDelta = 20,
    }: {
        throttleMs?: number;
        minDelta?: number;
    } = {}) {
        const pendingAsync = useRef(0);
        const setLoading = useStepStore((state) => state.setLoading);
        const queryClient = useQueryClient();
        const gameProps = useGameProps();

        const runAsync = async (fn: (props: StepLabelProps) => Promise<unknown>) => {
            try {
                pendingAsync.current += 1;
                setLoading(pendingAsync.current > 0);
                await fn(gameProps);
            } finally {
                pendingAsync.current -= 1;
                setLoading(pendingAsync.current > 0);
                if (pendingAsync.current === 0) {
                    queryClient.invalidateQueries({ queryKey: [INTERFACE_DATA_USE_QUEY_KEY] });
                }
            }
        };

        const handleWheel = useCallback(
            throttle(async (event: WheelEvent) => {
                // blocca lo scroll nativo
                event.preventDefault();

                const { deltaY } = event;

                // ignora micro-movimenti del trackpad
                if (Math.abs(deltaY) < minDelta) return;

                if (deltaY < 0) {
                    // ⬆️ Scroll up
                    await runAsync(narration.continue.bind(narration));
                }

                if (deltaY > 0) {
                    // ⬇️ Scroll down
                    await runAsync(stepHistory.back.bind(stepHistory));
                }
            }, throttleMs),
            [throttleMs, minDelta]
        );

        useEffect(() => {
            window.addEventListener("wheel", handleWheel, { passive: false });

            return () => {
                window.removeEventListener("wheel", handleWheel);
                handleWheel.cancel();
            };
        }, [handleWheel]);
    }
    ```
  </Accordion>
</Accordions>


# Labels and steps (/start/labels)



Visual novels are typically a sequence of scenes with images and text.

<Callout title="Nomenclature" type="info">
  The term `label` is borrowed from Ren'Py, where it acts as a "bookmark" or "landmark" in the story. In the ink language, the equivalent term is `knot`.

  The term `step` is introduced by Pixi’VN to represent the individual actions or events that occur within a `label`.
</Callout>

In Pixi’VN, the entire narrative flow is based on the concepts of `labels` and `steps`.

A `label` is used to organize the narrative; it works as a "bookmark" or section of the story. Technically, a `label` is a class that acts as a container for `steps`.

A `step` is an individual action or event that occurs within a `label`. Steps are used to display images, text, and other narrative elements.

The basic lifecycle of the game is as follows:

* The game starts by <DynamicLink href="/start/labels-flow#run-a-label">calling a `label`</DynamicLink>. The first `step` of the `label` is executed automatically.
* After that, by connecting the <DynamicLink href="/start/labels-flow#continue">Next Step</DynamicLink> function to an event (such as a button click), each time the function is called, the next `step` of the `label` is executed. Some `steps` can also start other `labels`.
* The game ends only when all `steps` are completed. At that point, the <DynamicLink href="/start/other-narrative-features#how-manage-the-end-of-the-game">Game.onEnd</DynamicLink> function is triggered.

Add [#add]

To create a `label`, use the `newLabel()` function.
This function has the following parameters:

* `id`: A unique identifier (string). Used to reference the `label` in the game (must be unique).
* `steps`: An array of functions to be executed in order. To create a dynamic array, you can find more information <DynamicLink href="/start/labels-advanced#dynamic-step-list">here</DynamicLink>.
* `options` (Optional): An object with the `label`'s options:
  * `onStepStart` (Optional): A function executed before each `step`. See more <DynamicLink href="/start/labels-advanced#onstepstart">here</DynamicLink>.
  * `onStepEnd` (Optional): A function executed after each `step`. See more <DynamicLink href="/start/labels-advanced#onstepend">here</DynamicLink>.
  * `onLoadingLabel` (Optional): A function executed in `onStepStart` if the `step` index is 0, or when loading a save file. See more <DynamicLink href="/start/labels-advanced#onloadinglabel">here</DynamicLink>.

```ts title="labels/startLabel.ts"
import { narration, StepLabelProps } from '@drincs/pixi-vn'

export const startLabel = newLabel("start_label",
    [
        () => {
            narration.dialogue = { character: liam, text: "Example of dialogue" }
        },
        (props: StepLabelProps, { labelId }) => narration.jump(labelId, props),
    ]
)
```

<Accordions>
  <Accordion title="overriding_stepLabelprops" id="steplabelprops">
    <Callout title="Templates" type="info">
      In all templates, the `StepLabelProps` interface is already overridden. You can find it in the `pixi-vn.d.ts` file.
    </Callout>

    All <DynamicLink href="/start/labels-flow">narration flow control functions</DynamicLink> require an object matching the `StepLabelProps` interface.

    By default, `StepLabelProps` is `{ [key: string]: any }`. You can "override" the `StepLabelProps` interface in your `.d.ts` file to specify required parameters.

    <CodeBlockTabs defaultValue="pixi-vn.d.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="pixi-vn.d.ts">
          pixi-vn.d.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="labels/startLabel.ts">
          labels/startLabel.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="pixi-vn.d.ts">
        ```ts
        import { narration } from '@drincs/pixi-vn'

        declare module '@drincs/pixi-vn' {
            interface StepLabelProps {
                navigate: (route: string) => void,
            }
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="labels/startLabel.ts">
        ```ts
        export const startLabel = newLabel("start_label",
            [
                ({ navigate }) => { // [!code focus]
                    navigate("/new-route") // [!code focus]
                }, // [!code focus]
            ]
        )
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    Other features [#other-features]
  </Accordion>

  <Accordion title="step_pros" id="step-pros">
    You can pass a type to the `newLabel` function to add custom parameters for that `label`, in addition to [`StepLabelProps`](#steplabelprops).

    ```ts title="labels/startLabel.ts"
    import { narration } from '@drincs/pixi-vn'

    export const startLabel = newLabel<{name: string}>("start_label",
        [
            (props) => {
                console.log(props.name)
            },
        ]
    )

    narration.call(startLabel, {
        // Add StepLabelProps here
        navigate: navigate, // example
        // And the custom props for the label
        name: "John"
    })
    ```
  </Accordion>

  <Accordion title="step_results" id="step-results">
    Steps can return a `StepLabelResult` object. By default, `StepLabelResult` is `{ [key: string]: any }`.

    You can "override" the `StepLabelResult` interface in your `.d.ts` file to define custom properties for `step` results.

    <CodeBlockTabs defaultValue="pixi-vn.d.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="pixi-vn.d.ts">
          pixi-vn.d.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="labels/startLabel.ts">
          labels/startLabel.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="pixi-vn.d.ts">
        ```ts
        declare module '@drincs/pixi-vn' {
            interface StepLabelResult {
                newRoute?: string,
                [key: string]: any
            }
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="labels/startLabel.ts">
        ```ts
        export const startLabel = newLabel("start_label",
            [
                () => {
                    return { // [!code focus]
                        newRoute: '/new-route', // [!code focus]
                        customProperty: 12 // [!code focus]
                    } // [!code focus]
                },
            ]
        )
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>
</Accordions>


# Make your game engine (/start/make-game-engine)



<Callout type="info">
  This guide is designed only for developers with good experience in JavaScript. If you are not a developer, you can skip this page and use the default engine.
</Callout>

One of the main goals of Pixi’VN is to provide basic utilities for developing video games. The engine is designed to be modular and flexible, allowing developers to use only the parts they need for their specific projects. This modularity also makes it easier to maintain and update the engine over time.

This is exactly what enables you to create your own game engine using the `pixi-vn` package.

The first `step` is to create a new project. You can find more information on how to create a new project starting from a template <DynamicLink href="/start#project-initialization">here</DynamicLink>. The "Game Engine" template is a simple project that contains the basic structure of a game engine. By default, it exports the basic functionality of pixi-vn while removing anything unused from the package.

<Callout type="info">
  A special thread was created to share your idea or ask for help during the development of your game engine. Feel free to write in the chat below!
</Callout>

The second `step` is to understand that Pixi’VN is divided into independent "modules". This means you can replace one "module" without having to worry about modifying the others. To do this, you just need to modify `GameUnifier`, which connects the modules together, as explained below.

It is also important to understand that by default the engine saves the current state of the game at each `step`, to give the player the possibility to go back. To do this, the following functions are defined:

* `GameUnifier.getCurrentGameStepState`: This function returns the current state of the game `step`.
* `GameUnifier.restoreGameStepState`: This function restores the state of the game `step`.
* `Game.exportGameState`: This function returns the current state of the game. (Optional)
* `Game.restoreGameState`: This function restores the state of the game. (Optional)

Storage [#storage]

Replacing the base storage of Pixi’VN is straightforward.

For example, here is how you could replace it with [`cacheable`](https://www.npmjs.com/package/cacheable):

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

    <CodeBlockTabsTrigger value="interfaces/GameState.ts">
      interfaces/GameState.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="index.ts">
    ```ts
    import { CacheableMemory } from "cacheable"; // [!code ++]

    const storage = new CacheableMemory(); // [!code ++]
    const flagStorage = new CacheableMemory(); // [!code ++]

    export namespace Game {
        export async function initialize(
            element: HTMLElement,
            options: Partial<ApplicationOptions> & { width: number; height: number },
            devtoolsOptions?: Devtools
        ) {
            GameUnifier.init({
                getCurrentGameStepState: () => {
                    return {
                        // ...
                        storage: storage.export(), // [!code --]
                        storage: { // [!code ++]
                            main: createExportableElement([...storage.items]), // [!code ++]
                            flags: createExportableElement([...flagStorage.items]), // [!code ++]
                        }, // [!code ++]
                    };
                },
                restoreGameStepState: async (state, navigate) => {
                    // ...
                    storage.restore(state.storage); // [!code --]
                    storage.setMany(state.storage.main); // [!code ++]
                    flagStorage.setMany(state.storage.flags); // [!code ++]
                },
                // storage
                getVariable: (key) => storage.get(key), // [!code --]
                setVariable: (key, value) => storage.set(key, value), // [!code --]
                removeVariable: (key) => storage.remove(key), // [!code --]
                getFlag: (key) => storage.getFlag(key), // [!code --]
                setFlag: (name, value) => storage.setFlag(name, value), // [!code --]
                // onLabelClosing is called when the label is closed, it can use for example to clear the temporary variables in the storage // [!code --]
                onLabelClosing: (openedLabelsNumber) => StorageManagerStatic.clearOldTempVariables(openedLabelsNumber),  // [!code --]
                getVariable: (key) => storage.get(key), // [!code ++]
                setVariable: (key, value) => storage.set(key, value), // [!code ++]
                removeVariable: (key) => storage.delete(key), // [!code ++]
                getFlag: (key) => flagStorage.get(key) ?? false, // [!code ++]
                setFlag: (name, value) => flagStorage.set(name, value), // [!code ++]
            });
            // ...
        }

        export function clear() {
            // ...
            storage.clear(); // [!code --]
            storage.clear(); // new class // [!code ++]
            flagStorage.clear(); // [!code ++]
        }

        export function exportGameState(): GameState {
            return {
                // ...
                storageData: storage.export(), // [!code --]
                storageData: { // [!code ++]
                    main: createExportableElement([...storage.items]), // [!code ++]
                    flags: createExportableElement([...flagStorage.items]), // [!code ++]
                }, // [!code ++]
            };
        }

        export async function restoreGameState(data: GameState, navigate: (path: string) => void) {
            // ...
            storage.restore(data.storageData); // [!code --]
            storage.clear(); // [!code ++]
            storage.setMany(data.storageData.main); // [!code ++]
            flagStorage.clear(); // [!code ++]
            flagStorage.setMany(data.storageData.flags); // [!code ++]
        }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="interfaces/GameState.ts">
    ```ts
    import { CacheableItem } from "cacheable";

    export default interface GameState {
        engine_version: string;
        step: NarrationGameState;
        storageData: StorageGameState; // [!code --]
        storageData: { // [!code ++]
            main: CacheableItem[]; // [!code ++]
            flags: CacheableItem[]; // [!code ++]
        }; // [!code ++]
        canvasData: CanvasGameState;
        soundData: SoundGameState;
        historyData: HistoryGameState;
        path: string;
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Renderer [#renderer]

The canvas is also a module that can be replaced. The default canvas uses the `pixi.js` library, but you can use any other canvas library you want.

You are not forced to use a WebGL-based 2D renderer. You can use any renderer you want, including 3D or React-based renderers. The only requirement is that the renderer state must be saved and restored at each `step`.

For example:

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

    <CodeBlockTabsTrigger value="interfaces/GameState.ts">
      interfaces/GameState.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="index.ts">
    ```ts
    const canvas = new Canvas(); // [!code ++]

    export namespace Game {
        export async function initialize(
            options: CanvasOptions, // [!code ++]
        ) {
            GameUnifier.init({
                getCurrentGameStepState: () => {
                    return {
                        // ...
                        canvas: canvas.export(), // [!code ++]
                    };
                },
                restoreGameStepState: async (state, navigate) => {
                    // ...
                    await canvas.restore(state.canvas); // [!code ++]
                },
                // This function is called when the step is completed, it can be used to force the completion of the animations // [!code ++]
                onPreContinue: async () => { // [!code ++]
                    canvas.forceCompletionOfAnimations(); // [!code ++]
                }, // [!code ++]
            });
            return await canvas.init(options); // [!code ++]
        }

        export function clear() {
            // ...
            canvas.clear(); // [!code ++]
        }

        export function exportGameState(): GameState {
            return {
                // ...
                canvasData: canvas.export(), // [!code ++]
            };
        }

        export async function restoreGameState(data: GameState, navigate: (path: string) => void) {
            // ...
            await canvas.restore(data.canvasData); // [!code ++]
        }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="interfaces/GameState.ts">
    ```ts
    import { CanvasGameState } from "./canvas"; // [!code ++]

    export default interface GameState {
        engine_version: string;
        stepData: NarrationGameState;
        storageData: StorageGameState;
        canvasData: CanvasState; // [!code ++]
        soundData: SoundGameState;
        historyData: HistoryGameState;
        path: string;
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Sound [#sound]

The sound module can also be replaced. The default uses [`PixiJS Sound`](https://pixijs.io/sound/examples/index.html), but you can use any sound library.

For example, to use [`howler.js`](https://howlerjs.com/):

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

    <CodeBlockTabsTrigger value="interfaces/GameState.ts">
      interfaces/GameState.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="index.ts">
    ```ts
    import { Howl, Howler } from "howler"; // [!code ++]

    export function exportHowlerState() { // [!code ++]
        const state = Howler._howls.map((howl) => ({ // [!code ++]
            src: howl._src, // [!code ++]
            volume: howl.volume(), // [!code ++]
            rate: howl.rate(), // [!code ++]
            loop: howl.loop(), // [!code ++]
            playing: howl.playing(), // [!code ++]
            seek: howl.seek(), // [!code ++]
        })); // [!code ++]
        return state; // [!code ++]
    } // [!code ++]

    export async function restoreHowlerState(state: Array<any>) { // [!code ++]
        state.forEach((soundData) => { // [!code ++]
            const sound = new Howl({ // [!code ++]
                src: soundData.src, // [!code ++]
                volume: soundData.volume, // [!code ++]
                rate: soundData.rate, // [!code ++]
                loop: soundData.loop, // [!code ++]
            }); // [!code ++]

            if (soundData.playing) { // [!code ++]
                sound.seek(soundData.seek); // [!code ++]
                sound.play(); // [!code ++]
            } // [!code ++]
        }); // [!code ++]
    } // [!code ++]

    export namespace Game {
        export async function initialize(
            element: HTMLElement,
            options: Partial<ApplicationOptions> & { width: number; height: number },
            devtoolsOptions?: Devtools
        ) {
            GameUnifier.init({
                getCurrentGameStepState: () => {
                    return {
                        // ...
                        sound: sound.export(), // [!code --]
                        sound: exportHowlerState(), // [!code ++]
                    };
                },
                restoreGameStepState: async (state, navigate) => {
                    // ...
                    sound.restore(state.sound); // [!code --]
                    await restoreHowlerState(state.soundData); // [!code ++]
                },
            });
            // ...
        }

        export function clear() {
            sound.clear(); // [!code --]
            Howler._howls.forEach((howl) => howl.unload()); // [!code ++]
            // ...
        }

        export function exportGameState(): GameState {
            return {
                // ...
                soundData: sound.export(), // [!code --]
                soundData: exportHowlerState(), // [!code ++]
            };
        }

        export async function restoreGameState(data: GameState, navigate: (path: string) => void) {
            // ...
            sound.restore(data.soundData); // [!code --]
            await restoreHowlerState(data.soundData); // [!code ++]
        }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="interfaces/GameState.ts">
    ```ts
    import { CacheableItem } from "cacheable";

    export default interface GameState {
        engine_version: string;
        stepData: NarrationGameState;
        storageData: StorageGameState;
        canvasData: CanvasGameState;
        soundData: SoundGameState; // [!code --]
        soundData: Array<any>; // [!code ++]
        historyData: HistoryGameState;
        path: string;
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Narration [#narration]

Replacing the entire narration module is possible but not recommended, as it is a strong point of Pixi’VN.

Since it is handled generically, you can implement your own <DynamicLink href="/start/labels#label">`Label`</DynamicLink> (the key element of narration) by extending `LabelAbstract`.

For example:

<CodeBlockTabs defaultValue="classes/Label.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="classes/Label.ts">
      classes/Label.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="utils/label.ts">
      utils/label.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="classes/Label.ts">
    ```ts
    import { LabelAbstract, LabelProps, StepLabelType } from "@drincs/pixi-vn";
    import sha1 from "crypto-js/sha1";

    export default class Label<T extends {} = {}> extends LabelAbstract<Label<T>, T> {
        public get stepCount(): number {
            return this.steps.length;
        }
        public getStepById(stepId: number): StepLabelType<T> | undefined {
            return this.steps[stepId];
        }
        /**
         * @param id is the id of the label
         * @param steps is the list of steps that the label will perform
         * @param props is the properties of the label
         */
        constructor(id: string, steps: StepLabelType<T>[] | (() => StepLabelType<T>[]), props?: LabelProps<Label<T>>) {
            super(id, props);
            this._steps = steps;
        }

        private _steps: StepLabelType<T>[] | (() => StepLabelType<T>[]);
        /**
         * Get the steps of the label.
         */
        public get steps(): StepLabelType<T>[] {
            if (typeof this._steps === "function") {
                return this._steps();
            }
            return this._steps;
        }

        public getStepSha(index: number): string {
            if (index < 0 || index >= this.steps.length) {
                console.warn("stepSha not found, setting to ERROR");
                return "error";
            }
            try {
                let step = this.steps[index];
                let sha1String = sha1(step.toString().toLocaleLowerCase());
                return sha1String.toString();
            } catch (e) {
                console.warn("stepSha not found, setting to ERROR", e);
                return "error";
            }
        }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="utils/label.ts">
    ```ts
    import { LabelProps, RegisteredLabels, StepLabelType } from "@drincs/pixi-vn";
    import Label from "../classes/Label";

    /**
     * Creates a new label and registers it in the system.
     * **This function must be called at least once at system startup to register the label, otherwise the system cannot be used.**
     * @param id The id of the label, it must be unique
     * @param steps The steps of the label
     * @param props The properties of the label
     * @returns The created label
     */
    export function newLabel<T extends {} = {}>(
        id: string,
        steps: StepLabelType<T>[] | (() => StepLabelType<T>[]),
        props?: Omit<LabelProps<Label<T>>, "choiseIndex">
    ): Label<T> {
        if (RegisteredLabels.get(id)) {
            console.info(`Label ${id} already exists, it will be overwritten`);
        }
        let label = new Label<T>(id, steps, props);
        RegisteredLabels.add(label);
        return label;
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

History [#history]

The history module can be replaced. The default uses the [`deep-diff`](https://www.npmjs.com/package/deep-diff) library, but you can use any history library.

For example:

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

    <CodeBlockTabsTrigger value="classes/HistoryManager.ts">
      classes/HistoryManager.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="index.ts">
    ```ts
    import HistoryManager, { HistoryManagerStatic } from "./classes/HistoryManager"; // [!code ++]

    const stepHistory = new HistoryManager(); // [!code ++]

    export namespace Game {
        export async function initialize(
            element: HTMLElement,
            options: Partial<ApplicationOptions> & { width: number; height: number },
            devtoolsOptions?: Devtools
        ) {
            GameUnifier.init({
                restoreGameStepState: async (state, navigate) => {
                    HistoryManagerStatic.originalStepData = state; // [!code ++]
                    // ...
                },
                addHistoryItem: (historyInfo, opstions) => {
                    return stepHistory.add(historyInfo, opstions); // [!code ++]
                },
                // ...
            });
            // ...
        }

        export function clear() {
            // ...
            stepHistory.clear(); // [!code ++]
        }

        export function exportGameState(): GameState {
            return {
                // ...
                historyData: stepHistory.export(), // [!code ++]
            };
        }

        export async function restoreGameState(data: GameState, navigate: (path: string) => void) {
            stepHistory.restore(data.historyData); // [!code ++]
            // ...
        }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="classes/HistoryManager.ts">
    ```ts
    import { GameStepStateData, GameUnifier, HistoryGameState, HistoryStep } from "@drincs/pixi-vn";
    import { diff } from "deep-diff";

    export class HistoryManagerStatic {
        static _stepsHistory: HistoryStep[] = [];
        static stepLimitSaved: number = 20;
        static get lastHistoryStep(): HistoryStep | null {
            if (HistoryManagerStatic._stepsHistory.length > 0) {
                return HistoryManagerStatic._stepsHistory[HistoryManagerStatic._stepsHistory.length - 1];
            }
            return null;
        }
        static originalStepData: GameStepStateData | undefined = undefined;
    }

    /**
     * This class is a class that manages the steps and labels of the game.
     */
    export default class HistoryManager {
        get stepsHistory() {
            return HistoryManagerStatic._stepsHistory;
        }
        add(
            historyInfo: HistoryInfo = {},
            opstions: {
                ignoreSameStep?: boolean;
            } = {}
        ) {
            const originalStepData = HistoryManagerStatic.originalStepData;
            const { ignoreSameStep } = opstions;
            const currentStepData: GameStepStateData = GameUnifier.currentGameStepState;
            if (!ignoreSameStep && this.isSameStep(originalStepData, currentStepData)) {
                return;
            }
            let data = diff(originalStepData, currentStepData);
            this.stepsHistory.push({
                ...(historyInfo as Omit<HistoryStep, "diff">),
                diff: data,
            });
            HistoryManagerStatic.originalStepData = currentStepData;
        }

        private isSameStep(originalState: GameStepStateData, newState: GameStepStateData) {
            if (originalState.openedLabels.length === newState.openedLabels.length) {
                try {
                    let lastStepDataOpenedLabelsString = JSON.stringify(originalState.openedLabels);
                    let historyStepOpenedLabelsString = JSON.stringify(newState.openedLabels);
                    if (
                        lastStepDataOpenedLabelsString === historyStepOpenedLabelsString &&
                        originalState.path === newState.path &&
                        originalState.labelIndex === newState.labelIndex
                    ) {
                        return true;
                    }
                } catch (e) {
                    console.error("Error comparing opened labels", e);
                    return true;
                }
            }
            return false;
        }

        public clear() {
            HistoryManagerStatic._stepsHistory = [];
            HistoryManagerStatic.originalStepData = undefined;
        }

        /* Export and Import Methods */

        public export(): HistoryGameState {
            return {
                stepsHistory: this.stepsHistory,
                originalStepData: HistoryManagerStatic.originalStepData,
            };
        }
        public async restore(data: object) {
            this.clear();
            HistoryManagerStatic._stepsHistory = (data as HistoryGameState)["stepsHistory"];
            HistoryManagerStatic.originalStepData = (data as HistoryGameState)["originalStepData"];
        }

        /* Options Methods */

        async back() {
            // TODO To be implemented
        }
        get narrativeHistory() {
            // TODO To be implemented
        }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>


# Make your VN builder or web-game editor (/start/make-ide)



Pixi’VN is a free, open-source npm library and will never be tied to a single VN builder or web-game editor.

We encourage VN builder or web-game editor developers to add an export that produces a file compatible with Pixi’VN projects.

<Callout type="info">
  Before you begin, contact the Pixi’VN team. We can offer advice, collaborate, and help promote your integration.
</Callout>

Create [#create]

If you are starting from scratch, here is some practical advice:

* Be realistic about the time and skills required.
* Choose your languages and tools based on your team and goals. We recommend using TypeScript so you can reuse Pixi’VN typings.
* The simplest and most portable approach is to export a JSON that follows the <DynamicLink href="/json">PixiVNJson</DynamicLink> model. That JSON contains the sequence of instructions Pixi’VN will execute and can be injected into a Pixi’VN template by the user or your tool.
* Exporting JSON keeps your tool engine-agnostic and makes it easier to support other engines later.

Migrate [#migrate]

Already have a tool and want Pixi’VN compatibility? Usually this is straightforward:

* If your tool already exports or internally serializes instructions as objects or JSON, create a small mapping layer that converts your format to the <DynamicLink href="/json">PixiVNJson</DynamicLink> model.

Once you can produce PixiVNJson, users can drop the exported JSON into a Pixi’VN template to run the game.


# Make your first RPG game (/start/make-rpg)



<Callout title="This page is under construction" type="warn">
  The toolkit for creating an RPG on Pixi’VN is still in development. If you are interested, feel free to write in the chat below!
</Callout>


# Make your first Visual Novel (/start/make-visual-novel)





This tutorial will guide you through the process of creating your first Visual Novel.

**What is a Visual Novel?** A visual novel (VN) is a form of digital interactive fiction. Visual novels are often associated with the medium of video games, but are not always labeled as such themselves. They combine a textual narrative with static or animated illustrations and a varying degree of interactivity. The format is more rarely referred to as novel game, a retranscription of the wasei-eigo term noberu gēmu (ノベルゲーム), which is more often used in Japanese.

For testing purposes, in this guide we will be recreating the visual novel [Breakdown](https://joshpowlison.itch.io/breakdown) using Pixi’VN. Breakdown is a short story that has all the features that a visual novel should have. Josh Powlison, the creator of Breakdown, has given us permission to use his narration for educational purposes❤️.

Since Pixi’VN gives you the ability to write your own narration by choosing one or more <DynamicLink href="/start/narration">available narrative languages</DynamicLink>, examples will be made for each currently available language at each development step.

Create a new project [#create-a-new-project]

The first step is to create a new project. You can find more information on how to create a new project starting from a template <DynamicLink href="/start#project-initialization">here</DynamicLink>. We will use the template "Visual Novel - React".

`Visual Novel -> React`

After the creation is complete, it is very important to read the `README.md` file that is in the root of the project. This file contains important information about the project and how to use it.

In our case, to start the project we will simply need to execute the following commands:

```bash
npm install
npm start
```

Characters creation [#characters-creation]

Now we will define the characters of this story. To do this, we will define in the `/values/characters.ts` file the characters that we will be using. For more information on how to create and use characters you can consult: <DynamicLink href="/start/character">Characters</DynamicLink>

What does `mc` mean? `mc` is a common abbreviation for "Main Character". It is a common practice in visual novels to use `mc` as the main character's name.

<CodeBlockTabs defaultValue="values/characters.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="values/characters.ts">
      values/characters.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="App.tsx">
      App.tsx
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="values/characters.ts">
    ```ts
    import { RegisteredCharacters } from "@drincs/pixi-vn";
    import Character from "../models/Character";

    export const mc = new Character('mc', {
        name: 'Me',
    });

    export const james = new Character('james', {
        name: 'James',
        color: "#0084ac"
    });

    export const steph = new Character('steph', {
        name: 'Steph',
        color: "#ac5900"
    });

    export const sly = new Character('sly', {
        name: 'Sly',
        color: "#6d00ac"
    });

    RegisteredCharacters.add([mc, james, steph, sly]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="App.tsx">
    ```ts
    // Remember to import the character file at least once into your project. // [!code focus]
    import "./values/characters"; // [!code focus]

    export default function App() {
    return // ...
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

First draft of the narrative [#first-draft-of-the-narrative]

<Callout title="Markup" type="info">
  All templates have  <DynamicLink href="/start/markup-markdown">Markdown</DynamicLink> and <DynamicLink href="/start/markup-tailwindcss">Tailwind CSS</DynamicLink> support, so we will use it for our narration.
</Callout>

Now we can start writing the "first draft" of the <DynamicLink href="/start/narration">narration</DynamicLink> of the visual novel.
We will create the first <DynamicLink href="/start/labels">`label`</DynamicLink> called `start`, which will be the beginning of the game. After that we can write the <DynamicLink href="/start/dialogue">dialogues</DynamicLink> that will follow in our visual novel.

This is the example:

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

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

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    === start ===
    james: You're my roommate's replacement, huh?
    james: Don't worry, you don't have much to live up to. Just don't use heroin like the last guy, and you' fine!
    mc: ...

    He thrusts out his hand.

    james: James!
    mc: ...Peter.

    I take his hand and shake.

    james: Ooh, Peter! Nice, firm handshake! The last quy always gave me the dead fish. I already think we'r gonna get along fine.
    james: Come on in and... 
    james: ...
    james: I know you're both watching, come on out already!

    sly: I just wanted to see what the new guy was like. Hey, you, Peter- be nice to our little brother, or you'll have to deal with *us*.
    mc: ...
    james: Peter, this is Sly. Yes, that is her real name.

    I put out my hand.

    sly: I'm not shakin' your hand until I decide you're an all-right dude. Sorry, policy.
    mc: Fair enough, I'm a pretty scary guy, or so l've been told.
    james: The redhead behind her is Stephanie.
    // Example of using Tailwind CSS
    steph: <span class="inline-block motion-translate-y-loop-25">Hey</span>! Everyone calls me Steph. I'll shake your hand.

    // ...
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    const startLabel = newLabel("start", [
        () => narration.dialogue = { character: james, text: `You're my roommate's replacement, huh?` },
        () => narration.dialogue = { character: james, text: `Don't worry, you don't have much to live up to. Just don't use heroin like the last guy, and you' fine!` },
        () => narration.dialogue = { character: mc, text: `...` },
        () => { narration.dialogue = "He thrusts out his hand." },
        () => narration.dialogue = { character: james, text: `James!` },
        () => narration.dialogue = { character: mc, text: `...Peter.` },
        () => { narration.dialogue = "I take his hand and shake." },
        () => narration.dialogue = { character: james, text: `Ooh, Peter! Nice, firm handshake! The last quy always gave me the dead fish. I already think we'r gonna get along fine.` },
        () => narration.dialogue = { character: james, text: `Come on in and...` },
        () => narration.dialogue = { character: james, text: `...` },
        () => narration.dialogue = { character: james, text: `I know you're both watching, come on out already!` },
        () => narration.dialogue = { character: james, text: `I just wanted to see what the new guy was like. Hey, you, Peter- be nice to our little brother, or you'll have to deal with *us*.` },
        () => narration.dialogue = { character: mc, text: `...` },
        () => narration.dialogue = { character: james, text: `Peter, this is Sly. Yes, that is her real name.` },
        () => { narration.dialogue = "I put out my hand." },
        () => narration.dialogue = { character: james, text: `I'm not shakin' your hand until I decide you're an all-right dude. Sorry, policy.` },
        () => narration.dialogue = { character: mc, text: `Fair enough, I'm a pretty scary guy, or so l've been told.` },
        () => narration.dialogue = { character: james, text: `The redhead behind her is Stephanie.` },
        // Example of using Tailwind CSS
        () => narration.dialogue = { character: steph, text: `<span class="inline-block motion-translate-y-loop-25">Hey</span>! Everyone calls me Steph. I'll shake your hand.` },
        // ...
    ]);
    export default startLabel;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Split the narrative into `labels` [#split-the-narrative-into-labels]

It is not advisable to create very long `labels` (even for linear visual novels), but it is advisable to create multiple small `labels` and "call" them when needed with the <DynamicLink href="/start/labels-flow">narration flow control features</DynamicLink>.

For this reason, even if in our case our story is linear, it will be divided into two `labels`, the first will be the one we just created (`start`), while the second will be called `second_part`.

This is the example:

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

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

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    === start ===
    james: You're my roommate's replacement, huh?
    james: Don't worry, you don't have much to live up to. Just don't use heroin like the last guy, and you' fine!
    mc: ...

    He thrusts out his hand.

    james: James!
    mc: ...Peter.

    // ...
    -> second_part

    === second_part ===

    She enters my room before I'VE even had a chance to. \\n\\n...I could've just come back and gotten the platter later...
    She sets it on a desk. I throw my two paper bags down beside the empty bed.

    steph: They got you a new mattress, right? That last guy was a druggie, did James tell you that?
    sly: *We're* the reason he got expelled!
    steph: Sly! If word gets out about that... well, actually, it wouldn't matter, *he's* the one who shot himself up.

    I'm fumbling for a new subject.

    // ...
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    const startLabel = newLabel("start", [
        () => narration.dialogue = { character: james, text: `You're my roommate's replacement, huh?` },
        () => narration.dialogue = { character: james, text: `Don't worry, you don't have much to live up to. Just don't use heroin like the last guy, and you' fine!` },
        () => narration.dialogue = { character: mc, text: `...` },
        () => { narration.dialogue = "He thrusts out his hand." },
        () => narration.dialogue = { character: james, text: `James!` },
        () => narration.dialogue = { character: mc, text: `...Peter.` },
        // ...
        async (props) => await narration.jump(secondPart, props),
    ]);
    export default startLabel;

    const secondPart = newLabel("second_part", [
        () => { narration.dialogue = `She enters my room before I'VE even had a chance to. \n\n...I could've just come back and gotten the platter later...` },
        () => { narration.dialogue = `She sets it on a desk. I throw my two paper bags down beside the empty bed.` },
        () => narration.dialogue = { character: steph, text: `They got you a new mattress, right? That last guy was a druggie, did James tell you that?` },
        () => narration.dialogue = { character: sly, text: `*We're* the reason he got expelled!` },
        () => narration.dialogue = { character: steph, text: `Sly! If word gets out about that... well, actually, it wouldn't matter, *he's* the one who shot himself up.` },
        () => { narration.dialogue = `I'm fumbling for a new subject.` },
        // ...
    ]);
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Use the "glue" feature of dialogues [#use-the-glue-feature-of-dialogues]

In visual novels, it is often useful to paste text into the current dialogue. For example, to pause a conversation and have it continue in a subsequent `step`. To do this, we can use the <DynamicLink href="/start/dialogue#dialogue-glue">glue functionality</DynamicLink>.

This is the example:

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

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

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    === start ===
    // ...

    james: Ooh, [mc]! Nice, firm handshake!
    <>The last guy always gave me the dead fish.
    <>I already think we're gonna get along fine.
    james: Come on in and...

    // ...
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    const startLabel = newLabel("start", [
        // ...
        async () => narration.dialogue = { character: james, text: `Ooh, ${mc.name}! Nice, firm handshake!` },
        async () => {
            narration.dialogGlue = true
            narration.dialogue = `The last guy always gave me the dead fish.`
        },
        async () => {
            narration.dialogGlue = true
            narration.dialogue = `I already think we're gonna get along fine.`
        },
        async () => narration.dialogue = { character: james, text: `Come on in and...` },
        // ...
    ]);
    export default startLabel;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Choice menus [#choice-menus]

Now we will ask the player if he wants to continue with the second part of the visual novel.

To do this, we will use the <DynamicLink href="/start/choices">choice menu</DynamicLink>.

This is the example:

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

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

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    === start ===
    // ...

    You want continue to the next part?
    * Yes, I want to continue
    -> second_part
    * No, I want to stop here
    -> END

    === second_part ===

    // ...
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    const startLabel = newLabel("start", [
        // ...
        async () => {
            narration.dialogue = `You want continue to the next part?`
            narration.choices = [
                newChoiceOption("Yes, I want to continue", secondPart, {}, { type: "jump" }),
                newCloseChoiceOption("No, I want to stop here"),
            ]
        },
    ]);
    export default startLabel;

    const secondPart = newLabel("second_part", [
        // ...
    ]);
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Edit character information and use it as a variable [#edit-character-information-and-use-it-as-a-variable]

Now I will give the player the ability to change the name of the `mc`.

To do this, I will ask the player to <DynamicLink href="/start/input">complete an input box using Pixi’VN's features</DynamicLink>.

After getting the input value, you can <DynamicLink href="/start/character#edit">set the character name</DynamicLink> using the obtained value.

This is the example:

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

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

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    === start ===
    // ...

    He thrusts out his hand.
    # request input type string default Peter
    What is your name?
    # rename mc { _input_value_ }

    // ...
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    const startLabel = newLabel("start", [
        // ...
        () => { narration.dialogue = `He thrusts out his hand.` },
        () => {
            narration.requestInput({ type: "string" }, "Peter")
            narration.dialogue = `What is your name?`
        },
        () => {
            mc.name = narration.inputValue as string
        },
        // ...
    ]);
    export default startLabel;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Now we could <DynamicLink href="/start/character#use">use character names</DynamicLink> within dialogues.

This is the example:

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

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

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    VAR steph_fullname = "Stephanie"

    === start ===
    // ...

    sly: I just wanted to see what the new guy was like. Hey, you, [mc]- be nice to our little brother, or you'll have to deal with *us*.
    mc: ...
    james: [mc], this is [sly]. Yes, that is her real name.

    I put out my hand.

    sly: I'm not shakin' your hand until I decide you're an all-right dude. Sorry, policy.
    mc: Fair enough, I'm a pretty scary guy, or so l've been told.
    james: The redhead behind her is [steph_fullname].
    steph: Hey! Everyone calls me [steph]. I'll shake your hand.

    She puts out her hand, and I take it.

    mc: Thanks, good to meet you, [steph_fullname].
    steph: WOW, that is, like, the most perfect handshake I've ever had! Firm, but also gentle. [sly], you *gotta* shake his hand!

    // ...
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    const steph_fullname = "Stephanie";

    const startLabel = newLabel("start", [
        // ...
        () => narration.dialogue = { character: sly, text: `I just wanted to see what the new guy was like. Hey, you, ${mc.name}- be nice to our little brother, or you'll have to deal with *us*.` },
        () => narration.dialogue = { character: mc, text: `...` },
        () => narration.dialogue = { character: james, text: `${mc.name}, this is ${sly.name}. Yes, that is her real name.` },
        () => { narration.dialogue = `I put out my hand.` },
        () => narration.dialogue = { character: sly, text: `I'm not shakin' your hand until I decide you're an all-right dude. Sorry, policy.` },
        () => narration.dialogue = { character: mc, text: `Fair enough, I'm a pretty scary guy, or so I've been told.` },
        () => narration.dialogue = { character: james, text: `The redhead behind her is ${steph_fullname}.` },
        () => narration.dialogue = { character: steph, text: `Hey! Everyone calls me ${steph.name}. I'll shake your hand.` },
        () => { narration.dialogue = `She puts out her hand, and I take it.` },
        () => narration.dialogue = { character: mc, text: `Thanks, good to meet you, ${steph_fullname}.` },
        () => narration.dialogue = { character: steph, text: `WOW, that is, like, the most perfect handshake I've ever had! Firm, but also gentle. ${sly.name}, you *gotta* shake his hand!` },
        // ...
    ]);
    export default startLabel;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Define assets and load them [#define-assets-and-load-them]

<Callout type="info">
  To load and manipulate assets (images, gifs, videos...) you will need to use `Assets`. `Assets` is a class with many features and comes from the PixiJS library, if you want more information read [here](https://pixijs.com/8.x/guides/components/assets).
</Callout>

One of the first steps is choosing where to save your visual novel assets. In this case, we will save the assets in the Firebase storage (a hosting service). You can use any hosting service you prefer or even save the assets locally in the project, read more about it <DynamicLink href="/start/assets">here</DynamicLink>.

Before using an asset it is highly recommended to <DynamicLink href="/start/assets-management#initialize-the-asset-matrix-at-project-start">initialize the asset matrix</DynamicLink>.

By default, as you can see in the `assets/manifest.ts` file, all templates in the `onLoadingLabel` try to load in the background the "bundle assets" with the alias equal to the current `label` id. So it is recommended to add, in the `manifest`, a "bundle assets" for each `label` with the alias equal to the `label` id and containing the images used in that `label`.

This is the example:

<CodeBlockTabs defaultValue="assets/manifest.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="utils/defineAssets.ts">
      utils/defineAssets.ts
    </CodeBlockTabsTrigger>

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

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";
    import { MAIN_MENU_ROUTE } from "../constans";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            // screens
            {
                name: MAIN_MENU_ROUTE,
                assets: [
                    {
                        alias: "background_main_menu",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/main-menu.png",
                    },
                ],
            },
            // labels
            {
                name: "start",
                assets: [
                    {
                        alias: "bg01-hallway",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/bg01-hallway.webp",
                    },
                ],
            },
            {
                name: "second_part",
                assets: [
                    {
                        alias: "bg02-dorm",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/bg02-dorm.webp",
                    },
                ],
            },
            // characters
            {
                name: "fm01",
                assets: [
                    {
                        alias: "fm01-body",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-body.webp",
                    },
                    {
                        alias: "fm01-eyes-grin",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-eyes-grin.webp",
                    },
                    {
                        alias: "fm01-eyes-smile",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-eyes-smile.webp",
                    },
                    {
                        alias: "fm01-eyes-soft",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-eyes-soft.webp",
                    },
                    {
                        alias: "fm01-eyes-upset",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-eyes-upset.webp",
                    },
                    {
                        alias: "fm01-eyes-wow",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-eyes-wow.webp",
                    },
                    {
                        alias: "fm01-mouth-grin00",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-mouth-grin00.webp",
                    },
                    {
                        alias: "fm01-mouth-serious00",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-mouth-serious00.webp",
                    },
                    {
                        alias: "fm01-mouth-serious01",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-mouth-serious01.webp",
                    },
                    {
                        alias: "fm01-mouth-smile00",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-mouth-smile00.webp",
                    },
                    {
                        alias: "fm01-mouth-smile01",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-mouth-smile01.webp",
                    },
                    {
                        alias: "fm01-mouth-soft00",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-mouth-soft00.webp",
                    },
                    {
                        alias: "fm01-mouth-soft01",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-mouth-soft01.webp",
                    },
                    {
                        alias: "fm01-mouth-upset00",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-mouth-upset00.webp",
                    },
                    {
                        alias: "fm01-mouth-upset01",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-mouth-upset01.webp",
                    },
                    {
                        alias: "fm01-mouth-wow01",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-mouth-wow01.webp",
                    },
                ],
            },
            {
                name: "fm02",
                assets: [
                    {
                        alias: "fm02-body",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-body.webp",
                    },
                    {
                        alias: "fm02-eyes-bawl",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-eyes-bawl.webp",
                    },
                    {
                        alias: "fm02-eyes-joy",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-eyes-joy.webp",
                    },
                    {
                        alias: "fm02-eyes-nervous",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-eyes-nervous.webp",
                    },
                    {
                        alias: "fm02-eyes-smile",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-eyes-smile.webp",
                    },
                    {
                        alias: "fm02-eyes-upset",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-eyes-upset.webp",
                    },
                    {
                        alias: "fm02-eyes-wow",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-eyes-wow.webp",
                    },
                    {
                        alias: "fm02-mouth-cry01",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-mouth-cry01.webp",
                    },
                    {
                        alias: "fm02-mouth-nervous00",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-mouth-nervous00.webp",
                    },
                    {
                        alias: "fm02-mouth-nervous01",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-mouth-nervous01.webp",
                    },
                    {
                        alias: "fm02-mouth-smile00",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-mouth-smile00.webp",
                    },
                    {
                        alias: "fm02-mouth-smile01",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-mouth-smile01.webp",
                    },
                    {
                        alias: "fm02-mouth-upset00",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-mouth-upset00.webp",
                    },
                    {
                        alias: "fm02-mouth-upset01",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-mouth-upset01.webp",
                    },
                    {
                        alias: "fm02-mouth-wow01",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-mouth-wow01.webp",
                    },
                ],
            },
            {
                name: "m01",
                assets: [
                    {
                        alias: "m01-body",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-body.webp",
                    },
                    {
                        alias: "m01-eyes-annoy",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-eyes-annoy.webp",
                    },
                    {
                        alias: "m01-eyes-concern",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-eyes-concern.webp",
                    },
                    {
                        alias: "m01-eyes-cry",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-eyes-cry.webp",
                    },
                    {
                        alias: "m01-eyes-grin",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-eyes-grin.webp",
                    },
                    {
                        alias: "m01-eyes-smile",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-eyes-smile.webp",
                    },
                    {
                        alias: "m01-eyes-wow",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-eyes-wow.webp",
                    },
                    {
                        alias: "m01-mouth-annoy00",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-annoy00.webp",
                    },
                    {
                        alias: "m01-mouth-annoy01",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-annoy01.webp",
                    },
                    {
                        alias: "m01-mouth-concern00",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-concern00.webp",
                    },
                    {
                        alias: "m01-mouth-concern01",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-concern01.webp",
                    },
                    {
                        alias: "m01-mouth-cry00",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-cry00.webp",
                    },
                    {
                        alias: "m01-mouth-cry01",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-cry01.webp",
                    },
                    {
                        alias: "m01-mouth-grin00",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-grin00.webp",
                    },
                    {
                        alias: "m01-mouth-neutral00",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-neutral00.webp",
                    },
                    {
                        alias: "m01-mouth-neutral01",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-neutral01.webp",
                    },
                    {
                        alias: "m01-mouth-smile00",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-smile00.webp",
                    },
                    {
                        alias: "m01-mouth-smile01",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-smile01.webp",
                    },
                    {
                        alias: "m01-mouth-wow01",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-wow01.webp",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>

  <CodeBlockTab value="utils/defineAssets.ts">
    ```ts
    import { Assets } from "@drincs/pixi-vn";
    import manifest from "../assets/manifest";

    /**
     * Define all the assets that will be used in the game.
     * This function will be called before the game starts.
     * You can read more about assets management in the documentation: https://pixi-vn.web.app/start/assets-management.html
     */
    export async function defineAssets() {
        await Assets.init({ manifest });

        // The game will not start until these asserts are loaded.
        await Assets.loadBundle("main_menu");

        // The game will start immediately, but these asserts will be loaded in the background.
        // Assets.backgroundLoadBundle("main_menu");
        // Assets.backgroundLoad("background_main_menu");
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="main.ts">
    ```ts
    import { Assets, canvas, Container, Game } from "@drincs/pixi-vn";
    import { createRoot } from "react-dom/client";
    import App from "./App";
    import { CANVAS_UI_LAYER_NAME } from "./constans";
    import "./index.css";
    import "./values/characters";

    // ...

    Game.onLoadingLabel((_stepId, { id }) => { // [!code focus]
        Assets.backgroundLoadBundle(id); // [!code focus]
    }); // [!code focus]
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Add background and character images [#add-background-and-character-images]

Now it's time to think about the visual part too. We will add the background and character sprites to the visual novel canvas.

**What is a sprite?** In computer graphics, a sprite is a two-dimensional bitmap that is integrated into a larger scene, most often in a 2D video game.

In our case the character sprites are composed of 3 images: the body, the eyes and the mouth. Then we use <DynamicLink href="/start/canvas-image-container">ImageContainer</DynamicLink> to compose the character. You can find more information on how to add canvas components in <DynamicLink href="/start/canvas-components">this documentation</DynamicLink>.

This is the example:

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

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

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    === start ===
    # show image bg bg01-hallway
    # show imagecontainer james [m01-body m01-eyes-smile m01-mouth-neutral01] xAlign 0.5 yAlign 1
    james: You're my roommate's replacement, huh?
    # show imagecontainer james [m01-body m01-eyes-grin m01-mouth-smile01]
    james: Don't worry, you don't have much to live up to. Just don't use heroin like the last guy, and you'll be fine!
    # show imagecontainer james [m01-body m01-eyes-smile m01-mouth-grin00]
    mc: ...

    // ...
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    const startLabel = newLabel("start", [
        async () => {
            await showImage("bg", "bg01-hallway");
            await showImageContainer("james", ["m01-body", "m01-eyes-smile", "m01-mouth-neutral01"], { xAlign: 0.5, yAlign: 1 });
            narration.dialogue = { character: james, text: `You're my roommate's replacement, huh?` }
        },
        async () => {
            await showImageContainer("james", ["m01-body", "m01-eyes-grin", "m01-mouth-smile01"])
            narration.dialogue = { character: james, text: `Don't worry, you don't have much to live up to. Just don't use heroin like the last guy, and you'll be fine!` }
        },
        async () => {
            await showImageContainer("james", ["m01-body", "m01-eyes-smile", "m01-mouth-grin00"])
            narration.dialogue = { character: mc, text: `...` }
        },
        // ...
    ]);
    export default startLabel;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Smart asset loading [#smart-asset-loading]

In our case we saved the game images on a hosting service (Firebase). For this reason the asset loading is not timely.

In order for the player not to perceive too many loadings we should group them in certain phases of the game. In my case I will load the most used images at the start of the `label`.

You can find more information on how to manage the loadings <DynamicLink href="/start/assets-management">here</DynamicLink>.

This is the example:

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

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

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    === start ===
    # lazyload bundle m01 fm01 fm02 // [!code focus]

    # show image bg bg01-hallway
    # show imagecontainer james [m01-body m01-eyes-smile m01-mouth-neutral01] xAlign 0.5 yAlign 1 with movein direction right speed 300
    james: You're my roommate's replacement, huh?
    # show imagecontainer james [m01-body m01-eyes-grin m01-mouth-smile01]
    james: Don't worry, you don't have much to live up to. Just don't use heroin like the last guy, and you'll be fine!
    # show imagecontainer james [m01-body m01-eyes-smile m01-mouth-grin00]
    mc: ...

    // ...
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    const startLabel = newLabel("start", [
        // ...
    ], {
        onLoadingLabel: () => { // [!code focus]
            Assets.backgroundLoadBundle(["fm01", "fm02", "m01"]); // [!code focus]
        } // [!code focus]
    });
    export default startLabel;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Use transitions [#use-transitions]

To make the visual novel more dynamic, you can use transitions to show images. You can find more information about using transitions <DynamicLink href="/start/canvas-transition">here</DynamicLink>.

This is the example:

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

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

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    === start ===
    // ...

    # show image bg bg01-hallway
    # show imagecontainer james [m01-body m01-eyes-smile m01-mouth-neutral01] xAlign 0.5 yAlign 1 with movein direction right speed 300
    james: You're my roommate's replacement, huh?
    # show imagecontainer james [m01-body m01-eyes-grin m01-mouth-smile01]
    james: Don't worry, you don't have much to live up to. Just don't use heroin like the last guy, and you'll be fine!
    # show imagecontainer james [m01-body m01-eyes-smile m01-mouth-grin00]
    mc: ...

    // ...
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    const startLabel = newLabel("start", [
        async () => {
            await showImage("bg", "bg01-hallway");
            await moveIn(
                "james",
                {
                    value: ["m01-body", "m01-eyes-smile", "m01-mouth-neutral01"],
                    options: { xAlign: 0.5, yAlign: 1 },
                },
                { direction: "right", ease: "circInOut", type: "spring" }
            );
            narration.dialogue = { character: james, text: `You're my roommate's replacement, huh?` };
        },
        async () => {
            await showImageContainer("james", ["m01-body", "m01-eyes-grin", "m01-mouth-smile01"]);
            narration.dialogue = {
                character: james,
                text: `Don't worry, you don't have much to live up to. Just don't use heroin like the last guy, and you'll be fine!`,
            };
        },
        async () => {
            await showImageContainer("james", ["m01-body", "m01-eyes-smile", "m01-mouth-grin00"]);
            narration.dialogue = { character: mc, text: `...` };
        },
        // ...
    ]);
    export default startLabel;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Building an animation [#building-an-animation]

To make the visual novel more dynamic, you can use animations. For more information about how to use animations, see <DynamicLink href="/start/canvas-animations-effects">here</DynamicLink>.

I recommend using TypeScript if you need to set many properties, as this gives you more control, more functionality, and type feedback.

In this example, my animation will take `steph` out of the scene and reinsert her in the next `step`. I'll also mirror her on the x-axis to make sure she's facing the right way.

To take `steph` out/in, I will use the `moveOut` and `moveIn` functions. For the mirror effect, I will use the `canvas.animate` function.

First, I use the `canvas.animate` function to create an animation that sets the `scaleX` property from `-1` (mirrored) to `1`, with `autoplay: false` so it does not start immediately.

Then, I use the `moveIn` function to move `steph` into the scene, passing the `tickerId` of the animation so it can be resumed after the transition is complete.

I use the `completeOnContinue: true` option to ensure the animation completes before the next `step` is executed. For `moveIn`, being a transition, `completeOnContinue` is true by default.

Since I use TypeScript for this animation, I created a `label` for it, so it can be called from other languages as well.

```ts title="labels/animation01.ts"
import { canvas, ImageContainer, moveIn, newLabel } from "@drincs/pixi-vn";

export const animation01 = newLabel("animation_01", [
    async () => {
        let tickerId = canvas.animate<ImageContainer>(
            "steph",
            {
                scaleX: 1,
            },
            { autoplay: false, completeOnContinue: true }
        );

        await moveIn(
            "steph",
            {
                value: ["fm02-body", "fm02-eyes-joy", "fm02-mouth-smile01"],
                options: { xAlign: 0.8, yAlign: 1, scale: { y: 1, x: -1 }, anchor: 0.5 },
            },
            { direction: "right", ease: "easeInOut", tickerIdToResume: tickerId }
        );
    },
]);
```

<Callout type="info" title="ink">
  As explained <DynamicLink href="/ink/labels#use-the-call-script">here</DynamicLink>, from *ink* you can call `labels` written in JS/TS and vice versa.
</Callout>

Now you can call this `label` (`animation_01`) from the main `label` (`start`).

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

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

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    === start ===
    // ...

    # show imagecontainer james [m01-body m01-eyes-grin m01-mouth-grin00]
    # show imagecontainer sly [fm01-body fm01-eyes-smile fm01-mouth-smile00]
    # show imagecontainer steph [fm02-body fm02-eyes-upset fm02-mouth-nervous00]
    # remove image steph with moveout direction left speed 300
    [steph_fullname] goes through the opposite door,
    # call animation_01
    <> and returns with a HUGE tinfoil-covered platter.

    // ...
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    const startLabel = newLabel("start", [
        // ...
        async () => {
            await showImageContainer("james", ["m01-body", "m01-eyes-grin", "m01-mouth-grin00"]);
            await showImageContainer("sly", ["fm01-body", "fm01-eyes-smile", "fm01-mouth-smile00"]);
            await showImageContainer("steph", ["fm02-body", "fm02-eyes-upset", "fm02-mouth-nervous00"]);
            moveOut("steph", { direction: "left", speed: 300 });
            narration.dialogue = `${steph_fullname} goes through the opposite door,`;
        },
        async (props) => {
            narration.dialogGlue = true;
            narration.dialogue = ` and returns with a HUGE tinfoil-covered platter.`;
            await narration.call(animation01, props);
        },
        // ...
    ]);
    export default startLabel;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Sounds and music [#sounds-and-music]

To add sounds and music to your visual novel, you can use the `sound` utility. You can find more information about how to use it <DynamicLink href="/start/sound">here</DynamicLink>.

The first step is to define the audio assets in the `manifest`. Then, you can load them in the background at the start of the game, so they will be available when needed without blocking the game start.

<CodeBlockTabs defaultValue="utils/assets-utility.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="utils/assets-utility.ts">
      utils/assets-utility.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="utils/assets-utility.ts">
    ```ts
    import { Assets, sound } from "@drincs/pixi-vn";
    import manifest from "../assets/manifest";

    /**
     * Define all the assets that will be used in the game.
     * This function will be called before the game starts.
     * You can read more about assets management in the documentation: https://pixi-vn.web.app/start/assets-management.html
     */
    export async function defineAssets() {
        await Assets.init({ manifest });

        // The audio bundle will be loaded in the background, so it will be available when needed, but it won't block the game start. // [!code focus]
        sound.backgroundLoadBundle("audio"); // [!code focus]
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "audio",
                assets: [
                    {
                        alias: "bgm_cheerful",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/audio/bgm_cheerful.wav",
                    },
                    {
                        alias: "sfx_whoosh",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/audio/sfx_whoosh.wav",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

You can also define sound channels to manage different types of sounds (e.g., BGM, SFX) and control their volume, pause, resume, etc. It is recommended to define the channels at the start of the game, for example in the `then` callback of the `Game.init` function.

Into this example, I define two channels: one for the background music (BGM) and one for the sound effects (SFX). I also set the `defaultChannelAlias` to the SFX channel, so if I don't specify a channel when playing a sound, it will be played in the SFX channel by default. To define the background channel, I set the `background` property to `true`, so unlike the other channels the sounds will not be stopped at the end of each narrative `step`, but they will continue until they are paused or stopped.

```ts title="main.ts"
import { Game, sound } from "@drincs/pixi-vn";
import {
    BGM_CHANNEL_NAME,
    SFX_CHANNEL_NAME,
} from "./constans";

Game.init(body, {
    // ...
}).then(() => {
    sound.addChannel(BGM_CHANNEL_NAME, { background: true });
    sound.addChannel(SFX_CHANNEL_NAME);
    sound.defaultChannelAlias = SFX_CHANNEL_NAME;
});
```

Finally, you can play the sounds and music in the `labels` using the `sound.play` function. You can also use channels to manage different types of sounds (e.g., BGM, SFX) and control their volume, pause, resume, etc.

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

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

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    === start ===
    # show image bg bg01-hallway
    # play sound sfx_whoosh delay 0.1
    # show imagecontainer james [m01-body m01-eyes-smile m01-mouth-neutral01] xAlign 0.5 yAlign 1 with movein direction right ease circInOut type spring
    james: You're my roommate's replacement, huh?
    # play sound sfx_whoosh channel bgm loop true
    # show imagecontainer james [m01-body m01-eyes-grin m01-mouth-smile01]
    james: Don't worry, you don't have much to live up to. Just don't use heroin like the last guy, and you'll be fine!
    # show imagecontainer james [m01-body m01-eyes-smile m01-mouth-grin00]
    mc: ...

    // ...

    # pause all sounds
    # show imagecontainer steph [fm02-body fm02-eyes-smile fm02-mouth-smile00]
    # play sound sfx_whoosh delay 0.1
    # remove image james with moveout direction right ease circInOut type spring duration 0.5 delay 0.05
    # remove image sly with moveout direction right ease anticipate duration 0.5
    # remove image steph with moveout direction left ease easeInOut duration 0.5 delay 0.1

    You want continue to the next part?<># continue
    * Yes, I want to continue
    -> second_part
    * No, I want to stop here
    -> END

    === second_part ===
    # show text bg "(A few minutes later...)" style \{ fontFamily: "Arial", dropShadow: \{ alpha: 0.8, angle: 2.1, blur: 4, color: "0x111111", distance: 10, \}, fill: "\#ffffff", stroke: \{ color: "\#004620", width: 12, join: "round" \}, fontSize: 60, fontWeight: "lighter" \} with fade
    # edit text bg align 0.5
    # pause

    # resume all sounds
    # show image bg bg02-dorm align 0 with fade
    # play sound sfx_whoosh delay 0.4
    // ...
    She enters my room before I'VE even had a chance to.

    // ...

    -> DONE

    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    const startLabel = newLabel("start", [
        async () => {
            await showImage("bg", "bg01-hallway");
            await sound.play("sfx_whoosh", { delay: 0.1 });
            await moveIn( "james", { value: ["m01-body", "m01-eyes-smile", "m01-mouth-neutral01"], options: { xAlign: 0.5, yAlign: 1 }, });
            narration.dialogue = { character: james, text: `You're my roommate's replacement, huh?` };
        },
        async () => {
            await sound.play("bgm_cheerful", { channel: BGM_CHANNEL_NAME, loop: true });
            await showImageContainer("james", ["m01-body", "m01-eyes-grin", "m01-mouth-smile01"]);
            narration.dialogue = {
                character: james,
                text: `Don't worry, you don't have much to live up to. Just don't use heroin like the last guy, and you'll be fine!`,
            };
        },
        async () => {
            await showImageContainer("james", ["m01-body", "m01-eyes-smile", "m01-mouth-grin00"]);
            narration.dialogue = { character: mc, text: `...` };
        },
        // ...
        async () => {
            sound.pauseAll();
            await showImageContainer("steph", ["fm02-body", "fm02-eyes-smile", "fm02-mouth-smile00"]);
            await sound.play("sfx_whoosh", { delay: 0.1 });
            moveOut("james", { direction: "right", ease: "circInOut", type: "spring", duration: 0.5, delay: 0.05 });
            moveOut("sly", { direction: "right", ease: "anticipate", duration: 0.5 });
            moveOut("steph", { direction: "left", ease: "easeInOut", duration: 0.5, delay: 0.1 });
            narration.dialogue = `You want continue to the next part?`;
            narration.choices = [
                newChoiceOption("Yes, I want to continue", secondPart, {}, { type: "jump" }),
                newCloseChoiceOption("No, I want to stop here"),
            ];
        },
    ]);
    export default startLabel;

    const secondPart = newLabel("second_part", [
        async ({ t }) => {
            narration.dialogue = undefined;
            const text = new Text({
                text: t(`(A few minutes later...)`),
            });
            await showWithFade("bg", text);
            text.align = 0.5;
        },
        async () => {
            sound.resumeAll();
            await showWithFade("bg", "bg02-dorm");
            await sound.play("sfx_whoosh", { delay: 0.4 });
            // ...
            narration.dialogue = `She enters my room before I'VE even had a chance to.`;
        },
        // ...
    ]);
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Conclusion [#conclusion]

Well, now you know how to create a visual novel with Pixi’VN. With great power comes great responsibility, so use it wisely and create a great story! 🚀

Here is an interactive example with a minimal UI (HTML). Scrolling down you can see the same result using a complete UI (React template).

<Tabs items="[&#x22;ink&#x22;, &#x22;Typescript&#x22;]" groupId="narrative_language">
  <Tab>
    <InkVisualNovelExample />
  </Tab>

  <Tab>
    <TSVisualNovelExample />
  </Tab>
</Tabs>

<iframe
  src="https://pixi-vn-react-template.web.app/"
  title="Visual Novel Demo"
  style="{
      width: &#x22;100%&#x22;,
      height: &#x22;400px&#x22;,
      border: &#x22;0&#x22;,
      borderRadius: &#x22;4px&#x22;,
      overflow: &#x22;hidden&#x22;,
  }"
  allowFullScreen="true"
/>


# Markdown (/start/markup-markdown)



**Markdown** is a lightweight markup language for creating formatted text using a plain-text editor. John Gruber created Markdown in 2004, in collaboration with Aaron Swartz, as a markup language that is intended to be easy to read in its source code form. Markdown is widely used for blogging and instant messaging, and also used elsewhere in online forums, collaborative software, documentation pages, and readme files.

Pixi’VN is not tied to any markup, and gives the developer the ability to choose the markup they prefer. However, it is recommended to use Markdown.

<Callout title="Templates" type="info">
  In all templates, the Markdown component is already defined.
</Callout>

<Callout title="ink" type="info">
  You can use this method with the *ink* syntax. See more <DynamicLink href="/ink/markup#markdown">here</DynamicLink>.
</Callout>

Here are some examples of implementations of Markdown in the JavaScript ecosystem:

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

    <CodeBlockTabsTrigger value="Vue">
      Vue
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Svelte">
      Svelte
    </CodeBlockTabsTrigger>

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

  <CodeBlockTab value="React">
    ```tsx
    // I use the react-markdown library to convert the Markdown to HTML
    // read more about it here: https://www.npmjs.com/package/react-markdown
    import Markdown from "react-markdown";
    import rehypeRaw from "rehype-raw";
    import remarkGfm from "remark-gfm";

    export default function MarkdownComponent({ text }: {
        text: string;
    }) {
        return (
            <Markdown
                remarkPlugins={[remarkGfm]}
                rehypePlugins={[rehypeRaw]}
            >
                {text}
            </Markdown>
        )
    };

    ```
  </CodeBlockTab>

  <CodeBlockTab value="Vue">
    ```vue
    <!-- I use the vue-markdown-render library to convert the Markdown to HTML -->
    <!-- read more about it here: https://www.npmjs.com/package/vue-markdown-render -->
    <template>
      <div>
        <vue-markdown :source="src" />
      </div>
    </template>

    <script lang="ts">
    import VueMarkdown from 'vue-markdown-render'

    export default defineComponent({
      name: 'MyComponent',
      components: {
        VueMarkdown
      },
      setup(props, ctx) {
        const src = ref('---
    title: header')
    ---

        return {
          src
        }
      }
    })
    </script>
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Svelte">
    ```svelte
    <!-- I use the svelte-markdown library to convert the Markdown to HTML -->
    <!-- read more about it here: https://www.npmjs.com/package/svelte-markdown -->
    <script>
      import SvelteMarkdown from 'svelte-markdown'
      const source = `
      ---
    title: This is a header
    ---

    This is a paragraph.

    * This is a list
    * With two items
      1. And a sublist
      2. That is ordered
        * With another
        * Sublist inside

    | And this is | A table |
    |-------------|---------|
    | With two    | columns |`
    </script>

    <SvelteMarkdown {source} />
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Angular">
    ```tsx
    // I use the ngx-markdown library to convert the Markdown to HTML
    // read more about it here: https://www.npmjs.com/package/ngx-markdown
    import { Component, Input } from "@angular/core";
    import { MarkdownModule } from "ngx-markdown";

    @Component({
      selector: "app-markdown",
      template: `
        <markdown [data]="text"></markdown>
      `,
    })
    export class MarkdownComponent {
      @Input() text: string;
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Sandbox template="4h8wst" entry="/src/components/MarkdownComponent.tsx" previewHeight="300" />

React Markdown Typewriter [#react-markdown-typewriter]

[React Markdown Typewriter](https://www.npmjs.com/package/react-markdown-typewriter) is a library that combines Markdown and Typewriter. This library was created by me for my need to add a Typewriter effect to the Markdown component in my React templates.

If you are using React, I recommend you use it:

```tsx title="React"
import { MarkdownTypewriter } from "react-markdown-typewriter";
import rehypeRaw from "rehype-raw";
import remarkGfm from "remark-gfm";

export default function MarkdownComponent({ text }: {
    text: string;
}) {
    return (
        <MarkdownTypewriter
            remarkPlugins={[remarkGfm]}
            rehypePlugins={[rehypeRaw]}
        >
            {text}
        </MarkdownTypewriter>
    )
};

```

<Sandbox template="rgjf6t" entry="/src/components/MarkdownComponent.tsx" previewHeight="320" />


# Tailwind CSS (/start/markup-tailwindcss)



**What is Tailwind CSS?** Tailwind CSS is a utility-first CSS framework for rapidly building custom designs. It is a low-level framework that provides a set of utility classes that can be used to build custom designs without having to leave the HTML. You can get more information on how install it [here](https://tailwindcss.com/docs/installation).

<Callout title="Templates" type="info">
  In all templates, the Tailwind CSS is already installed and configured.
</Callout>

<Callout title="ink" type="info">
  You can use this method with the *ink* syntax. See more <DynamicLink href="/ink/markup#css">here</DynamicLink>.
</Callout>

You can learn more on the [Tailwind CSS website](https://tailwindcss.com/).

There are various Tailwind CSS plugins available. Here is a list of some of them:

* [Tailwind CSS Motion](https://docs.rombo.co/tailwind): Adds animations to your Tailwind CSS project.
* [Tailwind CSS Typography](https://github.com/tailwindlabs/tailwindcss-typography): The official Tailwind CSS Typography plugin provides a set of classes you can use to add beautiful typographic.

It is recommended to use Tailwind CSS in your Pixi’VN project to add styling or animations to your dialogue text. Here is an example using the `tailwindcss-motion` plugin:

```ts title="labels/startLabel.ts"
import { narration, newLabel } from "@drincs/pixi-vn";

const startLabel = newLabel("start", [
    async () => {
        narration.dialogue = `<span className="inline-block motion-translate-y-loop-25">Hello</span>, welcome to the game!`;
    },
]);
export default startLabel;
```

<iframe
  src="https://play.tailwindcss.com/WCoOH2CSuZ?layout=preview"
  title="Tailwind CSS Motion"
  style="{
      width: &#x22;100%&#x22;,
      height: &#x22;320px&#x22;,
      border: &#x22;0&#x22;,
      borderRadius: &#x22;4px&#x22;,
      overflow: &#x22;hidden&#x22;,
  }"
/>


# Markup language and CSS (/start/markup)



<Callout title="ink" type="info">
  You can use this method with the *ink* syntax. See more <DynamicLink href="/ink/markup">here</DynamicLink>.
</Callout>

A markup language is a text-encoding system that specifies the structure, formatting, and relationships within a document. Markup can control how a document is displayed or enrich its content for automated processing. Common markup languages include HTML, KML/KMZ, XML, Markdown, and others.

For Pixi’VN, it is recommended to use <DynamicLink href="/start/markup-markdown">**Markdown**</DynamicLink> due to its simplicity and popularity. Markdown can often be combined with HTML, allowing you to use CSS for custom text styling. For advanced styling, consider using a CSS framework like <DynamicLink href="/start/markup-tailwindcss">**Tailwind CSS**</DynamicLink>.


# Minigames (/start/minigames)





<Callout type="info" name="AI">
  You can use the button above to create your own minigame, with AI.
</Callout>

The beauty of an interactive story compared to normal text is that you can take a break and interact with minigames related to the story.

<Callout type="info">
  Minigames in visual novels are typically launched during the narrative. To switch between the narrative UI and the minigame UI, it is recommended to link the minigame to a route (e.g., "/minigame") and navigate to it from the story. More information is available <DynamicLink href="/start/interface-navigate">here</DynamicLink>.
</Callout>

Here are some tips:

* Use components provided by the `@drincs/pixi-vn/pixi.js` submodule, such as `Graphics`, `Sprite`, and `Text`, to create your minigame. `@drincs/pixi-vn/pixi.js` is the PixiJS import, so you can use all its features.
* Use <DynamicLink href="/start/interface#adding-pixijs-ui-layers">PixiJS Layers</DynamicLink> to create a separate layer for your minigame. This allows you to manage the minigame independently from the main visual novel interface.
* Use the `Ticker` class to manage the game loop and update the game state.
* Use `window.addEventListener` to handle user input, such as keyboard or mouse events.
* Use HTML elements to create the UI, such as buttons, score displays, and game over messages.
* If you use PixiJS Layers, remember that Pixi’VN does not save the state of layers, so you need to manage the minigame state yourself. Save the state in a variable and restore it when the minigame restarts.

<Callout title="Templates" type="info">
  `useMinigame` is a custom hook that helps you manage the lifecycle of a minigame, including starting, updating, and cleaning up resources. It is present in all templates.
</Callout>

For example:

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

    <CodeBlockTabsTrigger value="hooks/useMinigame.ts">
      hooks/useMinigame.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="React">
    ```tsx
    import { Layer } from "@drincs/pixi-vn";
    import { Graphics, Ticker } from "@drincs/pixi-vn/pixi.js";
    import { useCallback, useMemo, useRef, useState } from "react";
    import useMinigame from "../hooks/useMinigame";

    export default function MiniGame() {
        const ticker = useMemo(() => new Ticker(), []);
        const [displayScore, setDisplayScore] = useState(0);
        const [gameOver, setGameOver] = useState(false);

        const onKeyDown = useCallback((e: KeyboardEvent) => {
            // Handle key down events for game controls
        }, []);

        const game = useCallback(
            (layer: Layer) => {
                const endGame = () => {
                    ticker.stop();
                    setGameOver(true);
                };

                window.addEventListener("keydown", onKeyDown);

                ticker.add(({ deltaMS }) => {
                    // Update game logic here
                });
                ticker.start();
            },
            [ticker] // They must not be changed during the game otherwise the game will restart
        );

        const options = useMemo(
            () => ({
                onExit() {
                    ticker.stop();
                    ticker.destroy();
                    window.removeEventListener("keydown", onKeyDown);
                },
            }),
            [ticker, onKeyDown] // They must not be changed during the game otherwise the game will restart
        );

        const { loading } = useMinigame(game, options);

        return (
            <>
                <div
                    style={{
                        position: "absolute",
                        top: 10,
                        left: 10,
                        color: "white",
                        fontSize: "24px",
                        background: "rgba(0,0,0,0.5)",
                        padding: "5px 10px",
                        borderRadius: "5px",
                    }}
                >
                    Score: {displayScore}
                </div>

                {gameOver && (
                    <div
                        style={{
                            position: "absolute",
                            top: "50%",
                            left: "50%",
                            transform: "translate(-50%, -50%)",
                            color: "red",
                            fontSize: "48px",
                            background: "rgba(0,0,0,0.7)",
                            padding: "20px 40px",
                            borderRadius: "10px",
                        }}
                    >
                        GAME OVER
                    </div>
                )}
            </>
        );
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="hooks/useMinigame.ts">
    ```ts
    import { canvas, Layer } from "@drincs/pixi-vn";
    import { Container } from "@drincs/pixi-vn/pixi.js";
    import { useEffect, useRef } from "react";
    import { CANVAS_MINIGAME_LAYER_NAME } from "../constans";

    export default function useMinigame(
        game: (layer: Layer) => void,
        props?: {
            onStart?: () => Promise<void>;
            onExit?: (layer: Layer) => void;
        }
    ) {
        const loading = useRef(false);

        // Keep latest callbacks in refs to avoid effect restarts
        const startRef = useRef<() => Promise<void>>(props?.onStart ?? (async () => {}));
        const exitRef = useRef<(layer: Layer) => void>(props?.onExit);

        // Update refs when props change, without changing effect identity
        useEffect(() => {
            startRef.current = props?.onStart ?? (async () => {});
        }, [props?.onStart]);

        useEffect(() => {
            exitRef.current = props?.onExit;
        }, [props?.onExit]);

        useEffect(() => {
            // Create the layer and start the game once
            loading.current = true;
            const layer = canvas.addLayer(CANVAS_MINIGAME_LAYER_NAME, new Container());
            if (!layer) {
                console.error("Failed to create UI layer for minigame");
                return;
            }

            let cancelled = false;

            startRef.current().then(() => {
                if (cancelled) return;
                loading.current = false;
                game(layer);
            });

            return () => {
                cancelled = true;
                canvas.removeLayer(CANVAS_MINIGAME_LAYER_NAME);
                if (exitRef.current) {
                    exitRef.current(layer);
                }
            };
        }, [game]);

        return { loading };
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Here are some examples:

<Callout type="info">
  The Pixi’VN Team welcomes new proposals and contributions to make this library even more complete. Feel free to share or propose your minigame implementations in the chat below!
</Callout>

<Accordions>
  <Accordion title="minigame_snake" id="snake">
    <CodeBlockTabs defaultValue="React">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="React">
          React
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="React">
        ```tsx
        import { canvas, Layer } from "@drincs/pixi-vn";
        import { Graphics, Ticker } from "@drincs/pixi-vn/pixi.js";
        import { useCallback, useMemo, useRef, useState } from "react";
        import useMinigame from "../hooks/useMinigame";

        export default function SnakeGame() {
            const ticker = useMemo(() => new Ticker(), []);
            const [displayScore, setDisplayScore] = useState(0);
            const [gameOver, setGameOver] = useState(false);

            const directionRef = useRef({ x: 1, y: 0 });
            const setDirection = (x: number, y: number) => {
                if ((x !== 0 && directionRef.current.x === 0) || (y !== 0 && directionRef.current.y === 0)) {
                    directionRef.current = { x, y };
                }
            };

            const onKeyDown = useCallback((e: KeyboardEvent) => {
                if (e.key === "ArrowUp" && directionRef.current.y === 0) setDirection(0, -1);
                else if (e.key === "ArrowDown" && directionRef.current.y === 0) setDirection(0, 1);
                else if (e.key === "ArrowLeft" && directionRef.current.x === 0) setDirection(-1, 0);
                else if (e.key === "ArrowRight" && directionRef.current.x === 0) setDirection(1, 0);
            }, []);

            const game = useCallback(
                (layer: Layer) => {
                    const gridSize = 20;
                    const snake: Graphics[] = [];
                    const moveInterval = 150;
                    let elapsed = 0;

                    const head = new Graphics();
                    head.rect(0, 0, gridSize, gridSize).fill({ color: 0x00ff00 });
                    head.x = 200;
                    head.y = 200;
                    layer.addChild(head);
                    snake.push(head);

                    const apple = new Graphics();
                    apple.rect(0, 0, gridSize, gridSize).fill({ color: 0xff0000 });
                    layer.addChild(apple);

                    const placeApple = () => {
                        const cols = Math.floor(canvas.width / gridSize);
                        const rows = Math.floor(canvas.height / gridSize);
                        apple.x = Math.floor(Math.random() * cols) * gridSize;
                        apple.y = Math.floor(Math.random() * rows) * gridSize;

                        // Avoid placing the apple on top of the snake
                        for (let segment of snake) {
                            if (segment.x === apple.x && segment.y === apple.y) {
                                placeApple();
                                return;
                            }
                        }
                    };
                    placeApple();

                    const endGame = () => {
                        ticker.stop();
                        setGameOver(true);
                    };

                    window.addEventListener("keydown", onKeyDown);

                    ticker.add(({ deltaMS }) => {
                        elapsed += deltaMS;
                        if (elapsed < moveInterval) return;
                        elapsed = 0;

                        // Move the body
                        for (let i = snake.length - 1; i > 0; i--) {
                            snake[i].position.set(snake[i - 1].x, snake[i - 1].y);
                        }

                        // Move the head
                        head.x += directionRef.current.x * gridSize;
                        head.y += directionRef.current.y * gridSize;

                        // Collision with the wall
                        if (head.x < 0 || head.y < 0 || head.x >= canvas.width || head.y >= canvas.height) {
                            endGame();
                            return;
                        }

                        // Collision with the body
                        for (let i = 1; i < snake.length; i++) {
                            if (head.x === snake[i].x && head.y === snake[i].y) {
                                endGame();
                                return;
                            }
                        }

                        // Eat the apple
                        if (head.x === apple.x && head.y === apple.y) {
                            const newSegment = new Graphics();
                            newSegment.rect(0, 0, gridSize, gridSize).fill({ color: 0x00ff00 });
                            newSegment.position.set(head.x, head.y);
                            layer.addChild(newSegment);
                            snake.push(newSegment);

                            setDisplayScore((prev) => prev + 1);
                            placeApple();
                        }
                    });

                    ticker.start();
                },
                [ticker]
            );

            const options = useMemo(
                () => ({
                    onExit() {
                        ticker.stop();
                        ticker.destroy();
                        window.removeEventListener("keydown", onKeyDown);
                    },
                }),
                [ticker, onKeyDown]
            );

            useMinigame(game, options);

            return (
                <>
                    <div
                        style={{
                            position: "absolute",
                            top: 10,
                            left: 10,
                            color: "white",
                            fontSize: "24px",
                            background: "rgba(0,0,0,0.5)",
                            padding: "5px 10px",
                            borderRadius: "5px",
                        }}
                    >
                        Score: {displayScore}
                    </div>

                    {gameOver && (
                        <div
                            style={{
                                position: "absolute",
                                top: "50%",
                                left: "50%",
                                transform: "translate(-50%, -50%)",
                                color: "red",
                                fontSize: "48px",
                                background: "rgba(0,0,0,0.7)",
                                padding: "20px 40px",
                                borderRadius: "10px",
                            }}
                        >
                            GAME OVER
                        </div>
                    )}

                    {/* Direction buttons */}
                    <div
                        style={{
                            position: "absolute",
                            bottom: 0,
                            right: 0,
                            textAlign: "center",
                            pointerEvents: "auto",
                        }}
                    >
                        <div style={{ marginTop: "10px" }}>
                            <button style={{ fontSize: "30px" }} onClick={() => setDirection(0, -1)}>
                                ⬆️
                            </button>
                        </div>
                        <div>
                            <button style={{ fontSize: "30px", marginRight: "50px" }} onClick={() => setDirection(-1, 0)}>
                                ⬅️
                            </button>
                            <button style={{ fontSize: "30px" }} onClick={() => setDirection(1, 0)}>
                                ➡️
                            </button>
                        </div>
                        <div>
                            <button style={{ fontSize: "30px" }} onClick={() => setDirection(0, 1)}>
                                ⬇️
                            </button>
                        </div>
                    </div>
                </>
            );
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <SnakeExample />
  </Accordion>
</Accordions>


# Narration (/start/narration)



Narration is the core of a visual novel. It consists of <DynamicLink href="/start/dialogue">dialogues</DynamicLink>, <DynamicLink href="/start/choices">choices</DynamicLink>, and <DynamicLink href="/start/input">input prompts</DynamicLink> shown to the player as the game progresses.

With Pixi’VN, you can use different narrative languages and even switch between them to take advantage of each one's features.

* **JavaScript/TypeScript**: A programming language that lets you write your narrative with full access to all project functions, but may require more code.
* **<DynamicLink href="/ink">*ink*</DynamicLink>**: A narrative language designed for writing stories easily, with minimal code.
* **<DynamicLink href="/renpy">Ren'Py</DynamicLink>**: Another narrative language for writing stories with little code.

| Narrative languages                  | JavaScript/TypeScript | *ink*                                                                 | Ren'Py             |
| ------------------------------------ | --------------------- | --------------------------------------------------------------------- | ------------------ |
| Ease of learning                     | ❌                     | ✅                                                                     | ✅                  |
| Is it a typed language?              | ✅                     | ❌                                                                     | ❌                  |
| Visual Studio Code extension         | ✅                     | ✅                                                                     | ✅                  |
| Translatable into multiple languages | ✅                     | ✅                                                                     | ✅                  |
| Auto-generation of translation files | ❌                     | ✅                                                                     | ✅                  |
| Ability to use non-Pixi’VN features  | ✅                     | ✅  (<DynamicLink href="/ink/hashtag">custom "# script"</DynamicLink>) | ✅ (using $ script) |
| Debugging                            | ✅                     | ❌                                                                     | ❌                  |


# Other narrative features (/start/other-narrative-features)



<Accordions>
  <Accordion title="managing_the_end_of_the_game" id="managing-the-end-of-the-game">
    When all `steps` of all `labels` are executed, the game will stop. The developer is responsible for handling the end of the game, as visual novels can have different ending strategies:

    * The game ends when all `steps` are executed.
    * The game has no end; if all steps are completed, another `label` will be started or the player will have to interact with an interface that can potentially start another `label`.
    * The game ends when the player reaches a specific point, such as due to game over.

    To manage the end of the game, set `Game.onEnd`. This function is called when the game ends and has the same signature as a `step`.

    For example, to end the game and navigate to an end screen:

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

    Game.onEnd(async (props) => {
        props.navigate("/end")
    })
    ```

    If your game has no end and should restart or loop:

    ```ts title="labels/startLabel.ts"
    export const startLabel = newLabel("start_label_id",
        () => {
            return [
                // ...
            ]
        }
    )
    ```

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

    Game.onEnd(async (props) => {
        narration.call(startLabel, props)
    })
    ```
  </Accordion>

  <Accordion title="random_number_generation" id="random-number-generation">
    Pixi’VN includes a built-in function to generate random numbers. Use `narration.getRandomNumber()` with the following parameters:

    * `min`: The minimum value.
    * `max`: The maximum value.
    * `options` (Optional):
      * `onceonly`: If `true`, the number will be generated only once for the current `step` of the `label` (default: `false`). Note: `min` and `max` affect the storage of already generated numbers.
  </Accordion>

  <Accordion title="check_if_the_label_has_already_been_completed" id="check-if-the-label-has-already-been-completed">
    To check if a `label` has already been completed, use the `narration.isLabelAlreadyCompleted` function.
    This function has the following parameters:

    * `label`: The <DynamicLink href="/start/labels">`label`</DynamicLink> to check.

    ```typescript
    const isLabelCompleted = narration.isLabelAlreadyCompleted(startLabel)
    const isLabelCompleted = narration.isLabelAlreadyCompleted("labelid")
    ```
  </Accordion>

  <Accordion title="check_if_current_step_is_already_been_opened" id="check-if-current-step-is-already-been-opened">
    To check if the current `step` has already been opened, use `narration.isCurrentStepAlreadyOpened`.

    ```typescript
    const isCurrentStepOpened = narration.isCurrentStepAlreadyOpened;
    ```
  </Accordion>

  <Accordion title="counter_of_execution_times_of_the_current_step" id="counter-of-execution-times-of-the-current-step">
    To get the execution count for the current `step`, use `narration.currentStepTimesCounter`. &#x2A;*Important:** The counter is only incremented if `narration.currentStepTimesCounter` is executed.

    ```ts title="labels/startLabel.ts"
    export const label = newLabel("id",
        () => {
            if (narration.currentStepTimesCounter === 0) { // ✅ will be incremented
                // ...
            } else {
                // ...
            }
        }
    )
    ```

    ```ts title="labels/startLabel.ts"
    export const label = newLabel("id",
        () => {
            if (narration.currentStepTimesCounter === 0) { // ✅ will be incremented
                // ...
            } else if (narration.currentStepTimesCounter === 1) { // ✅ Not incremented again in this step
                // ...
            }
        }
    )
    ```

    ```ts title="labels/startLabel.ts"
    export const label = newLabel("id",
        () => {
            if (flag) {
                if (narration.currentStepTimesCounter === 1) { // ❌ Only incremented if "flag" is true
                    // ...
                }
            }
        }
    )
    ```

    To reset the execution counter for the current `step`, set `narration.currentStepTimesCounter = 0`.

    ```typescript
    narration.currentStepTimesCounter = 0;
    ```
  </Accordion>
</Accordions>


# Save and load (/start/save)



<Callout type="info" title="Templates">
  The `createGameSave` and `loadSave` functions are already implemented in all templates. See `utils/save-utility.ts`.
</Callout>

Saving and loading is a core feature that lets players save their progress and continue later. This is essential for visual novels, allowing players to resume the story from where they left off.

Create [#create]

To create a save, use `Game.exportGameState()`. This returns an object with the game data, which you can store in a file or database.

Tip: Add extra info to your save file, such as the save name, creation date, and a screenshot of the current game state.

<Callout title="Templates" type="info">
  To generate an image, use `canvas.extractImage()`. This returns a base64 string of the current canvas, which you can use as a screenshot.
</Callout>

For example:

<CodeBlockTabs defaultValue="utils/save-utility.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="utils/save-utility.ts">
      utils/save-utility.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="models/GameSaveData.ts">
      models/GameSaveData.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="utils/save-utility.ts">
    ```ts
    import { Game } from "@drincs/pixi-vn";
    import GameSaveData from "../models/GameSaveData";

    export function createGameSave(options?: { image?: string; name?: string }): GameSaveData {
        const { image, name = "" } = options || {};
        return {
            saveData: Game.exportGameState(),
            gameVersion: __APP_VERSION__,
            date: new Date(),
            name: name,
            image: image,
        };
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="models/GameSaveData.ts">
    ```ts
    import { GameState } from "@drincs/pixi-vn";

    export default interface GameSaveData {
        saveData: GameState;
        gameVersion: string;
        date: Date;
        name: string;
        image?: string;
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Load [#load]

To load a save, use `Game.restoreGameState`. This function has the following parameters:

* `saveData`: The save data object to restore the game state.
* `navigate`: <DynamicLink href="/start/interface-navigate">A function to navigate to a specific route</DynamicLink> after loading the save.

For example:

<CodeBlockTabs defaultValue="utils/save-utility.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="utils/save-utility.ts">
      utils/save-utility.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="utils/save-utility.ts">
    ```ts
    import { Game } from "@drincs/pixi-vn";
    import { LOADING_ROUTE } from "../constans";
    import GameSaveData from "../models/GameSaveData";

    export async function loadSave(saveData: GameSaveData, navigate: NavigateFunction) {
        await navigate(LOADING_ROUTE);
        await Game.restoreGameState(saveData.saveData, navigate);
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

FAQ [#faq]

<Accordions>
  <Accordion title="generate_file" id="generate-file">
    You can export the save data to a file for backup or sharing.

    For example:

    <CodeBlockTabs defaultValue="utils/save-utility.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="utils/save-utility.ts">
          utils/save-utility.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="utils/save-utility.ts">
        ```ts
        import { NavigateFunction } from "react-router-dom";
        import { LOADING_ROUTE, NARRATION_ROUTE } from "../constans";
        import GameSaveData from "../models/GameSaveData";

        const SAVE_FILE_EXTENSION = "json";

        export function downloadGameSave(data: GameSaveData = createGameSave()) {
            const jsonString = JSON.stringify(data);
            // download the save data as a JSON file
            const blob = new Blob([jsonString], { type: "application/json" });
            // download the file
            const url = URL.createObjectURL(blob);
            const a = document.createElement("a");
            a.href = url;
            a.download = `${__APP_NAME__}-${__APP_VERSION__}-${data.name} ${data.date.toISOString()}.${SAVE_FILE_EXTENSION}`;
            a.click();
        }

        export function loadGameSaveFromFile(navigate: NavigateFunction, afterLoad?: () => void) {
            // load the save data from a JSON file
            const input = document.createElement("input");
            input.type = "file";
            input.accept = `application/${SAVE_FILE_EXTENSION}`;
            input.onchange = (e) => {
                const file = (e.target as HTMLInputElement).files?.[0];
                if (file) {
                    const reader = new FileReader();
                    reader.onload = (e) => {
                        const jsonString = e.target?.result as string;
                        navigate(LOADING_ROUTE);
                        let data: GameSaveData = JSON.parse(jsonString);
                        // load the save data from the JSON string
                        loadSave(data, navigate)
                            .then(() => {
                                afterLoad && afterLoad();
                            })
                            .catch(() => {
                                navigate(NARRATION_ROUTE);
                            });
                    };
                    reader.readAsText(file);
                }
            };
            input.click();
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="indexeddb" id="indexeddb">
    **What is IndexedDB?** IndexedDB is a browser API for storing large amounts of structured data, including files/blobs. It lets you save and load game states efficiently.

    For example:

    <CodeBlockTabs defaultValue="utils/save-utility.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="utils/save-utility.ts">
          utils/save-utility.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="utils/indexedDB-utility.ts">
          utils/indexedDB-utility.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="utils/save-utility.ts">
        ```ts
        import { canvas } from "@drincs/pixi-vn";
        import GameSaveData from "../models/GameSaveData";
        import {
            deleteRowFromIndexDB,
            getLastRowFromIndexDB,
            getListFromIndexDB,
            getRowFromIndexDB,
            INDEXED_DB_SAVE_TABLE,
            putRowIntoIndexDB,
        } from "./indexedDB-utility";

        export async function saveGameToIndexDB(
            info: Partial<GameSaveData> & { id?: number } = {},
            data = createGameSave()
        ): Promise<GameSaveData & { id: number }> {
            const { image = await canvas.extractImage(), ...rest } = info;
            let item = {
                ...data,
                image: image,
                ...rest,
            };
            if (item.id === undefined) {
                let lastSave = await getLastRowFromIndexDB<GameSaveData & { id: number }>(INDEXED_DB_SAVE_TABLE);
                if (lastSave) {
                    item.id = lastSave.id + 1;
                } else {
                    item.id = 0;
                }
            }
            await putRowIntoIndexDB(INDEXED_DB_SAVE_TABLE, item);
            if (item.id) {
                return item as GameSaveData & { id: number };
            }
            return (await getLastSaveFromIndexDB()) as GameSaveData & { id: number };
        }

        export async function getSaveFromIndexDB(id: number): Promise<(GameSaveData & { id: number }) | null> {
            return await getRowFromIndexDB(INDEXED_DB_SAVE_TABLE, id);
        }

        export async function getLastSaveFromIndexDB(): Promise<(GameSaveData & { id: number }) | null> {
            let list = await getListFromIndexDB<GameSaveData & { id: number }>(INDEXED_DB_SAVE_TABLE, {
                pagination: { limit: 1, offset: 0 },
                order: { field: "date", direction: "prev" },
            });
            if (list.length > 0) {
                return list[0];
            }
            return null;
        }

        export async function deleteSaveFromIndexDB(id: number): Promise<void> {
            return await deleteRowFromIndexDB(INDEXED_DB_SAVE_TABLE, id);
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="utils/indexedDB-utility.ts">
        ```ts
        const INDEXED_DB_VERSION = 2; // Increment this version number when you change the database schema
        const INDEXED_DB_NAME = "game_db";
        export const INDEXED_DB_SAVE_TABLE = "saves";

        export function initializeIndexedDB(): Promise<void> {
            return new Promise((resolve, reject) => {
                let request = indexedDB.open(INDEXED_DB_NAME, INDEXED_DB_VERSION);
                // check if the object store exists
                request.onupgradeneeded = function (_event) {
                    let db = request.result;
                    if (!db.objectStoreNames.contains(INDEXED_DB_SAVE_TABLE)) {
                        // create the object store
                        let objectStore = db.createObjectStore(INDEXED_DB_SAVE_TABLE, { keyPath: "id", autoIncrement: true });
                        objectStore.createIndex("id", "id", { unique: true });
                        objectStore.createIndex("date", "date", { unique: false });
                        objectStore.createIndex("name", "name", { unique: false });
                        objectStore.createIndex("gameVersion", "gameVersion", { unique: false });
                    }
                };

                request.onsuccess = function (_event) {
                    resolve();
                };
                request.onerror = function (event) {
                    console.error("Error opening indexDB", event);
                    reject();
                };
            });
        }

        export async function putRowIntoIndexDB<T extends {}>(tableName: string, data: T): Promise<T> {
            return new Promise((resolve, reject) => {
                let request = indexedDB.open(INDEXED_DB_NAME);

                request.onsuccess = function (_event) {
                    let db = request.result;
                    // run onupgradeneeded before onsuccess
                    if (!db.objectStoreNames.contains(tableName)) {
                        console.error("Object store rescues does not exist");
                        reject();
                    }
                    let transaction = db.transaction([tableName], "readwrite");
                    let objectStore = transaction.objectStore(tableName);
                    let setRequest = objectStore.put(data);
                    setRequest.onsuccess = function (_event) {
                        resolve(data);
                    };
                    setRequest.onerror = function (event) {
                        console.error("Error adding save data to indexDB", event);
                        reject();
                    };
                };
                request.onerror = function (event) {
                    console.error("Error adding save data to indexDB", event);
                };
            });
        }

        export async function getRowFromIndexDB<T extends {}>(tableName: string, id: any): Promise<T | null> {
            return new Promise((resolve, reject) => {
                let request = indexedDB.open(INDEXED_DB_NAME);
                request.onsuccess = function (_event) {
                    let db = request.result;
                    // check if the object store exists
                    if (!db.objectStoreNames.contains(tableName)) {
                        resolve(null);
                        return;
                    }
                    let transaction = db.transaction([tableName], "readwrite");
                    let objectStore = transaction.objectStore(tableName);
                    let getRequest = objectStore.get(id);
                    getRequest.onsuccess = function (_event) {
                        resolve(getRequest.result);
                    };
                    getRequest.onerror = function (event) {
                        console.error("Error getting save data from indexDB", event);
                        reject();
                    };
                };
                request.onerror = function (event) {
                    console.error("Error opening indexDB", event);
                    reject();
                };
            });
        }

        export async function getLastRowFromIndexDB<T extends {}>(tableName: string): Promise<T | null> {
            return new Promise((resolve, reject) => {
                let request = indexedDB.open(INDEXED_DB_NAME);
                request.onsuccess = function (_event) {
                    let db = request.result;
                    // check if the object store exists
                    if (!db.objectStoreNames.contains(tableName)) {
                        resolve(null);
                        return;
                    }
                    let transaction = db.transaction([tableName], "readwrite");
                    let objectStore = transaction.objectStore(tableName);
                    let getRequest = objectStore.openCursor(null, "prev");
                    getRequest.onsuccess = function (_event) {
                        let cursor = getRequest.result;
                        if (cursor) {
                            resolve(cursor.value);
                        } else {
                            resolve(null);
                        }
                    };
                    getRequest.onerror = function (event) {
                        console.error("Error getting save data from indexDB", event);
                        reject();
                    };
                };
                request.onerror = function (event) {
                    console.error("Error opening indexDB", event);
                    reject();
                };
            });
        }

        export async function deleteRowFromIndexDB(tableName: string, id: any): Promise<void> {
            return new Promise((resolve, reject) => {
                let request = indexedDB.open(INDEXED_DB_NAME);
                request.onsuccess = function (_event) {
                    let db = request.result;
                    let transaction = db.transaction([tableName], "readwrite");
                    let objectStore = transaction.objectStore(tableName);
                    let deleteRequest = objectStore.delete(id);
                    deleteRequest.onsuccess = function (_event) {
                        resolve();
                    };
                    deleteRequest.onerror = function (event) {
                        console.error("Error deleting save data from indexDB", event);
                        reject();
                    };
                };
                request.onerror = function (event) {
                    console.error("Error deleting save data from indexDB", event);
                };
            });
        }

        export async function getListFromIndexDB<T extends {}>(
            tableName: string,
            options: {
                order?: { field: keyof T; direction: IDBCursorDirection };
                pagination?: { offset: number; limit: number };
            } = {}
        ): Promise<T[]> {
            return new Promise((resolve, reject) => {
                let request = indexedDB.open(INDEXED_DB_NAME);
                request.onsuccess = function (_event) {
                    let db = request.result;
                    // check if the object store exists
                    if (!db.objectStoreNames.contains(tableName)) {
                        resolve([]);
                        return;
                    }
                    let transaction = db.transaction([tableName], "readwrite");
                    let objectStore = transaction.objectStore(tableName);
                    let getRequest = options.order
                        ? objectStore.index(options.order.field as string).openCursor(null, options.order.direction)
                        : objectStore.openCursor();
                    let results: T[] = [];
                    let counter = 0;
                    let limit = options.pagination?.limit ?? Infinity;
                    let offset = options.pagination?.offset ?? 0;
                    let advanced = false;
                    getRequest.onsuccess = (_event) => {
                        let cursor = getRequest.result;
                        if (cursor) {
                            if (counter >= offset) {
                                results.push(cursor.value);
                                if (results.length >= limit) {
                                    resolve(results);
                                    advanced = true;
                                }
                            }
                            counter++;
                            cursor.continue();
                        } else {
                            if (!advanced) {
                                resolve(results);
                            }
                        }
                    };
                    getRequest.onerror = function (event) {
                        console.error("Error getting save data from indexDB", event);
                        reject();
                    };
                };
                request.onerror = function (event) {
                    console.error("Error opening indexDB", event);
                    reject();
                };
            });
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="prevent_accidental_closure" id="prevent-accidental-closure">
    Since it is possible to create browser games, the problem of losing the last state of the game after accidentally closing the browser is common.

    To prevent this, you can generate a timely save when closing the game and automatically load it when you reopen it.

    For example:

    <CodeBlockTabs defaultValue="hooks/useClosePageDetector.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="hooks/useClosePageDetector.ts">
          hooks/useClosePageDetector.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="utils/save-utility.ts">
          utils/save-utility.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="hooks/useClosePageDetector.ts">
        ```ts
        import { useQueryClient } from "@tanstack/react-query";
        import { useEffect } from "react";
        import { useLocation } from "react-router-dom";
        import { LOADING_ROUTE, MAIN_MENU_ROUTE } from "../constans";
        import { addRefreshSave, loadRefreshSave } from "../utils/save-utility";
        import useEventListener from "./useKeyDetector";
        import useMyNavigate from "./useMyNavigate";
        import { INTERFACE_DATA_USE_QUEY_KEY } from "./useQueryInterface";

        export default function useClosePageDetector() {
            const navigate = useMyNavigate();
            const queryClient = useQueryClient();
            const location = useLocation();

            useEventListener({
                type: "beforeunload",
                listener: async () => {
                    if (location.pathname === MAIN_MENU_ROUTE || location.pathname === LOADING_ROUTE) {
                        return;
                    }
                    await addRefreshSave();
                },
            });

            useEffect(() => {
                loadRefreshSave(navigate).then(() =>
                    queryClient.invalidateQueries({ queryKey: [INTERFACE_DATA_USE_QUEY_KEY] })
                );
            }, []);
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="utils/save-utility.ts">
        ```ts
        import { NavigateFunction } from "react-router-dom";
        import { LOADING_ROUTE, MAIN_MENU_ROUTE, REFRESH_SAVE_LOCAL_STORAGE_KEY } from "../constans";
        import GameSaveData from "../models/GameSaveData";

        export async function addRefreshSave() {
            const data = createGameSave();
            let jsonString = JSON.stringify(data);
            if (jsonString) {
                localStorage.setItem(REFRESH_SAVE_LOCAL_STORAGE_KEY, jsonString);
            }
        }

        export async function loadRefreshSave(navigate: NavigateFunction) {
            const jsonString = localStorage.getItem(REFRESH_SAVE_LOCAL_STORAGE_KEY);
            if (jsonString) {
                navigate(LOADING_ROUTE);
                let data: GameSaveData = JSON.parse(jsonString);

                return loadSave(data, navigate)
                    .then(() => {
                        localStorage.removeItem(REFRESH_SAVE_LOCAL_STORAGE_KEY);
                    })
                    .catch(() => {
                        navigate(MAIN_MENU_ROUTE);
                    });
            } else {
                navigate(MAIN_MENU_ROUTE);
            }
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>
</Accordions>


# Sounds and music (/start/sound)





<Callout type="warn">
  The entire audio system has been revised in version 1.6.0.
</Callout>

The sound module is a wrapper around the [PixiJS Sound](https://github.com/pixijs/sound) library. It provides a simple interface for playing sounds and saves the current state at each <DynamicLink href="/start/labels">`step`</DynamicLink>.

<Callout title="ink" type="info">
  You can use this method with the *ink* syntax. See more <DynamicLink href="/ink/sound">here</DynamicLink>.
</Callout>

It is composed of the following elements, which will be referenced later:

* `sound` (manager) is the controller of the entire audio system. It is used to manage `channels`, start and control musical `media`, and retrieve information or modify sound `assets`. You can set values to adjust the overall audio level. These settings are not stored in save files and are mainly intended for game settings.
* `channels` is a sub-level of the sound manager and can be seen as a container. It is used to contain, start, and manage musical `media`. You can set values to affect only the contained media. These settings are not stored in save files and are mainly intended for game settings.
* `media` are instances of a sound that has been started. You can set values that apply only to themselves. All settings applied to them are saved in the game save. These settings are mainly intended to be modified during gameplay. They are contained within a `channel` in a one-to-many relationship. Each media has a unique `alias`.
* `assets` (sound assets), as the name suggests, are the assets used during the game to play sounds. You can set values to influence all media that use this asset. These settings are not saved and are mainly intended to be configured during game initialization when loading assets.

<CodeBlockTabs defaultValue="labels/startLabel.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="labels/startLabel.ts">
      labels/startLabel.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="labels/startLabel.ts">
    ```ts
    import { narration, newLabel, sound } from "@drincs/pixi-vn";

    export const startLabel = newLabel("start_label", [
        async () => {
            await sound.play("sfx_whoosh", { delay: 0.1 });
            await sound.play("bgm_cheerful", { loop: true, channel: "bgm" });
            narration.dialogue = "Hello, I'm a cheerful background music that will loop forever until you stop me.";
        },
        () => {
            sound.pause("bgm_cheerful");
            narration.dialogue = "I'm paused, but I can be resumed.";
        },
        () => {
            sound.resume("bgm_cheerful");
            narration.dialogue = "I'm back!";
        },
    ]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "audio",
                assets: [
                    {
                        alias: "bgm_cheerful",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/audio/bgm_cheerful.wav",
                    },
                    {
                        alias: "sfx_whoosh",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/audio/sfx_whoosh.wav",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<SoundExample />

Initialize [#initialize]

First of all, you need to define the <DynamicLink href="/start/assets-management#initialize-the-asset-matrix-at-project-start">asset matrix</DynamicLink> exactly as with other components. After that, it is recommended to load sounds at the start of the game using the functions provided by `sound`.

<CodeBlockTabs defaultValue="utils/assets-utility.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="utils/assets-utility.ts">
      utils/assets-utility.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="utils/assets-utility.ts">
    ```ts
    import { Assets, sound } from "@drincs/pixi-vn";
    import manifest from "../assets/manifest";

    /**
     * Define all the assets that will be used in the game.
     * This function will be called before the game starts.
     * You can read more about assets management in the documentation: https://pixi-vn.web.app/start/assets-management.html
     */
    export async function defineAssets() {
        await Assets.init({ manifest });

        // The audio bundle will be loaded in the background, so it will be available when needed, but it won't block the game start. // [!code focus]
        sound.backgroundLoadBundle("audio"); // [!code focus]
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "audio",
                assets: [
                    {
                        alias: "bgm_cheerful",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/audio/bgm_cheerful.wav",
                    },
                    {
                        alias: "sfx_whoosh",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/audio/sfx_whoosh.wav",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

It is also recommended to define `channels` immediately after game initialization. During the definition of `channels`, you can configure their settings, which are all intuitive and based on PixiJS Sound, except for:

* `background` (Optional): this is a boolean value that can be used to define `channels` intended for background sounds such as music or ambient audio. Unlike other sounds, they will not be stopped between narrative `step`s.

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

Game.init(body, {
    // ...
}).then(() => {
    sound.addChannel("bgm", { background: true });
    sound.addChannel("sfx");
    sound.defaultChannelAlias = "sfx";
});
```

Play [#play]

<Callout type="info">
  If no `channel` is specified during the `play` function, the `media` will be assigned to `sound.defaultChannelAlias`.
</Callout>

The basic functionality is to start a sound (`asset`). This can be done using the `play` function. The `play` function generates a `media` instance that you can interact with to control the produced sound.

This function has the following parameters:

* `alias`: The alias to identify the `media`.
* `soundUrl` (Optional): The URL or path. If you have initialized the <DynamicLink href="/start/assets-management#initialize-the-asset-matrix-at-project-start">asset matrix</DynamicLink>, you can use the alias of the sound. If you don't provide the URL, then the alias is used as the URL.
* `options` (Optional): The options for the `media`.
  * `delay`: The delay before the sound starts, in seconds.
  * `loop`: Override default loop, default to the Sound's loop setting.
  * `speed`: Override default speed, default to the Sound's speed setting.
  * `volume`: Override default volume, default to the Sound's volume setting.
  * `start`: Start time offset in seconds.
  * `end`: End time in seconds.
  * `muted`: If sound instance is muted by default.
  * `filters`: Filters that apply to play. Only supported with WebAudio.
  * `channel`: The alias of the `channel` to which the `media` will be assigned. If not specified, it will be assigned to `sound.defaultChannelAlias`.

<Accordions>
  <Accordion title="sound_channel" id="channel-play">
    ```ts
    import { sound } from "@drincs/pixi-vn";

    await sound.findChannel("sfx").play("sfx_whoosh", { delay: 0.1 });
    await sound.findChannel("bgm").play("bgm", "bgm_cheerful", { loop: true });
    ```
  </Accordion>

  <Accordion title="sound_manager" id="sound-manager-play">
    ```ts
    import { sound } from "@drincs/pixi-vn";

    await sound.play("sfx_whoosh", { delay: 0.1 });
    await sound.play("bgm", "bgm_cheerful", { loop: true, channel: "bgm" });
    ```
  </Accordion>
</Accordions>

Pause and resume [#pause-and-resume]

There are various ways to pause individual or multiple `media`.

<Accordions>
  <Accordion title="sound_media" id="media-pause">
    ```ts
    import { sound } from "@drincs/pixi-vn";

    const bgmMedia = sound.find("bgm_cheerful");
    if (bgmMedia) bgmMedia.paused = true;
    // ...
    if (bgmMedia) bgmMedia.paused = false;
    ```
  </Accordion>

  <Accordion title="sound_channel" id="channel-pause">
    ```ts
    import { sound } from "@drincs/pixi-vn";

    sound.findChannel("sfx").pauseAll();
    sound.findChannel("sfx").resumeAll();
    ```
  </Accordion>

  <Accordion title="sound_manager" id="sound-manager-pause">
    ```ts
    import { sound } from "@drincs/pixi-vn";

    sound.pause("bgm_cheerful")
    sound.pauseAll()

    sound.resume("bgm_cheerful")
    sound.resumeAll()
    ```
  </Accordion>
</Accordions>

Edit [#edit]

<Callout type="info">
  Only `media` settings will be saved in game save files.
</Callout>

It is possible to edit almost all settings at any time for different purposes.

<Accordions>
  <Accordion title="sound_media" id="media-edit">
    ```ts
    import { sound } from "@drincs/pixi-vn";

    const bgmMedia = sound.find("bgm_cheerful");
    if (bgmMedia) bgmMedia.volume = 90
    ```
  </Accordion>

  <Accordion title="sound_channel" id="channel-edit">
    ```ts
    import { sound } from "@drincs/pixi-vn";

    sound.findChannel("sfx").volume = 90
    ```
  </Accordion>

  <Accordion title="sound_manager" id="sound-manager-edit">
    ```ts
    import { sound } from "@drincs/pixi-vn";

    sound.volumeAll = 90
    ```
  </Accordion>

  <Accordion title="sound_asset" id="asset-edit">
    ```ts title="utils/assets-utility.ts"
    import { Assets, sound } from "@drincs/pixi-vn";
    import manifest from "../assets/manifest";

    /**
     * Define all the assets that will be used in the game.
     * This function will be called before the game starts.
     * You can read more about assets management in the documentation: https://pixi-vn.web.app/start/assets-management.html
     */
    export async function defineAssets() {
        await Assets.init({ manifest });

        // The audio bundle will be loaded in the background, so it will be available when needed, but it won't block the game start. // [!code focus]
        sound.backgroundLoadBundle(AUDIO_BUNDLE_NAME).then(() => { // [!code focus]
            sound.edit("bgm_cheerful", { volume: 90 }); // [!code focus]
        }); // [!code focus]
    }
    ```
  </Accordion>
</Accordions>

Stop [#stop]

To stop a sound, you can use the `stop` function.

<Accordions>
  <Accordion title="sound_media" id="media-stop">
    ```ts
    import { sound } from "@drincs/pixi-vn";

    sound.find("bgm_cheerful")?.stop();
    ```
  </Accordion>

  <Accordion title="sound_channel" id="channel-stop">
    ```ts
    import { sound } from "@drincs/pixi-vn";
    sound.findChannel("sfx").stopAll();
    ```
  </Accordion>

  <Accordion title="sound_manager" id="sound-manager-stop">
    ```ts
    import { sound } from "@drincs/pixi-vn";
    sound.stop("bgm_cheerful");
    sound.stopAll();
    ```
  </Accordion>
</Accordions>

Filters [#filters]

<Callout type="warn">
  Currently, they can only be modified when starting a media.
</Callout>

Filters are elements that allow advanced customization of sounds.

<Accordions>
  <Accordion title="sound_media" id="media-edit">
    ```ts
    import { sound, filters } from "@drincs/pixi-vn";

    await sound.play("sfx_whoosh", { filters: [new filters.ReverbFilter()] });
    ```
  </Accordion>

  <Accordion title="sound_channel" id="channel-edit">
    ```ts
    import { sound, filters } from "@drincs/pixi-vn";

    sound.addChannel("bgm", {
        filters: [new filters.ReverbFilter()],
    });
    ```
  </Accordion>

  <Accordion title="sound_manager" id="sound-manager-edit">
    ```ts
    import { sound, filters } from "@drincs/pixi-vn";

    sound.filtersAll = [new filters.ReverbFilter()];
    ```
  </Accordion>
</Accordions>


# Storage (/start/storage)



**What is the game storage?** The game storage is a place where you can save variables that you want to keep between game sessions.

It is essential to understand that if variables are not saved in the game memory, the engine will not be able to handle them when you <DynamicLink href="/start/save#load">load a save</DynamicLink> or when you <DynamicLink href="/start/labels-flow#go-back">go back</DynamicLink>.

Additionally, in the game archive you can save any type of variable, except `class` and `function` (because they cannot be converted to JSON), such as: `string`, `number`, `boolean`, `object`, `array`, etc. If you want to save "flags" (boolean), it is recommended to use the <DynamicLink href="/start/flags">flags functionality</DynamicLink>, a very high-performance flag management system.

<Callout title="ink" type="info">
  You can use this method with the *ink* syntax. See more <DynamicLink href="/ink/storage">here</DynamicLink>.
</Callout>

Set [#set]

To set a variable in the game storage, use `storage.set`. This function has the following parameters:

* `name`: The name of the variable to set.
* `value`: The value of the variable to set.

```typescript
import { storage } from '@drincs/pixi-vn'

storage.set("myVariable", 42);
```

Get [#get]

To get a variable from the game storage, use `storage.get`. This function has the following parameters:

* `name`: The name of the variable to get.

```typescript
import { storage } from '@drincs/pixi-vn'

const myVariable = storage.get("myVariable");
```

Remove [#remove]

To remove a variable from the game storage, use `storage.remove`. This function has the following parameters:

* `name`: The name of the variable to remove.

```typescript
import { storage } from '@drincs/pixi-vn'

storage.remove("myVariable");
```

Other features [#other-features]

<Accordions>
  <Accordion title="system_variables" id="system-variables">
    In game storage, there are some system variables that are used by the game engine. All system variables start with the prefix `___`.
    So please avoid using this prefix in your variables.

    You can get all system variable keys from the `SYSTEM_RESERVED_STORAGE_KEYS` constant.
  </Accordion>

  <Accordion title="keyv" id="keyv">
    The entire storage system was developed using `Map`, a native JavaScript object, so you can use Keyv to interact with game storage.

    **What is Keyv?** Keyv is a simple key-value storage. It is a very easy-to-use system and very popular in the Node.js community. Keyv can be combined with other libraries, such as [Cacheable](https://cacheable.org/) (Caching for Node.js based on Keyv). You can learn more on the [Keyv website](https://keyv.org/).

    **How to use Keyv with Pixi’VN?** You can use Keyv with Pixi’VN by creating a new instance of Keyv and passing the storage object as a parameter.

    ```typescript
    import { storage } from '@drincs/pixi-vn'
    import Keyv from 'keyv';

    const keyvStorage = new Keyv({ store: storage.base });

    keyvStorage.get<string>("myValue").then((value) => {
        console.log(value);
    });
    ```
  </Accordion>

  <Accordion title="default_storage_variables" id="default-storage-variables">
    You can set the starting value of storage variables.

    These variables will have the following characteristics:

    * If they are removed or set to undefined or null, the value will automatically be set to the default value (so they can never be undefined or null).
    * Default values ​​will not be saved in saves, so you can change them from one version to another without any problems.

    You can set the default storage variables using the `storage.default` object.

    ```typescript
    import { storage } from '@drincs/pixi-vn'

    storage.default = {
        myVariable: 42,
        anotherVariable: "Hello, world!"
    };
    ```
  </Accordion>
</Accordions>


# Storage classes (/start/stored-classes)



Pixi’VN provides an abstract class `StoredClassModel` that you can use to create classes with properties saved in the game storage.

The constructor of the `StoredClassModel` class has two parameters:

* `categoryId`: The id of the category. For example, if you are storing a character class, you can use `"character"` as `categoryId`. All instances of that class will be stored in the `"character"` category.
* `id`: The unique id of the instance within its category.

```ts
const CITY_CATEGORY = "city"

export default class City extends StoredClassModel {
    constructor(id: string, props: CityProps) {
        super(CITY_CATEGORY, id)
        // ...
    }
}
```

```ts
const milan = new City("milan", {
    // ...
})
```

Storate properties [#storate-properties]

To stored class properties in the game storage use the `getStorageProperty` and `setStorageProperty` helpers.

```typescript
export default class City extends StoredClassModel {
    constructor(id: string, props: CityProps) {
        // ...
    }

    get inhabitants(): number {
        return this.getStorageProperty<string>("inhabitants") || ""
    }
    set inhabitants(value: number) {
        this.setStorageProperty<string>("inhabitants", value)
    }
}
```

```ts
const milan = new City("milan", {
    // ...
})

milan.inhabitants = 100000
```


# Temporary storage (/start/temp-storage)



In many cases, it is useful to use variables only during a certain period of the narrative. Using normal storage, you would need to manually remove these variables when they are no longer needed, to keep saves light and efficient.

To solve this problem, Pixi’VN has a temporary storage system. Temporary variables initialized in a `label` will be deleted when the `label` is closed. If another `label` is called from it, the temporary variable will still be accessible from the child `label`. However, if another `label` is called with `jump` (so the current `label` will be closed and the new one started), the temporary variable will no longer be accessible.

Set [#set]

To set a temporary variable, use `storage.setTempVariable`. This function has the following parameters:

* `name`: The name of the variable to set.
* `value`: The value of the variable to set.

```typescript
import { storage } from '@drincs/pixi-vn'

storage.setTempVariable("myTempVariable", 42);
```

Get [#get]

To get a temporary variable, use the normal <DynamicLink href="/start/storage#set">`storage.get` function</DynamicLink>.

Remove [#remove]

To remove a temporary variable, use `storage.removeTempVariable`. This function has the following parameters:

* `name`: The name of the variable to remove.

```typescript
import { storage } from '@drincs/pixi-vn'

storage.removeTempVariable("myTempVariable");
```


# Templates (/start/templates)



The available template presets are:

<Callout title="More templates will be added in the future" type="info">
  Pixi’VN gives you the opportunity to propose your own templates and helps you in its development. If you are interested or want to propose a template, feel free to write in the chat below!
</Callout>

Visual Novel [#visual-novel]

Visual Novel for React [#visual-novel-for-react]

<iframe
  src="https://pixi-vn-react-template.web.app/"
  title="Visual Novel - React"
  style="{
      width: &#x22;100%&#x22;,
      height: &#x22;400px&#x22;,
      border: &#x22;0&#x22;,
      borderRadius: &#x22;4px&#x22;,
      overflow: &#x22;hidden&#x22;,
  }"
  allowFullScreen="true"
/>

* **[Visual Novel - React - Typescript - Web page](https://github.com/DRincs-Productions/pixi-vn-react-template)**
* **[Visual Novel - React - Typescript - Web page + Desktop + Mobile](https://github.com/DRincs-Productions/pixi-vn-react-template/tree/tauri)**
* **[Visual Novel - React - Ink + Typescript - Web page](https://github.com/DRincs-Productions/pixi-vn-react-template/tree/ink)**
* **[Visual Novel - React - Ink + Typescript - Web page + Desktop + Mobile](https://github.com/DRincs-Productions/pixi-vn-react-template/tree/ink-tauri)**

Text-based Story [#text-based-story]

Text-based Story for React [#text-based-story-for-react]

<iframe
  src="https://pixi-vn-react-st-template.web.app/"
  title="Visual Novel - React"
  style="{
      width: &#x22;100%&#x22;,
      height: &#x22;400px&#x22;,
      border: &#x22;0&#x22;,
      borderRadius: &#x22;4px&#x22;,
      overflow: &#x22;hidden&#x22;,
  }"
  allowFullScreen="true"
/>

* **[Text-based Story - React - Typescript - Web page](https://github.com/DRincs-Productions/pixi-vn-nonlinear-stories-react-template)**
* **[Text-based Story - React - Typescript - Web page + Desktop + Mobile](https://github.com/DRincs-Productions/pixi-vn-nonlinear-stories-react-template/tree/tauri)**
* **[Text-based Story - React - Ink + Typescript - Web page](https://github.com/DRincs-Productions/pixi-vn-nonlinear-stories-react-template/tree/ink)**
* **[Text-based Story - React - Ink + Typescript - Web page + Desktop + Mobile](https://github.com/DRincs-Productions/pixi-vn-nonlinear-stories-react-template/tree/ink-tauri)**

Point & Click Adventure [#point--click-adventure]

Point & Click Adventure for React [#point--click-adventure-for-react]

<iframe
  src="https://nqtr-react-template.firebaseapp.com/"
  title="Point & Click Adventure - React"
  style="{
      width: &#x22;100%&#x22;,
      height: &#x22;400px&#x22;,
      border: &#x22;0&#x22;,
      borderRadius: &#x22;4px&#x22;,
      overflow: &#x22;hidden&#x22;,
  }"
  allowFullScreen="true"
/>

* **[Point & Click Adventure - React - Typescript - Web page](https://github.com/DRincs-Productions/nqtr-react-template)**
* **[Point & Click Adventure - React - Typescript - Web page + Desktop + Mobile](https://github.com/DRincs-Productions/nqtr-react-template/tree/tauri)**
* **[Point & Click Adventure - React - Ink + Typescript - Web page](https://github.com/DRincs-Productions/nqtr-react-template/tree/ink)**
* **[Point & Click Adventure - React - Ink + Typescript - Web page + Desktop + Mobile](https://github.com/DRincs-Productions/nqtr-react-template/tree/ink-tauri)**

Other templates [#other-templates]

* **[Game engine](https://github.com/DRincs-Productions/pixi-vn-game-engine-template)**


# Internalization (/start/translate)





In visual novels and similar games, it is common to allow players to select their native language.

For your Pixi’VN project, you should use an external library to handle translations. This gives you the flexibility to choose the implementation that best fits your needs.

<Callout title="Templates" type="info">
  In all templates, i18next is already included and configured. You can start translating your game right away.
</Callout>

The most popular and widely compatible library is **i18next**.

<img alt="i18next-h2" src="__img0" />

i18next [#i18next]

**What is i18next?** i18next is an internationalization framework for JavaScript. To use it, you need to install and initialize it. Learn more on the [i18next website](https://www.i18next.com/).

Translations are stored in multiple JSON files (one per language), using key-value pairs. The key is a unique identifier for the text, and the value is the translated string.

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

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

  <CodeBlockTab value="i18n.ts">
    ```ts
    import i18n from 'i18next';
    import LanguageDetector from 'i18next-browser-languagedetector';
    import { initReactI18next } from 'react-i18next';
    import strings_en from '../src/values/translations/strings_en.json';
    import strings_es from '../src/values/translations/strings_es.json';

    const getUserLang = (): string => {
        let userLang: string = navigator.language || "en";
        return userLang?.toLocaleLowerCase()?.split("-")[0];
    }

    export const useI18n = () => {
        if (!i18n.isInitialized) {
            i18n
                .use(LanguageDetector)
                .use(initReactI18next)
                .init({
                    debug: false,
                    fallbackLng: 'en',
                    lng: getUserLang(),
                    interpolation: {
                        escapeValue: false,
                    },
                    resources: {
                        en: strings_en,
                        es: strings_es,
                        // Add more languages here
                    }
                });
        }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="main.ts">
    ```ts
    import { useI18n } from './i18n';

    useI18n()
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Accordions>
  <Accordion title="translate_ui" id="translate-ui">
    To translate the UI, use the `t` function provided by i18next. Pass the translation key to `t` to get the corresponding text in the player's language.

    For example:

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

        <CodeBlockTabsTrigger value="Vue">
          Vue
        </CodeBlockTabsTrigger>

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

      <CodeBlockTab value="React">
        ```tsx
        import { useTranslation } from 'react-i18next';

        export default function MyComponent() {
            const { t } = useTranslation("ui");

            return (
                <div>
                    <Button>{t("text_speed")}</Button>
                </div>
            );
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="Vue">
        ```vue
        <script setup>
            import { useTranslation } from "i18next-vue";
            const { t } = useTranslation("ui");
        </script>

        <template>
            <div>
                <button>{{ t('text_speed') }}</button>
            </div>
        </template>
        ```
      </CodeBlockTab>

      <CodeBlockTab value="Svelte">
        ```svelte
        <script>
            import { useTranslation } from 'svelte-i18n';
            const { t } = useTranslation("ui");
        </script>

        <div>
            <button>{t('text_speed')}</button>
        </div>
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="translate_narration" id="translate-narration">
    <Callout title="Templates" type="info">
      In all templates, the `StepLabelProps` interface already includes a `t` function. See `pixi-vn.d.ts`.
    </Callout>

    <Callout type="info">
      It is recommended to use `t` inside the <DynamicLink href="/start/labels">label</DynamicLink> rather than directly in the UI, so you can take advantage of [i18n Interpolation](https://i18next.com/translation-function/interpolation).
    </Callout>

    In Pixi’VN projects, you often need to translate narration text in TypeScript/JavaScript <DynamicLink href="/start/labels">`labels`</DynamicLink>. To enable this, the translation function must be in the <DynamicLink href="/start/labels#steplabelprops">`StepLabelProps` interface</DynamicLink>.

    It is recommended to use the original string as the translation key.

    <CodeBlockTabs defaultValue="labels/startLabel.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="labels/startLabel.ts">
          labels/startLabel.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pixi-vn.d.ts">
          pixi-vn.d.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="labels/startLabel.ts">
        ```ts
        export const startLabel = newLabel("start_label",
            [
                ({ t }) => { // [!code focus]
                    narration.dialogue = {
                        character: liam,
                        text: t("Hello, my name is {{name}}", { name: "Liam" }) // [!code focus]
                    }
                },
            ]
        )
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pixi-vn.d.ts">
        ```ts
        declare module '@drincs/pixi-vn' {
            interface StepLabelProps {
                /**
                 * Translate a key to a string.
                 * @param key The key to translate.
                 * @returns The translated string.
                 */
                t: TFunction<[string], undefined>
                // ...
            }
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>
</Accordions>

Create [#create]

<Callout title="ink" type="info">
  If you use `ink`, you can automatically extract strings from `ink` text for translation. See more <DynamicLink href="/ink/translate">here</DynamicLink>.
</Callout>

Translation JSON files must be created manually. It is recommended to split translations into two sections (see `strings_es.json`):

* <DynamicLink href="/start/interface">UI</DynamicLink> texts: for screens, settings, quick buttons, etc.—everything not part of the narration.
* <DynamicLink href="/start/narration">Narration</DynamicLink> texts: for dialogues, choice menus, etc.

<CodeBlockTabs defaultValue="locales/strings_es.json">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="locales/strings_es.json">
      locales/strings_es.json
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="locales/strings_es.json">
    ```json
    {
        "ui": {
            "text_speed": "Velocidad del texto",
            // ...
        },
        "narration": {
            "Hello, my name is {{name}}": "Hola, mi nombre es {{name}}"
            // ...
        }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>


# Ren'Py vs Pixi’VN (/start/versus-renpy)





Making a comparison between Ren'Py and Pixi’VN is necessary because Ren'Py is currently the most widely used engine for creating visual novels.

<Callout title="Templates" type="info">
  This comparison was made by the Pixi’VN team, aiming to be unbiased. If you disagree with this comparison or think other features should be compared, feel free to write in the chat below!
</Callout>

**What is Ren'Py?**

Ren'Py is a visual novel engine – used by thousands of creators from around the world – that helps you use words, images, and sounds to tell interactive stories that run on computers and mobile devices. These can be both visual novels and life simulation games.

* Programming language: `Ren'Py language`, a programming language that allows you to develop visual novels quickly, even without much programming knowledge. It is based on Python.
* Canvas library: [`Pygame_sdl2`](https://github.com/renpy/pygame_sdl2) is a reimplementation of the Pygame API using SDL2 and related libraries. While it was originally meant to support multiple applications, it is now mainly used as the technology underlying Ren'Py.
* How does it work: Ren'Py is a complete visual novel engine/framework that takes care of creating a project, executing it, distributing it, and much more.

Programming language [#programming-language]

Ren'Py uses its own language, `Ren'Py language`, which is a superset of Python. You can use Python statements in Ren'Py language.

Pixi’VN uses JavaScript/TypeScript, which are powerful and popular languages. To write the narration, you can use JavaScript/TypeScript or choose one or more narrative languages from those available.

| Programming language      | Ren'Py                                                                                                                                            | Pixi’VN                                                                                                                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ease of learning          | Intended for people who do not know how to program                                                                                                | You can get started quickly using a template, but as you progress and need to integrate new features, you will need to learn some basics of JavaScript/TypeScript, NodeJS, and npm |
| Is it a typed language?   | ❌ (Using Python you can use types, but the Ren'Py compiler does not have type checking. Also, much of the native Ren'Py code does not use types.) | ✅                                                                                                                                                                                  |
| Can you use the debugger? | ❌                                                                                                                                                 | ✅                                                                                                                                                                                  |
| Package/libraries manager | ❌                                                                                                                                                 | npm                                                                                                                                                                                |
| Narrative Language        | Ren'Py language and Python statements                                                                                                             | JavaScript/TypeScript and various narrative languages (including Ren'Py language)                                                                                                  |
| Mini-games implementation | You can use Ren'Py Creator-Defined Displayables (CDD)                                                                                             | You can use PixiJS or install other libraries                                                                                                                                      |
| UI implementation         | You can use Ren'Py screens                                                                                                                        | You can use PixiJS, React, Vue, etc.                                                                                                                                               |
| UI components             | Components provided by Ren'Py, usually based on images                                                                                            | Depending on the UI framework, you can use any component library (e.g., Material-UI, Bootstrap, PixiJS UI, etc.)                                                                   |

Writing the narrative [#writing-the-narrative]

With Ren'Py, to write the narrative, you use the `Ren'Py language`. This language is simple and easy to learn. It is based on Python, and you can use Python statements in Ren'Py language.

With Pixi’VN, you can use JavaScript/TypeScript to write the narration. You can also use various narrative languages (potentially you can integrate any narrative language using <DynamicLink href="/json">PixiVNJson</DynamicLink>).

Example of Ren'Py:

```renpy title="start.rpy"
label start:
    "Hello, world!"
    "This is a Pixi’VN tutorial."
    "I hope you enjoy it!"
```

Example of Pixi’VN:

```typescript title="startLabel.ts"
const startLabel = newLabel("start_label_id", [
    () => narration.dialogue = "Hello, world!",
    () => narration.dialogue = "This is a Pixi’VN tutorial.",
    () => narration.dialogue = "I hope you enjoy it!"
])
```

```ink title="start.ink"
=== start
Hello, world!
This is a Pixi’VN tutorial.
I hope you enjoy it!
->DONE
```

Implementation of minigames [#implementation-of-minigames]

With Ren'Py, for creating minigames with complex mechanics/animations, you need to use [`Creator-Defined Displayables (CDD)`](https://www.renpy.org/doc/html/cdd.html). This is necessary because otherwise you will have performance problems. With CDD you can create/control one or more graphic elements through a render loop.
CDD is not very intuitive and is complicated to use. There are very few examples and few developers using CDD. In fact, most minigames do not have complex logic and animations.

With Pixi’VN, you can use PixiJS to create minigames. PixiJS is a very powerful library that allows you to create complex animations and mechanics. The documentation and examples are detailed, and there are many developers using PixiJS.

You can try some Ren'Py and PixiJS minigames to understand the difference:

* [Ren'Py minigames](https://itch.io/game-assets/free/tag-minigames/tag-renpy)
* [PixiJS minigames](https://github.com/pixijs/open-games)
* [PixiJS tutorials](https://pixijs.com/8.x/tutorials)

UI implementation [#ui-implementation]

With Ren'Py, to create the user interface, you use `screens` and `styles`. The recommended implementation is to draw a series of images and add them inside the canvas through the graphics components. The graphic components are limited and not very intuitive.

With Pixi’VN, in addition to using the components of PixiJS, you can also use systems such as React, Vue, etc., and install component libraries such as Material-UI, Bootstrap, etc. This allows you to create much more complex UI screens with excellent performance.

Performance and project size [#performance-and-project-size]

Performance and project size are important factors to consider when choosing a framework.

**Canvas libraries used:**

* [`Pygame_sdl2`](https://github.com/renpy/pygame_sdl2): This canvas is underperforming. You can test this by inserting lots of moving graphics into Ren'Py.
* PixiJS: It is based on modern systems and has great performance. This can be tested directly from this example:

<PerformanceExample />

**UI performance:**

* Ren'Py's UI is based on canvas components that use images within the project.
* With Pixi’VN you can use HTML and/or JavaScript frameworks, known for their performance and usability, or the canvas. HTML/JavaScript components are not necessarily based on images, which leads to a smaller project size.

**Project size:**

* The entire UI of Ren'Py is based on "physical images", making the project size very large.
* Since Pixi’VN is a library, it does not determine the project size, but if you use [vite](https://vitejs.dev/) or other tools, the project size will be very light.

Distribution on multiple devices [#distribution-on-multiple-devices]

Ren'Py is directly responsible for distributing the game on various devices.

Pixi’VN does not handle distribution. You can use various frameworks (Tauri, Electron, Cordova, etc.) to distribute the project on multiple devices. Pixi’VN provides templates that already include the necessary configurations for distribution.

| Distribution on multiple devices                              | Ren'Py                                                                         | Pixi’VN                                                                                                                                 |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| Ease of use                                                   | **Very simple**. You can use the Ren'Py UI to create the package to distribute | For less experienced users, it **can be difficult** to set up the project for multiple devices. Using templates can simplify this step. |
| Package configurations                                        | Essential                                                                      | Very complete (you can choose if the package should be installed or run without installation)                                           |
| Deployment automations with GitHub Actions or GitLab Pipeline | ❌                                                                              | ✅                                                                                                                                       |
| System notification                                           | ❌                                                                              | ✅                                                                                                                                       |
| Use connected devices (Camera, Flashlight, etc.)              | ❌                                                                              | ✅                                                                                                                                       |
| UI scaling based on device type                               | ✅                                                                              | ✅                                                                                                                                       |
| UI scaling to fit screen size                                 | ❌                                                                              | ✅                                                                                                                                       |
| Windows/Linux/Mac OS                                          | ✅ (using Ren'Py)                                                               | ✅ (using Tauri, Electron, Cordova, etc.)                                                                                                |
| Android/iOS                                                   | ✅ (using Ren'Py)                                                               | ✅ (using Ionic or Cordova)                                                                                                              |
| Web                                                           | ✅ (in beta)                                                                    | ✅ (natively supported)                                                                                                                  |
| Xbox/PlayStation/Nintendo Switch                              | ✅ (using Sen’py)                                                               | Only Xbox with UWP                                                                                                                      |

Development possibilities [#development-possibilities]

Ren'Py is an engine designed only for creating visual novels. Adding complex functionality through Python that goes beyond the development of a normal visual novel is very complicated and is not recommended by the Ren'Py team. It does not have a package/library manager.

Pixi’VN is an [npm](https://www.npmjs.com/) library that allows you to create visual novels. You can also use this library in a project that is not natively a visual novel. [npm](https://www.npmjs.com/) is a package manager for JavaScript and the world's largest software registry.

Longevity and ease of internal development [#longevity-and-ease-of-internal-development]

Ren'Py was born in 2004 and is still used today. It is a very stable and mature project.
Ren'Py, in addition to including the development of its own library for visual novels, also includes the development of `Ren'Py language` and `Pygame_sdl2`. Since Ren'Py also handles the distribution of the project on various devices, it is necessary to keep the system up to date with updates for supported operating systems.

This means that keeping Ren'Py updated is a constant and very complex process that "touches" many types of programming (parsing, graphics, etc.).

Pixi’VN was born in 2024. It is a very young project.
Pixi’VN is only a library that uses PixiJS for the canvas. As well as providing functionality for visual novels, it doesn't handle anything else.

This means that keeping Pixi’VN updated is a very simple process and, once it reaches a stable version, it will not need constant updates to be compatible with the latest devices.

Conclusion [#conclusion]

In conclusion, if you know object-oriented programming and want to create a visual novel with many features, minigames, a very complex UI, etc., you should use Pixi’VN. If you are not a programmer, want to create your visual novel quickly, and are willing to learn knowledge over time that you can reuse later, consider Pixi’VN. If you want a unified framework that takes care of everything without you having to decide which libraries to use, then Pixi’VN is not for you—Ren'Py is a valid option. If you want a no-code framework, currently, neither Ren'Py nor Pixi’VN are for you.


# Why? (/start/why)



The reason why Pixi’VN was born is that the current systems for creating visual novels or 2D RPGs are based on old systems and have many shortcomings.

Pixi’VN combines the development of various 2D games in a single engine, bringing video game development closer to web applications in order to take advantage of their great compatibility and cloud services.

What is Pixi’VN? [#what-is-pixivn]

Pixi’VN is a versatile and powerful 2D game engine based on JavaScript/TypeScript and [PixiJS](https://pixijs.com/).

It provides the following features:

* Narrative management
* 2D rendering
* Functionality to play sounds and music
* Storage to set and get game variables
* Saves the current state of the entire game at each `step`, giving the possibility to go back
* Functionality to save and load the current state of the game

For a quick start, various <DynamicLink href="/start#project-initialization">project templates</DynamicLink> are available. Less experienced developers can use these templates without much knowledge of JavaScript/TypeScript.

You have the option to use various types of narrative languages (in addition to JavaScript/TypeScript). Currently you can use the following:

* <DynamicLink href="/ink">
    *ink*
  </DynamicLink>
* <DynamicLink href="/renpy">
    Ren'Py
  </DynamicLink>

Features of Pixi’VN [#features-of-pixivn]

Its great **versatility** is due to the fact that Pixi’VN is an npm package, not a framework. This means it can be installed in any JavaScript project and integrated with your favorite JavaScript framework (React, Vue, etc.).
You may use the provided functionality for a variety of purposes, from creating a visual novel or other type of 2D game (such as point-and-click adventure, RPGs, etc.), using only the narrative features in a 3D game, displaying an animation on a website, and more.

To be as **lightweight** as possible, it only deals with specific features, allowing and encouraging you to add more with other libraries. There is no need to use heavy IDEs for development; any code editor will do.

It does **not reinvent things** that already exist. Pixi’VN binds together several very popular libraries and provides APIs to interact with them and have full access. It does not invent new programming or narrative languages.


# Assets (/ink/assets)



As explained in more detail <DynamicLink href="/start/assets-management">here</DynamicLink>, initialize the asset matrix at project start and decide when assets should be loaded.

In &#x2A;**ink**&#x2A; you have less control than in JavaScript/TypeScript over how and when to load assets. Pixi’VN provides a single &#x2A;**ink*** command that <DynamicLink href="/start/assets-management#load-assets-before-a-label-starts">loads assets before a `label` starts</DynamicLink>. Use the following syntax:

```ink title="ink"
# {operation} {assets or bundle} {list of URL/path of the image}
```

* `#`: is the hashtag symbol to identify a hashtag command.
* `operation`: the operation to perform. Currently supported:
  * `load`: It loads with await the assets or bundle (`Assets.load` or `Assets.loadBundle`).
  * `lazyload`: It loads the assets or bundle in the background (`Assets.backgroundLoad` or `Assets.backgroundLoadBundle`).
* `assets or bundle`: The type of asset to load. Available types are:
  * `assets`: It loads the assets.
  * `bundle`: It loads the bundle.
* `list of URL/path of the image`: The list of URLs/paths of the images (or other assets) you want to load. If you initialized the <DynamicLink href="/start/assets-management#initialize-the-asset-matrix-at-project-start">asset matrix</DynamicLink>, you can use an asset alias instead of a URL. Note: to write `https://&#x60; in &#x2A;**ink*** you must escape the slashes as `https:\/\/` because `//&#x60; is treated as a comment in &#x2A;**ink***.

<CodeBlockTabs defaultValue="ink/start.ink">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="ink/start.ink">
      ink/start.ink
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="utils/defineAssets.ts">
      utils/defineAssets.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="ink/start.ink">
    ```ink
    === start ===
    # lazyload bundle main_menu start
    # load assets eggHead flowerTop my_video
    # show image eggHead
    # show image flowerTop
    # show video my_video
    # pause
    -> start
    ```
  </CodeBlockTab>

  <CodeBlockTab value="utils/defineAssets.ts">
    ```ts
    import { Assets } from "@drincs/pixi-vn"

    export async function defineAssets() {
        // manifest
        await Assets.init({ manifest });
        // single asset
        Assets.add({ alias: 'eggHead', src: "https://pixijs.com/assets/eggHead.png" })
        Assets.add({ alias: 'flowerTop', src: "https://pixijs.com/assets/flowerTop.png" })
        Assets.add({ alias: "my_video", src: "https://pixijs.com/assets/video.mp4" });
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            // screens
            {
                name: "main_menu",
                assets: [
                    {
                        alias: "background_main_menu",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/main-menu.png",
                    },
                ],
            },
            // labels
            {
                name: "start",
                assets: [
                    {
                        alias: "bg01-hallway",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/bg01-hallway.webp",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>


# Canvas (WebGL/WebGPU) (/ink/canvas)





The ***ink* + Pixi’VN integration** introduces a "# script" that allows you to show, edit, remove, and animate a <DynamicLink href="/start/canvas-components">canvas component</DynamicLink>. To do this, you need to use the following syntax:

```ink title="ink"
# {operation} {component type} {alias} {parameters}
```

* `#`: is the hashtag symbol to identify a hashtag command.
* `operation`: the operation to perform. Currently supported:
  * `show`: Show a canvas component. (Read more [here](#show))
  * `edit`: Edit a canvas component. (Read more [here](#edit))
  * `remove`: Remove a canvas component. (Read more [here](#remove))
  * `pause`: Pause a canvas component. (Read more [here](#pause))
  * `resume`: Resume a canvas component. (Read more [here](#resume))
* `component type`: the component type. Available types:
  * <DynamicLink href="/start/canvas-image">
      `image`
    </DynamicLink>
  * <DynamicLink href="/start/canvas-image-container">
      `imagecontainer`
    </DynamicLink>
  * <DynamicLink href="/start/canvas-video">
      `video`
    </DynamicLink>
  * <DynamicLink href="/start/canvas-text">
      `text`
    </DynamicLink>
* `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component. Use double quotes if the alias contains spaces.
* `parameters&#x60; (Optional): a space-separated list of property/value pairs. If a value contains spaces, wrap it in double quotes. If a value is a object, pass valid JSON and escape the braces for &#x2A;**ink*** (e.g. `\{ "placeholder": "Enter your name", "maxLength": 20 \}`).

<CodeBlockTabs defaultValue="ink/start.ink">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="ink/start.ink">
      ink/start.ink
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="ink/start.ink">
    ```ink
    === start ===
    # show image eggHead x 20 y 20
    # show image flowerTop x 220 y 20 with dissolve
    # show image helmlok x 20 y 220 with movein
    # show image skully x 220 y 220 with zoomin
    # pause
    # move eggHead x 300 y 0
    # rotate flowerTop
    # edit image helmlok alpha 0.5
    # shake skully
    # pause
    # remove image eggHead
    # remove image flowerTop with dissolve duration 2
    # remove image helmlok with moveout
    # remove image skully with zoomout
    # pause
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    { alias: "eggHead", src: "https://pixijs.com/assets/eggHead.png" },
                    { alias: "flowerTop", src: "https://pixijs.com/assets/flowerTop.png" },
                    { alias: "helmlok", src: "https://pixijs.com/assets/helmlok.png" },
                    { alias: "skully", src: "https://pixijs.com/assets/skully.png" },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<CanvasExample />

Components functions [#components-functions]

Show [#show]

You can use the `show` to show a <DynamicLink href="/start/canvas-components">canvas component</DynamicLink&#x3E; in &#x2A;**ink***.

Is raccomended to <DynamicLink href="/start/assets-management#initialize-the-asset-matrix-at-project-start">initialize the asset matrix at project start</DynamicLink> to use the alias of texture in `source`. To do this, you need to use the following syntax:

```ink title="ink"
# show {component type} {alias} {source} {parameters}
```

<Callout type="info">
  To include `https://&#x60; in an ***ink* script** you must escape the slashes like `https:\/\/` because `//&#x60; is treated as a comment in &#x2A;**ink***.
</Callout>

<Callout type="info">
  If you initialize the <DynamicLink href="/start/assets-management#initialize-the-asset-matrix-at-project-start">asset matrix</DynamicLink> at project start, you can use the asset alias as the `source` parameter.
</Callout>

<Callout type="info">
  If omitting the `source` parameter, it defaults to the `alias`.
</Callout>

* `component type`: the component type. Available types:
  * <DynamicLink href="/start/canvas-image">
      `image`
    </DynamicLink>
  * <DynamicLink href="/start/canvas-image-container">
      `imagecontainer`
    </DynamicLink>
  * <DynamicLink href="/start/canvas-video">
      `video`
    </DynamicLink>
  * <DynamicLink href="/start/canvas-text">
      `text`
    </DynamicLink>
* `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component. Use double quotes if the alias contains spaces.
* `source` (Optional): meaning varies by component:
  * `image` and `video`: URL or asset alias for the texture.
  * `text`: the text to display.
  * `imagecontainer`: a list of texture aliases/URLs (e.g. `[url1 url2 url3]`).
* `parameters&#x60; (Optional): a space-separated list of property/value pairs. If a value contains spaces, wrap it in double quotes. If a value is a object, pass valid JSON and escape the braces for &#x2A;**ink*** (e.g. `\{ "placeholder": "Enter your name", "maxLength": 20 \}`). Valid parameters vary by component:
  * `image` and `video`: [`PixiJS.Sprite`](https://pixijs.download/release/docs/scene.Sprite.html) and <DynamicLink href="/start/canvas-position">`properties for positioning`</DynamicLink> properties.
  * `text`: [`PixiJS.Text`](https://pixijs.com/8.x/guides/components/text) and <DynamicLink href="/start/canvas-position">`properties for positioning`</DynamicLink> properties.
  * `imagecontainer`: [`PixiJS.Container`](https://pixijs.com/8.x/guides/components/containers) and <DynamicLink href="/start/canvas-position">`properties for positioning`</DynamicLink> properties.

<Accordions>
  <Accordion title="example" id="example">
    <CodeBlockTabs defaultValue="ink/start.ink">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="ink/start.ink">
          ink/start.ink
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="ink/start.ink">
        ```ink
        === start ===
        # show image eggHead
        # show image "eggHead 2" eggHead xAlign 1 yAlign 1
        # show image flowerTop xAlign 0 yAlign 1 visible true cursor "pointer" alpha 0.5
        # show video my_video xAlign 1 yAlign 0
        # show text hello "Hello, this is a text" xAlign 0.5 yAlign 0.5 style \\\{ "fill": "red", "fontSize": 30 \\\}
        # pause
        -> DONE
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        { alias: "eggHead", src: "https://pixijs.com/assets/eggHead.png" },
                        { alias: "flowerTop", src: "https://pixijs.com/assets/flowerTop.png" },
                        { alias: "my_video", src: "https://pixijs.com/assets/video.mp4" },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ShowComponentExample />
  </Accordion>

  <Accordion title="example_imagecontainer" id="example-imagecontainer">
    <CodeBlockTabs defaultValue="ink/start.ink">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="ink/start.ink">
          ink/start.ink
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="utils/defineAssets.ts">
          utils/defineAssets.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="ink/start.ink">
        ```ink
        === start ===
        # show imagecontainer james [m01-body m01-eyes m01-mouth] xAlign 0.5 yAlign 1
        # show imagecontainer sly [fm01-body fm01-eyes fm01-mouth] xAlign 0.2 yAlign 1 with movein
        # show imagecontainer steph [fm02-body fm02-eyes fm02-mouth] xAlign 0.8 yAlign 1 with dissolve
        # pause
        -> DONE
        ```
      </CodeBlockTab>

      <CodeBlockTab value="utils/defineAssets.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        {
                            alias: "fm01-body",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-body.webp",
                        },
                        {
                            alias: "fm01-eyes",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-eyes-smile.webp",
                        },
                        {
                            alias: "fm01-mouth",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm01/fm01-mouth-smile00.webp",
                        },
                        {
                            alias: "fm02-body",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-body.webp",
                        },
                        {
                            alias: "fm02-eyes",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-eyes-smile.webp",
                        },
                        {
                            alias: "fm02-mouth",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/fm02/fm02-mouth-smile00.webp",
                        },
                        {
                            alias: "m01-body",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-body.webp",
                        },
                        {
                            alias: "m01-eyes",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-eyes-smile.webp",
                        },
                        {
                            alias: "m01-mouth",
                            src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/breakdown/m01/m01-mouth-smile00.webp",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    <ShowContainerExample />
  </Accordion>

  <Accordion title="show_transition" id="show-with-transition">
    If you want to show the canvas component with a <DynamicLink href="/start/canvas-transition">transition</DynamicLink>, you can add into the parameters the `with {transition type}`.

    ```ink title="ink"
    # show {component type} {alias} {source} {parameters} with {transition type} {transition parameters}
    ```

    * `transition type` (Optional): the available transitions are:
      * `dissolve`: The canvas component appears with a <DynamicLink href="/start/canvas-transition#dissolve-transition">dissolve transition</DynamicLink>.
      * `fade`: The canvas component appears with a <DynamicLink href="/start/canvas-transition#fade-transition">fade transition</DynamicLink>.
      * `movein`: The canvas component appears with a <DynamicLink href="/start/canvas-transition#move-inout-transition">movein transition</DynamicLink>.
      * `zoomin`: The canvas component appears with a <DynamicLink href="/start/canvas-transition#zoom-inout-transition">zoomin transition</DynamicLink>.
      * `pushin`: The canvas component appears with a <DynamicLink href="/start/canvas-transition#push-inout-transition">pushin transition</DynamicLink>.
    * `transition parameters` (Optional): a space-separated list of property/value pairs. Corresponds to the `options&#x60; parameter of their Javascript counterpart. If a value contains spaces, wrap it in double quotes. If a value is a object, pass valid JSON and escape the braces for &#x2A;**ink*** (e.g. `\{ "placeholder": "Enter your name", "maxLength": 20 \}`). You can add all the [`motion` options](https://motion.dev/docs/animate#options) and additional parameters you would use in JS/TS.

    <CodeBlockTabs defaultValue="ink/start.ink">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="ink/start.ink">
          ink/start.ink
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="ink/start.ink">
        ```ink
        === start ===
        # show eggHead with dissolve duration 3
        temp durationVar = 3
        # show eggHead eggHead2 with fade duration {durationVar}
        # show flowerTop x 20 y 30 with movein direction left
        # show helmlok x 20 y 30 with zoomin
        # show skully x 20 y 30 with pushin
        -> DONE
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        { alias: "eggHead", src: "https://pixijs.com/assets/eggHead.png" },
                        { alias: "flowerTop", src: "https://pixijs.com/assets/flowerTop.png" },
                        { alias: "my_video", src: "https://pixijs.com/assets/video.mp4" },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>
</Accordions>

Edit [#edit]

You can use the `edit` to edit a <DynamicLink href="/start/canvas-components">canvas component</DynamicLink&#x3E; in &#x2A;**ink***. To do this, you need to use the following syntax:

```ink title="ink"
# edit {component type} {alias} {parameters}
```

* `component type`: the component type. Available types:
  * <DynamicLink href="/start/canvas-image">
      `image`
    </DynamicLink>
  * <DynamicLink href="/start/canvas-image-container">
      `imagecontainer`
    </DynamicLink>
  * <DynamicLink href="/start/canvas-video">
      `video`
    </DynamicLink>
  * <DynamicLink href="/start/canvas-text">
      `text`
    </DynamicLink>
* `parameters&#x60; (Optional): a space-separated list of property/value pairs. If a value contains spaces, wrap it in double quotes. If a value is a object, pass valid JSON and escape the braces for &#x2A;**ink*** (e.g. `\{ "placeholder": "Enter your name", "maxLength": 20 \}`). Valid parameters vary by component:
  * `image` and `video`: [`PixiJS.Sprite`](https://pixijs.download/release/docs/scene.Sprite.html) and <DynamicLink href="/start/canvas-position">`properties for positioning`</DynamicLink> properties.
  * `text`: [`PixiJS.Text`](https://pixijs.com/8.x/guides/components/text) and <DynamicLink href="/start/canvas-position">`properties for positioning`</DynamicLink> properties.
  * `imagecontainer`: [`PixiJS.Container`](https://pixijs.com/8.x/guides/components/containers) and <DynamicLink href="/start/canvas-position">`properties for positioning`</DynamicLink> properties.

```ink title="ink"
# edit image bg position \{ "x": 20, "y": 30 \} visible true cursor "pointer" alpha 0.5 
```

Remove [#remove]

You can use the `remove` to remove a <DynamicLink href="/start/canvas-components">canvas component</DynamicLink&#x3E; in &#x2A;**ink***. To do this, you need to use the following syntax:

```ink title="ink"
# remove {component type} {alias}
```

* `component type`: the component type. Available types:
  * <DynamicLink href="/start/canvas-image">
      `image`
    </DynamicLink>
  * <DynamicLink href="/start/canvas-image-container">
      `imagecontainer`
    </DynamicLink>
  * <DynamicLink href="/start/canvas-video">
      `video`
    </DynamicLink>
  * <DynamicLink href="/start/canvas-text">
      `text`
    </DynamicLink>
* `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component. Use double quotes if the alias contains spaces.

```ink title="ink"
# remove image bg
# remove image "bg 2"
```

<Accordions>
  <Accordion title="remove_transition" id="remove-with-transition">
    If you want to remove the canvas component with a <DynamicLink href="/start/canvas-transition">transition</DynamicLink>, you can add after the alias of the canvas component `with {transition type}`.

    ```ink title="ink"
    # remove {component type} {alias} with {transition type} {transition parameters}
    ```

    * `transition type` (Optional): the available transitions are:
      * `dissolve`: The canvas component appears with a <DynamicLink href="/start/canvas-transition#dissolve-transition">dissolve transition</DynamicLink>.
      * `fade`: The canvas component appears with a <DynamicLink href="/start/canvas-transition#fade-transition">fade transition</DynamicLink>.
      * `movein`: The canvas component appears with a <DynamicLink href="/start/canvas-transition#move-inout-transition">movein transition</DynamicLink>.
      * `zoomin`: The canvas component appears with a <DynamicLink href="/start/canvas-transition#zoom-inout-transition">zoomin transition</DynamicLink>.
      * `pushin`: The canvas component appears with a <DynamicLink href="/start/canvas-transition#push-inout-transition">pushin transition</DynamicLink>.
    * `transition parameters` (Optional): a space-separated list of property/value pairs. Corresponds to the `options&#x60; parameter of their Javascript counterpart. If a value contains spaces, wrap it in double quotes. If a value is a object, pass valid JSON and escape the braces for &#x2A;**ink*** (e.g. `\{ "placeholder": "Enter your name", "maxLength": 20 \}`). You can add all the [`motion` options](https://motion.dev/docs/animate#options) and additional parameters you would use in JS/TS.

    ```ink title="ink"
    # remove image bg with dissolve duration 3
    temp durationVar = 3
    # remove image bg with fade duration {durationVar}
    # remove image bg with moveout
    # remove image bg with zoomout
    # remove image bg with pushout
    ```
  </Accordion>
</Accordions>

Pause and resume [#pause-and-resume]

<CodeBlockTabs defaultValue="ink/start.ink">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="ink/start.ink">
      ink/start.ink
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="ink/start.ink">
    ```ink
    === start ===
    # show video my_video
    Video started
    # pause video my_video
    Video
    Video paused
    # resume video my_video
    Video resumed
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    { alias: "my_video", src: "https://pixijs.com/assets/video.mp4" },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Sandbox template="p3qgjq" entry="/src/ink/start.ink,/src/utils/assets-utility.ts" />

<Accordions>
  <Accordion title="pause" id="pause">
    To pause a video in &#x2A;**ink***, you can use `pause`. To do this, you need to use the following syntax:

    ```ink title="ink"
    # pause video {alias}
    ```

    ```ink title="ink"
    # pause video bg
    # pause video "bg 2"
    ```
  </Accordion>

  <Accordion title="resume" id="resume">
    To resume a video in &#x2A;**ink***, you can use `resume`. To do this, you need to use the following syntax:

    ```ink title="ink"
    # resume video {alias}
    ```

    ```ink title="ink"
    # resume video bg
    # resume video "bg 2"
    ```
  </Accordion>
</Accordions>

Animate [#animate]

You can use the `animate` to use the <DynamicLink href="/start/canvas-motion">animations</DynamicLink&#x3E; in &#x2A;**ink***. To do this, you need to use the following syntax:

```ink title="ink"
# animate {alias} {keyframes} options {parameters}
```

* `alias`: The <DynamicLink href="/start/canvas-alias">alias</DynamicLink> to identify the component. Use double quotes if the alias contains spaces.
* `keyframes&#x60;: a space-separated list of property/value pairs representing the properties to animate and the values to reach. If a value contains spaces, wrap it in double quotes. If a value is a object, pass valid JSON and escape the braces for &#x2A;**ink*** (e.g. `\{ "placeholder": "Enter your name", "maxLength": 20 \}`). Valid parameters vary by component:
  * `image` and `video`: [`PixiJS.Sprite`](https://pixijs.com/8.x/guides/components/sprites) and <DynamicLink href="/start/canvas-position">`properties for positioning`</DynamicLink> properties.
  * `text`: [`PixiJS.Text`](https://pixijs.com/8.x/guides/components/text) and <DynamicLink href="/start/canvas-position">`properties for positioning`</DynamicLink> properties.
  * `imagecontainer`: [`PixiJS.Container`](https://pixijs.com/8.x/guides/components/containers) and <DynamicLink href="/start/canvas-position">`properties for positioning`</DynamicLink> properties.
* `parameters` (Optional): a space-separated list of property/value pairs. Corresponds to the `options&#x60; parameter of their Javascript counterpart. If a value contains spaces, wrap it in double quotes. If a value is a object, pass valid JSON and escape the braces for &#x2A;**ink*** (e.g. `\{ "placeholder": "Enter your name", "maxLength": 20 \}`). You can add all the [`motion` options](https://motion.dev/docs/animate#options) and additional parameters you would use in JS/TS.

Here are some examples:

<Accordions>
  <Accordion title="move" id="move">
    <CodeBlockTabs defaultValue="ink/start.ink">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="ink/start.ink">
          ink/start.ink
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="ink/start.ink">
        ```ink
        === start ===
        # show image alien
        # animate alien xAlign 1 yAlign 0 options ease "easeOut"
        # pause
        # animate alien xAlign 1 yAlign 1 options ease "backOut"
        # pause
        # animate alien xAlign 0 yAlign 1 options ease "circIn"
        # pause
        # animate alien xAlign 0 yAlign 0 options ease "linear"
        # pause
        -> DONE
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        {
                            alias: "alien",
                            src: "https://pixijs.com/assets/eggHead.png",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="rotate" id="rotate">
    <CodeBlockTabs defaultValue="ink/start.ink">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="ink/start.ink">
          ink/start.ink
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="ink/start.ink">
        ```ink
        === start ===
        # show alien
        # animate alien angle 360 options duration 1 type "spring" repeat Infinity repeatDelay 0.2
        # pause
        -> DONE
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        {
                            alias: "alien",
                            src: "https://pixijs.com/assets/eggHead.png",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="fade" id="fade">
    <CodeBlockTabs defaultValue="ink/start.ink">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="ink/start.ink">
          ink/start.ink
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="ink/start.ink">
        ```ink
        === start ===
        # show alien
        # animate alien alpha 0 options ease "linear" duration 1
        # pause
        -> DONE
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        {
                            alias: "alien",
                            src: "https://pixijs.com/assets/eggHead.png",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="zoom" id="zoom">
    <CodeBlockTabs defaultValue="ink/start.ink">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="ink/start.ink">
          ink/start.ink
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="ink/start.ink">
        ```ink
        === start ===
        # show alien
        # animate alien scaleX 0 scaleY 0 options ease "circInOut" duration 1
        # pause
        -> DONE
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        {
                            alias: "alien",
                            src: "https://pixijs.com/assets/eggHead.png",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="mirror" id="mirror">
    <CodeBlockTabs defaultValue="ink/start.ink">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="ink/start.ink">
          ink/start.ink
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="assets/manifest.ts">
          assets/manifest.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="ink/start.ink">
        ```ink
        === start ===
        # show alien
        # animate alien scaleX -1 options duration 1
        # pause
        # animate alien scaleX 1 options duration 1
        # pause
        -> DONE
        ```
      </CodeBlockTab>

      <CodeBlockTab value="assets/manifest.ts">
        ```ts
        import { AssetsManifest } from "@drincs/pixi-vn";

        /**
         * Manifest for the assets used in the game.
         * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
         */
        const manifest: AssetsManifest = {
            bundles: [
                {
                    name: "start",
                    assets: [
                        {
                            alias: "alien",
                            src: "https://pixijs.com/assets/eggHead.png",
                        },
                    ],
                },
            ],
        };
        export default manifest;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>
</Accordions>


# Characters (/ink/character)





Before to read this section, it is recommended to read <DynamicLink href="/start/character#initialize">how to create and use characters in Pixi’VN</DynamicLink>.

Use [#use]

Associate a character with a dialogue [#associate-a-character-with-a-dialogue]

You can associate a character with a dialogue in &#x2A;**ink***. To do this, you need to use the following syntax:

```ink title="ink"
{character_id}: {text}
```

* `character_id`: is the character `id` defined in **JavaScript/TypeScript**.
* `:`: is the separator between the character and the text.
* `text`: is the dialogue text.

<CodeBlockTabs defaultValue="ink/start.ink">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="ink/start.ink">
      ink/start.ink
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="values/characters.ts">
      values/characters.ts
    </CodeBlockTabsTrigger>

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

  <CodeBlockTab value="ink/start.ink">
    ```ink
    === start ===
    mc: Hello, I'm Liam.
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="values/characters.ts">
    ```ts
    import { CharacterBaseModel, RegisteredCharacters } from "@drincs/pixi-vn";

    export const mc = new CharacterBaseModel("mc", {
        name: "Liam",
    });

    RegisteredCharacters.add(mc);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="main.ts">
    ```ts
    import "./values/characters";

    // ...
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<CharacterDialogueExample />

Use character name in dialogues text [#use-character-name-in-dialogues-text]

You can use the character name in dialogues. To do this, you need to use the following syntax:

`[` + `character_id` + `]`

* `[` and `]`: are the delimiters to identify the character.
* `character_id`: is the character `id` defined in **JavaScript/TypeScript**.

<CodeBlockTabs defaultValue="ink/start.ink">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="ink/start.ink">
      ink/start.ink
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="values/characters.ts">
      values/characters.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="ink/start.ink">
    ```ink
    === start ===
    Hello, [mc].
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="values/characters.ts">
    ```ts
    import { CharacterBaseModel, RegisteredCharacters } from "@drincs/pixi-vn";

    export const mc = new CharacterBaseModel("mc", {
        name: "Liam",
    });

    RegisteredCharacters.add(mc);
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<CharacterDialogueTextExample />

To do this, you'll first need to implement the functionality to replace the id with the character's name. To do this, you can use one of the following methods:

<Callout title="Templates" type="info">
  In all templates, this implementation is already included.
</Callout>

<Accordions>
  <Accordion title="i18next_implementation" id="i18next-implementation">
    If you are using [i18next](https://www.i18next.com/) for translation, you can use the following method:

    <CodeBlockTabs defaultValue="utils/ink-utility.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="utils/ink-utility.ts">
          utils/ink-utility.ts
        </CodeBlockTabsTrigger>

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

      <CodeBlockTab value="utils/ink-utility.ts">
        ```ts
        import { onReplaceTextBeforeTranslation } from "@drincs/pixi-vn-ink";

        export function initializeInk() {
            onReplaceTextBeforeTranslation((key) => { // [!code focus]
                return `{{${key}}}`; // [!code focus]
            }); // [!code focus]
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="i18n.ts">
        ```ts
        import { RegisteredCharacters } from "@drincs/pixi-vn";
        import i18n from "i18next";
        import Backend from "i18next-chained-backend";
        import { initReactI18next } from "react-i18next";

        export const useI18n = () => {
            if (!i18n.isInitialized) {
                i18n.use(Backend)
                    .use(initReactI18next)
                    .init({
                        debug: false,
                        fallbackLng: "en",
                        lng: "en",
                        interpolation: {
                            escapeValue: false,
                        },
                        load: "currentOnly",
                        missingInterpolationHandler(_text, value, _options) { // [!code focus]
                            let key = value[1]; // [!code focus]
                            let character = RegisteredCharacters.get(key); // [!code focus]
                            if (character) { // [!code focus]
                                return character.name; // [!code focus]
                            } // [!code focus]
                            return `[${key}]`; // [!code focus]
                        }, // [!code focus]
                    });
            }
        };
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="replacement_implementation" id="replacement-implementation">
    To use the character name in dialogues, you can take advantage of the <DynamicLink href="/ink/replacement">possibility of replacing portions of text</DynamicLink>. For example, you can use the following method:

    ```ts title="utils/ink-utility.ts"
    import { RegisteredCharacters } from "@drincs/pixi-vn";
    import { onReplaceTextAfterTranslation } from "@drincs/pixi-vn-ink";

    export function initializeInk() {
        onReplaceTextAfterTranslation((key) => { // [!code focus]
            let character = RegisteredCharacters.get(key); // [!code focus]
            if (character) { // [!code focus]
                return character.name; // [!code focus]
            } // [!code focus]

            // if return undefined, the system will not replace the character id // [!code focus]
            return undefined; // [!code focus]
        }); // [!code focus]
    }
    ```
  </Accordion>
</Accordions>

Edit [#edit]

You can edit a character's information in &#x2A;**ink***, for example, you can change the character's name. To do this, you need to use the following syntax:

```ink title="ink"
# rename {character_id} {new_name}
```

* `#`: is the hashtag symbol to identify a hashtag command.
* `rename`: is the command to rename a character.
* `character_id`: is the character `id` defined in **JavaScript/TypeScript**.
* `new_name`: is the new name for the character.

<CodeBlockTabs defaultValue="ink/start.ink">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="ink/start.ink">
      ink/start.ink
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="values/characters.ts">
      values/characters.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="ink/start.ink">
    ```ink
    === start ===
    mc: Hello, I'm [mc].
    # request input string
    mc: My name is:
    # rename mc {_input_value_}
    mc: My name is [mc]
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="values/characters.ts">
    ```ts
    import { CharacterBaseModel, RegisteredCharacters } from "@drincs/pixi-vn";

    export const mc = new CharacterBaseModel("mc", {
        name: "Liam",
    });

    RegisteredCharacters.add(mc);
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<CharacterEditExample />

To do this, you'll first need to implement the functionality to rename the character.  To do this, you can use one of the following methods:

<Callout title="Templates" type="info">
  In all templates, this implementation is already included.
</Callout>

<Accordions>
  <Accordion title="custom_hashtag_script_implementation" id="custom-hashtag-script-implementation">
    Using the possibility of <DynamicLink href="/ink/hashtag">customizing hashtag commands</DynamicLink>. For example, you can use the following method:

    ```ts title="utils/ink-utility.ts"
    import { RegisteredCharacters } from "@drincs/pixi-vn";
    import { HashtagCommands } from "@drincs/pixi-vn-ink";

    export function initializeInk() {
        HashtagCommands.add((script, props, convertListStringToObj) => { // [!code focus]
            if (script[0] === "rename" && script.length === 3) { // [!code focus]
                let character = RegisteredCharacters.get(script[1]); // [!code focus]
                if (character) { // [!code focus]
                    character.name = script[2]; // [!code focus]
                } // [!code focus]
                return true; // [!code focus]
            } // [!code focus]
            return false; // [!code focus]
        }); // [!code focus]
    }
    ```
  </Accordion>
</Accordions>

Character emotions [#character-emotions]

You can use the <DynamicLink href="/start/character#character-emotions">character emotions</DynamicLink&#x3E; in &#x2A;**ink***. To do this you just need to use a special ID composed of:

`character_id` + `@` + `emotion`

* `character_id`: is the character `id` defined in **JavaScript/TypeScript**.
* `@`: is the separator between the character and the emotion.
* `emotion`: is the emotion defined in **JavaScript/TypeScript**.

For example:

```ink title="ink"
{character_id}@{emotion}: {text}
```

<CodeBlockTabs defaultValue="ink/start.ink">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="ink/start.ink">
      ink/start.ink
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="values/characters.ts">
      values/characters.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="ink/start.ink">
    ```ink
    === start ===
    mc@happy: Hi, I'm Liam. I'm very happy today.
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="values/characters.ts">
    ```ts
    import { CharacterBaseModel, RegisteredCharacters } from "@drincs/pixi-vn";

    export const mc = new CharacterBaseModel("mc", {
      name: "Liam",
    });

    export const mcHappy = new CharacterBaseModel(
      { id: "mc", emotion: "happy" },
      {
        name: "Liam happy",
      }
    );

    RegisteredCharacters.add([mc, mcHappy]);
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<CharacterEmotionsExample />


# Choice menus (/ink/choices)



<Callout>
  The ***ink* + Pixi’VN integration** supports native *ink* choices without introducing new choice types. For full details on choice syntax and behavior, refer to the [official ink documentation](https://www.inklestudios.com/ink/).
</Callout>

You can ask the player to make a choice in *ink* using a list of `*` or `+` bullets, followed by the choice text. The choice text is displayed to the player and they select one option to continue the story.

* `*` indicates a choice that can only be made once.
* `+` indicates a choice that can be made multiple times (sticky choice).

```ink title="ink"
=== start ===
* Go to Paris
  You decide to visit Paris. -> visit_paris
+ Go to London -> visit_london
* Stay at home
  You decide to stay at home. -> DONE
```

Suppressing choice text [#suppressing-choice-text]

By default, the text of a chosen option is printed again in the output. If the visible choice text is given in square brackets, that text is shown only in the choice menu and not printed in the subsequent output.

```ink title="ink"
=== start ===
Hello world!
* [Hello back!]
 Nice to hear from you!
```

The square brackets split the option content: what appears before is printed in both the menu and the output; what is inside the brackets appears only in the menu; what follows appears only in the output. This is useful for dialogue choices:

```ink title="ink"
=== start ===
"What's that?" my master asked.
* "I am somewhat tired[."]," I repeated.
 "Really," he responded. "How deleterious."
```

Varying choices [#varying-choices]

Fallback choices [#fallback-choices]

Fallback choices are never shown to the player but are automatically chosen by the engine if no other options are available.

A fallback choice is simply a choice without visible choice text:

```ink title="ink"
* -> out_of_options
```

```ink title="ink"
=== start ===
 You search desperately for a friendly face in the crowd.
 * The woman in the hat[?] pushes you roughly aside. -> find_help
 * The man with the briefcase[?] looks disgusted as you stumble past him. -> find_help
 * -> // fallback
  But it is too late: you collapse onto the station platform. This is the end.
  -> END
```

Conditional choices [#conditional-choices]

You can enable or disable choices with conditions. The simplest test is whether the player has previously visited a particular `knot` or `stitch`.

```ink title="ink"
* { not visit_paris }  [Go to Paris] -> visit_paris
+ { visit_paris }      [Return to Paris] -> visit_paris
* { visit_paris.met_estelle } [Telephone Mme Estelle] -> phone_estelle
```

Note: the test `knot_name` is true if any `stitch` inside that knot has been visited. Conditionals do not override the once-only behaviour of `*` options — use `+` for repeatable options.


# Custom hashtag command (/ink/hashtag)



***ink*** gives the ability to use the `#` character to define custom hashtag commands (or *tags*). Pixi’VN uses this feature to add custom functionality to the ink script, for example, to interact with the canvas.

Pixi’VN gives the developer the ability to intercept the event that parses the scripts # to add custom functionality. This is done through the `HashtagCommands.add` function.

The `HashtagCommands.add` function receives a callback function that will be called whenever a hashtag command is found in the ink script. The callback function returns a boolean or a string. The return value will be used to determine if the script was processed.

* If it is not returned or returns `false`, the script will be processed by the default functionality of Pixi’VN.
* If it returns `true`, the script will not be processed by the default functionality of Pixi’VN.
* If it returns a string, the string will be used as the new hashtag command. For example, if you want to add a feature that shows the image linked to a character `# show character alice xAlign 0.8 yAlign 1 with dissolve`, you can return `# show imagecontainer alice [alice-body alice-eyes alice-mouth] xAlign 0.8 yAlign 1 with dissolve` for leverage the <DynamicLink href="/ink/canvas#show-a-image-container-in-ink">existing functionality to add a container</DynamicLink>.

The callback function receives two parameters:

* `script`: an array with the hashtag command split by spaces. For add a space in a string, you need to use `""`. For example, the Hashtag-Script `# command "Hello World"` will be split into `["command", "Hello World"]`.
* `convertListStringToObj`: a function that receives an array of strings and returns an object. This function is used to convert a list of strings into an object. For example, the array `["prop1", "value 1", "prop2", "value 2"]` will be converted to `{prop1: "value 1", prop2: "value 2"}`.

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

    <CodeBlockTabsTrigger value="ink/start.ink">
      ink/start.ink
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="main.ts">
    ```ts
    import { HashtagCommands } from '@drincs/pixi-vn-ink'

    HashtagCommands.add((script, convertListStringToObj) => {
        // script: ["navigate", "scene_name", "relative", "path"]
        if (script[0] === "navigate" && script.length > 1) {
            let prop = undefined
            if (script.length > 2) {
                // prop: {relative: "path"}
                prop = convertListStringToObj(script.slice(2))
            }
            navigateTo(script[1], prop)
            return true
        }
        return false
    })
    ```
  </CodeBlockTab>

  <CodeBlockTab value="ink/start.ink">
    ```ink
    === start ===
    # navigate /game relative path
    -> DONE
    ```
  </CodeBlockTab>
</CodeBlockTabs>


# ink language integration (/ink)





Pixi’VN lets you write interactive narratives using &#x2A;**ink***, a scripting language designed for branching stories.

**What is *ink*?*&#x2A; &#x2A;**ink*** is a simple scripting language for interactive stories, used in games like 80 Days, Heaven's Vault, and Sorcery! Learn more on the [*ink* website](https://www.inklestudios.com/ink/).

The ***ink* + Pixi’VN integration** uses [inkjs](https://github.com/inkle/inkjs) and <DynamicLink href="/json">PixiVNJson</DynamicLink&#x3E; to parse ***ink* code*&#x2A; and generate JSON that Pixi’VN can interpret. This means JavaScript/TypeScript and &#x2A;**ink**&#x2A; share the same storage and canvas, and you can launch &#x2A;**ink*** `knots` (or `labels&#x60;) from JavaScript/TypeScript and vice versa. You get the best of both worlds: write narration in &#x2A;**ink***, and use JavaScript/TypeScript for minigames or advanced animations.

```ink title="ink/start.ink"
=== start ===
We arrived into London at 9.45pm exactly.

* "There is not a moment to lose!"[] I declared.
 -> hurry_outside

* "Monsieur, let us savour this moment!"[] I declared.
 My master clouted me firmly around the head and dragged me out of the door.
 -> dragged_outside

* [We hurried home] -> hurry_outside

=== hurry_outside ===
We hurried home to Savile Row -> as_fast_as_we_could

=== dragged_outside ===
He insisted that we hurried home to Savile Row
-> as_fast_as_we_could

=== as_fast_as_we_could ===
<> as fast as we could.
-> start
```

<InkExample />

Why? [#why]

Writing narrative directly in **JavaScript/TypeScript*&#x2A; can be slow and complex, especially for beginners. &#x2A;**ink*** is much easier to learn and write.

New developers can start with an <DynamicLink href="/start#project-initialization">*ink* template</DynamicLink>, then gradually learn JavaScript/TypeScript for advanced features.

Installation [#installation]

<Callout title="Templates" type="info">
  Starting a new Pixi’VN project? Use a <DynamicLink href="/start#project-initialization">template</DynamicLink> that already includes *ink*.
</Callout>

To install the *ink* package in an existing JavaScript project, use one of the following commands:

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

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

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

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

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

  <CodeBlockTab value="npm">
    ```sh
    npm install @drincs/pixi-vn @drincs/pixi-vn-ink
    ```
  </CodeBlockTab>

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

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

  <CodeBlockTab value="bun">
    ```sh
    bun add @drincs/pixi-vn @drincs/pixi-vn-ink
    ```
  </CodeBlockTab>

  <CodeBlockTab value="deno">
    ```sh
    deno install npm:@drincs/pixi-vn npm:@drincs/pixi-vn-ink
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Initialize [#initialize]

After installing, use `importInkText()&#x60; to load your ***ink* script**:

```typescript title="main.ts"
import { importInkText } from '@drincs/pixi-vn-ink'

const inkText = `
=== start ===
Hello
-> END
`

importInkText([inkText, ...])
```

Now you can run an &#x2A;**ink* `knot`** (or `label`) using <DynamicLink href="/start/labels#run-a-label">Pixi’VN functions</DynamicLink>:

```typescript title="main.ts"
import { narration } from '@drincs/pixi-vn'

narration.call(`start`, {})
```

<Accordions>
  <Accordion title="import_ink_files" id="import-ink-files">
    <Callout type="info">
      This guide uses [Vite](https://vitejs.dev/), but the same logic applies elsewhere.
    </Callout>

    To import `.ink` files, you need to configure your project to handle them as text files.

    Below are the steps to do this:

    * Declare the `*.ink` module in `ink.d.ts`.
    * Add `.ink` to `assetsInclude` in `vite.config.ts`.
    * Import the file with `?raw` to get its text content.

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

        <CodeBlockTabsTrigger value="vite.config.ts">
          vite.config.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="ink.d.ts">
          ink.d.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="main.ts">
        ```ts
        import { importInkText } from '@drincs/pixi-vn-ink'
        import startLabel from './ink/start.ink?raw'

        importInkText([startLabel, ...])
        ```
      </CodeBlockTab>

      <CodeBlockTab value="vite.config.ts">
        ```ts
        export default defineConfig({
          // ...
          assetsInclude: ['**/*.ink'],
        })
        ```
      </CodeBlockTab>

      <CodeBlockTab value="ink.d.ts">
        ```ts
        declare module '*.ink' {
            const value: string
            export default value
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="import_ink_folder" id="import-ink-folder">
    <Callout type="info">
      This guide uses [Vite](https://vitejs.dev/), but the same logic applies elsewhere.
    </Callout>

    To import multiple `.ink` files, use `import.meta.glob`:

    <CodeBlockTabs defaultValue="utils/ink-utility.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="utils/ink-utility.ts">
          utils/ink-utility.ts
        </CodeBlockTabsTrigger>

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

      <CodeBlockTab value="utils/ink-utility.ts">
        ```ts
        import { convertInkText, importInkText } from "@drincs/pixi-vn-ink";

        async function getInkText() {
            const files = import.meta.glob<string>("../ink/*.ink", { query: "?raw", import: "default" });
            return await Promise.all(
                Object.values(files).map(async (importFile) => {
                    return await importFile();
                })
            );
        }

        export async function importAllInkLabels() {
            let fileEntries = await getInkText();
            await importInkText(fileEntries);
        }

        export async function convertInkToJson() {
            let fileEntries = await getInkText();
            return await Promise.all(fileEntries.map((data) => convertInkText(data)));
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="vite.config.ts">
        ```ts
        export default defineConfig({
          // ...
          assetsInclude: ['**/*.ink'],
        })
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="vite_js_plugin" id="vite-plugin">
    For a better developer experience, use the Vite plugin:

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

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

        <CodeBlockTabsTrigger value="utils/ink-utility.ts">
          utils/ink-utility.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

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

      <CodeBlockTab value="main.ts">
        ```ts
        import { setupInkHmrListener } from '@drincs/pixi-vn-ink/vite-listener'

        setupInkHmrListener()
        ```
      </CodeBlockTab>

      <CodeBlockTab value="utils/ink-utility.ts">
        ```ts
        async function getInkText() {
            const files = import.meta.glob<string>("../ink/*.ink", { eager: true, import: "default" });
            return await Promise.all(
                Object.values(files).map(async (importFile) => {
                    return importFile;
                })
            );
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>
</Accordions>

Upcoming features [#upcoming-features]

These features are in development.

<Callout type="info">
  If you are interested, feel free to write in the chat below!
</Callout>

* [Functions and Game Queries](https://github.com/inkle/ink/blob/master/Documentation/WritingWithInk.md#9-game-queries-and-functions) ([#11](https://github.com/DRincs-Productions/pixi-vn-ink/issues/11)):
  * [User-created functions](https://github.com/inkle/ink/blob/master/Documentation/WritingWithInk.md#5-functions) ([#32](https://github.com/DRincs-Productions/pixi-vn-ink/issues/32))
  * `CHOICE_COUNT()`
  * `TURNS()`
  * `TURNS_SINCE()`
  * `SEED_RANDOM()`
* [`LIST`](https://github.com/inkle/ink/blob/master/Documentation/WritingWithInk.md#1-basic-lists) ([#15](https://github.com/DRincs-Productions/pixi-vn-ink/issues/15))
* [`Tunnels`](https://github.com/inkle/ink/blob/master/Documentation/WritingWithInk.md#1-tunnels) ([#38](https://github.com/DRincs-Productions/pixi-vn-ink/issues/38))

Syntax ignored by Pixi’VN [#syntax-ignored-by-pixivn]

Some *ink&#x2A; syntax is ignored by Pixi’VN. You can use these in your ***ink* script** (e.g., for testing in Inky editor), but Pixi’VN will ignore them.

INCLUDE [#include]

`INCLUDE` is an *ink* statement to include another *ink* file. In Pixi’VN, you should use `importInkText()` to load multiple *ink* files instead, so `INCLUDE` is ignored.

Narration outside the `knots` [#narration-outside-the-knots]

Narration outside the `knots` (or `labels`) is ignored, except for variables.

For example:

```ink title="ink"
VAR my_var = false // ✅ This will be handled (because it is a variable)
Hello // ❌ This will be ignored  [!code warning]
-> start // ❌ This will be ignored [!code warning]
=== start === // ✅ This will be handled
My name is John // ✅ This will be handled
-> DONE // ✅ This will be handled
```

Other features [#other-features]

<Accordions>
  <Accordion title="ink_differences" id="ink-differences">
    * Since "Threads" are not supported by pixi-vn, the `<-` symbol corresponds to <DynamicLink href="/ink/labels#call">calling a knot</DynamicLink>.

    * in this case:

      ```ink title="ink"
      { shuffle:
        -  2 of Diamonds.
          'You lose this time!' crowed the croupier.
      }
      ```

      **In native *ink***, you will see two different dialogues, the first one will be `2 of Diamonds.` and the second one will be `'You lose this time!' crowed the croupier.`.

      **In Pixi’VN *ink***, you will not see two different dialogues, but the following dialogue: `2 of Diamonds.\n\n'You lose this time!' crowed the croupier.`. In <DynamicLink href="/ink/markup#markdown-on-ink">Markdown</DynamicLink> it will be displayed like this:

      ```txt
      2 of Diamonds.
      'You lose this time!' crowed the croupier.
      ```

    * if a `weave` (in following example `shove`) is attached to a one time choice, and it is opened with `-> shove` it will not invalidate the one time choice. To invalidate it you will have to select the choice as usual.

      Here is an example:

      ```ink title="ink"
      -> start
      === start ===
      * [1] -> shove
      * (shove) [2] 2
      * {shove} [3] -> END
      -  -> start
      -> DONE
      ```

      In case you take choice `1`, the second time it will be opened `start`:

      * if you use &#x2A;*native *ink***, you will only be able to choose choice `3`. The choice `2` is hidden because being "one time" &#x2A;*native *ink*** will know that you have already made this decision with `-> shove`.
      * if you use &#x2A;*Pixi’VN *ink***, you will be able to choose choice `2` or `3`. The choice `2` is not hidden because &#x2A;*Pixi’VN *ink*** doesn't know that `shove` is paired with a choice.

      To get the same logic as `start` both in &#x2A;*native *ink*** and &#x2A;*Pixi’VN *ink*** you will have to write the following code:

      ```ink title="ink"
      -> start
      === start ===
      * [1] -> shove
      * (shove) {!shove} [2] 2
      * {shove} [3] -> END
      -  -> start
      -> DONE
      ```
  </Accordion>
</Accordions>


# Inky (/ink/inky)





<Callout title="VS Code" type="warn">
  If you are using VS Code, consider installing the [Ink extension](https://marketplace.visualstudio.com/items?itemName=drincs-productions.pixi-vn-ink-vscode) for syntax highlighting and basic support for ink files. It has a setting to put the engine, so you can set it to `pixi-vn` to avoid warnings for Pixi’VN-specific features.
</Callout>

**Inky** is the official editor for *ink* scripts, developed by Inkle (the creators of *ink*). Download it from [the official site](https://www.inklestudios.com/ink/).

<img alt="Inky" src="__img0" />

Why? [#why]

Writing and testing your narrative in Inky is much faster than running your own web project. Inky gives you a clear overview of all branching paths and story logic.

<Callout type="info">
  Pixi’VN-specific features (such as character sprites, backgrounds, music, etc.) are ignored in Inky.
</Callout>

To use Inky, create a file named `main.ink` in your project and include the ink file you want to run. Then open `main.ink` in Inky.

```ink title="main.ink"
INCLUDE ink/start.ink
-> start
```


# Input prompt (/ink/input)





The ***ink* + Pixi’VN integration** introduces a "# script" that allows you to request an <DynamicLink href="/start/input">input prompt</DynamicLink> from the user. To do this, you need to use the following syntax:

```ink title="ink"
# {operation} input {parameters}
```

* `#`: is the hashtag symbol to identify a hashtag command.
* `operation`: the operation for the input prompt. Currently supported:
  * `request`: request an input prompt.
* `input`: keyword indicating an input request.
* `parameters` (Optional): a space-separated list of property/value pairs. If a value contains spaces, wrap it in double quotes.

Common `parameters`:

* `type` (Optional): a string identifying the kind of input (e.g., `string`, `number`, `html textarea`).
* `default` (Optional): the default value to display in the input field.

<Callout>
  The entered value is saved in storage under the system key `_input_value_`, so you can reference `{ _input_value_ }` in your ink content.
</Callout>

For example:

```ink title="ink"
=== start ===
Hello, 
# request input type string // [!code focus]
<>what is your name?
My name is { _input_value_ } // [!code focus]
# request input type number default 18 // [!code focus]
How old are you?
I am { _input_value_ } years old // [!code focus]
# request input type "html textarea" // [!code focus]
Describe who you are:
{ _input_value_ } // [!code focus]
Restart
-> DONE
```

<InputExample />


# Knots (/ink/labels)





What is a &#x2A;*`knot`**? As explained in the [official documentation](https://www.inklestudios.com/ink/web-tutorial/), the story is comprised of multiple linked sections which we call `knots&#x60; in ***ink* terminology**. The start of a `knot&#x60; is indicated in &#x2A;**ink*** using at least two equals signs the left hand side `knot`'s name, and optionally on the right too (so for example `=== london ===`).

Are there differences between `label` and `knot`? No, they are the same thing. In Pixi’VN, when you create a `knot&#x60; with &#x2A;**ink***, a `label` will be created internally and saved in the registry.

Run a knot [#run-a-knot]

To run a `knot` you can use the following methods:

<Accordions>
  <Accordion title="ink_jump" id="jump">
    You can execute a `knot` using the `->` symbol. It corresponds to the <DynamicLink href="/start/labels#jump-to-a-label">`jump` functionality</DynamicLink> in the Pixi’VN library.

    Write the `->` symbol followed by the name of the `knot`, for example:

    ```ink title="ink"
    === start ===
    Start
    -> after // [!code focus]

    === after ===
    After
    End
    -> DONE
    ```

    <NativeJumpExample />
  </Accordion>

  <Accordion title="ink_call" id="call">
    You can execute a `knot` using the `->` symbol. It corresponds to the <DynamicLink href="/start/labels#call-to-a-label">`call` functionality</DynamicLink> in the Pixi’VN library.

    Write the `<-` symbol followed by the name of the `knot`, for example:

    ```ink title="ink"
    == start ==
    I had a headache; threading is hard to get your head around.
    <- conversation // [!code focus]
    <- walking // [!code focus]


    == conversation ==
    It was a tense moment for Monty and me.
     * "What did you have for lunch today?"[] I asked.
        "Spam and eggs," he replied.
     * "Nice weather, we're having,"[] I said.
        "I've seen better," he replied.
     - -> house

    == walking ==
    We continued to walk down the dusty road.
     * [Continue walking]
        -> house

    == house ==
    Before long, we arrived at his house.
    -> DONE
    ```

    <NativeCallExample />
  </Accordion>
</Accordions>


# Markup language and CSS (/ink/markup)





The ***ink* + Pixi’VN integration** provides some additional features to facilitate the use of components that introduce a <DynamicLink href="/start/markup-markdown">Markup</DynamicLink> in the text.

New Lines [#new-lines]

To create a new line, you can use the escape character `\\n`.

<Callout>
  In our case, since we use Markdown to display the line break, we will need two `\\n\\n`.
</Callout>

For example:

```ink title="ink"
=== start ===
Hello, this is a test. \\n\\n This is a new line.
```

<NewLinesExample />

Markdown [#markdown]

On Pixi’VN it is recommended to use Markdown to add style to your text. If you have <DynamicLink href="/start/markup-markdown">implemented Markdown in your project</DynamicLink&#x3E; then you will be able to use Markdown syntax to style your text in &#x2A;**ink***.

To do this you need to keep in mind that many symbols of Markdown syntax are also used by ***ink* syntax**, such as: `#`, `*`, `/`, `~`, `-`, `|` etc. To avoid conflicts you can use the escape character `\` before the Markdown symbol.

For example:

```ink title="ink"
Hello, this is some *italic* text and this is some **bold** text.
```

<MarkdownExample />

<CodeBlockTabs defaultValue="On ink">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="On ink">
      On ink
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="On Markdown">
      On Markdown
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="On ink">
    ```ink
    \# Markdown Test \\n<>
    Hello, this is a test of the markdown parser. Pixi’VN does not manage markdown, but you can implement a markdown parser to display text with markdown syntax. \\n<>
    For example in React, you can use the library [react-markdown](https:\/\/www.npmjs.com/package/react-markdown). \\n<>
    \#\# Bold Text \\n<>
    \**This is bold text.** \\n<>
    \#\# Italic Text \\n<>
    \*This is italic text.* \\n<>
    \#\# Delete Text \\n<>
    \~~This is deleted text.~~ \\n<>
    \#\# Link Test \\n<>
    [Link to Google](https:\/\/www.google.com) \\n<>
    \#\# H2 Test \\n<>
    \#\#\# H3 Test \\n<>
    \#\#\#\# H4 Test \\n<>
    \#\# Code Test \\n<>
    \`Hello World\` \\n<>
    \`\`\`js \\n<>
    console.log("Hello World") \\n<>
    \`\`\` \\n<>
    \#\# List Test \\n<>
    \- Item 1 \\n<>
    \* Item 2 \\n<>
    \- [x] Item 3 \\n<>
    \#\# Table Test \\n<>
    \| Header 1 \| Header 2 \| \\n<>
    \| -------- \| -------- \| \\n<>
    \| Cell 1   \| Cell 2   \| \\n<>
    \#\# Separator Test \\n<>
    \*\*\* \\n<>
    Footer
    ```
  </CodeBlockTab>

  <CodeBlockTab value="On Markdown">
    ```markdown
    # Markdown Test

    Hello, this is a test of the markdown parser. Pixi’VN does not manage markdown, but you can implement a markdown parser to display text with markdown syntax.

    For example in React, you can use the library [react-markdown](https://www.npmjs.com/package/react-markdown).

    ## Bold Text

    **This is bold text.**

    ## Italic Text

    *This is italic text.*

    ## Delete Text

    ~~This is deleted text.~~

    ## Link Test

    [Link to Google](https://www.google.com)

    ## H2 Test

    ### H3 Test

    #### H4 Test
     
    ## Code Test

    \`Hello World\`

    \`\`\`js
    console.log("Hello World")
    \`\`\`

    ## List Test

    - Item 1
    * Item 2
    - [x] Item 3

    ## Table Test

    | Header 1 | Header 2 |
    | -------- | -------- |
    | Cell 1   | Cell 2   |

    ## Separator Test

    ***
    Footer
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Markdown2Example />

CSS [#css]

You can also use inline CSS to format text using HTML.

For example:

```ink title="ink"
<span style="color:blue">some *blue* text</span>.
<span style="color:red">some *red* text</span>.
<span style="color:green">some *green* text</span>.
```

<CSSExample />


# Other narrative features (/ink/other-narrative-features)





Pause [#pause]

After executing a "# script", the system performs a <DynamicLink href="/start/labels-flow#continue">`continue`</DynamicLink> to move to the next `step`. For example, in this case you will see the image and the dialogue text.

```ink title="ink"
=== start ===
# show image alien eggHead
Hello, world!
-> DONE
```

You can use `# pause` to stop progression to the next `step` and clear the dialogue text until the flow resumes. This is useful when you need to display an image or change state without showing any dialogue.

The syntax is:

```ink title="ink"
# pause
```

<CodeBlockTabs defaultValue="ink/start.ink">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="ink/start.ink">
      ink/start.ink
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="ink/start.ink">
    ```ink
    === start ===
    # show image alien eggHead
    # pause
    Hello, world!
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "start",
                assets: [
                    {
                        alias: "eggHead",
                        src: "https://pixijs.com/assets/eggHead.png",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<PauseExample />

Continue [#continue]

Normally, when a choice is presented after dialogue the narration uses two `steps`: the first shows only the dialogue, and the second shows the dialogue plus the choices.

```ink title="ink"
=== start ===
Who are we going to rescue: the kitten or the wizard?
* [workplace_midground_kitten] 
    -> END
* [workplace_midground_wizard]
    -> END
```

To present the dialogue and the choices in a single `step`, append `<># continue` to the dialogue line. This avoids an extra `step`.

```ink title="ink"
=== start ===
Who are we going to rescue: the kitten or the wizard?<># continue
* [workplace_midground_kitten] 
    -> END
* [workplace_midground_wizard]
    -> END
```

<ContinueExample />


# Text replacement (/ink/replacement)



In &#x2A;*native *ink*** it is possible to inject variables in the text as in the following example `Hello, {name}`. But in case you need to use a property of an object that is in the storage or if you want to use the value of a JS/TS function, you cannot use the following syntax `{ key }`.

In &#x2A;*Pixi’VN *ink*** you can use the following syntax to replace the text:

```ink title="ink"
What do you want, [alice]?
* Talk to \[bob\]
```

In this case Pixi’VN checks if there is a value linked to the keys `alice` and `bob`. If there is a value linked to the key `alice`, the text `[alice]` will be replaced by the value, same for the key `bob`.

To assign a value to a key you can use the following 2 methods:

Replace after translation [#replace-after-translation]

You can override the function `onReplaceTextAfterTranslation` to assign a value to a key. This function is called after the <DynamicLink href="/ink/translate">translation</DynamicLink> of the text and have how parameter the key to replace and return the value to replace or `undefined` if the key does not need to be replaced (so the key will be displayed with the brackets `[key]`).

```ts
import { onReplaceTextAfterTranslation } from '@drincs/pixi-vn-ink'
import { getCharacterById } from "@drincs/pixi-vn";

onReplaceTextAfterTranslation((key) => {
    if (key === 'bob') {
        return 'Bob'
    }

    let character = getCharacterById(key)
    if (character) {
        return character.name
    }

    // if return undefined, the system will not replace the character id
    return undefined
})
```

Replace before translation [#replace-before-translation]

You can override the function `onReplaceTextBeforeTranslation` to add a script that can be interpreted by the <DynamicLink href="/ink/translate">translation library</DynamicLink> used (for example [i18next](https://www.i18next.com/)).

```ts
import { onReplaceTextBeforeTranslation, onInkTranslate } from '@drincs/pixi-vn-ink'
import { useTranslation } from "react-i18next";
import { bob } from "../values/characters"

const { t } = useTranslation(["narration"]);

onInkTranslate((text) => {
    return t(text)
})

onReplaceTextBeforeTranslation((key) => {
    return `{{${key}}}`
})

i18n.init({
    debug: false,
    fallbackLng: 'en',
    // ...
    missingInterpolationHandler(_text, value, _options) {
        let key = value[1]
        if (key === 'bob') {
            return 'Bob'
        }

        let character = getCharacterById(key)
        if (character) {
            return character.name
        }

        return `[${key}]`
    },
});
```


# Sounds and music (/ink/sound)





The ***ink* + Pixi’VN integration** introduces a "# script" that allows you to use the <DynamicLink href="/start/sound">sounds and music</DynamicLink>. To do this, you need to use the following syntax:

```ink title="ink"
# {operation} {component type} {alias} {parameters}
```

* `#`: is the hashtag symbol to identify a hashtag command.
* `operation`: the operation to perform. Currently supported:
  * `play`: Play a sound. (Read more [here](#play))
  * `pause`: Pause a sound. (Read more [here](#pause-and-resume))
  * `resume`: Resume a sound. (Read more [here](#pause-and-resume))
  * `stop`: Stop a sound. (Read more [here](#stop))
  * `edit`: Edit a sound. (Read more [here](#edit))
* `component type`: the component type. Available types:
  * `sound`: to play, pause, resume, stop or edit a sound.
  * `channel`: to run an operation on a channel.
* `alias`: The alias to identify the sound. Use double quotes if the alias contains spaces.
* `parameters&#x60; (Optional): a space-separated list of property/value pairs. If a value contains spaces, wrap it in double quotes. If a value is a object, pass valid JSON and escape the braces for &#x2A;**ink*** (e.g. `\{ "placeholder": "Enter your name", "maxLength": 20 \}`).

<CodeBlockTabs defaultValue="ink/start.ink">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="ink/start.ink">
      ink/start.ink
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="ink/start.ink">
    ```ink
    # play sound sfx_whoosh delay 0.1
    # play sound bgm_cheerful loop true channel bgm
    Hello, I'm a cheerful background music that will loop forever until you stop me.
    # pause sound bgm_cheerful
    I'm paused, but I can be resumed.
    # resume sound bgm_cheerful
    I'm back!
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "audio",
                assets: [
                    {
                        alias: "bgm_cheerful",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/audio/bgm_cheerful.wav",
                    },
                    {
                        alias: "sfx_whoosh",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/audio/sfx_whoosh.wav",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<SoundExample />

Play [#play]

You can use the `play` to <DynamicLink href="/start/sound#play">play</DynamicLink&#x3E; a sound in &#x2A;**ink***. To do this, you need to use the following syntax:

```ink title="ink"
# play sound {alias} {source} {parameters}
```

* `[parameters] (Optional)`: In the `parameters` you must include the properties of `SoundPlayOptions` that you want to set. The `parameters` must be set as follows: `parameterName` + `SPACE` + `value`. If the `value` is a string and includes spaces, you must use double quotes.

<CodeBlockTabs defaultValue="ink/start.ink">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="ink/start.ink">
      ink/start.ink
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="assets/manifest.ts">
      assets/manifest.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="ink/start.ink">
    ```ink
    # play sound sfx_whoosh
    Now the sfx_whoosh is singing.
    # play sound sfx_whoosh volume 100
    Now the sfx_whoosh is singing louder.
    ```
  </CodeBlockTab>

  <CodeBlockTab value="assets/manifest.ts">
    ```ts
    import { AssetsManifest } from "@drincs/pixi-vn";

    /**
     * Manifest for the assets used in the game.
     * You can read more about the manifest here: https://pixijs.com/8.x/guides/components/assets#loading-multiple-assets
     */
    const manifest: AssetsManifest = {
        bundles: [
            {
                name: "audio",
                assets: [
                    {
                        alias: "bgm_cheerful",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/audio/bgm_cheerful.wav",
                    },
                    {
                        alias: "sfx_whoosh",
                        src: "https://raw.githubusercontent.com/DRincs-Productions/pixi-vn-bucket/refs/heads/main/audio/sfx_whoosh.wav",
                    },
                ],
            },
        ],
    };
    export default manifest;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Pause and resume [#pause-and-resume]

To <DynamicLink href="/start/sound#pause-and-resume">pause</DynamicLink&#x3E; a sound or a channel in &#x2A;**ink***, you can use the `pause` operation. To do this, you need to use the following syntax:

```ink title="ink"
# pause {component type} {alias}
```

To <DynamicLink href="/start/sound#pause-and-resume">resume</DynamicLink&#x3E; a sound or a channel in &#x2A;**ink***, you can use the `resume` operation. To do this, you need to use the following syntax:

```ink title="ink"
# resume {component type} {alias}
```

To pause or resume all sounds, you can use the following syntax:

```ink title="ink"
# pause all sounds
# resume all sounds
```

Edit [#edit]

To <DynamicLink href="/start/sound#edit">edit</DynamicLink&#x3E; a sound in &#x2A;**ink***, you can use the `edit` operation. To do this, you need to use the following syntax:

```ink title="ink"
# edit sound {alias} {parameters}
```

```ink title="ink"
# edit sound bgm_cheerful volume 50
# edit sound bgm_cheerful loop false
```

Stop [#stop]

To <DynamicLink href="/start/sound#stop">stop</DynamicLink&#x3E; a sound in &#x2A;**ink***, you can use the `stop` operation. To do this, you need to use the following syntax:

```ink title="ink"
# stop sound {alias}
```

```ink title="ink"
# stop sound bgm_cheerful
```

To stop all sounds, you can use the following syntax:

```ink title="ink"
# stop all sounds
```


# Storage (/ink/storage)



<Callout type="info">
  You can read more about using variables in ink on the [official documentation](https://github.com/inkle/ink/blob/master/Documentation/WritingWithInk.md#part-3-variables-and-logic).
</Callout>

***ink*** also supports variables, both temporary and global, storing numerical and content data, or even story flow commands. It is fully-featured in terms of logic, and contains a few additional structures to help keep the often complex logic of a branching story better organised.

In the ***ink* + Pixi’VN integration**, the variables `VAR` and `CONST` are equivalent to <DynamicLink href="/start/storage">variables in storage</DynamicLink> and the variables `temp` are equivalent to <DynamicLink href="/start/storage#temporary-storage">temporary variables in storage</DynamicLink>.

The name of the &#x2A;**ink*** variables corresponds to the key of a variable in the <DynamicLink href="/start/storage">storage</DynamicLink>.

Define [#define]

<Callout type="info">
  This functionality in Javascript/TypeScript corresponds to <DynamicLink href="/start/storage#default-storage-variables">"Default storage variables"</DynamicLink>.
</Callout>

You can define a variable in &#x2A;**ink*** with the following code:

```ink title="ink"
VAR myVariable = 42
```

Set [#set]

<Callout type="info">
  This functionality in Javascript/TypeScript corresponds to <DynamicLink href="/start/storage#set">`storage.set`</DynamicLink>.
</Callout>

You can set a variable in &#x2A;**ink*** with the following code:

```ink title="ink"
~ myVariable = 100
```

Get [#get]

<Callout type="info">
  This functionality in Javascript/TypeScript corresponds to <DynamicLink href="/start/storage#get">`storage.get`</DynamicLink>.
</Callout>

In ink, variables can be used for different purposes. For each of these purposes, the way to get the value of a variable is different.

```ink title="ink"
The value of myDuration is: {myDuration}
# show image bg /image.png with dissolve duration {myDuration}
{myDuration > 5:
    The duration is greater than 5.
- else:
    The duration is 5 or less.
}
```


# Temporary storage (/ink/temp-storage)



Define [#define]

Set [#set]

Get [#get]

To get a temporary variable, use the normal <DynamicLink href="/ink/storage#set">`storage.get` function</DynamicLink>.


# Internalization (/ink/translate)





As explained in more detail <DynamicLink href="/start/translate">here</DynamicLink>, Pixi’VN gives the possibility to translate the game text using a library, such as [i18next](https://www.i18next.com/&#x29;. Also in ***ink* + Pixi’VN integration*&#x2A; you can use a library to translate the text of the &#x2A;**ink***.

Pixi’VN gives the developer the ability to intercept the translation event with the `onInkTranslate` function.

The `onInkTranslate` function has as a parameter a callback function takes as parameter the text to translate and returns the translated text.

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

    <CodeBlockTabsTrigger value="ink/start.ink">
      ink/start.ink
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="locales/strings_es.json">
      locales/strings_es.json
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="index.ts">
    ```ts
    import { onInkTranslate } from "@drincs/pixi-vn-ink";

    export function initializeInk(options: { t: (key: string) => string }) {
        const { t } = options;
        onInkTranslate(t);
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="ink/start.ink">
    ```ink
    === start ===
    Hello, my name is [joe]
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="locales/strings_es.json">
    ```json
    {
        "narration": {
            "Hello, my name is [joe]": "Hola, mi nombre es [joe]"
            // ...
        }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Auto-generation of translation files [#auto-generation-of-translation-files]

<Callout title="Templates" type="info">
  In all templates, you can use the following button in the settings to automatically generate the json file that will be used for translations.
    <img alt="dowload-translate" src="__img0" />
</Callout>

To facilitate the creation of the translation files, you can use the `generateJsonInkTranslation` function to automatically generate the JSON structure from the ink text.

```ts
import { generateJsonInkTranslation } from "@drincs/pixi-vn-ink";
import i18n from "i18next";
import { convertInkToJson } from "./utils/ink-utility";

function getLocalesResource(lng: string): Promise<any> {
    return import(`./locales/strings_${lng}.json`);
}

async function generateResourceToTranslate(lng: string): Promise<any> {
    let res = await getLocalesResource(lng);
    res = { ...res };
    if (!res) {
        res = {};
    }
    if (!res.narration) {
        res.narration = {};
    }
    if (res.default) {
        delete res.default;
    }
    (await convertInkToJson()).forEach((element) => {
        element && generateJsonInkTranslation(element, res.narration);
    });
    return res;
}

export async function downloadResourceToTranslate() {
    const lng = i18n.options.fallbackLng?.toString() || "en";
    const data = await generateResourceToTranslate(lng);
    const jsonString = JSON.stringify(data);
    // download the save data as a JSON file
    const blob = new Blob([jsonString], { type: "application/json" });
    // download the file
    const url = URL.createObjectURL(blob);
    const a = document.createElement("a");
    a.href = url;
    a.download = `strings_${lng}.json`;
    a.click();
}
```


# VS Code Extension (/ink/vscode-extension)



If you're using *ink*, we recommend using the *ink* extension we developed. In addition to providing standard *ink* language features, it lets you select `pixi-vn` as your game engine and test your narration in real time.

You can download it and get more information [here](https://marketplace.visualstudio.com/items?itemName=drincs-productions.pixi-vn-ink-vscode).

<img alt="ink VS Code Extension" src="https://github.com/user-attachments/assets/cc17384a-7f2f-4e86-b99a-efbf823269d9" width="1843" height="735" />

Here's the recommended settings file:

```json title="settings.json"
{
    "ink.mainFile": "start.ink",
    "ink.rootFolder": "src/ink",
    "ink.markup": "Markdown",
    "ink.engine": "pixi-vn"
}
```


# Ren'Py Language Integration (/renpy)



Pixi’VN gives you the ability to write your own narrative using Ren'Py Language.

<Callout title="This page is under construction" type="warn">
  Ren'Py integration is in development. If you are interested, feel free to write in the chat below!
</Callout>

**What is Ren'Py Language?**

Ren'Py Language is a scripting language for writing interactive narrative. It is used in games like Doki Doki Literature Club, Katawa Shoujo, and Long Live the Queen to create branching stories. Ren'Py Language is used in Ren'Py, a visual novel engine that helps you to create visual novels and story-based games.

You can learn more about Ren'Py on the [Ren'Py website](https://www.renpy.org/).

Why use Ren'Py integration? [#why-use-renpy-integration]

Programming a game narrative in **Javascript/Typescript** has the advantage of having total development freedom, but the disadvantage is that it slows down the writing of a narrative (it makes you write a lot of code).


# PixiVNJson Model (/json/PixiVNJson)



`PixiVNJson` is the main template. It contains the following properties:

* `initialOperations` (Optional): An array of initial <DynamicLink href="/json/PixiVNJsonOperation">operations</DynamicLink> to run when the project starts.
* `labels` (Optional): A dictionary of [`labels`](#pixivnjsonlabels-model).

PixiVNJsonLabels Model [#pixivnjsonlabels-model]

To add <DynamicLink href="/start/labels">`labels`</DynamicLink> you need to use `PixiVNJsonLabels`. This is a dictionary where the key is the label ID and the value is an array of <DynamicLink href="/json/PixiVNJsonLabelStep">`PixiVNJsonLabelStep`</DynamicLink>.

```ts title="PixiVNJsonLabels.ts"
type PixiVNJsonLabels = {
    [labelId: string]: PixiVNJsonLabelStep[];
};
```

PixiVNJsonLabelStep Model [#pixivnjsonlabelstep-model]

`PixiVNJsonLabelStep` corresponds to the <DynamicLink href="/start/labels">`label steps`</DynamicLink>, so a set of actions that are performed at each <DynamicLink href="/start/labels-flow#continue">`continue`</DynamicLink>. It contains the following properties:

* `operations` (Optional): An array of <DynamicLink href="/json/PixiVNJsonOperation">operations</DynamicLink> to run when the step is executed. You can use the <DynamicLink href="/json/PixiVNJsonConditionalStatements">condition</DynamicLink> pattern to use a certain pattern based on a condition.
* `choices` (Optional): A <DynamicLink href="/json/PixiVNJsonChoices">choices</DynamicLink> object that contains the choices available in this step. You can use the <DynamicLink href="/json/PixiVNJsonConditionalStatements">condition</DynamicLink> pattern to use a certain pattern based on a condition.
* `dialogue` (Optional):
* `glueEnabled` (Optional): It is a boolean that corresponds to <DynamicLink href="/start/labels#dialogue-glue">`glue`</DynamicLink>. You can use the <DynamicLink href="/json/PixiVNJsonConditionalStatements">condition</DynamicLink> pattern to use a certain pattern based on a condition.
* `labelToOpen` (Optional): An item or an array of <DynamicLink href="/json/PixiVNJsonLabelToOpen">`PixiVNJsonLabelToOpen`</DynamicLink> objects that correspond to the <DynamicLink href="/start/labels-flow#run-a-label">`open labels`</DynamicLink>. You can use the <DynamicLink href="/json/PixiVNJsonConditionalStatements">condition</DynamicLink> pattern to use a certain pattern based on a condition.
* `goNextStep` (Optional): It is a boolean that corresponds to <DynamicLink href="/start/labels-flow#continue">`continue`</DynamicLink>. You can use the <DynamicLink href="/json/PixiVNJsonConditionalStatements">condition</DynamicLink> pattern to use a certain pattern based on a condition.
* `end` (Optional): It is a string that can be `game_end` or `label_end`. If it is `game_end`, the game ends. If it is `label_end`, the current label ends and the game continues with the next step of the previous label. You can use the <DynamicLink href="/json/PixiVNJsonConditionalStatements">condition</DynamicLink> pattern to use a certain pattern based on a condition.


# PixiVNJsonChoices Model (/json/PixiVNJsonChoices)



This pase is in progress. It will be updated soon.


# PixiVNJsonConditionalStatements Model (/json/PixiVNJsonConditionalStatements)



The `PixiVNJsonConditionalStatements<Then>` is used to define conditional statements. It contains the following properties:

Depending on the `type`, it can respond to the following models.

* If is `ifelse` it responds to the [`PixiVNJsonIfElse`](#pixivnjsonifelse-model) model.
* If is `stepswitch` it responds to the [`PixiVNJsonStepSwitch`](#pixivnjsonstepswitch-model) model.

PixiVNJsonIfElse Model [#pixivnjsonifelse-model]

The `PixiVNJsonIfElse<Then>` is used to define an if-else statement. It contains the following properties:

* `condition`: PixiVNJsonConditions;
* `then`: `Then` | `PixiVNJsonIfElse<Then>`;
* `else` (Optional): `Then` | `PixiVNJsonIfElse<Then>`;

PixiVNJsonStepSwitch Model [#pixivnjsonstepswitch-model]

* `choiceType`: "random" "sequential" "loop" "sequentialrandom"
* `elements`: `PixiVNJsonStepSwitchElementsType<Then>`;

PixiVNJsonConditions Model [#pixivnjsonconditions-model]


# PixiVNJsonLabelToOpen Model (/json/PixiVNJsonLabelToOpen)



This pase is in progress. It will be updated soon.


# PixiVNJsonOperation Model (/json/PixiVNJsonOperation)



This pase is in progress. It will be updated soon.


# Pixi’VN + Json Integration (/json)



Pixi’VN can be integrated with JSON files to create a visual novel. This method is useful for:

* Add a new narrative to Pixi’VN (It was used to create the integration with <DynamicLink href="/ink">***ink***</DynamicLink> and <DynamicLink href="/renpy">Ren'Py</DynamicLink>)
* Create a external tool to create visual novels with Pixi’VN

( In both these cases it is advisable to notify the developers of Pixi’VN to add the new feature to be helped )

<Mermaid
  chart="
flowchart LR;
K@{ img: &#x22;/renpy.svg&#x22;, label: &#x22;RenPy&#x22;, pos: &#x22;b&#x22;, w: 90, h: 90, constraint: &#x22;on&#x22; }---->Json;
H@{ img: &#x22;/ink.svg&#x22;, label: &#x22;ink&#x22;, pos: &#x22;b&#x22;, w: 90, h: 90, constraint: &#x22;on&#x22; }---->Json;
I@{ img: &#x22;/twine.svg&#x22;, label: &#x22;Twine&#x22;, pos: &#x22;b&#x22;, w: 90, h: 90, constraint: &#x22;on&#x22; }---->Json;
J@{ img: &#x22;/yarn-spinner.svg&#x22;, label: &#x22;Yarn Spinner&#x22;, pos: &#x22;b&#x22;, w: 90, h: 90, constraint: &#x22;on&#x22; }---->Json;
Json@{ img: &#x22;/pixivn-json.svg&#x22;, label: &#x22;Pixi’VN + Json&#x22;, pos: &#x22;b&#x22;, w: 140, h: 140, constraint: &#x22;on&#x22; }
Json===>PixiVN;
PixiVN@{ img: &#x22;/logo.webp&#x22;, label: &#x22;Pixi’VN&#x22;, pos: &#x22;b&#x22;, w: 180, h: 180, constraint: &#x22;on&#x22; }
classDef img fill:none,stroke:none,borderRadius:50px
class Json,D,K,H,B,I,J,PixiVN img
"
/>

How use Pixi’VN + Json? [#how-use-pixivn--json]

First of all you need to install the following library:

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

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

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

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

  <CodeBlockTab value="npm">
    ```sh
    npm install @drincs/pixi-vn-json
    ```
  </CodeBlockTab>

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

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

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

All you need to do to use this integration is create a object using the <DynamicLink href="/json/PixiVNJson">`PixiVNJson` Model</DynamicLink> and use the `importPixiVNJson()` function to import the object.

```ts title="main.ts"
import { PixiVNJson, importPixiVNJson} from '@drincs/pixi-vn-json';

let obj: PixiVNJson = {
    labels: {
        back_in_london: [
            {
                dialogue: "We arrived into London at 9.45pm exactly.",
            },
            {
                labelToOpen: {
                    label: "hurry_home",
                    type: "jump",
                },
            },
        ],
        hurry_home: [
            {
                dialogue: "We hurried home to Savile Row as fast as we could.",
            },
            {
                end: "label_end",
            },
        ]
    }
}

importPixiVNJson(obj);
```

After that you can run the `back_in_london` label with <DynamicLink href="/start/labels#run-a-label">Pixi’VN functions</DynamicLink>.

```ts title="main.ts"
import { narration } from '@drincs/pixi-vn'

narration.call(`back_in_london`, {})
```


# Activity (/nqtr/activity)



The `activity` are actions the player can take, and they can be linked to a <DynamicLink href="/nqtr/navigation">navigation element</DynamicLink>. The developer will decide how the player interacts with them.

Initialize [#initialize]

To initialize a `activity`, create a new instance of the `ActivityBaseModel` class (or your [custom class](#custom-class)) and add it to the game activity dictionary when the game is initialized.

<Callout type="info">
  It is recommended to import the instances at project startup, see the `src/main.ts` file.
</Callout>

To create a new instance of `ActivityBaseModel`, you need the following parameters:

* `id`: A unique identifier (string). Used to reference the `activity` in the game (must be unique).
* `onRun`: A function that is called when the `activity` is run. It receives two parameters:
  * The `activity` instance itself.
  * `props`: the properties that will be passed to the activity. Its interface corresponds to <DynamicLink href="/nqtr#onrunprops">`OnRunProps`</DynamicLink>.
* `props`: An object with the activity's properties:
  * `name`: The name of the activity (Optional).
  * `timeSlot`: The time slot in which the activity will be active (Optional).
  * `dateScheduling`: Used to schedule what date it will be added and removed (Optional).
  * `disabled`: Whether the activity is disabled. You can also pass a Pixi’VN flag name (optional, default is `false`).
  * `hidden`: Whether the activity is hidden. You can also pass a Pixi’VN flag name (optional, default is `false`).
  * `renderIcon`: The icon of the activity (Optional).

<CodeBlockTabs defaultValue="values/activities.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="values/activities.ts">
      values/activities.ts
    </CodeBlockTabsTrigger>

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

  <CodeBlockTab value="values/activities.ts">
    ```ts
    import { ActivityBaseModel, RegisteredActivities, timeTracker } from "@drincs/nqtr";
    import { narration } from "@drincs/pixi-vn";
    import { NARRATION_ROUTE } from "../constans";
    import { napLabel, sleepLabel } from "../labels/sleepNapLabels";
    import { ORDER_PRODUCT_LABEL_KEY, TAKE_KEY_LABEL_KEY } from "../labels/variousActionsLabelKeys";

    export const bed = new ActivityBaseModel(
        "bed",
        async (_, props) => {
            await props.navigate(NARRATION_ROUTE);
            if (timeTracker.nowIsBetween(5, 22)) {
                await narration.jump(napLabel, props);
            } else {
                await narration.jump(sleepLabel, props);
            }
        },
        {
            name: "bed",
        },
    );

    export const orderProduct = new ActivityBaseModel(
        "order_product",
        async (_, props) => {
            await props.navigate(NARRATION_ROUTE);
            await narration.jump(ORDER_PRODUCT_LABEL_KEY, props);
        },
        {
            name: "order_product",
        },
    );

    export const takeProduct = new Activity(
        "take_product",
        async (_, props) => {
            await props.navigate(NARRATION_ROUTE);
            await narration.jump(TAKE_KEY_LABEL_KEY, props);
        },
        {
            name: "take_product",
        },
    );

    RegisteredActivities.add([bed, orderProduct, takeProduct]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="main.ts">
    ```ts
    import "./values/activities";

    // ...
    ```
  </CodeBlockTab>
</CodeBlockTabs>

`RegisteredActivities.add` is **required** to save the `activities` in the game.

You can also create a function to load `activities`. The important thing is that it is called at least once before the `activities` are used in the game, otherwise they will not be available.

Link [#link]

For an `activity` to be available to the player, it must be linked to a <DynamicLink href="/nqtr/navigation">navigation element</DynamicLink>. The relationship between an `activity` and a navigation element is many-to-many, meaning that an `activity` can be linked to multiple navigation elements and a navigation element can have multiple `activities` associated with it.

There are two ways to do this:

During game initialization [#during-game-initialization]

When the game starts, a list of related activities will be defined. This list will not be saved when the game is saved. Therefore, the developer can modify this list from one version of the game to another without having to worry about migrations for older versions.

<CodeBlockTabs defaultValue="values/rooms.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="values/rooms.ts">
      values/rooms.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="values/activities.ts">
      values/activities.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="values/rooms.ts">
    ```ts
    import { RegisteredRooms, RoomBaseModel } from "@drincs/nqtr";
    import { bed } from "./activity";
    import { mcHome } from "./locations";

    export const mcRoom = new RoomBaseModel("mc_room", mcHome, {
        name: "MC room",
        image: "location_myroom",
        activities: [bed], // [!code ++]
    });

    RegisteredRooms.add([mcRoom]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="values/activities.ts">
    ```ts
    import { ActivityBaseModel, RegisteredActivities, timeTracker } from "@drincs/nqtr";
    import { narration } from "@drincs/pixi-vn";
    import { napLabel, sleepLabel } from "../labels/sleepNapLabels";

    export const bed = new ActivityBaseModel(
        "bed",
        async (_, props) => {
            if (timeTracker.nowIsBetween(5, 22)) {
                await narration.jump(napLabel, props);
            } else {
                await narration.jump(sleepLabel, props);
            }
        },
        {
            name: "bed",
        }
    );

    RegisteredActivities.add([bed]);
    ```
  </CodeBlockTab>
</CodeBlockTabs>

During the game [#during-the-game]

You can also link an activity to a navigation element during the game. This feature is useful if you want to temporarily add an activity. The list of activities added this way will be included in your game saves.

To link an activity to a navigation element during the game, you can use the `addActivity` method.

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

    <CodeBlockTabsTrigger value="ink">
      ink
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="values/activities.ts">
      values/activities.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="values/rooms.ts">
      values/rooms.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    import { newLabel, showImageContainer } from "@drincs/pixi-vn";
    import { orderProduct } from "../activities";
    import { mcRoom } from "../rooms";

    const startLabel = newLabel("start", [
        async () => {
            mcRoom.addActivity(orderProduct); // [!code focus]
        },
    ]);
    export default startLabel;
    ```
  </CodeBlockTab>

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    == start ==
    // {order_product} is the id of the activity
    # add activity {order_product} in mc_room
    ```
  </CodeBlockTab>

  <CodeBlockTab value="values/activities.ts">
    ```ts
    import { ActivityBaseModel, RegisteredActivities } from "@drincs/nqtr";
    import { narration } from "@drincs/pixi-vn";
    import { orderProductLabel } from "../labels/variousActionsLabels";

    export const orderProduct = new ActivityBaseModel(
        "order_product",
        async (_, props) => await narration.jump(orderProductLabel, props),
        {
            name: "order_product",
        }
    );

    RegisteredActivities.add([orderProduct]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="values/rooms.ts">
    ```ts
    import { RegisteredRooms, RoomBaseModel } from "@drincs/nqtr";
    import { mcHome } from "./locations";

    export const mcRoom = new RoomBaseModel("mc_room", mcHome, {
        name: "MC room",
        image: "location_myroom",
    });

    RegisteredRooms.add([mcRoom]);
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Unlink [#unlink]

To unlink an activity from a navigation element, you can use the `removeActivity` method.

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

    <CodeBlockTabsTrigger value="Typescript">
      Typescript
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="ink">
      ink
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="values/rooms.ts">
      values/rooms.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Example">
    ```ts
    import { orderProduct } from "../activities";
    import { mcRoom } from "../rooms";

    mcRoom.removeActivity(orderProduct);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  title="index.ts" groupId="narrative_language"
    import { ActivityBaseModel, RegisteredActivities } from "@drincs/nqtr";
    import { narration } from "@drincs/pixi-vn";
    import { orderProductLabel } from "../labels/variousActionsLabels";

    export const orderProduct = new ActivityBaseModel(
        "order_product",
        async (_, props) => await narration.jump(orderProductLabel, props),
        {
            name: "order_product",
        }
    );

    RegisteredActivities.add([orderProduct]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="ink">
    ```ink  title="index.ink" groupId="narrative_language"
    // {order_product} is the id of the activity
    # remove activity {order_product} from mc_room
    ```
  </CodeBlockTab>

  <CodeBlockTab value="values/rooms.ts">
    ```ts
    import { RegisteredRooms, RoomBaseModel } from "@drincs/nqtr";
    import { mcHome } from "./locations";

    export const mcRoom = new RoomBaseModel("mc_room", mcHome, {
        name: "MC room",
        image: "location_myroom",
    });

    RegisteredRooms.add([mcRoom]);
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Get [#get]

To get a `activity` by its `id`, use the `RegisteredActivities.get` function.

```ts
import { RegisteredActivities } from "@drincs/nqtr";

const orderProduct = RegisteredActivities.get('order_product');
```

Get all [#get-all]

To get all `activities`, use the `RegisteredActivities.values` function.

```ts
import { RegisteredActivities } from "@drincs/nqtr";

const activities = RegisteredActivities.values();
```

Custom class [#custom-class]

<Callout title="Templates" type="info">
  In all templates, the `Activity` class is already defined in the file `models/nqtr/Activity.ts`. You can use it directly or modify it to suit your needs.
</Callout>

It is recommended to create your own class `Activity` that extends `ActivityStoredClass` and "override" the interface `ActivityInterface` to add, edit, or remove properties or methods.

For example, if you want to create a class `Activity`, you must "override" the interface `ActivityInterface` to use your properties or methods. (See the file `nqtr.d.ts`)

Now you can create a class `Activity` that extends `ActivityStoredClass` and implements the `ActivityInterface`. (For more information on how to create a class in TypeScript, read [the official documentation](https://www.typescriptlang.org/docs/handbook/2/classes.html))

To create a property that stores its value in the game storage, you can create [Getters/Setters](https://www.typescriptlang.org/docs/handbook/2/classes.html#getters--setters) and use the `this.getStorageProperty()` / `this.setStorageProperty()` methods. (See the file `Activity.ts`)

<CodeBlockTabs defaultValue="models/nqtr/Activity.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="models/nqtr/Activity.ts">
      models/nqtr/Activity.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="nqtr.d.ts">
      nqtr.d.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="models/nqtr/Activity.ts">
    ```ts
    import {
        ActiveScheduling,
        ActivityInterface,
        ActivityStoredClass,
        ActivityStoredClassProps,
        OnRunEvent,
        OnRunProps,
    } from "@drincs/nqtr";
    import { PixiUIParam, PixiUIProp, ReactUIParam, ReactUIProp } from "./ui-elements";
    import { OnRunAsyncFunction } from "@drincs/nqtr";

    export default class Activity extends ActivityStoredClass implements ActivityInterface {
        constructor(
            id: string,
            onRun: OnRunEvent<ActivityInterface>,
            props: {
                name?: string;
                sprite?: PixiUIParam<Activity>;
                icon?: ReactUIParam<Activity>;
                disabled?: boolean | (() => boolean);
                hidden?: boolean | (() => boolean);
            } & ActivityStoredClassProps,
        ) {
            super(id, onRun, props);
            this.name = props.name || "";
            this._sprite = props.sprite;
            this._icon = props.icon;
            this._defaultDisabled = props.disabled || false;
            this._defaultHidden = props.hidden || false;
        }
        readonly name: string;
        private readonly _sprite?: PixiUIParam<Activity>;
        get sprite(): PixiUIProp | undefined {
            const sprite = this._sprite;
            if (typeof sprite === "function") {
                return (runProps: OnRunProps) => sprite(this, runProps);
            }
            return sprite;
        }
        private readonly _icon?: ReactUIParam<Activity>;
        get icon(): ReactUIProp | undefined {
            const icon = this._icon;
            if (typeof icon === "function") {
                return (runProps: OnRunProps) => icon(this, runProps);
            }
            return icon;
        }
        private _defaultDisabled: boolean | (() => boolean) = false;
        get disabled(): boolean {
            let value = this.getStorageProperty<boolean>("disabled") || this._defaultDisabled;
            if (typeof value === "function") {
                return value();
            }
            return value;
        }
        set disabled(value: boolean) {
            this.setStorageProperty("disabled", value);
        }
        private _defaultHidden: boolean | (() => boolean) = false;
        get hidden(): boolean {
            let value = this.getStorageProperty<boolean>("hidden") || this._defaultHidden;
            if (typeof value === "function") {
                return value();
            }
            return value;
        }
        set hidden(value: boolean) {
            this.setStorageProperty("hidden", value);
        }
        override isActive(options?: ActiveScheduling): boolean {
            if (this.hidden) {
                return false;
            }
            return super.isActive(options);
        }
        override get run(): OnRunAsyncFunction {
            return async (runProps: OnRunProps) => {
                const res = await super.run(runProps);
                await runProps.invalidateInterfaceData();
                return res;
            };
        }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="nqtr.d.ts">
    ```ts
    import { StepLabelProps } from "@drincs/pixi-vn";
    import { PixiUIProp, ReactUIProp } from "./models/nqtr/ui-elements";

    declare module "@drincs/nqtr" {
        interface ActivityInterface {
            /**
             * The name of the activity.
             */
            readonly name: string;
            /**
             * Whether is disabled.
             */
            disabled: boolean;
            /**
             * Whether is hidden.
             */
            hidden: boolean;
            /**
             * The sprite of the activity.
             */
            readonly sprite?: PixiUIProp;
            /**
             * The React icon of the activity.
             */
            readonly icon?: ReactUIProp;
        }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>


# Navigation Quest Time Routine (NQTR) (/nqtr)



**What is NQTR?** NQTR (Navigation Quest Time Routine) is an extension for Pixi’VN that adds advanced systems for navigation, quests, time management, and game state handling. It is fully customizable and extensible, enabling developers to implement complex game mechanics with ease.

Installation [#installation]

<Callout title="Templates" type="info">
  Starting a new Pixi’VN project? Use a <DynamicLink href="/start#project-initialization">template</DynamicLink> that already includes NQTR.
</Callout>

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

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

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

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

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

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

  <CodeBlockTab value="npm">
    ```sh
    npm install @drincs/nqtr
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```sh
    yarn add @drincs/nqtr
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```sh
    pnpm add @drincs/nqtr
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```sh
    bun add @drincs/nqtr
    ```
  </CodeBlockTab>

  <CodeBlockTab value="deno">
    ```sh
    deno install npm:@drincs/nqtr
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Accordions>
  <Accordion title="ink_integration" id="ink">
    To access NQTR features you can add a handler to *ink*'s hashtag commands.

    <CodeBlockTabs defaultValue="utils/ink-utility.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="utils/ink-utility.ts">
          utils/ink-utility.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="utils/ink-utility.ts">
        ```ts
        import { nqtrHandler } from "@drincs/nqtr/ink";
        import { HashtagCommands } from "@drincs/pixi-vn-ink";

        export function initializeInk() {
            HashtagCommands.add(nqtrHandler());
            // ...
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="onrunprops" id="onrunprops">
    <Callout title="Templates" type="info">
      In all templates, the `StepLabelProps` interface is already overridden. You can find it in the `pixi-vn.d.ts` file.
    </Callout>

    Some NQTR functions require you to pass an `OnRunProps` object as a parameter. This allows you to customize and access properties in system-triggered functions.

    By default, `OnRunProps` is `{ [key: string]: any }`. You can override the `OnRunProps` interface in your `.d.ts` file to specify required parameters.

    <CodeBlockTabs defaultValue="pixi-vn.d.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="pixi-vn.d.ts">
          pixi-vn.d.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="pixi-vn.d.ts">
        ```ts
        import { narration } from '@drincs/pixi-vn'

        declare module '@drincs/pixi-vn' {
            interface OnRunProps {
                navigate: (route: string) => void,
            }
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>
</Accordions>

Features [#features]

NQTR provides the following features (the order is important):

1. <DynamicLink href="/nqtr/navigation">
     Navigation and map
   </DynamicLink>
2. <DynamicLink href="/nqtr/time">
     Time system
   </DynamicLink>
3. <DynamicLink href="/nqtr/activity">
     Activity
   </DynamicLink>
4. <DynamicLink href="/nqtr/routine">
     Routine
   </DynamicLink>
5. <DynamicLink href="/nqtr/quest">
     Quest system
   </DynamicLink>


# Make your first Point & Click Adventure (/nqtr/make-point-and-click)



<Callout type="warn">
  Before continuing, it is important to consider that this page assumes the concepts explained in <DynamicLink href="/start/make-visual-novel">"Make your first Visual Novel"</DynamicLink>, and that all the features explained on that page can also be applied here. Additionally, having an intermediate knowledge of JS/TS (such as functions, classes, interfaces, and the use of `.d.ts` files) is essential.
  Do not continue if you do not have this knowledge.
</Callout>

This tutorial will guide you through the process of creating your first Point & Click Adventure.

**What is a Point & Click Adventure?** A Point & Click Adventure is a game genre in which the player interacts with the environment and objects through mouse pointing and clicking. These games often feature puzzles, dialogues, and an engaging narrative.

**How to implement it in a Pixi’VN project?** The Pixi’VN environment provides a utility library and base models, called `NQTR` (Navigation Quest Time Routine), which allow you to easily implement a navigation system, time management, and quests. The way NQTR works is based on creating class instances that comply with specific interfaces, which will be registered and provided by the NQTR utilities. In this way, it is possible to create a UI tailored to the game's needs. Alternatively, you can use the base models provided by NQTR and the UI included in the "Point & Click Adventure - React" template to create a complete game in a short time.

Additionally, it is very important to consider that elements can trigger `labels` (narratives), allowing you to switch to the narrative interface and back.

Create a new project [#create-a-new-project]

The first step is to create a new project. You can find more information on how to create a new project starting from a template <DynamicLink href="/start#project-initialization">here</DynamicLink>. We will use the template "Point & Click Adventure - React".

`Point & Click Adventure -> React`

After the creation is complete, it is very important to read the `README.md` file that is in the root of the project. This file contains important information about the project and how to use it.

In our case, to start the project we will simply need to execute the following commands:

```bash
npm install
npm start
```

Add clickable elements [#add-clickable-elements]

The main feature of a Point & Click Adventure is the ability to interact with the environment through mouse clicks. To add clickable elements, it is recommended to use UI (in our case React or PixiJS) rather than the Pixi’VN canvas, as it is easier to manage events and interactions.

In the template we are using, when creating the elements that we will see later, there is the possibility to define graphical elements (such as an icon). These graphical elements can be defined using different types; based on this, the system will add the graphical element to the <DynamicLink href="/start/interface-pixijs">PixiJS UI</DynamicLink> or to the <DynamicLink href="/start/interface-react">React</DynamicLink> UI. In this way, it is possible to create clickable elements in a simple and fast way.

Usually, it is possible to define a graphical element as a string representing the asset alias. The template also provides the possibility to use the <DynamicLink href="/nqtr/time#image-time-period">`TimeSlotsImage`</DynamicLink> class, which allows you to define a different image depending on the time of day.

```ts
export const nightcityMap = new Map("nightcity_map", {
    name: "Nightcity",
    background: "map-nightcity", // [!code focus]
    neighboringMaps: {
        south: "main_map",
    },
});
```

Usually, it is possible to define a graphical element as a React element.

```tsx
export const bed = new Activity(
    "bed",
    async (_, props) => {
        await props.navigate(NARRATION_ROUTE);
        if (timeTracker.nowIsBetween(5, 22)) {
            await narration.jump(napLabel, props);
        } else {
            await narration.jump(sleepLabel, props);
        }
    },
    {
        name: "bed",
        icon: (activity, props) => { // [!code focus]
            return ( // [!code focus]
                <NqtrRoundIconButton // [!code focus]
                    disabled={activity.disabled} // [!code focus]
                    onClick={() => { // [!code focus]
                        activity.run(props).then(() => { // [!code focus]
                            props.invalidateInterfaceData(); // [!code focus]
                        }); // [!code focus]
                    }} // [!code focus]
                    ariaLabel={props.uiTransition(activity.name)} // [!code focus]
                    variant='solid' // [!code focus]
                    color='primary' // [!code focus]
                > {/* [!code focus] */}
                    <BedIcon // [!code focus]
                        sx={{ // [!code focus]
                            fontSize: { sx: "1.5rem", sm: "2rem", md: "2.5rem", lg: "3rem", xl: "3.5rem" }, // [!code focus]
                        }} // [!code focus]
                    /> {/* [!code focus] */}
                </NqtrRoundIconButton> // [!code focus]
            ); // [!code focus]
        }, // [!code focus]
    }
);
```

Additionally, when the `sprite` property is available, it is possible to define a graphical element as a PixiJS element.

```ts
import { Assets, Sprite, Texture } from "@drincs/pixi-vn/pixi.js";

export const mcHome = new Location("mc_home", mainMap, {
    name: "MC Home",
    sprite: async (location, { navigate }) => { // [!code focus]
        const texture = await Assets.load<Texture>("icon_location_home"); // [!code focus]
        const icon = new Sprite({ // [!code focus]
            texture, // [!code focus]
            x: 300, // [!code focus]
            y: 200, // [!code focus]
            height: 120, // [!code focus]
            width: 120, // [!code focus]
            eventMode: "static", // [!code focus]
            cursor: "pointer", // [!code focus]
        }); // [!code focus]
        icon.on("pointerdown", () => { // [!code focus]
            const entrance = location.entrance; // [!code focus]
            if (entrance) { // [!code focus]
                navigator.currentRoom = entrance; // [!code focus]
                navigate(NAVIGATION_ROUTE); // [!code focus]
            } // [!code focus]
        }); // [!code focus]
        return icon; // [!code focus]
    }, // [!code focus]
});
```

Navigation and map [#navigation-and-map]

<Callout type="info">
  You can find more detailed documentation about these elements <DynamicLink href="/nqtr/navigation">here</DynamicLink>.
</Callout>

The first step to create a Point & Click Adventure is to create the navigation elements. These elements allow the player to move within the game and interact with the environment.

The navigation system is composed of the following elements:

* `rooms`: The core elements of navigation, from which the position of the `mc` and `npc` is deduced.
* `locations`: A container of `rooms`.
* `maps`: A container of `locations`.

For example:

```ts title="values/rooms.ts"
import { RegisteredRooms } from "@drincs/nqtr";
import TimeSlotsImage from "../models/TimeSlotsImage";
import Room from "../models/nqtr/Room";
import { bed } from "./activities";
import { mcHome } from "./locations";

export const mcRoom = new Room("mc_room", mcHome, {
    name: "MC room",
    background: new TimeSlotsImage({
        morning: "location_myroom-0",
        afternoon: "location_myroom-1",
        evening: "location_myroom-2",
        night: "location_myroom-3",
    }),
    activities: [bed],
});

RegisteredRooms.add([mcRoom]);
```

```ts title="values/locations.ts"
import { navigator, RegisteredLocations } from "@drincs/nqtr";
import { Assets, Sprite, Texture } from "@drincs/pixi-vn/pixi.js";
import { NAVIGATION_ROUTE } from "../constans";
import Location from "../models/nqtr/Location";
import { mainMap } from "./maps";

export const mcHome = new Location("mc_home", mainMap, {
    name: "MC Home",
    sprite: async (location, { navigate }) => {
        const texture = await Assets.load<Texture>("icon_location_home");
        const icon = new Sprite({
            texture,
            x: 300,
            y: 200,
            height: 120,
            width: 120,
            eventMode: "static",
            cursor: "pointer",
        });
        icon.on("pointerdown", () => {
            const entrance = location.entrance;
            if (entrance) {
                navigator.currentRoom = entrance;
                navigate(NAVIGATION_ROUTE);
            }
        });
        return icon;
    },
});

RegisteredLocations.add([mcHome]);
```

```ts title="values/maps.ts"
import { RegisteredMaps } from "@drincs/nqtr";
import TimeSlotsImage from "../models/TimeSlotsImage";
import Map from "../models/nqtr/Map";

export const mainMap = new Map("main_map", {
    name: "Main Map",
    background: new TimeSlotsImage({
        morning: "map-0",
        afternoon: "map-1",
        evening: "map-2",
        night: "map-3",
    }),
    neighboringMaps: {
        north: "nightcity_map",
    },
});

RegisteredMaps.add([mainMap]);
```

Now, before you can use the navigation utilities, you need to set the current room. After that, it is possible to navigate to the navigation screen at the start of the game or after a short initial narrative.

Additionally, it is important to keep in mind that the current `location` and `map` are deduced from the current `room`, so it is sufficient to set the `room` to obtain all the necessary information for navigation.

<Callout type="info">
  You can find more detailed documentation on how to navigate between UI screens <DynamicLink href="/start/interface-navigate">here</DynamicLink>.
</Callout>

For example:

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

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

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    === start ===
        # navigate /narration
        Hello, welcome to the my first game!

        # enter room mc_room
        # navigate /navigation
        -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    import { navigator } from "@drincs/nqtr";
    import { narration, newLabel } from "@drincs/pixi-vn";
    import { mcRoom } from "../values/rooms";

    const startLabel = newLabel("start", [
        async (props) => {
            await props.navigate("/narration");
            narration.dialogue = "Hello, welcome to the my first game!";
        },
        async (props) => {
            navigator.currentRoom = mcRoom;
            await props.navigate("/navigation");
        },
    ]);
    export default startLabel;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Time system [#time-system]

<Callout type="info">
  You can find more detailed documentation about these elements <DynamicLink href="/nqtr/time">here</DynamicLink>.
</Callout>

Now let's move on to another fundamental element: the time management system. The time management system is a key component in a Point & Click Adventure, as it allows you to create a dynamic and realistic world where the player's actions can have different consequences depending on the time of day.

Before you can use the time management features, it is necessary to initialize the `timeTracker` with the information required for the system to function. As shown in the following example, it is possible to define every aspect of the time management system, such as time slots, days of the week, the start and end time of the day, and so on.

<CodeBlockTabs defaultValue="utils/nqtr-utility.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="utils/nqtr-utility.ts">
      utils/nqtr-utility.ts
    </CodeBlockTabsTrigger>

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

  <CodeBlockTab value="utils/nqtr-utility.ts">
    ```ts
    import { timeTracker } from "@drincs/nqtr";
    import { timeSlots } from "../constans";

    const weekDaysNames = ["monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"];
    export function initializeNQTR() {
        timeTracker.initialize({
            defaultTimeSpent: 1,
            dayStartTime: 0,
            dayEndTime: 24,
            timeSlots: [
                { name: timeSlots.morning.description, startTime: timeSlots.morning.value },
                { name: timeSlots.afternoon.description, startTime: timeSlots.afternoon.value },
                { name: timeSlots.evening.description, startTime: timeSlots.evening.value },
                { name: timeSlots.night.description, startTime: timeSlots.night.value },
            ],
            getDayName: (weekDayNumber: number) => {
                return weekDaysNames[weekDayNumber];
            },
            weekendStartDay: 6,
            weekLength: 7,
        });
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="constans.ts">
    ```ts
    export const timeSlots = {
        morning: { description: "morning", value: 5 },
        afternoon: { description: "afternoon", value: 12 },
        evening: { description: "evening", value: 18 },
        night: { description: "night", value: 22 },
    };
    ```
  </CodeBlockTab>
</CodeBlockTabs>

The main functionality of the time management system is the ability to advance time based on the player's actions.

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

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

  <CodeBlockTab value="ink">
    ```ink  title="index.ink" groupId="narrative_language"
    // {timeValue} is a number representing the amount of time to increment
    // {dateValue} is a number representing the amount of days to increment
    # wait {timeValue} // Increment time by {value}
    # wait // Increment time by defaultTimeSpent
    # wait days {dateValue} // Increment date by {dateValue} and set time to dayStartTime
    # wait days {dateValue} hours {timeValue} // Increment date by {dateValue} and time by {timeValue}
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  title="index.ts" groupId="narrative_language"
    import { timeTracker } from "@drincs/nqtr";

    timeTracker.increaseTime(2);
    timeTracker.increaseDate(1, 8); // Increment date by 1 and set time to 8
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Activity [#activity]

<Callout type="info">
  You can find more detailed documentation about these elements <DynamicLink href="/nqtr/activity">here</DynamicLink>.
</Callout>

A fundamental element in Point & Click Adventures is interactive elements, which allow the player to interact with the environment and progress the story. In NQTR, these elements are represented by `activity`. `activity` are elements that can be executed by the player and can have different consequences depending on the context in which they are performed.

For example:

<CodeBlockTabs defaultValue="values/activities.tsx">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="values/activities.tsx">
      values/activities.tsx
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="values/activities.tsx">
    ```ts
    import { RegisteredActivities, timeTracker } from "@drincs/nqtr";
    import { narration } from "@drincs/pixi-vn";
    import BedIcon from "@mui/icons-material/Bed";
    import NqtrRoundIconButton from "../components/NqtrRoundIconButton";
    import { NARRATION_ROUTE } from "../constans";
    import { napLabel, sleepLabel } from "../labels/sleepNapLabels";
    import Activity from "../models/nqtr/Activity";

    export const bed = new Activity(
        "bed",
        async (_, props) => {
            await props.navigate(NARRATION_ROUTE);
            if (timeTracker.nowIsBetween(5, 22)) {
                await narration.jump(napLabel, props);
            } else {
                await narration.jump(sleepLabel, props);
            }
        },
        {
            name: "bed",
            icon: (activity, props) => {
                return (
                    <NqtrRoundIconButton
                        disabled={activity.disabled}
                        onClick={() => {
                            activity.run(props).then(() => {
                                props.invalidateInterfaceData();
                            });
                        }}
                        ariaLabel={props.uiTransition(activity.name)}
                        variant='solid'
                        color='primary'
                    >
                        <BedIcon
                            sx={{
                                fontSize: { sx: "1.5rem", sm: "2rem", md: "2.5rem", lg: "3rem", xl: "3.5rem" },
                            }}
                        />
                    </NqtrRoundIconButton>
                );
            },
        },
    );

    RegisteredActivities.add([bed]);
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Callout type="info">
  Activities are connected to rooms in a many-to-many relationship, meaning that an activity can be present in multiple rooms and a room can contain multiple activities.
</Callout>

To use them, you must link them to a `room` [through the `activities` property](#navigation-and-map). This way, when the player is in that room, they will be able to see the activity and interact with it.

Alternatively, during the narrative session, it is possible to add an activity to a room using the `addActivity` function.

For example:

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

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

  <CodeBlockTab value="ink">
    ```ink  groupId="narrative_language"
    == start ==
    # add activity bed in mc_room
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  groupId="narrative_language"
    import { newLabel, showImageContainer } from "@drincs/pixi-vn";
    import { bed } from "../activities";
    import { mcRoom } from "../rooms";

    const startLabel = newLabel("start", [
        async () => {
            mcRoom.addActivity(bed); // [!code focus]
        },
    ]);
    export default startLabel;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Routine [#routine]

<Callout type="info">
  You can find more detailed documentation about these elements <DynamicLink href="/nqtr/routine">here</DynamicLink>.
</Callout>

`Routine` refers to the set of elements that make up the daily routine of non-player characters (NPC).

The routine is composed of `commitment`, which represent a character’s obligation to perform a specific activity at a certain moment of the day. These commitments are very similar to `activity`, as they represent an activity that the character performs.

For example:

<CodeBlockTabs defaultValue="values/routine.tsx">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="values/routine.tsx">
      values/routine.tsx
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="values/routine.tsx">
    ```ts
    import { RegisteredCommitments } from "@drincs/nqtr";
    import { narration } from "@drincs/pixi-vn";
    import QuestionAnswerIcon from "@mui/icons-material/QuestionAnswer";
    import NqtrRoundIconButton from "../components/NqtrRoundIconButton";
    import { NARRATION_ROUTE } from "../constans";
    import { TALK_SLEEP_LABEL_KEY } from "../labels/variousActionsLabelKeys";
    import Commitment from "../models/nqtr/Commitment";
    import { alice } from "./characters";

    export const aliceSleep = new Commitment("alice_sleep", alice, {
        priority: 1,
        timeSlot: {
            from: 20,
            to: 10,
        },
        background: "alice_roomsleep0A",
        icon: (commitment, props) => {
            return (
                <NqtrRoundIconButton
                    disabled={commitment.disabled}
                    onClick={() => {
                        if (commitment.run) {
                            commitment.run(props);
                        }
                    }}
                    ariaLabel={commitment.name}
                    variant='solid'
                    color='primary'
                >
                    <QuestionAnswerIcon
                        sx={{
                            fontSize: { sx: "1.5rem", sm: "2rem", md: "2.5rem", lg: "3rem", xl: "3.5rem" },
                        }}
                    />
                </NqtrRoundIconButton>
            );
        },
        onRun: async (_, event) => {
            await event.navigate(NARRATION_ROUTE);
            await narration.jump(TALK_SLEEP_LABEL_KEY, event);
        },
    });

    RegisteredCommitments.add([aliceSleep]);
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Callout type="info">
  Commitments are linked to rooms in a one-to-many relationship, meaning that a room can have multiple commitments, but a commitment is present in only one room (a character cannot be in multiple rooms at the same time).
</Callout>

To use them, you need to link them to a `room` [through the `commitments` property](#navigation-and-map). This will also set the NPC positions, as the position of a commitment is deduced from the room it is linked to. When the player is in that room, they will see the active commitments and be able to interact with them.

Alternatively, during the narrative session, it is possible to add a commitment to a room using the `addCommitment` function.

For example:

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

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

  <CodeBlockTab value="ink">
    ```ink  groupId="narrative_language"
    == start ==
    # add routine alice_sleep in alice_room
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  groupId="narrative_language"
    import { newLabel } from "@drincs/pixi-vn";
    import { aliceSleep } from "../routine";
    import { aliceRoom } from "../rooms";

    const startLabel = newLabel("start", [
        async () => {
            aliceRoom.addCommitment(aliceSleep); // [!code focus]
        },
    ]);
    export default startLabel;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Quests [#quests]

<Callout type="info">
  You can find more detailed documentation about these elements <DynamicLink href="/nqtr/quest">here</DynamicLink>.
</Callout>

`Quest` represent an objective or a series of objectives that the player can complete during the game. Quests are composed of `stage`, which represent the different phases of a quest. Each stage has a specific objective and can be completed in different ways depending on the player's choices.

For example:

<CodeBlockTabs defaultValue="values/quests/aliceQuest.tsx">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="values/quests/aliceQuest.tsx">
      values/quests/aliceQuest.tsx
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="values/quests/aliceQuest.tsx">
    ```ts
    import { RegisteredCommitments, RegisteredQuests, routine } from "@drincs/nqtr";
    import { narration } from "@drincs/pixi-vn";
    import { NARRATION_ROUTE } from "../../constans";
    import { TALK_ALICE_QUEST_KEY } from "../../labels/variousActionsLabelKeys";
    import TimeSlotsImage from "../../models/TimeSlotsImage";
    import Commitment from "../../models/nqtr/Commitment";
    import Quest from "../../models/nqtr/Quest";
    import Stage from "../../models/nqtr/Stage";
    import { orderProduct, takeProduct } from "../activities";
    import { alice } from "../characters";
    import { mcRoom, terrace } from "../rooms";

    export const aliceQuest = new Quest(
        "aliceQuest",
        [
            // stages
            new Stage("talk_alice1", {
                onStart: () => {
                    terrace.addCommitment(aliceQuest_talk);
                },
                name: "Talk to Alice",
                description: "Talk to Alice on the terrace",
            }),
            new Stage("order_products", {
                onStart: () => {
                    mcRoom.addActivity(orderProduct);
                },
                name: "Order products",
                description: "Order the products with your PC",
            }),
            new Stage("take_products", {
                onStart: (_, { notify }) => {
                    terrace.addActivity(takeProduct);
                    notify("You can take the products on the Terrace");
                },
                name: "Take products",
                description: "Take products on the Terrace",
                requestDescriptionToStart: "Wait for the products you ordered to arrive (2 day)",
                deltaDateRequired: 2,
            }),
            new Stage("talk_alice2", {
                name: "Talk to Alice",
                description: "Talk to Alice on the terrace",
            }),
        ],
        {
            // props
            name: "Help Alice",
            description:
                'To learn more about how the repo works, Talk to Alice. \nGoing when she is there will automatically start an "Event" (see aliceQuest.tsx to learn more). \nAfter that an action will be added to open the pc, in MC room. \n\n(during the quest you can talk to Alice and you will see her talking during the quests of the same Quest)',
            image: "alice_terrace0A",
            onStart: (quest, { notify, uiTransition }) => {
                notify(uiTransition("notify_quest_is_started", { quest: quest.name }));
            },
            onContinue: (stage, { notify, uiTransition }) => {
                notify(uiTransition("notify_quest_is_updated", { quest: stage.name }));
            },
        },
    );

    RegisteredQuests.add(aliceQuest);

    const aliceQuest_talk = new Commitment("alice_quest_talk", alice, {
        timeSlot: {
            from: 10,
            to: 20,
        },
        image: new TimeSlotsImage("alice_terrace0A"),
        executionType: "automatic",
        priority: 1,
        onRun: async (_, props) => {
            await props.navigate(NARRATION_ROUTE);
            await narration.jump(TALK_ALICE_QUEST_KEY, props);
            routine.remove(aliceQuest_talk);
        },
    });

    RegisteredCommitments.add(aliceQuest_talk);
    ```
  </CodeBlockTab>
</CodeBlockTabs>

To start a quest, you need to call the `start` function on the quest itself. This will begin the first stage of the quest, allowing the player to start completing its objectives.

For example:

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

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

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    == start ==
    # start quest aliceQuest
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    import { newLabel } from "@drincs/pixi-vn";
    import { aliceQuest } from "../values/quests";

    const startLabel = newLabel("start", [
        async (props) => {
            await aliceQuest.start(props); // [!code focus]
        },
    ]);
    export default startLabel;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

To continue a quest that has already been started, you need to call the `continue` function on the quest itself. This will complete the current stage of the quest and move on to the next one.

For example:

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

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

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    == start ==
    # continue quest aliceQuest
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    import { newLabel } from "@drincs/pixi-vn";
    import { aliceQuest } from "../values/quests";

    const startLabel = newLabel("start", [
        async (props) => {
            await aliceQuest.continue(props); // [!code focus]
        },
    ]);
    export default startLabel;
    ```
  </CodeBlockTab>
</CodeBlockTabs>

During gameplay or narrative sequences, it is very useful to perform checks on the state of a quest, such as verifying whether a quest has been completed or if a specific stage has been reached. To do this, you can use various query functions available in the `Quest` class, such as `completed` or `failed`.

<Callout type="info">
  You can find a complete list of query functions in the `Quest` class documentation <DynamicLink href="/nqrt/quest#queries">here</DynamicLink>.
</Callout>

For example:

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

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

  <CodeBlockTab value="ink">
    ```ink  title="ink/variousActionsLabels.ink" groupId="narrative_language"
    === talkAliceQuest ===
    # show image background alice_terrace0At
    { aliceQuest_currentStageIndex:
    - 0:  -> talkAliceQuest0
    - 1:  -> talkAliceQuest1
    - 2:  -> talkAliceQuest2
    - else: alice: Thanks for the book.
    }
    -> DONE

    = talkAliceQuest0
    alice: Hi, can you order me a new book from pc?
    mc: Ok
    alice: Thanks
    # continue quest aliceQuest
    -> DONE

    = talkAliceQuest1
    mc: What book do you want me to order?
    alice: For me it is the same.
    -> DONE

    = talkAliceQuest2
    mc: I ordered the Book, hope you enjoy it.
    alice: Great, when it arrives remember to bring it to me.
    -> DONE

    = talkAliceQuest3
    mc: Here's your book.
    alice: Thank you, I can finally read something new.
    # continue quest aliceQuest
    -> DONE
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/variousActionsLabels.ts" groupId="narrative_language"
    import { newLabel } from "@drincs/pixi-vn";
    import { aliceQuest } from "../values/quests";

    export const talkAliceQuest = newLabel(
        TALK_ALICE_QUEST_KEY,
        () => {
            if (aliceQuest.currentStageIndex == 0) {
                return [
                    async () => {
                        narration.dialogue = { character: alice, text: "Hi, can you order me a new book from pc?" };
                    },
                    () => {
                        narration.dialogue = { character: mc, text: "Ok" };
                    },
                    () => {
                        narration.dialogue = { character: alice, text: "Thanks" };
                    },
                    (props) => {
                        aliceQuest.continue(props);
                        narration.continue(props);
                    },
                ];
            } else if (aliceQuest.currentStageIndex == 1) {
                return [
                    async () => {
                        narration.dialogue = { character: mc, text: "What book do you want me to order?" };
                    },
                    () => {
                        narration.dialogue = { character: alice, text: "For me it is the same." };
                    },
                ];
            } else if (aliceQuest.currentStageIndex == 2) {
                return [
                    async () => {
                        narration.dialogue = { character: mc, text: "I ordered the Book, hope you enjoy it." };
                    },
                    () => {
                        narration.dialogue = {
                            character: alice,
                            text: "Great, when it arrives remember to bring it to me.",
                        };
                    },
                ];
            } else if (aliceQuest.currentStageIndex == 3) {
                return [
                    async () => {
                        narration.dialogue = { character: mc, text: "Here's your book." };
                    },
                    () => {
                        narration.dialogue = { character: alice, text: "Thank you, I can finally read something new." };
                    },
                    (props) => {
                        aliceQuest.continue(props);
                        narration.continue(props);
                    },
                ];
            }
            return [
                () => {
                    narration.dialogue = { character: alice, text: "Thanks for the book." };
                },
            ];
        },
        {
            onStepStart: async (stepIndex) => {
                if (stepIndex == 0) {
                    await showImage(BACKGROUND_ID, "alice_terrace0At");
                }
            },
        },
    );
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Conclusion [#conclusion]

Now you know the basics for creating a Point & Click Adventure with Pixi’VN and NQTR. So far, we have only looked at the components provided by the template, but it is possible to create custom components to adapt them to the needs of your game. If you have some experience with JS/TS, I’m confident that by modifying the `.d.ts` files and creating classes that implement NQTR interfaces, you will be able to create custom components quickly and easily.

Make me proud by creating an amazing Point & Click Adventure with Pixi’VN and NQTR! 🚀

Now, you can try a small Point & Click Adventure created with the template to see in practice how the components work and interact with each other.

<iframe
  src="https://nqtr-react-template.firebaseapp.com/"
  title="Point & Click Adventure Demo"
  style="{
      width: &#x22;100%&#x22;,
      height: &#x22;400px&#x22;,
      border: &#x22;0&#x22;,
      borderRadius: &#x22;4px&#x22;,
      overflow: &#x22;hidden&#x22;,
  }"
  allowFullScreen="true"
/>


# Navigation and map (/nqtr/navigation)



<Callout title="Nomenclature" type="info">
  Usually in video games, navigation elements used to identify the position of characters are called room, location (e.g. restaurant, house, hospital, etc.), and map. For this reason, names that follow this logic are used.

  This does not prevent you from using these elements to manage navigation with the same logic but with different terms. For example, in a game set in space where the player moves between planets, rooms can be the planets, locations can be the solar systems, and maps can be the galaxy.
</Callout>

The navigation system is composed of the following elements:

* `rooms`: The core elements of navigation, from which the position of the `mc` and `npc` is deduced.
* `locations`: A container of `rooms`.
* `maps`: A container of `locations`.

The player can move between `rooms`. The `location` and the `map` are also determined based on the `room` in which the player is located.

Initialize [#initialize]

To initialize a `room`/`location`/`map`, create a new instance of the `RoomBaseModel` / `LocationBaseModel` / `MapBaseModel` class (or your [custom class](#custom-class)) and add it to the game room/location/map dictionary when the game is initialized.

<Callout type="info">
  It is recommended to import the instances at project startup, see the `src/main.ts` file.
</Callout>

To create a new instance of `RoomBaseModel`, you need the following parameters:

* `id`: A unique identifier (string). Used to reference the `room` in the game (must be unique).
* `location`: The `location` where the `room` is.
* `props`: An object with the room's properties:
  * `name` (Optional): The room's name.
  * `image` (Optional): The room's image URL.
  * `activities` (Optional): The <DynamicLink href="/nqtr/activity">activities</DynamicLink> available in this room.
  * `routine` (Optional): The <DynamicLink href="/nqtr/routine">commitments</DynamicLink> that run automatically when the player is in this room.
  * `disabled` (Optional): Whether the room is disabled. You can also pass a <DynamicLink href="/start/flags">Pixi’VN flag</DynamicLink> name.
  * `hidden` (Optional): Whether the room is hidden. You can also pass a <DynamicLink href="/start/flags">Pixi’VN flag</DynamicLink> name.
  * `icon` (Optional): The room's icon image URL.

To create a new instance of `LocationBaseModel`, you need the following parameters:

* `id`: A unique identifier (string). Used to reference the `location` in the game (must be unique).
* `map`: The `map` where the `location` is.
* `props`: An object with the location's properties:
  * `name` (Optional): The location's name.
  * `icon` (Optional): The location's icon image URL.
  * `activities` (Optional): The <DynamicLink href="/nqtr/activity">activities</DynamicLink> available in this location.
  * `disabled` (Optional): Whether the location is disabled. You can also pass a <DynamicLink href="/start/flags">Pixi’VN flag</DynamicLink> name.
  * `hidden` (Optional): Whether the location is hidden. You can also pass a <DynamicLink href="/start/flags">Pixi’VN flag</DynamicLink> name.

To create a new instance of `MapBaseModel`, you need the following parameters:

* `id`: A unique identifier (string). Used to reference the `map` in the game (must be unique).
* `props`: An object with the map's properties:
  * `name` (Optional): The map's name.
  * `image` (Optional): The map's image URL.
  * `activities` (Optional): The <DynamicLink href="/nqtr/activity">activities</DynamicLink> available in this map.

<CodeBlockTabs defaultValue="values/rooms.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="values/rooms.ts">
      values/rooms.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="values/locations.ts">
      values/locations.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="values/maps.ts">
      values/maps.ts
    </CodeBlockTabsTrigger>

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

  <CodeBlockTab value="values/rooms.ts">
    ```ts
    import { RegisteredRooms, RoomBaseModel } from "@drincs/nqtr";
    import { bed } from "./activities";
    import { mcHome } from "./locations";
    import { aliceSleep, aliceSmokes } from "./routine";

    export const mcRoom = new RoomBaseModel("mc_room", mcHome, {
        name: "MC room",
        image: "location_myroom",
        activities: [bed],
    });

    export const aliceRoom = new RoomBaseModel("alice_room", mcHome, {
        name: "Alice room",
        image: "location_aliceroom",
        routine: [aliceSleep],
    });

    export const annRoom = new RoomBaseModel("ann_room", mcHome, {
        name: "Ann room",
        image: "location_annroom",
    });

    export const bathroom = new RoomBaseModel("bathroom", mcHome, {
        name: "Bathroom",
        image: "location_bathroom",
    });

    export const lounge = new RoomBaseModel("lounge", mcHome, {
        name: "Lounge",
        image: "location_lounge",
    });

    export const terrace = new RoomBaseModel("terrace", mcHome, {
        name: "Terrace",
        image: "location_terrace",
        routine: [aliceSmokes],
    });

    RegisteredRooms.add([mcRoom, aliceRoom, annRoom, bathroom, lounge, terrace]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="values/locations.ts">
    ```ts
    import { LocationBaseModel, navigator, RegisteredLocations } from "@drincs/nqtr";
    import { mainMap } from "./maps";

    export const mcHome = new LocationBaseModel("mc_home", mainMap, {
        name: "MC Home",
    });

    export const gym = new LocationBaseModel("gym", mainMap, {
        name: "Gym",
    });

    export const school = new LocationBaseModel("school", mainMap, {
        name: "School",
    });

    RegisteredLocations.add([mcHome, gym, school]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="values/maps.ts">
    ```ts
    import { MapBaseModel, RegisteredMaps } from "@drincs/nqtr";

    export const mainMap = new MapBaseModel("main_map", {
        name: "Main Map",
        image: "map",
    });

    export const nightcityMap = new MapBaseModel("nightcity_map", {
        name: "Nightcity",
        image: "nightcity_map",
    });

    RegisteredMaps.add([mainMap, nightcityMap]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="main.ts">
    ```ts
    import "./values/rooms";
    import "./values/locations";
    import "./values/maps";

    // ...
    ```
  </CodeBlockTab>
</CodeBlockTabs>

`RegisteredRooms.add` / `RegisteredLocations.add` / `RegisteredMaps.add` is **required** to save the `rooms`/`locations`/`maps` in the game.

You can also create a function to load `rooms`/`locations`/`maps`. The important thing is that it is called at least once before the `rooms`/`locations`/`maps` are used in the game, otherwise they will not be available.

It is also recommended to [set the current room](#navigate) during the start of the game.

```ts title="labels/startLabel.ts"
import { navigator } from "@drincs/nqtr";
import { newLabel } from "@drincs/pixi-vn";
import { mcRoom } from "../values/rooms";

const startLabel = newLabel("start", [
    async () => {
        navigator.currentRoom = mcRoom;
        // ... other initialization logic
    },
]);
export default startLabel;
```

Get [#get]

To get a `room`/`location`/`map` by its `id`, use the `RegisteredRooms.get` / `RegisteredLocations.get` / `RegisteredMaps.get` function.

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

    <CodeBlockTabsTrigger value="Locations">
      Locations
    </CodeBlockTabsTrigger>

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

  <CodeBlockTab value="Rooms">
    ```ts
    import { RegisteredRooms } from "@drincs/nqtr";

    const mcRoom = RegisteredRooms.get('mc_room');
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Locations">
    ```ts
    import { RegisteredLocations } from "@drincs/nqtr";

    const mcHome = RegisteredLocations.get('mc_home');
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Maps">
    ```ts
    import { RegisteredMaps } from "@drincs/nqtr";

    const mainMap = RegisteredMaps.get('main_map');
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Get all [#get-all]

To get all `rooms`/`locations`/`maps`, use the `RegisteredRooms.values` / `RegisteredLocations.values` / `RegisteredMaps.values` function.

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

    <CodeBlockTabsTrigger value="Locations">
      Locations
    </CodeBlockTabsTrigger>

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

  <CodeBlockTab value="Rooms">
    ```ts
    import { RegisteredRooms } from "@drincs/nqtr";

    const rooms = RegisteredRooms.values();
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Locations">
    ```ts
    import { RegisteredLocations } from "@drincs/nqtr";

    const locations = RegisteredLocations.values();
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Maps">
    ```ts
    import { RegisteredMaps } from "@drincs/nqtr";

    const maps = RegisteredMaps.values();
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Navigate [#navigate]

As explained above, the player can navigate between `rooms`, and the current `room` determines the current `location` and `map`.

To navigate to a `room`, set the `navigator.currentRoom` property to the desired room instance. This will automatically update the current `location` and `map` based on the room's location and map.

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

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

  <CodeBlockTab value="Typescript">
    ```ts  title="index.ts" groupId="narrative_language"
    import { navigator } from "@drincs/nqtr";
    import { mcRoom } from "../values/rooms";

    navigator.currentRoom = mcRoom;
    ```
  </CodeBlockTab>

  <CodeBlockTab value="ink">
    ```ink  title="index.ink" groupId="narrative_language"
    // {roomId} is the id of the room
    # enter room {roomId}
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Custom class [#custom-class]

<Callout title="Templates" type="info">
  In all templates, the `Room` / `Location` / `Map` class is already defined in the file `models/nqtr/Room.ts` / `models/nqtr/Location.ts` / `models/nqtr/Map.ts`. You can use it directly or modify it to suit your needs.
</Callout>

It is recommended to create your own class `Room` / `Location` / `Map` that extends `RoomStoredClass` / `LocationStoredClass` / `MapStoredClass` and "override" the interface `RoomInterface` / `LocationInterface` / `MapInterface` to add, edit, or remove properties or methods.

For example, if you want to create a class `Room` / `Location` / `Map`, you must "override" the interface `RoomInterface` / `LocationInterface` / `MapInterface` to use your properties or methods. (See the file `nqtr.d.ts`)

Now you can create a class `Room` / `Location` / `Map` that extends `RoomStoredClass` / `LocationStoredClass` / `MapStoredClass` and implements the `RoomInterface` / `LocationInterface` / `MapInterface`. (For more information on how to create a class in TypeScript, read [the official documentation](https://www.typescriptlang.org/docs/handbook/2/classes.html))

To create a property that stores its value in the game storage, you can create [Getters/Setters](https://www.typescriptlang.org/docs/handbook/2/classes.html#getters--setters) and use the `this.getStorageProperty()` / `this.setStorageProperty()` methods. (See the file `Room.ts` / `Location.ts` / `Map.ts`)

<CodeBlockTabs defaultValue="models/nqtr/Room.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="models/nqtr/Room.ts">
      models/nqtr/Room.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="models/nqtr/Location.ts">
      models/nqtr/Location.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="models/nqtr/Map.ts">
      models/nqtr/Map.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="nqtr.d.ts">
      nqtr.d.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="models/nqtr/Room.ts">
    ```ts
    import {
        ActivityInterface,
        CommitmentInterface,
        LocationInterface,
        OnRunProps,
        RoomInterface,
        RoomStoredClass,
    } from "@drincs/nqtr";
    import { PixiUIParam, PixiUIProp } from "./ui-elements";

    export default class Room extends RoomStoredClass implements RoomInterface {
        constructor(
            id: string,
            location: LocationInterface,
            props: {
                name: string;
                disabled?: boolean | (() => boolean);
                hidden?: boolean | (() => boolean);
                background: PixiUIParam<Room>;
                activities?: ActivityInterface[];
                routine?: CommitmentInterface[];
                isEntrance?: boolean;
            },
        ) {
            super(id, location, {
                activities: props.activities || [],
                routine: props.routine || [],
            });
            this.name = props.name;
            this._defaultDisabled = props.disabled || false;
            this._defaultHidden = props.hidden || false;
            this._background = props.background;
            this.isEntrance = props.isEntrance || false;
        }
        readonly name: string;
        private readonly _background: PixiUIParam<Room>;
        get background(): PixiUIProp {
            const background = this._background;
            if (typeof background === "function") {
                return (runProps: OnRunProps) => background(this, runProps);
            }
            return background;
        }
        readonly isEntrance: boolean;
        private _defaultDisabled: boolean | (() => boolean) = false;
        get disabled(): boolean {
            let value = this.getStorageProperty<boolean>("disabled") || this._defaultDisabled;
            if (typeof value === "function") {
                return value();
            }
            return value;
        }
        set disabled(value: boolean) {
            this.setStorageProperty("disabled", value);
        }
        private _defaultHidden: boolean | (() => boolean) = false;
        get hidden(): boolean {
            let value = this.getStorageProperty<boolean>("hidden") || this._defaultHidden;
            if (typeof value === "function") {
                return value();
            }
            return value;
        }
        set hidden(value: boolean) {
            this.setStorageProperty("hidden", value);
        }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="models/nqtr/Location.ts">
    ```ts
    import {
        ActivityInterface,
        LocationInterface,
        LocationStoredClass,
        MapInterface,
        OnRunProps,
        RoomInterface,
    } from "@drincs/nqtr";
    import { PixiUIParam, PixiUIProp } from "./ui-elements";

    export default class Location extends LocationStoredClass implements LocationInterface {
        constructor(
            id: string,
            map: MapInterface,
            props: {
                activities?: ActivityInterface[];
                name: string;
                disabled?: boolean | (() => boolean);
                hidden?: boolean | (() => boolean);
                sprite: PixiUIParam<Location>;
            },
        ) {
            super(id, map, props.activities);
            this.name = props.name;
            this._defaultDisabled = props.disabled || false;
            this._defaultHidden = props.hidden || false;
            this._sprite = props.sprite;
        }
        readonly name: string;
        private readonly _sprite: PixiUIParam<Location>;
        get sprite(): PixiUIProp {
            let sprite = this._sprite;
            if (typeof sprite === "function") {
                return (runProps: OnRunProps) => sprite(this, runProps);
            }
            return sprite;
        }
        private _defaultDisabled: boolean | (() => boolean) = false;
        get disabled(): boolean {
            let value = this.getStorageProperty<boolean>("disabled") || this._defaultDisabled;
            if (typeof value === "function") {
                return value();
            }
            return value;
        }
        set disabled(value: boolean) {
            this.setStorageProperty("disabled", value);
        }
        private _defaultHidden: boolean | (() => boolean) = false;
        get hidden(): boolean {
            let value = this.getStorageProperty<boolean>("hidden") || this._defaultHidden;
            if (typeof value === "function") {
                return value();
            }
            return value;
        }
        set hidden(value: boolean) {
            this.setStorageProperty("hidden", value);
        }
        override get rooms(): RoomInterface[] {
            return super.rooms.filter((room) => !room.hidden);
        }
        get entrance(): RoomInterface | undefined {
            if (super.rooms.length === 0) {
                return undefined;
            }
            return super.rooms.find((room) => room.isEntrance) || super.rooms[0];
        }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="models/nqtr/Map.ts">
    ```ts
    import { ActivityInterface, LocationInterface, MapInterface, MapStoredClass, OnRunProps } from "@drincs/nqtr";
    import { PixiUIParam, PixiUIProp } from "./ui-elements";

    export default class Map extends MapStoredClass implements MapInterface {
        constructor(
            id: string,
            props: {
                activities?: ActivityInterface[];
                name: string;
                background: PixiUIParam<Map>;
            },
        ) {
            super(id, props.activities);
            this.name = props.name;
            this._background = props.background;
        }
        readonly name: string;
        private readonly _background: PixiUIParam<Map>;
        get background(): PixiUIProp {
            const background = this._background;
            if (typeof background === "function") {
                return (runProps: OnRunProps) => background(this, runProps);
            }
            return background;
        }
        override get locations(): LocationInterface[] {
            return super.locations.filter((location) => !location.hidden);
        }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="nqtr.d.ts">
    ```ts
    import { PixiUIProp } from "./models/nqtr/ui-elements";

    declare module "@drincs/nqtr" {
        interface RoomInterface {
            /**
             * The name.
             * If you set undefined, it will return the initial value of name.
             */
            readonly name: string;
            /**
             * The background of the room.
             */
            readonly background: PixiUIProp;
            /**
             * Whether is disabled.
             */
            disabled: boolean;
            /**
             * Whether is hidden.
             */
            hidden: boolean;
            /**
             * If is the entrance of the location. (the first room)
             */
            readonly isEntrance: boolean;
        }
        interface LocationInterface {
            /**
             * The name of the location.
             * If you set undefined, it will return the initial value of name.
             */
            readonly name: string;
            /**
             * Whether is disabled.
             */
            disabled: boolean;
            /**
             * Whether is hidden.
             */
            hidden: boolean;
            /**
             * The sprite of the location.
             */
            readonly sprite: PixiUIProp;
            /**
             * The entrance room of the location.
             */
            readonly entrance: RoomInterface | undefined;
        }
        interface MapInterface {
            /**
             * The name of the map.
             */
            readonly name: string;
            /**
             * The background of the map.
             */
            readonly background: PixiUIProp;
        }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

FAQ [#faq]

<Accordions>
  <Accordion title="how_set_default_room_for_location" id="how-set-default-room-for-location">
    The developer can designate an "index" `room` for locations.

    To set a default room for a location, you can add in your [Custom class](#custom-class) a property `isEntrance` to the `Room` class, which will be set to `true` for the default room of the location, and then use the `entrance` property of the `Location` class to get the default room.

    For example:

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

        <CodeBlockTabsTrigger value="models/nqtr/Room.ts">
          models/nqtr/Room.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="models/nqtr/Location.ts">
          models/nqtr/Location.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="nqtr.d.ts">
          nqtr.d.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="mcRoom.ts">
        ```ts
        import { navigator, RegisteredRooms } from "@drincs/nqtr";
        import { ImageSprite } from "@drincs/pixi-vn";
        import { NAVIGATION_ROUTE } from "../constans";
        import Location from "../models/nqtr/Location";
        import Room from "../models/nqtr/Room";
        import { mainMap } from "./maps";

        export const mcHome = new Location("mc_home", mainMap, {
            name: "MC Home",
            icon: (location, { navigate }) => {
                const icon = new ImageSprite(
                    { xAlign: 0.3, yAlign: 0.2, height: 120, width: 120, eventMode: "static", cursor: "pointer" },
                    "icon_location_home"
                );
                icon.on("pointerdown", () => {
                    const entrance = location.entrance;
                    if (entrance) {
                        navigator.currentRoom = entrance;
                        navigate(NAVIGATION_ROUTE);
                    }
                });
                icon.load();
                return icon;
            },
        });

        export const mcRoom = new Room("mc_room", mcHome, {
            name: "MC room",
            image: "location_myroom",
            isEntrance: true, // This room is the entrance of the location
        });

        RegisteredRooms.add([mcRoom]);
        ```
      </CodeBlockTab>

      <CodeBlockTab value="models/nqtr/Room.ts">
        ```ts
        import { RoomInterface, RoomStoredClass } from "@drincs/nqtr";

        export default class Room extends RoomStoredClass implements RoomInterface {
            constructor() {
                // ... other initializations
                this.isEntrance = props.isEntrance || false;
            }
            // ... other methods and properties
            readonly isEntrance: boolean;
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="models/nqtr/Location.ts">
        ```ts
        import { LocationInterface, LocationStoredClass, RoomInterface } from "@drincs/nqtr";

        export default class Location extends LocationStoredClass implements LocationInterface {
            // ... other methods and properties
            get entrance(): RoomInterface | undefined {
                if (super.rooms.length === 0) {
                    return undefined;
                }
                return super.rooms.find((room) => room.isEntrance) || super.rooms[0];
            }
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="nqtr.d.ts">
        ```ts
        declare module "@drincs/nqtr" {
            interface LocationInterface {
                /**
                 * The entrance room of the location.
                 */
                readonly entrance: RoomInterface | undefined;
            }
            interface RoomInterface {
                /**
                 * If is the entrance of the location. (the first room)
                 */
                readonly isEntrance: boolean;
            }
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>
</Accordions>


# Quests (/nqtr/quest)



The quest system is a way to create and manage quests in your game. Quests can have multiple stages, and players can complete them to earn rewards or progress in the story.

Initialize [#initialize]

To initialize a `quest`, create a new instance of the `QuestBaseModel` class (or your [custom class](#custom-class)) and add it to the game quest dictionary when the game is initialized.

<Callout type="info">
  It is recommended to import the instances at project startup, see the `src/main.ts` file.
</Callout>

To create a new instance of `QuestBaseModel`, you need the following parameters:

<CodeBlockTabs defaultValue="values/aliceQuest.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="values/aliceQuest.ts">
      values/aliceQuest.ts
    </CodeBlockTabsTrigger>

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

  <CodeBlockTab value="values/aliceQuest.ts">
    ```ts
    import { QuestBaseModel, RegisteredQuests, StageBaseModel } from "@drincs/nqtr";
    import { orderProduct, takeProduct } from "../quests";
    import { mcRoom, terrace } from "../rooms";

    export const aliceQuest = new QuestBaseModel(
        "aliceQuest",
        [
            // stages
            new StageBaseModel("talk_alice1", {
                name: "Talk to Alice",
                description: "Talk to Alice on the terrace",
            }),
            new StageBaseModel("order_products", {
                onStart: () => {
                    mcRoom.addActivity(orderProduct);
                },
                name: "Order products",
                description: "Order the products with your PC",
            }),
            new StageBaseModel("take_products", {
                onStart: (_, { notify }) => {
                    terrace.addActivity(takeProduct);
                    notify("You can take the products on the Terrace");
                },
                name: "Take products",
                description: "Take products on the Terrace",
                requestDescriptionToStart: "Wait for the products you ordered to arrive (2 day)",
                deltaDateRequired: 2,
            }),
            new StageBaseModel("talk_alice2", {
                name: "Talk to Alice",
                description: "Talk to Alice on the terrace",
            }),
        ],
        {
            // props
            name: "Help Alice",
            description:
                'To learn more about how the repo works, Talk to Alice. \nGoing when she is there will automatically start an "Event" (see aliceQuest.tsx to learn more). \nAfter that an action will be added to open the pc, in MC room. \n\n(during the quest you can talk to Alice and you will see her talking during the quests of the same Quest)',
            image: "alice_terrace0A",
            onStart: (quest, { notify, uiTransition }) => {
                notify(uiTransition("notify_quest_is_started", { quest: quest.name }));
            },
            onContinue: (stage, { notify, uiTransition }) => {
                notify(uiTransition("notify_quest_is_updated", { quest: stage.name }));
            },
        }
    );

    RegisteredQuests.add(aliceQuest);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="main.ts">
    ```ts
    import "./values/aliceQuest";

    // ...
    ```
  </CodeBlockTab>
</CodeBlockTabs>

`RegisteredQuests.add` is **required** to save the `quests` in the game.

You can also create a function to load `quests`. The important thing is that it is called at least once before the `quests` are used in the game, otherwise they will not be available.

Start [#start]

To start a `quest`, you can use the `start` method of the Quest class. This method will set the current stage to the first stage of the quest and trigger the `onStart` action defined in the quest. This function has the following parameters:

* `props`: the properties that will be passed to `onStart`. Its interface corresponds to <DynamicLink href="/nqtr#onrunprops">`OnRunProps`</DynamicLink>.

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

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

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    import { newLabel } from "@drincs/pixi-vn";
    import { aliceQuest } from "../values/quests";

    const startLabel = newLabel("start", [
        async (props) => {
            await aliceQuest.start(props); // [!code focus]
        },
    ]);
    export default startLabel;
    ```
  </CodeBlockTab>

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    === start ===
    //  {aliceQuest} the id of the quest
    # start quest {aliceQuest}
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Continue [#continue]

To go to the next stage of a `quest`, you can use the `continue` method of the Quest class. This method will set the current stage to the next stage of the quest and trigger the `onContinue` action defined in the quest. This function has the following parameters:

* `props`: the properties that will be passed to `onContinue`. Its interface corresponds to <DynamicLink href="/nqtr#onrunprops">`OnRunProps`</DynamicLink>.

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

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

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    import { newLabel } from "@drincs/pixi-vn";
    import { aliceQuest } from "../values/quests";

    const startLabel = newLabel("start", [
        async (props) => {
            await aliceQuest.continue(props); // [!code focus]
        },
    ]);
    export default startLabel;
    ```
  </CodeBlockTab>

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    === start ===
    //  {aliceQuest} the id of the quest
    # continue quest {aliceQuest}
    ```
  </CodeBlockTab>
</CodeBlockTabs>

<Accordions>
  <Accordion title="go_next_only_if_is_completed" id="go-next-only-if-is-completed">
    To go to the next stage of a `quest` only if the current stage is completed, you can use the `advanceIfCompleted` method of the Quest class. This method will check if the current stage is completed and then set the current stage to the next stage of the quest and trigger the `onContinue` action defined in the quest. This function has the following parameters:

    * `props`: the properties that will be passed to `onContinue`. Its interface corresponds to <DynamicLink href="/nqtr#onrunprops">`OnRunProps`</DynamicLink>.

    <CodeBlockTabs defaultValue="labels/startLabel.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="labels/startLabel.ts">
          labels/startLabel.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="labels/startLabel.ts">
        ```ts
        import { newLabel } from "@drincs/pixi-vn";
        import { aliceQuest } from "../values/quests";

        const startLabel = newLabel("start", [
            async (props) => {
                await aliceQuest.advanceIfCompleted(props); // [!code focus]
            },
        ]);
        export default startLabel;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>
</Accordions>

Get [#get]

To get a `quest` by its `id`, use the `RegisteredQuests.get` function.

```ts
import { RegisteredQuests } from "@drincs/nqtr";

const aliceQuest = RegisteredQuests.get('aliceQuest');
```

Get all [#get-all]

To get all `quests`, use the `RegisteredQuests.values` function.

```ts
import { RegisteredQuests } from "@drincs/nqtr";

const quests = RegisteredQuests.values();
```

Custom class [#custom-class]

<Callout title="Templates" type="info">
  In all templates, the `Quest` class is already defined in the file `models/nqtr/Quest.ts`. You can use it directly or modify it to suit your needs.
</Callout>

It is recommended to create your own class `Quest` that extends `QuestStoredClass` and "override" the interface `QuestInterface` to add, edit, or remove properties or methods.

For example, if you want to create a class `Quest`, you must "override" the interface `QuestInterface` to use your properties or methods. (See the file `nqtr.d.ts`)

Now you can create a class `Quest` that extends `QuestStoredClass` and implements the `QuestInterface`. (For more information on how to create a class in TypeScript, read [the official documentation](https://www.typescriptlang.org/docs/handbook/2/classes.html))

To create a property that stores its value in the game storage, you can create [Getters/Setters](https://www.typescriptlang.org/docs/handbook/2/classes.html#getters--setters) and use the `this.getStorageProperty()` / `this.setStorageProperty()` methods. (See the file `Quest.ts`)

<CodeBlockTabs defaultValue="models/nqtr/Quest.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="models/nqtr/Quest.ts">
      models/nqtr/Quest.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="nqtr.d.ts">
      nqtr.d.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="models/nqtr/Quest.ts">
    ```ts
    import { QuestInterface, QuestStoredClass, QuestStoredClassProps, StageInterface } from "@drincs/nqtr";

    export default class Quest extends QuestStoredClass implements QuestInterface {
        constructor(
            id: string,
            _stages: StageInterface[],
            props: {
                name?: string;
                description?: string;
                image?: string;
                inDevelopment?: boolean;
            } & QuestStoredClassProps
        ) {
            super(id, _stages, props);
            this.name = props.name || "";
            this.description = props.description || "";
            this.image = props.image;
            this.inDevelopment = props.inDevelopment || false;
        }
        readonly name: string;
        readonly description: string;
        readonly image?: string;
        readonly inDevelopment: boolean;
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="nqtr.d.ts">
    ```ts
    declare module "@drincs/nqtr" {
        interface QuestInterface {
            /**
             * The name of the quest.
             */
            readonly name: string;
            /**
             * The description of the quest.
             */
            readonly description: string;
            /**
             * The image of the quest.
             */
            readonly image?: string;
            /**
             * If the quest is in development.
             */
            readonly inDevelopment: boolean;
        }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

FAQ [#faq]

<Accordions>
  <Accordion title="fail_quest" id="fail-quest">
    To fail a quest, you can use the `failed` property of the `QuestBaseModel` class. This property is a boolean that indicates whether the quest has been failed or not. You can set it to `true` to fail the quest.

    <CodeBlockTabs defaultValue="labels/startLabel.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="labels/startLabel.ts">
          labels/startLabel.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="labels/startLabel.ts">
        ```ts
        import { newLabel } from "@drincs/pixi-vn";
        import { aliceQuest } from "../values/quests";

        const startLabel = newLabel("start", [
            async (props) => {
                aliceQuest.failed = true; // [!code focus]
            },
        ]);
        export default startLabel;
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="queries" id="queries">
    To query the state of a quest, you can use the following properties and methods:

    `currentStageIndex`: the index of the current stage of the quest. It starts at `0` and goes up to `stages.length - 1`. If the quest is completed, it will be equal to `stages.length`.

    * `started`: a boolean that indicates whether the quest has been started or not.
    * `completed`: a boolean that indicates whether the quest has been completed or not.
    * `failed`: a boolean that indicates whether the quest has been failed or not.

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

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

      <CodeBlockTab value="Typescript">
        ```ts  title="labels/startLabel.ts" groupId="narrative_language"
        import { newLabel } from "@drincs/pixi-vn";
        import { aliceQuest } from "../values/quests";

        const startLabel = newLabel("start", [
            async () => {
                await showImage(BACKGROUND_ID, "alice_terrace0At");
                narration.dialogue = { character: alice, text: "Hi, what do you want to talk about?" };
                let optionsMenu: StoredChoiceInterface[] = [];
                if (aliceQuest.started) { // [!code focus]
                    optionsMenu.push(newChoiceOption("Quest started", startLabel, {}));
                }
                if (aliceQuest.completed) { // [!code focus]
                    optionsMenu.push(newChoiceOption("Quest completed", startLabel, {}));
                }
                if (aliceQuest.failed) { // [!code focus]
                    optionsMenu.push(newChoiceOption("Quest failed", startLabel, {}));
                }
                if (aliceQuest.currentStageIndex === 3) { // [!code focus]
                    optionsMenu.push(newChoiceOption("Quest not started", startLabel, {}));
                }
                narration.choices = [...optionsMenu, newCloseChoiceOption("Cancel")];
            },
        ]);
        export default startLabel;
        ```
      </CodeBlockTab>

      <CodeBlockTab value="ink">
        ```ink  title="ink/start.ink" groupId="narrative_language"
        === start ===
        //  {aliceQuest} the id of the quest
        + {aliceQuest_started} Quest started
            -> start
        + {aliceQuest_completed} Quest completed
            -> start
        + {aliceQuest_failed} Quest failed
            -> start
        + {aliceQuest_currentStageIndex == 3} Quest not started
            -> start
        + Cancel
            -> DONE
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>
</Accordions>


# Routine (/nqtr/routine)



Initialize [#initialize]

To initialize a `commitment`, create a new instance of the `CommitmentBaseModel` class (or your [custom class](#custom-class)) and add it to the game commitment dictionary when the game is initialized.

<Callout type="info">
  It is recommended to import the instances at project startup, see the `src/main.ts` file.
</Callout>

To create a new instance of `CommitmentBaseModel`, you need the following parameters:

* `id`: A unique identifier (string). Used to reference the `commitment` in the game (must be unique).
* `character`: The character or characters that are in the commitment and so in the room. It can be a single character or an array of characters.
* `props`: An object with the commitment's properties:
  * `name`: The name of the commitment (Optional).
  * `image`: The image of the commitment (Optional). It can be a string with the path to the image or a function that returns a `ContainerChild` (Optional).
  * `icon`: The React icon of the commitment (Optional). It can be a React element or a function that returns a React element (Optional).
  * `onRun`: A function that is called when the commitment is run. It receives two parameters:
    * The `commitment` instance itself.
    * `event`: The event that triggered the run. It is an instance of `OnRunEvent<CommitmentInterface>`, which contains methods to navigate to other routes, jump to labels, and more.
  * `disabled`: Whether the commitment is disabled. It can be a boolean or a function that returns a boolean (optional, default is `false`). If it is disabled, this commitment will not be taken into consideration, so the characters will not be in the room, but will be busy with other commitments.
  * `hidden`: Whether the commitment is hidden. It can be a boolean or a function that returns a boolean (optional, default is `false`). If it is hidden, the commitment will not be displayed in the UI.
  * `priority`: The priority of the commitment. The higher the number, the higher the priority (optional, default is `0`).
  * `executionType`: The execution type of the commitment. It can be "automatic" or "interaction". If it is "automatic", the `onRun` function will be called automatically when the player is in the room. If it is "interaction", the player must interact with the character to run the `onRun` function (optional, default is "interaction").
  * `dateScheduling`: Used to schedule what date it will be added and removed. It is an instance of `DateSchedulingInterface` (Optional).
  * `timeSlot`: The time slot in which the commitment will be active. It is an instance of `TimeSchedulingInterface` (Optional).

<CodeBlockTabs defaultValue="values/routine.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="values/routine.ts">
      values/routine.ts
    </CodeBlockTabsTrigger>

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

  <CodeBlockTab value="values/routine.ts">
    ```ts
    import { CommitmentBaseModel, RegisteredCommitments } from "@drincs/nqtr";
    import { narration } from "@drincs/pixi-vn";
    import { NARRATION_ROUTE } from "../constans";
    import { TALK_SLEEP_LABEL_KEY } from "../labels/variousActionsLabelKeys";
    import { aliceTalkMenuLabel } from "../labels/variousActionsLabels";
    import { alice } from "./characters";

    export const aliceSleep = new CommitmentBaseModel("alice_sleep", alice, {
        priority: 1,
        timeSlot: {
            from: 20,
            to: 10,
        },
        onRun: async (_, event) => {
            await event.navigate(NARRATION_ROUTE);
            await narration.jump(TALK_SLEEP_LABEL_KEY, event);
        },
    });

    export const aliceGoSchool = new CommitmentBaseModel("alice_go_school", alice, {
        timeSlot: {
            from: 8,
            to: 14,
        },
        priority: 2,
    });

    export const aliceSmokes = new CommitmentBaseModel("alice_smokes", alice, {
        timeSlot: {
            from: 10,
            to: 20,
        },
        onRun: async (_, event) => {
            await event.navigate(NARRATION_ROUTE);
            await narration.jump(aliceTalkMenuLabel, event);
        },
    });

    RegisteredCommitments.add([aliceSleep, aliceGoSchool, aliceSmokes]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="main.ts">
    ```ts
    import "./values/routine";

    // ...
    ```
  </CodeBlockTab>
</CodeBlockTabs>

`RegisteredCommitments.add` is **required** to save the `commitments` in the game.

You can also create a function to load `commitments`. The important thing is that it is called at least once before the `commitments` are used in the game, otherwise they will not be available.

Link [#link]

For an `commitment` to be linked to a `room`, the `room` must be included in the `Commitment` instance. The relationship between a `commitment` and a `room` is one-to-many, meaning that a `rooms` can be linked to multiple `commitments`, but a `commitment` can only be linked to one `room` (a character cannot be in two places at the same time).

There are two ways to do this:

During game initialization [#during-game-initialization]

For a `commitment` to be available to the player, it must be linked to a `room`.

<CodeBlockTabs defaultValue="values/rooms.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="values/rooms.ts">
      values/rooms.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="values/routine.ts">
      values/routine.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="values/rooms.ts">
    ```ts
    import { RegisteredRooms, RoomBaseModel } from "@drincs/nqtr";
    import { mcHome } from "./locations";
    import { aliceSleep } from "./routine";

    export const aliceRoom = new RoomBaseModel("alice_room", mcHome, {
        name: "Alice room",
        background: "location_aliceroom",
        routine: [aliceSleep], // [!code ++]
    });

    RegisteredRooms.add([aliceRoom]);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="values/routine.ts">
    ```ts
    import { CommitmentBaseModel, RegisteredCommitments } from "@drincs/nqtr";
    import { narration } from "@drincs/pixi-vn";
    import { NARRATION_ROUTE } from "../constans";
    import { TALK_SLEEP_LABEL_KEY } from "../labels/variousActionsLabelKeys";
    import { alice } from "./characters";

    export const aliceSleep = new CommitmentBaseModel("alice_sleep", alice, {
        priority: 1,
        timeSlot: {
            from: 20,
            to: 10,
        },
        onRun: async (_, event) => {
            await event.navigate(NARRATION_ROUTE);
            await narration.jump(TALK_SLEEP_LABEL_KEY, event);
        },
    });

    RegisteredCommitments.add([aliceSleep]);
    ```
  </CodeBlockTab>
</CodeBlockTabs>

During the game [#during-the-game]

You can also link a commitment to a room during the game. This feature is useful if you want to temporarily add a commitment. The list of routine added this way will be included in your game saves.

To link a commitment to a room during the game, you can use the `addCommitment` method.

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

    <CodeBlockTabsTrigger value="ink">
      ink
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="values/routine.ts">
      values/routine.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Typescript">
    ```ts  title="labels/startLabel.ts" groupId="narrative_language"
    import { newLabel, showImageContainer } from "@drincs/pixi-vn";
    import { aliceSmokes } from "../routine";
    import { terrace } from "../rooms";

    const startLabel = newLabel("start", [
        async () => {
            terrace.addCommitment(aliceSmokes); // [!code focus]
        },
    ]);
    export default startLabel;
    ```
  </CodeBlockTab>

  <CodeBlockTab value="ink">
    ```ink  title="ink/start.ink" groupId="narrative_language"
    == start ==
    // {alice_smokes} is the id of the commitment
    # add routine {alice_smokes} in terrace
    ```
  </CodeBlockTab>

  <CodeBlockTab value="values/routine.ts">
    ```ts
    import { CommitmentBaseModel, RegisteredCommitments } from "@drincs/nqtr";
    import { narration } from "@drincs/pixi-vn";
    import { NARRATION_ROUTE } from "../constans";
    import { aliceTalkMenuLabel } from "../labels/variousActionsLabels";
    import { alice } from "./characters";

    export const aliceSmokes = new CommitmentBaseModel("alice_smokes", alice, {
        timeSlot: {
            from: 10,
            to: 20,
        },
        onRun: async (_, event) => {
            await event.navigate(NARRATION_ROUTE);
            await narration.jump(aliceTalkMenuLabel, event);
        },
    });

    RegisteredCommitments.add([aliceSmokes]);
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Unlink [#unlink]

To detach a `commitment` from a `room`, you must first consider how it was linked.

If it was linked during the game initialization, it cannot be removed. However, you can add another `commitment` with the same character at the same time slot, so the character will be occupied with the new `commitment` and therefore will no longer be present in the previous `room`. By default, priority is given to the `commitment` added during gameplay over the one added during initialization, but this behavior can be modified using the `priority` property.

If it was linked during gameplay, it can be removed using the `removeCommitment` method.

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

    <CodeBlockTabsTrigger value="ink">
      ink
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="values/routine.ts">
      values/routine.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Typescript">
    ```ts  title="index.ts" groupId="narrative_language"
    import { aliceSmokes } from "../routine";
    import { routine } from "@drincs/nqtr";

    routine.remove(aliceSmokes);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="ink">
    ```ink  title="index.ink" groupId="narrative_language"
    // {alice_smokes} is the id of the commitment
    # remove routine {alice_smokes}
    ```
  </CodeBlockTab>

  <CodeBlockTab value="values/routine.ts">
    ```ts
    import { CommitmentBaseModel, RegisteredCommitments } from "@drincs/nqtr";
    import { narration } from "@drincs/pixi-vn";
    import { NARRATION_ROUTE } from "../constans";
    import { aliceTalkMenuLabel } from "../labels/variousActionsLabels";
    import { alice } from "./characters";
    import { terrace } from "./rooms";

    const aliceSmokes = new CommitmentBaseModel("alice_smokes", alice, terrace, {
        timeSlot: {
            from: 10,
            to: 20,
        },
        onRun: (_, event) => {
            event.navigate(NARRATION_ROUTE);
            narration.jump(aliceTalkMenuLabel, event);
        },
    });

    RegisteredCommitments.add([aliceSmokes]);
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Get [#get]

To get a `commitment` by its `id`, use the `RegisteredCommitments.get` function.

```ts
import { RegisteredCommitments } from "@drincs/nqtr";

const aliceWorks = RegisteredCommitments.get('alice_works');
```

Get all [#get-all]

To get all `commitments`, use the `RegisteredCommitments.values` function.

```ts
import { RegisteredCommitments } from "@drincs/nqtr";

const commitments = RegisteredCommitments.values();
```

Custom class [#custom-class]

<Callout title="Templates" type="info">
  In all templates, the `Commitment` class is already defined in the file `models/nqtr/Commitment.ts`. You can use it directly or modify it to suit your needs.
</Callout>

It is recommended to create your own class `Commitment` that extends `CommitmentStoredClass` and "override" the interface `CommitmentInterface` to add, edit, or remove properties or methods.

For example, if you want to create a class `Commitment`, you must "override" the interface `CommitmentInterface` to use your properties or methods. (See the file `nqtr.d.ts`)

Now you can create a class `Commitment` that extends `CommitmentStoredClass` and implements the `CommitmentInterface`. (For more information on how to create a class in TypeScript, read [the official documentation](https://www.typescriptlang.org/docs/handbook/2/classes.html))

To create a property that stores its value in the game storage, you can create [Getters/Setters](https://www.typescriptlang.org/docs/handbook/2/classes.html#getters--setters) and use the `this.getStorageProperty()` / `this.setStorageProperty()` methods. (See the file `Commitment.ts`)

<CodeBlockTabs defaultValue="models/nqtr/Commitment.ts">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="models/nqtr/Commitment.ts">
      models/nqtr/Commitment.ts
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="nqtr.d.ts">
      nqtr.d.ts
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="models/nqtr/Commitment.ts">
    ```ts
    import {
        ActiveScheduling,
        CommitmentInterface,
        CommitmentStoredClass,
        CommitmentStoredClassProps,
        OnRunAsyncFunction,
        OnRunEvent,
        OnRunProps,
    } from "@drincs/nqtr";
    import { CharacterInterface } from "@drincs/pixi-vn";
    import { PixiUIParam, PixiUIProp, ReactUIParam, ReactUIProp } from "./ui-elements";

    export default class Commitment extends CommitmentStoredClass implements CommitmentInterface {
        constructor(
            id: string,
            characters: CharacterInterface | CharacterInterface[],
            props: {
                name?: string;
                image?: PixiUIParam<Commitment>;
                background?: PixiUIParam<Commitment>;
                icon?: ReactUIParam<Commitment>;
                onRun?: OnRunEvent<CommitmentInterface>;
                disabled?: boolean | (() => boolean);
                hidden?: boolean | (() => boolean);
            } & CommitmentStoredClassProps,
        ) {
            characters = Array.isArray(characters) ? characters : [characters];
            super(id, characters, props.onRun, props);
            this.name = props.name || "";
            this._image = props.image;
            this._background = props.background;
            this._icon = props.icon;
            this._defaultDisabled = props.disabled || false;
            this._defaultHidden = props.hidden || false;
        }
        readonly name: string;
        private readonly _image?: PixiUIParam<Commitment>;
        get sprite(): PixiUIProp | undefined {
            const image = this._image;
            if (typeof image === "function") {
                return (runProps: OnRunProps) => image(this, runProps);
            }
            return image;
        }
        private readonly _background?: PixiUIParam<Commitment>;
        get background(): PixiUIProp | undefined {
            const background = this._background;
            if (typeof background === "function") {
                return (runProps: OnRunProps) => background(this, runProps);
            }
            return background;
        }
        private readonly _icon?: ReactUIParam<Commitment>;
        get icon(): ReactUIProp | undefined {
            const icon = this._icon;
            if (typeof icon === "function") {
                return (runProps: OnRunProps) => icon(this, runProps);
            }
            return icon;
        }
        private _defaultDisabled: boolean | (() => boolean) = false;
        get disabled(): boolean {
            let value = this.getStorageProperty<boolean>("disabled") || this._defaultDisabled;
            if (typeof value === "function") {
                return value();
            }
            return value;
        }
        set disabled(value: boolean) {
            this.setStorageProperty("disabled", value);
        }
        private _defaultHidden: boolean | (() => boolean) = false;
        get hidden(): boolean {
            let value = this.getStorageProperty<boolean>("hidden") || this._defaultHidden;
            if (typeof value === "function") {
                return value();
            }
            return value;
        }
        set hidden(value: boolean) {
            this.setStorageProperty("hidden", value);
        }
        override isActive(options?: ActiveScheduling): boolean {
            if (this.hidden) {
                return false;
            }
            return super.isActive(options);
        }
        override get run(): OnRunAsyncFunction {
            return async (runProps: OnRunProps) => {
                const res = await super.run(runProps);
                await runProps.invalidateInterfaceData();
                return res;
            };
        }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="nqtr.d.ts">
    ```ts
    import { ReactElement } from "react";
    import { ContainerChild } from "@drincs/pixi-vn";

    declare module "@drincs/nqtr" {
        interface CommitmentInterface {
            /**
             * The name of the commitment.
             */
            readonly name: string;
            /**
             * The sprite of the commitment.
             */
            readonly sprite?: PixiUIProp;
            /**
             * The background of the commitment.
             */
            readonly background?: PixiUIProp;
            /**
             * The React icon of the commitment.
             */
            readonly icon?: ReactUIProp;
            /**
             * Whether is disabled.
             */
            disabled: boolean;
            /**
             * Whether is hidden.
             */
            hidden: boolean;
        }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>


# Time system (/nqtr/time)



<Callout title="Nomenclature" type="info">
  It was decided to use the very generic terms date and time. The reason is that, depending on what is being developed, time can correspond to hours, minutes, or a long period of time. The same applies to date.
</Callout>

The time system is composed of the following elements:

* `date`: A counter used to determine the date of the game.
* `time`: A counter is used to determine the time of day and which is reset every time date is incremented.

You can use `timeTracker` instance to manage your time system. It provides methods to initialize, get, increment time, etc. The time system is designed to be flexible and can be adapted to various game requirements.

Initialize [#initialize]

To initialize the time system, you need use the `initialize` method of the `timeTracker` instance. This function has the following parameters:

* `defaultTimeSpent`: The default time spent in the game (number). It is used to increment the time when no specific time is set.
* `dayStartTime`: The minimum time of the day (number). It is used to determine the start time of the day.
* `dayEndTime`: The maximum time of the day (number). It is used to determine the end time of the day.
* `timeSlots`: An array of time slots. Each slot is an object with the following properties:
  * `name`: The name of the time slot (string).
  * `startTime`: The start time of the time slot (number). It is used to determine the start time of the slot.
* `weekLength`: The length of the week (number). It is used to determine the number of days in the week.
* `weekendStartDay`: The start day of the weekend (number). It is used to determine the weekend days.
* `getDayName`: A function that returns the name of the day based on the week day number (number). It is used to determine the name of the day.

```ts title="main.ts"
timeTracker.initialize({
    defaultTimeSpent: 1,
    dayStartTime: 0,
    dayEndTime: 24,
    timeSlots: [
        { name: "Morning", startTime: 5 },
        { name: "Afternoon", startTime: 12 },
        { name: "Evening", startTime: 18 },
        { name: "Night", startTime: 22 },
    ],
    getDayName: (weekDayNumber: number) => {
        const weekDaysNames = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
        return weekDaysNames[weekDayNumber];
    },
    weekendStartDay: 6,
    weekLength: 7,
});
```

Get [#get]

To get a current `time`, use the `timeTracker.currentTime` property. It returns the current time as a number.

```typescript
import { timeTracker } from "@drincs/nqtr";

const currentTime: number = timeTracker.currentTime;
```

To get a current `date`, use the `timeTracker.currentDate` property. It returns the current date as a number.

```typescript
import { timeTracker } from "@drincs/nqtr";

const currentDate: number = timeTracker.currentDate;
```

Set [#set]

To set a specific `time`, use the `timeTracker.currentTime` property. It accepts a number representing the time to set.

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

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

  <CodeBlockTab value="Typescript">
    ```ts  title="index.ts" groupId="narrative_language"
    import { timeTracker } from "@drincs/nqtr";

    timeTracker.currentTime = 12; // Set time to 12
    ```
  </CodeBlockTab>

  <CodeBlockTab value="ink">
    ```ink  title="index.ink" groupId="narrative_language"
    // {value} is a number representing the time to set
    # set time {value}
    // you can use a float number to set the time with decimals
    # set time 18.30
    # set time 18:30 // if you prefer to use the colon as a separator, it will be converted to a dot internally
    ```
  </CodeBlockTab>
</CodeBlockTabs>

To set a specific `date`, use the `timeTracker.currentDate` property. It accepts a number representing the date to set.

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

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

  <CodeBlockTab value="Typescript">
    ```ts  title="index.ts" groupId="narrative_language"
    import { timeTracker } from "@drincs/nqtr";

    timeTracker.currentDate = 5; // Set date to 5
    ```
  </CodeBlockTab>

  <CodeBlockTab value="ink">
    ```ink  title="index.ink" groupId="narrative_language"
    // {value} is a number representing the date to set
    # set date {value}
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Increment [#increment]

`timeTracker` has some functions to increment the time and date with some additional logic.

To increment the current `time` by a specific amount, use the `increaseTime` method. In case that the new time exceeds the `dayEndTime`, it will automatically increment the date and reset the time to the `dayStartTime` plus the overflow time.
This function has the following parameters:

* `delta`: The amount of time to increment (number). If not provided, it defaults to the `defaultTimeSpent` value.

To increment the current `date` by a specific amount, use the `increaseDate` method. This function has the following parameters:

* `delta`: The number of days to increase (number). If not provided, it defaults to 1.
* `time`: The time of the new day (number). If not provided, it defaults to the `dayStartTime`.

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

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

  <CodeBlockTab value="Typescript">
    ```ts  title="index.ts" groupId="narrative_language"
    import { timeTracker } from "@drincs/nqtr";

    timeTracker.increaseTime(2);
    timeTracker.increaseDate(1, 8); // Increment date by 1 and set time to 8
    ```
  </CodeBlockTab>

  <CodeBlockTab value="ink">
    ```ink  title="index.ink" groupId="narrative_language"
    // {timeValue} is a number representing the amount of time to increment
    // {dateValue} is a number representing the amount of days to increment
    # wait {timeValue} // Increment time by {value}
    # wait // Increment time by defaultTimeSpent
    # wait days {dateValue} // Increment date by {dateValue} and set time to dayStartTime
    # wait days {dateValue} hours {timeValue} // Increment date by {dateValue} and time by {timeValue}
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Is weekend [#is-weekend]

To check if the current day is a weekend, use the `timeTracker.isWeekend` property. It returns a boolean indicating whether the current day is a weekend.

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

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

  <CodeBlockTab value="Example">
    ```ts
    import { timeTracker } from "@drincs/nqtr";

    const isWeekend: boolean = timeTracker.isWeekend;
    ```
  </CodeBlockTab>

  <CodeBlockTab value="main.ts">
    ```ts
    timeTracker.initialize({
        defaultTimeSpent: 1,
        dayStartTime: 0,
        dayEndTime: 24,
        timeSlots: [
            { name: "Morning", startTime: 5 },
            { name: "Afternoon", startTime: 12 },
            { name: "Evening", startTime: 18 },
            { name: "Night", startTime: 22 },
        ],
        getDayName: (weekDayNumber: number) => {
            const weekDaysNames = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
            return weekDaysNames[weekDayNumber];
        },
        weekendStartDay: 6, // [!code focus]
        weekLength: 7, // [!code focus]
    });
    ```
  </CodeBlockTab>
</CodeBlockTabs>

FAQ [#faq]

<Accordions>
  <Accordion title="image_time_period" id="image-time-period">
    You can create a class that manages the image based on the current time slot. The class can have properties for each time slot and a method to get the current image based on the time slot.

    For example:

    <CodeBlockTabs defaultValue="models/TimeSlotsImage.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="models/TimeSlotsImage.ts">
          models/TimeSlotsImage.ts
        </CodeBlockTabsTrigger>

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

      <CodeBlockTab value="models/TimeSlotsImage.ts">
        ```ts
        import { timeTracker } from "@drincs/nqtr";

        export default class TimeSlotsImage {
            constructor(data: { morning: string; afternoon: string; evening: string; night: string } | string) {
                if (typeof data === "string") {
                    this.morning = data;
                    this.afternoon = data;
                    this.evening = data;
                    this.night = data;
                    return;
                }
                this.morning = data.morning;
                this.afternoon = data.afternoon;
                this.evening = data.evening;
                this.night = data.night;
            }
            get src(): string {
                if (timeTracker.currentTimeSlot === 0) {
                    return this.morning;
                } else if (timeTracker.currentTimeSlot === 2) {
                    return this.evening;
                } else if (timeTracker.currentTimeSlot === 3) {
                    return this.night;
                }
                return this.afternoon;
            }
            morning: string;
            afternoon: string;
            evening: string;
            night: string;
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="main.ts">
        ```ts
        timeTracker.initialize({
            defaultTimeSpent: 1,
            dayStartTime: 0,
            dayEndTime: 24,
            timeSlots: [ // [!code focus]
                { name: "Morning", startTime: 5 }, // [!code focus]
                { name: "Afternoon", startTime: 12 }, // [!code focus]
                { name: "Evening", startTime: 18 }, // [!code focus]
                { name: "Night", startTime: 22 }, // [!code focus]
            ], // [!code focus]
            getDayName: (weekDayNumber: number) => {
                const weekDaysNames = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
                return weekDaysNames[weekDayNumber];
            },
            weekendStartDay: 6,
            weekLength: 7,
        });
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>
</Accordions>


# FAQ (/faq)



Some common questions you may encounter.

<Accordions>
  <Accordion title="enable_typescript_decorators" id="enable-typescript-decorators">
    In Pixi’VN, in some advanced features, it is necessary to use decorators.

    By default, TypeScript does not enable the use of decorators. To enable the use of decorators in TypeScript, you must add the following configuration to the `tsconfig.json` file:

    ```json title="tsconfig.json"
    {
        "compilerOptions": {
            // ...
            "experimentalDecorators": true
        }
    }
    ```
  </Accordion>

  <Accordion title="skip_auto" id="skip-auto">
    In a visual novel, it's very useful to be able to "skip," accelerate, or skip multiple `steps`, or automatically advance to the next `step` after a period of time.

    The suggested implementation for this feature is to create the following function:

    ```tsx title="React example"
    const [skipEnabled, setSkipEnabled] = useState<boolean>(false)
    const [autoEnabled, setAutoEnabled] = useState<boolean>(false)
    const [recheckSkipAuto, setRecheckSkipAuto] = useState<number>(0)

    useEffect(() => {
        if (skipEnabled || autoEnabled) {
            nextOnClick()
        }
    }, [skipEnabled, recheckSkipAuto, autoEnabled])

    function nextOnClick() {
        narration.continue({})
            .then(() => {
                if (skipEnabled) {
                    setTimeout(() => {
                        setRecheckSkipAuto((p) => p + 1)
                    }, 0.2);
                }
                else if (autoEnabled) {
                    setTimeout(() => {
                        setRecheckSkipAuto((p) => p + 1)
                    }, 2);
                }
            })
            .catch((e) => {
                // ...
            })
    }

    // Button for enable skip and auto ...
    ```
  </Accordion>

  <Accordion title="link_character_to_image" id="link-character-to-image">
    Linking a character to an image to add to the canvas is a common feature in visual novels. It can be useful for example for showing the character's expression.

    To do this, you just need to create a <DynamicLink href="/start/character#custom-class">custom character</DynamicLink> or modify the existing one (it is already present in the templates).
    I recommend adding an array of strings containing the links/aliases of the images that make up the character (body, head...), and using an <DynamicLink href="/start/canvas-image-container">ImageContainer</DynamicLink> when you need to display the character.

    For example:

    <CodeBlockTabs defaultValue="models/Character.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="models/Character.ts">
          models/Character.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pixi-vn.d.ts">
          pixi-vn.d.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="models/Character.ts">
        ```ts
        import { CharacterInterface, CharacterStoredClass } from "@drincs/pixi-vn";

        export class Character extends CharacterStoredClass implements CharacterInterface {
            constructor(id: string | { id: string, emotion: string }, props: CharacterProps) {
                // ...
                this.images = props.images ?? []
            }
            
            // other properties...

            readonly images: string[] = []
        }

        interface CharacterProps {
            // other properties...
            images?: string[] // is optional
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pixi-vn.d.ts">
        ```ts
        declare module '@drincs/pixi-vn' {
            interface CharacterInterface {
                // other properties...
                readonly images: string[]
            }
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    Now you can use the `images` property to show the character on the canvas.

    <CodeBlockTabs defaultValue="labels/startLabel.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="labels/startLabel.ts">
          labels/startLabel.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="values/characters.ts">
          values/characters.ts
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="labels/startLabel.ts">
        ```ts
        import { newLabel, showImageContainer } from "@drincs/pixi-vn";
        import { alice } from "../values/characters";

        export const startLabel = newLabel("start_label", [
            async () => {
                await showImageContainer("alice", alice.images, { // [!code focus]
                    xAlign: 0.5, // [!code focus]
                    yAlign: 1, // [!code focus]
                }); // [!code focus]
            },
        ]);
        ```
      </CodeBlockTab>

      <CodeBlockTab value="values/characters.ts">
        ```ts
        import { Character } from "../models/Character";

        const alice = new Character('alice_id', {
            // other properties...
            images: ['alice-body', 'alice-head', 'alice-eyes']
        })
        RegisteredCharacters.add(alice)
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    **If you are using *ink***:

    You can create a <DynamicLink href="/ink/hashtag">custom hashtag command</DynamicLink> to use this feature.
    For example you can add a script with the following syntax and convert it to a <DynamicLink href="/ink/canvas#show-a-image-container-in-ink">show imagecontainer script</DynamicLink>:

    ```ink title="ink"
    # show character {character id} {parameters}
    ```

    <CodeBlockTabs defaultValue="utils/ink-utility.ts">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="utils/ink-utility.ts">
          utils/ink-utility.ts
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="ink/start.ink">
          ink/start.ink
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="utils/ink-utility.ts">
        ```ts
        import { HashtagCommands } from '@drincs/pixi-vn-ink'
        import { getCharacterById } from '@drincs/pixi-vn'

        HashtagCommands.add((script, convertListStringToObj) => {
            // ...
            if (script[0] === "show" && script[1] === "character" && script.length > 2) {
                let character = getCharacterById(script[2])
                if (character) {
                    console.error('Character not found')
                    return false 
                }
                let characterId: string = script[2].split('@')[0] // to remove the emotion
                let oltherProps: string = script.slice(3).join(' ')
                let images = character.images.join(' ')
                let newScript: string = `show imagecontainer ${characterId} [${images}] ${oltherProps}`
                return newScript
            }
            return false
        })
        ```
      </CodeBlockTab>

      <CodeBlockTab value="ink/start.ink">
        ```ink
        === start ===
        # show character alice xAlign 0.8 yAlign 1 with dissolve
        -> DONE
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="hotkeys" id="hotkeys">
    I suggest the following hotkeys:

    * `Space` or `Enter`: Continue the dialogue.
    * `Keep Space` or `Keep Enter`: Skip the dialogue.
    * `Alt` + `S`: Quick save the game.
    * `Alt` + `L`: Quick load the game.
    * `Alt` + `H`: Open the history modal.
    * `Esc`: Open the settings modal.
    * `Alt` + `V`: Hide the UI (Show only the canvas).

    Why not use the `Ctrl` key? Because it is used by the browser for many shortcuts, and it is better to avoid conflicts.
  </Accordion>

  <Accordion title="keymaps_events" id="keymaps-events">
    To attach events to keymaps is useful to allow hotkeys.

    For example:

    ```ts title="EventInterceptor.ts"
    import { useEffect } from 'react';

    export default function EventInterceptor() {
        useEffect(() => {
            window.addEventListener('keydown', onkeydown);

            return () => {
                window.removeEventListener('keydown', onkeydown);
            };
        }, []);

        function onkeydown(event: KeyboardEvent) {
            if (event.code == 'Enter' || event.code == 'Space') {
                nextStep((prev) => prev + 1)
            }
            else if (event.code == 'Escape') {
                setOpenSettings((prev) => !prev)
            }
            else if (event.code == 'KeyH') {
                setOpenHistory((prev) => !prev)
            }
        }

        return null
    }
    ```
  </Accordion>

  <Accordion title="license" id="license">
    Pixi’VN is released under the &#x2A;*GNU Lesser General Public License v2.1 (LGPL 2.1)**.\
    This license is designed for *libraries*, making it a great fit for a game engine like this.

    Here’s what it means in simple, practical terms — even if you’re not an expert in licenses.

    **What You Can Freely Do**

    If you use Pixi’VN in your own project — for example, to create a game, a visual novel, or a tool — **you have almost no restrictions**.

    You can:

    * **Use Pixi’VN in free or commercial projects**: You can sell your game, publish it on Steam, itch.io, mobile stores, etc.
    * **Keep your game’s source code private**: You are **not** required to open-source your project.
    * **Use Pixi’VN without giving credit**: You are *not* required to mention Pixi’VN anywhere.\
      (Though we always appreciate it!)
    * **Install and use the library from npm without limitations**: Normal dependency usage is fully allowed.

    **When Restrictions Apply**

    The LGPL only matters **if you modify Pixi’VN itself**, meaning:

    * you create a *fork* of the engine,
    * you change its source code,
    * or you distribute a modified version of the library.

    In that case:

    * **Your modifications to Pixi’VN must remain open source**: If you change the engine and distribute your version, you must publish your modifications.
    * **You must keep the same license (LGPL 2.1)**: Modified versions of the library must remain under LGPL.

    > These conditions apply **only to the engine**, *not* to your game.
  </Accordion>
</Accordions>


# Migration guide (/faq/migration)



pixi-vn [#pixi-vn]

Migration from v1.5.x to v1.6.0 [#migration-from-v15x-to-v160]

In this version, the audio system has been completely redesigned, as the previous implementation was very limiting. In this new version, the `channel` component has been introduced, and the system has been divided into four elements, each responsible for a specific role, unlike before where they could be used in multiple ways, leading to instability (`sound` (manager), `channels`, `media`, sound `assets`).

```ts
import { sound } from '@drincs/pixi-vn'

sound.add('bird', 'resources/bird.mp3'); // [!code --]
sound.play('bird', {
    loop: true,
});

let s = sound.add('bird', 'resources/bird.mp3'); // [!code --]
s.play({ // [!code --]
sound.play('bird', { // [!code ++]
    loop: true,
});

let s = sound.add('bird', { // [!code --]
    url: 'resources/bird.mp3', // [!code --]
    loop: true, // [!code --]
}); // [!code --]
s.play(); // [!code --]
sound.play('bird', { // [!code ++]
    loop: true, // [!code ++]
}); // [!code ++]

s.play(); // [!code --]
sound.play('bird'); // [!code ++]
s.pause(); // [!code --]
sound.pause('bird'); // [!code ++]
s.resume(); // [!code --]
sound.resume('bird'); // [!code ++]
s.stop(); // [!code --]
sound.stop('bird'); // [!code ++]
```

Also, to have a cleaner start to the game, `Game.start` has been added. `Game.start` has the same functionality as `narration.call`, but in the future if I need to add some processes before starting the narration, I can do it without breaking changes. For now, it is just an alias for `narration.call`, but it is recommended to use `Game.start` instead of `narration.call` to start the game.

```ts
Game.clear(); // [!code --]
narration.call("start", gameProps) // [!code --]
Game.start("start", gameProps) // [!code ++]
```

The storage keyword system has also been improved by adopting a common naming convention using `:` as a separator, and by adding the ability to use prefixes to better identify keys (for example `character:alice:friendship`). This change was made to improve the cache management of storage and to make it easier to identify the type of data stored. (This change does not affect the API and will not cause any issues with existing saves).

Finally, error handling has been improved by adding the ability to manage errors through specific handlers.

```ts title="main.ts"
import { Game, drawCanvasErrorHandler } from '@drincs/pixi-vn'

Game.addOnError(drawCanvasErrorHandler()); // [!code ++]

Game.onError((type, error, { notify, uiTransition }) => { // [!code --]
    notify(uiTransition("allert_error_occurred"), { variant: "error" }); // [!code --]
    console.error(`Error occurred: ${type}`, error); // [!code --]
Game.addOnError((error, { notify, uiTransition }) => { // [!code ++]
    notify && uiTransition && notify(uiTransition("allert_error_occurred"), { variant: "error" }); // [!code ++]
    console.error(`Error occurred`, error); // [!code ++]
});
```

Migration from v1.4.x to v1.5.0 [#migration-from-v14x-to-v150]

In this update, the `pixi.js` dependency has been marked as **external** for non-CDN builds (for example, when using Vite.js or the official templates).

When using a CDN, the version of `pixi.js` bundled with the library will continue to be used. This ensures compatibility, prevents known issues, and preserves the overall integrity of the library.

**Why is `pixi.js` now external?** `pixi.js` does not support multiple instances. Making it external allows developers to safely integrate third-party libraries that are designed to work with `pixi.js`, without running into instance conflicts.

In v1.5.4, the canvas resizing logic has also been changed. If you used an official template, it's recommended to modify the CSS as follows:

```css title="src/index.css"
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "tailwindcss-motion";

html, /* [!code ++] */
body { /* [!code ++] */
  background-color: #242424; /* [!code ++] */
  height: 100%; /* [!code ++] */
} /* [!code ++] */

body {
  margin: 0;
  min-height: 100vh; /* [!code ++] */
  display: flex;
  overflow: hidden;
}
```

Migration from v1.3.x to v1.4.0 [#migration-from-v13x-to-v140]

This document describes the changes that need to be made to your code to migrate from v1.3.x to v1.4.0.

In this release, some functions for managing "navigation of the narrative" have been modified to allow for the easy implementation of rollback and rollforward. Specifically, it is now possible to execute multiple back and continue requests synchronously, and the system will internally queue them and calculate the delta to execute only the necessary processes. You can read more about this in the <DynamicLink href="/start/labels-flow#rollback-rollforward">Rollback and Rollforward</DynamicLink> section.

For this reason it was necessary to modify the `stepHistory.back()` function and the `Game.init()` function. `stepHistory.back()` now requires a path navigation function rather than a `StepLabelProps` function. You can now define the path navigation function in `Game.init()`.

```ts
stepHistory.back((_path) => { // [!code --]
    // TODO: navigate in the url path // [!code --]
    // READ THIS: https://pixi-vn.web.app/start/interface.html#navigate-switch-between-ui-screens // [!code --]
}) // [!code --]
const gameProps = {}; // [!code ++]
stepHistory.back(gameProps); // [!code ++]
```

```ts
Game.init(body, {
    height: 1080,
    width: 1920,
    backgroundColor: "#303030",
    navigate: (_path) => { // [!code ++]
        // TODO: navigate in the url path // [!code ++]
    }, // [!code ++]
}).then(() => {
    // ...
});
```

Some long-deprecated features have been removed in this release, including: `stepHistory.goBack`, `narration.goNext`, `PIXI`, `canvas.canvasWidth`, `canvas.canvasHeight`, `canvas.onEndOfTicker`, `FadeAlphaTicker`, `MoveTicker`, `RotateTicker`, `ZoomTicker`, `narration.canContinue`, `narration.callLabel`, `narration.jumpLabel`, `narration.choiceMenuOptions`, `storage.startingStorage`, `storage.setVariable`, `storage.getVariable` and `storage.removeVariable`.

Migration from v1.2.x to v1.3.0 [#migration-from-v12x-to-v130]

This document describes the changes that need to be made to your code to migrate from v1.2.x to v1.3.0.

In this release, the canvas component animations have been revolutionized. The core animation function is now <DynamicLink href="/start/canvas-motion">`canvas.animate`</DynamicLink>, a function that combines PixiJS tickers and [`motion`](https://motion.dev/docs/animate). So the provided tickers preset (`FadeAlphaTicker`, `MoveTicker`, `RotateTicker`, `ZoomTicker`) has been deprecated.

Migration from v0.10.x to v1.0 [#migration-from-v010x-to-v10]

This document describes the changes that need to be made to your code to migrate from v0.10.x to v1.0.

Being version 1.0.0 it is the first complete release of the library. It is a breaking change and the API has changed significantly. The fundamental change of this release was to split the entire engine into independent modules. This allows for a more modular and flexible design, making it easier to use the engine in different contexts. The size of packages has been reduced significantly (150 MB to 50 MB) and the engine is now more efficient and faster.

The `Game` namespace object has been introduced for the which contains all the functionality that exploits multiple modules. This is the main entry point for the engine and is used to access all the functions of the engine.

The `stepHistory` module has been introduced to manage the history of the game. Previously the entire management of the game's history was handled by `narration`.

```ts
clearAllGameDatas(); // [!code --]
Game.clear(); // [!code ++]
```

```ts
canvas // [!code --]
    .initialize(body, { // [!code --]
        height: 1080, // [!code --]
        width: 1920, // [!code --]
        backgroundColor: "#303030", // [!code --]
    }) // [!code --]
    .then(() => { // [!code --]
        // Pixi.JS UI Layer // [!code --]
        canvas.addLayer(CANVAS_UI_LAYER_NAME, new Container()); // [!code --]
Game.init(body, { // [!code ++]
    height: 1080, // [!code ++]
    width: 1920, // [!code ++]
    backgroundColor: "#303030", // [!code ++]
}).then(() => { // [!code ++]
    // Pixi.JS UI Layer // [!code ++]
    canvas.addLayer(CANVAS_UI_LAYER_NAME, new Container()); // [!code ++]
```

```ts
getSaveData(); // [!code --]
Game.exportGameState(); // [!code ++]
```

```ts
getSaveJson(); // [!code --]
JSON.stringify(Game.exportGameState()); // [!code ++]
```

```ts
loadSaveData(data, navigate); // [!code --]
Game.restoreGameState(data, navigate); // [!code ++]
```

```ts
loadSaveJson(data, navigate); // [!code --]
Game.restoreGameState(JSON.parse(dataString) as GameState, navigate); // [!code ++]
```

```ts
loadSaveJson(data, navigate); // [!code --]
Game.restoreGameState(JSON.parse(dataString) as GameState, navigate); // [!code ++]
```

```ts
jsonToSaveData(json); // [!code --]
JSON.parse(json); // [!code ++]
```

```ts
narration.canGoBack; // [!code --]
stepHistory.canGoBack; // [!code ++]
```

```ts
narration.back(); // [!code --]
stepHistory.back(); // [!code ++]
```

```ts
narration.narrativeHistory; // [!code --]
stepHistory.narrativeHistory; // [!code ++]
```

nqtr [#nqtr]

Migration from v0.7.x to v0.8.0 (nqtr) [#migration-from-v07x-to-v080-nqtr]

<Callout title="ink" type="error">
  This version does not support save files created with previous versions if temporary `commitment` were used (i.e., if they were added using `routine.add`).

  To make the saves compatible, you need to modify the save file (remember that it is a JSON) by changing the `___nqtr-temporary_commitment___` variable from an array of strings (a list of `commitment` IDs) to an object with keys corresponding to the `commitment` IDs and values corresponding to an object containing `id` and `roomId` (the latter is required to identify the link between the `commitment` and the `room`).

  ```json title="save.json"
  {
      // ...
      "___nqtr-temporary_commitment___": [ // [!code --]
          "alice_sleep", // [!code --]
          "alice_eat", // [!code --]
      ], // [!code --]
      "___nqtr-temporary_commitment___": { // [!code ++]
          "alice_sleep": { // [!code ++]
              "id": "alice_sleep", // [!code ++]
              "roomId": "alice_room" // [!code ++]
          }, // [!code ++]
          "alice_eat": { // [!code ++]
              "id": "alice_eat", // [!code ++]
              "roomId": "alice_room" // [!code ++]
          }, // [!code ++]
      }, // [!code ++]
      // ...
  }
  ```
</Callout>

This document describes the changes that need to be made to your code to migrate from v0.7.x to v0.8.0.

In this release, the way to link a `commitment` to a `room` has been changed. You can now define its routine directly inside the `room`. Therefore, instead of passing the `room` in the `commitment` constructor, you can define the routine directly in the `room` constructor.

This change was made to simplify the management of routines and to make the relationship between `commitment` and `room` clearer.

```ts title="models/nqtr/Commitment.ts"
export default class Commitment extends CommitmentStoredClass implements CommitmentInterface {
    constructor(
        id: string,
        characters: CharacterInterface | CharacterInterface[],
        room: RoomInterface, // [!code --]
        props: {
            name?: string;
            image?: PixiUIParam<Commitment>;
            background?: PixiUIParam<Commitment>;
            icon?: ReactUIParam<Commitment>;
            onRun?: OnRunEvent<CommitmentInterface>;
            disabled?: boolean | (() => boolean);
            hidden?: boolean | (() => boolean);
        } & CommitmentStoredClassProps,
    ) {
        characters = Array.isArray(characters) ? characters : [characters];
        super(id, characters, room, props.onRun, props); // [!code --]
        super(id, characters, props.onRun, props); // [!code ++]
        this.name = props.name || "";
        this._image = props.image;
        this._background = props.background;
        this._icon = props.icon;
        this._defaultDisabled = props.disabled || false;
        this._defaultHidden = props.hidden || false;
    }
    // ...
    override get isActive(): boolean { // [!code --]
    override isActive(options?: ActiveScheduling): boolean { // [!code ++]
        if (this.hidden) {
            return false;
        }
        return super.isActive; // [!code --]
        return super.isActive(options); // [!code ++]
    }
}
```

```ts title="models/nqtr/Room.ts"
export default class Room extends RoomStoredClass implements RoomInterface {
    constructor(
        id: string,
        location: LocationInterface,
        props: {
            name: string;
            disabled?: boolean | (() => boolean);
            hidden?: boolean | (() => boolean);
            background: PixiUIParam<Room>;
            activities?: ActivityInterface[];
            routine?: CommitmentInterface[]; // [!code ++]
            isEntrance?: boolean;
        },
    ) {
        super(id, location, props.activities); // [!code --]
        super(id, location, { // [!code ++]
            activities: props.activities || [], // [!code ++]
            routine: props.routine || [], // [!code ++]
        }); // [!code ++]
        this.name = props.name;
        this._defaultDisabled = props.disabled || false;
        this._defaultHidden = props.hidden || false;
        this._background = props.background;
        this.isEntrance = props.isEntrance || false;
    }
    // ...
}
```

```ts title="models/nqtr/Activity.ts"
export default class Activity extends ActivityStoredClass implements ActivityInterface {
    // ...
    override get isActive(): boolean { // [!code --]
    override isActive(options?: ActiveScheduling): boolean { // [!code ++]
        if (this.hidden) {
            return false;
        }
        return super.isActive; // [!code --]
        return super.isActive(options); // [!code ++]
    }
}
```

```tsx title="values/routine.tsx"
const aliceSleep = new Commitment("alice_sleep", alice, aliceRoom, { // [!code --]
const aliceSleep = new Commitment("alice_sleep", alice, { // [!code ++]
    priority: 1,
    timeSlot: {
        from: 20,
        to: 10,
    },
    // ...
});

// ...

export const fixedRoutine = [aliceSleep, ...]; // [!code --]

RegisteredCommitments.add(fixedRoutine); // [!code --]
RegisteredCommitments.add([aliceSleep, ...]);  // [!code ++]
```

```ts title="utils/nqtr-utility.ts"
export function initializeNQTR() {
    // ...
    routine.fixedRoutine = fixedRoutine; // [!code --]
}
```

```tsx title="values/rooms.tsx"
export const aliceRoom = new Room("alice_room", mcHome, {
    name: "Alice room",
    background: new TimeSlotsImage({
        morning: "location_aliceroom-0",
        afternoon: "location_aliceroom-1",
        evening: "location_aliceroom-2",
        night: "location_aliceroom-3",
    }),
    routine: [aliceSleep], // [!code ++]
});
```

```ts
routine.add(aliceSleep); // [!code --]
aliceRoom.addCommitment(aliceSleep); // [!code ++]
```