Customizing Campaigns#

Campaigns are configured using the settings.yaml file in the campaign’s .npc/ directory. All of the campaign settings are under the campaign key.

name:

The campaign’s name

system:

The game system the campaign uses

desc:

A long-form description of the campaign

characters:

An object that defines where characters are stored and displayed

plot:

An object that defines how plot files are stored

session:

Object that defines how session files are stored

create_on_init:

List of additional folder names to create for every new campaign

A basic campaign’s settings.yaml file#
campaign:
    name: The First or the Last
    desc: My First Campaign
    plot:
        latest_index: 1
    session:
        latest_index: 1
    system: dnd5
npc:
    version: 2.0.1

New Campaigns#

Newly created campaigns are given a few directories by default:

  • .npc/

  • Characters/ (from campaign.characters.path)

  • Plot/ (from campaign.plot.path)

  • Session History/ (from campaign.session.path)

Since the campaign does not yet have its own settings file, the values for new campaigns are read from your user settings file. See Open Settings Files for how to edit that file.

An empty directy is also created for each entry in campaign.create_on_init.

The new campaign’s .npc/settings.yaml file is populated with the chosen name and system, as well as the current npc.version.

See Create a Campaign for how to set up a new campaign.

Plot and Session Management#

Plot and session files are configured in the campaign.plot and campaign.session objects, respectively. Both config objects share the same keys:

path:

Directory where the files should be placed

latest_index:

Numerical index of the most recent file

filename_pattern:

How to name the file

filename_contents:

What to put in the file

additional_files:

Other files to create alongside the plot or session file

Fully qualified plot and session blocks#
campaign:
    plot:
        path: Plot
        latest_index: 0
        filename_pattern: Plot ((NN)).md
        file_contents: ((COPY))
        additional_files: []
    session:
        path: Session History
        latest_index: 0
        filename_pattern: Session ((NN)).md
        file_contents: |
            Played:

            # (in-game date and time)
        additional_files: []

Naming and Indexes#

When a new plot or session file is created through NPC, it’s named using its filename_pattern, replacing the text ((NN)) with the index number that comes next. The new file’s index is derived from existing files, if they’re in path, so you can do things like manually create a plot file for next session, then use session to generate the corresponding session file. If neither file exists, then NPC falls back on the saved latest_index to generate the new file’s index.

File Contents#

New files created through NPC are filled with the value in file_contents. Plot files may use the special ((COPY)) placeholder string, which is replaced with the entire contents of the previous plot file, if it exists. This is a great way to keep running planning notes.

Additional Files#

Each entry in the additional_files list is an object with a filename_pattern and file_contents property. These properties act just like the ones for the main plot and session files.

An example of additional session files#
campaign:
    session:
        additional_files:
            - filename_pattern: Session ((NN)) Recap.md
              file_contents: "# Recap for Session NN"
            - filename_pattern: Session ((NN)) Journals.md
              file_contents: |
                # Character Journals for Session NN

                ## Tybalt

                ## Jolene

Added in 2.0.1

Character Management#

Character organization and handling is configured in the campaign.characters object.

path:

Directory where characters should be put

ignore_subpaths:

List of directories under path that should be ignored when loading characters. Good for archiving.

subpath_components:

List of objects that describe how to build the “ideal path” for a character based on its tags.

listing:

Object configuring how to generate Character Listings

use_blocks:

Which npc.tag_blocks to use for new files, and in what order

Basic Organization#

All character files are stored within the directory in campaign.characters.path, default Characters/.

Any character files within a directory found in ignore_subpaths is skipped entirely and will not be available within NPC. This is most useful for archiving old files or cordoning off generic sheets.

Guide to Subpaths#

When creating a new character, or reorganizing existing characters, the list of objects within subpath_components are used to build out the character’s path. Each of these objects is applied in order and can add a directory to the character’s path.

If a directory would be added that doesn’t already exist, it will be skipped entirely and the next subpath component will be evaluated. This can be very useful for creating branching paths.

Hint

Some cli commands (like reorg) have an option to create these missing directories instead.

Important

Subpaths can only examine top-level tags. Nested tags, like the character’s role within an org, cannot be accessed.

The fallback properties were added in NEW_VERSION

These are the available subpath components:

Conditional Value#

Add the directory from value if at least one of the tags is present in the character.

Properties:

selector:

required Must be conditional_value

value:

required The directory name to return

tags:

required The tags whose presence will be checked, in order

fallback:

A directory name to use if none of the tags are present

Example:

subpath_components:
    - selector: conditional_value
      value: Deceased
      tags: [dead]

First Value#

Add a directory from the first value found for any of the specified tags. Tags are checked in order.

Properties:

selector:

required Must be first_value

tags:

required The tags to read, in order

fallback:

A directory name to use if none of the tags are present

Example:

subpath_components:
    - selector: first_value
      tags: [org, location]

Static Value#

Add the directory from value.

Properties:

selector:

required Must be static_value

value:

required The directory name to return

Example:

subpath_components:
    - selector: static_value
      value: Unaligned

Match Value#

Add the directory from value if at least one of the tags contains the value in equals.

Properties:

selector:

required Must be match_value

value:

required The directory name to return

equals:

required The tag value to test against

tags:

required The tags to examine

fallback:

A directory name to use if none of the tags match the value in equals

Example:

subpath_components:
    - selector: match_value
      tags: [class]
      equals: Cleric
      value: Blessed

Added in 2.0.2

File Names#

Character file names have three parts: the character’s name, their mnemonic, and the file extension.

Grete Mann - goodest boy.npc
^            ^           ^
name         mnemonic    extension

The name and mnemonic must be separated by a space, hyphen, and then another space (n - m).

The default file extension is .npc, but a more specific extension can be used instead based on the extension used for the character type’s sheet template. This is usually the same as the key of the campaign’s game system, like .fate or .nwod.

If a character’s name cannot be part of a valid filename, usually because of special characters, use a simplified version for the filename and add a @realname tag to the file with the correct name. This is handled automatically by NPC when it creates a new character, but is important to remember when you create or rename character files by hand.