narratio/docs/integrations/party.md

Canonical Party Input

party.yml is a campaign-owned roster input. It must be a single, versioned narratio.party.v1 document when Narratio resolves a pipeline, campaign, and session together.

schema_version: narratio.party.v1

characters:
  arannis:
    player:
      name: Eric
    character:
      name: Arannis
      alias:
        - Ari
        - The Grey Owl
      classes:
        - name: wizard
          level: 8

characters is a non-empty mapping. Each key is a stable character ID using the configured-artifact key grammar: a lowercase ASCII letter followed by zero or more lowercase ASCII letters, digits, or underscores. Character order is preserved where roster order matters.

Every entry has player.name, character.name, and a non-empty character.classes list. Class entries require a non-empty name and may include a positive integer level. The optional, intentionally singular character.alias field is a list. Names, aliases, and class names must be non-empty, trimmed display strings without control characters. Character names and aliases must be unique across the full roster under Unicode-aware case-insensitive comparison; player names may repeat.

The document has exactly one YAML document and accepts no unknown fields. schema_version is required: a missing, wrong, or malformed value is an error.

Migration

Unversioned party inputs are rejected. Replace each legacy party document with the versioned structure above, move each roster entry under characters, and remove separate player and session-party settings: those keys are unsupported.

The configuration rules and source-relative path behavior are defined in the Configuration Reference.

Derived players document

During prepare, Narratio copies the canonical party source bytes unchanged to inputs/party.yml and writes this deterministic players-only projection to inputs/players.yml:

schema_version: narratio.players.v1
players:
    - name: Eric
      character:
        id: arannis
        name: Arannis
        alias:
            - Ari
            - The Grey Owl

There is one entry per character, sorted by stable character ID. Repeated player names remain separate entries. The optional alias list retains its declared order and is omitted when empty. The projection carries no class data. Its prepared manifest record is marked derived_from_party; it is not a separate user-provided players_file.