74 lines
2.6 KiB
Markdown
74 lines
2.6 KiB
Markdown
# 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.
|
|
|
|
```yaml
|
|
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](../config.md).
|
|
|
|
## 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`:
|
|
|
|
```yaml
|
|
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`.
|