narratio/docs/integrations/party.md

Canonical Party Input

party.yml is a campaign-owned roster input. Narratio recognizes the versioned narratio.party.v1 document below when it 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. A wrong or malformed schema_version is an error.

Legacy migration boundary

An unversioned party input remains supported only as opaque legacy reference material while campaigns migrate. It requires a separate players_file and retains the existing session override behavior. It cannot be mixed with a canonical party: canonical campaigns must omit players_file, and sessions must not override their party or players inputs.

Use the canonical document for new campaigns. The configuration rules and source-relative path behavior are defined in the Configuration Reference.