# Characters (/ink/character)





<CalloutContainer type="info">
  <CalloutDescription>
    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>.
  </CalloutDescription>
</CalloutContainer>

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

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

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

  <CodeBlockTab value="ink">
    ```ink
    mc: Hello
    ```
  </CodeBlockTab>

  <CodeBlockTab value="CLI">
    ```txt
    <character_id>: <text>

    where:
        character_id = character identifier
        text = any text message
    ```
  </CodeBlockTab>
</CodeBlockTabs>

For example:

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

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

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

  <CodeBlockTab value="ink">
    ```ink
    Hello, [mc].
    ```
  </CodeBlockTab>

  <CodeBlockTab value="CLI">
    ```txt
    [<character_id>]

    where:
        character_id = character identifier
    ```
  </CodeBlockTab>
</CodeBlockTabs>

For example:

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

<Accordions>
  <Accordion title="Implementation" id="replace-implementation">
    To use this syntax, you need to register a <DynamicLink href="/ink/replacement">text replace</DynamicLink> that replaces the character id with the character's name.

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

      <CalloutDescription>
        In all templates, this text replace is already included.
      </CalloutDescription>
    </CalloutContainer>

    For example, you can add the following text replace:

    ```ts title="content/ink/text-replaces.ts"
    import { TextReplaces } from "@drincs/pixi-vn-ink";
    import { RegisteredCharacters } from "@drincs/pixi-vn/characters";

    TextReplaces.add((key) => RegisteredCharacters.get(key)?.name, {
        name: "character name",
        validation: "characterId",
        type: "after-translation",
        i18nInterpolation: true,
        description:
            "Replaces a character ID with the character's name in the game.",
    });
    ```
  </Accordion>
</Accordions>

<CharacterDialogueTextExample />

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

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

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

  <CodeBlockTab value="ink">
    ```ink
    # rename mc Liam
    ```
  </CodeBlockTab>

  <CodeBlockTab value="CLI">
    ```txt
    # rename <character_id> <new_name>

    where:
        character_id = character identifier
        new_name = the new name for the character
    ```
  </CodeBlockTab>
</CodeBlockTabs>

For example:

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

<Accordions>
  <Accordion title="Implementation" id="rename-implementation">
    To use this syntax, you need to register a <DynamicLink href="/ink/hashtag">hashtag command</DynamicLink> that renames the character.

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

      <CalloutDescription>
        In all templates, this hashtag command is already included.
      </CalloutDescription>
    </CalloutContainer>

    For example, you can add the following hashtag command:

    ```ts title="content/ink/hashtag-commands.ts"
    import { characterIdsEnum } from "@/pixi-vn.keys.gen";
    import { HashtagCommands } from "@drincs/pixi-vn-ink";
    import { RegisteredCharacters } from "@drincs/pixi-vn/characters";
    import zod from "zod";

    HashtagCommands.add(
        async (script) => {
            const character = RegisteredCharacters.get(script[1]);
            if (character) {
                character.name = script[2];
            }
            return true;
        },
        {
            name: "character rename",
            description: `Renames a character in the game.

    \`\`\`ink
    # rename <characterId> <newName>
    \`\`\``,
            validation: zod.tuple([
                zod.literal("rename"),
                zod.enum(characterIdsEnum),
                zod.string(),
            ]),
        },
    );
    ```
  </Accordion>
</Accordions>

<CharacterEditExample />

## 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 the character id, the `@` separator, and the emotion:

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

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

  <CodeBlockTab value="ink">
    ```ink
    mc@happy: Hi, I'm Liam. I'm very happy today.
    ```
  </CodeBlockTab>

  <CodeBlockTab value="CLI">
    ```txt
    <character_id>@<emotion>: <text>

    where:
        character_id = character identifier
        emotion = the emotion defined in JavaScript/TypeScript
        text = any text message
    ```
  </CodeBlockTab>
</CodeBlockTabs>

For example:

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