/characters

name: pixi-vn-characters
description: Use when defining visual novel characters for a @drincs/pixi-vn game — creating a character with a name, color, icon and other props, registering it so it can be looked up by id, and referencing it from dialogue/narration. Load this before writing any `CharacterBaseModel` or `RegisteredCharacters` code.

Pixi'VN Characters

When to use this skill

Use this skill whenever a task involves creating the characters that appear in a Pixi'VN game (name, surname, age, color, icon, and any custom fields), storing them so the engine and narration code can find them by id, or hooking a character into a `narration.dialogue` line. It does not cover how dialogue/text itself is displayed (see the narration skill) or how variables are generally saved (see the storage skill).

import { CharacterBaseModel, RegisteredCharacters } from "@drincs/pixi-vn";

(Also available from the narrower `@drincs/pixi-vn/characters` subpath — see `pixi-vn` for when to prefer that.)

Full reference: https://pixi-vn.com/start/character

1. Defining a character

`CharacterBaseModel` is the built-in character class. Construct it with a unique string `id` and a props object (`name`, `surname`, `age`, `icon`, `color` — all optional):

import { CharacterBaseModel } 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: "#c23b7f",
});

The `id` is the value used everywhere else in the game (dialogue, lookups, history) to reference this character, so it must be unique and stable across saves.

`name`/`surname`/`age` are actually get/set accessors backed by the game's storage (see `CharacterStoredClass`, which `CharacterBaseModel` extends, and the [stored classes](https://pixi-vn.com/start/stored-classes) doc): the value passed in the constructor becomes the _default_, but setting `liam.name = "..."` at runtime persists an override in storage that survives save/load and takes priority over the default. `icon` and `color` are plain readonly fields, not stored/overridable at runtime.

import { liam } from "@/content/characters";

console.log(liam.name); // "Liam"
liam.name = "Liam Smith";
console.log(liam.name); // "Liam Smith" — now persisted in game storage

If a character's `id` is ever changed between game versions, the engine does **not** migrate the storage data from the old id to the new one — treat ids as permanent once shipped.

Custom character classes with extra fields

If you need fields beyond `name`/`surname`/`age`/`icon`/`color` (e.g. a `sprite` id or a relationship stat), this is the recommended, docs-endorsed approach (project templates already ship it as `models/Character.ts`):

1. Create a class `Character extends CharacterStoredClass implements CharacterInterface`. 2. Augment the (otherwise empty) `CharacterInterface` in a `pixi-vn.d.ts` file via `declare module "@drincs/pixi-vn"` so every `CharacterInterface` consumer in the project — including `RegisteredCharacters.get()` — sees the richer, project-specific type. 3. For any field that must persist across saves, back it with a getter/setter that calls `this.getStorageProperty()` / `this.setStorageProperty()` (inherited from `CharacterStoredClass`), the same pattern `CharacterBaseModel` uses internally for `name`/`surname`/`age`.

This is exactly what the official `pixi-vn-react-template` (the "TS narration

• React" project `npm create pixi-vn@latest` scaffolds) ships as

`src/models/Character.ts` — stored getters/setters for `name`, `surname` and `age`, and plain (non-stored) fields for `icon`/`color`:

// models/Character.ts
import { type CharacterInterface, CharacterStoredClass } from "@drincs/pixi-vn";

export default 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.defaultName = props.name;
    this.defaultSurname = props.surname;
    this.defaultAge = props.age;
    this.icon = props.icon;
    this.color = props.color;
  }

  // stored — persists across save/load, same pattern as CharacterBaseModel
  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;
  get age(): number | undefined {
    return this.getStorageProperty<number>("age") || this.defaultAge;
  }
  set age(value: number | undefined) {
    this.setStorageProperty<number>("age", value);
  }

  // not stored
  readonly icon?: string;
  readonly color?: string;
}

interface CharacterProps {
  name?: string;
  surname?: string;
  age?: number;
  icon?: string;
  color?: string;
}

// pixi-vn.d.ts
declare module "@drincs/pixi-vn" {
  interface CharacterInterface {
    name: string;
    surname?: string;
    age?: number;
    readonly icon?: string;
    readonly color?: string;
  }
}

2. Registering and looking up characters

Characters are looked up at runtime by id through the `RegisteredCharacters` registry (a namespace, not a decorator despite its file name). Calling `RegisteredCharacters.add(...)` is **required** — a `CharacterBaseModel` (or custom class) instance tha