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.

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.