# Labels and steps (/start/labels)



Visual novels are typically a sequence of scenes with images and text. 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.

<CalloutContainer type="info">
  <CalloutTitle>
    Nomenclature
  </CalloutTitle>

  <CalloutDescription>
    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`.
  </CalloutDescription>
</CalloutContainer>

<Accordions>
  <Accordion title="Lifecycle" id="lifecycle">
    1. The game starts by calling a `label`, with the [`Game.start`](/jsdoc/pixi-vn/index/namespaces/Game/functions/start) function. The first `step` of the `label` is executed automatically.
    2. After that, by connecting the [`narration.continue`](/jsdoc/pixi-vn/index/interfaces/NarrationManagerInterface#continue) 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`.
    3. The game ends only when all `steps` are completed. At that point, the [`Game.onEnd`](/jsdoc/pixi-vn/index/namespaces/Game/functions/onEnd) function is triggered.
  </Accordion>
</Accordions>

Add [#add]

To create a `label`, use the [`newLabel`](/jsdoc/pixi-vn/index/functions/newLabel) function.

```ts title="content/labels/start.label.ts"
import { narration, StepLabelProps } from "@drincs/pixi-vn";

export const startLabel = newLabel("start", [
    () => {
        narration.dialogue = { character: liam, text: "Example of dialogue" };
    },
    (props: StepLabelProps, { labelId }) => narration.jump(labelId, props),
]);
```

Other features [#other-features]

<Accordions>
  <Accordion title="`StepLabelProps`" id="steplabelprops">
    <CalloutContainer type="info">
      <CalloutTitle>
        Templates
      </CalloutTitle>

      <CalloutDescription>
        In all templates, the `StepLabelProps` interface is already overridden. You can find it in the `pixi-vn.d.ts` file.
      </CalloutDescription>
    </CalloutContainer>

    All <DynamicLink href="/start/labels-flow">narration flow control functions</DynamicLink> require an object matching the [`StepLabelProps`](/jsdoc/pixi-vn/index/interfaces/StepLabelProps) interface. 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="content/labels/start.label.ts">
          content/labels/start.label.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="content/labels/start.label.ts">
        ```ts
        export const startLabel = newLabel("start", [
            ({ navigate }) => {
                navigate("/new-route");
            },
        ]);
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="`step` pros" id="step-pros">
    You can pass a type to the [`newLabel`](/jsdoc/pixi-vn/index/functions/newLabel) function to add custom parameters for that `label`, in addition to [`StepLabelProps`](#steplabelprops).

    ```ts title="content/labels/start.label.ts"
    import { narration } from "@drincs/pixi-vn";

    export const startLabel = newLabel<{ name: string }>("start", [
        (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="`StepLabelResult`" id="step-results">
    Steps can return a [`StepLabelResult`](/jsdoc/pixi-vn/index/interfaces/StepLabelResult) object. 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="content/labels/start.label.ts">
          content/labels/start.label.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="content/labels/start.label.ts">
        ```ts
        export const startLabel = newLabel("start", [
            () => {
                return {
                    newRoute: "/new-route",
                    customProperty: 12,
                };
            },
        ]);
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>
</Accordions>