# RPG player character parser

It's FreeRPG Day again, which means you can go to participating local game stores and choose from several no-cost roleplaying game booklets to take home with you.
For me, a good tabletop roleplaying game (RPG), sometimes called a pen-and-paper RPG, is the perfect hobby for getting away from my computer.
The classic editions of Dungeons & Dragons (D&D), for example, were released well before PDFs and ebooks existed, so I bring hardcover books and paper character sheets to my gaming table.
In recent years, however, I've also started gaming online using [Mumble](https://opensource.com/article/20/4/voice-chat-mumble) voice chat.
At first, I treated these games the same as my in-person games, but as more games started integrating online maps like [MythicTable](https://opensource.com/article/20/11/open-source-battle-maps), I found switching back and forth between keyboard-and-screen and pen-and-paper became a little frantic.
When I'm running a player character (PC), most of what I need to refer to is on a character sheet, a document that lists my special abilities and powers.
To get to that information quickly while managing a bunch of other applications, I use the `pc` command.

The `pc` command parses RPG character sheets written in a the [INI format](https://opensource.com/article/21/6/what-config-files#ini).
It works with any RPG game system, as long as that system's character sheet data can be expressed as basic INI (and most of them can be.)

## Install

The `pc` command is written in [Perl](https://opensource.com/article/22/2/perl-cheat-sheet), so you must have Perl installed to use it.
On Linux and macOS, you already have Perl installed.

On Windows, you can install either [ActiveState or Strawberry](https://www.perl.org/get.html#win32) Perl.

To install the `pc` command, you can just make it executable and move `src/pc.pl` to [some location in your path](https://opensource.com/article/17/6/set-path-linux).
For example:

```bash
$ chmod +x src/pc.pl
$ sudo mv src/pc.pl /usr/local/bin/pc
```

You can alternately use cmake:

```bash
$ mkdir build
$ cd build
$ cmake ..
$ cmake --install .
```

## Building characters in INI

For `pc` to be able to parse your character's stats, you must build or document your PC in the INI format.
INI is a simple text format that consists of a heading in brackets, and a group of key and value pairs.
For example, here's a portion of a D&D character sheet:

```
[Character]
Name=Tristan
Ancestry=Human
Background=Urchin
Class=Paladin
Level=8

[Health]
HP=35
Max.HP=68
AC=19

[Stat]
STR=+2
DEX=0
CON=+2
INT=-1
WIS=+3
CHA=+4
```

All of this is for your own reference, so you don't have to adhere to anything but the general INI format.
You can include stats that aren't on the paper version of your character sheet, or even just write personal reminders to yourself as comments.
Make your INI character sheet work for you and let `pc` do the rest.

Once you've got your character sheet, save it, with the `.ini` extension, to `~/.local/share/pc`.

## List your character sheets

Using `pc`, you can get a list of all the character sheets you have saved:

```bash
$ pc --list
Abbadon.ini
Dreadmax.ini
NPC_1076.ini
NPC_1077.ini
Tristan.ini
Zoe.ini
```

## Get a stat

When you roll dice in an RPG, you often have to adjust your roll according to your character sheet.
For instance, if you're attacking an evil orc, you might roll 10 on your 20-sided die, and then add a number to represent your physical strength.
To get your Strength (often abbreviated as `STR`), provide the character name and the stat you want to see.
Character names are case-sensitive, so if your character is saved as `Tristan.ini`, the character name is `Tristan` and not `tristan` or `TRISTAN`.

```bash
$ pc Tristan STR
STR=2
```

You now know that you must add 2 to your roll.

## Unique and non-unique stats

As long as a stat is unique, you don't have to type out the whole string.
For instance, if the only stat in your character sheet starting with `Max` is `Max.HP`, then you can just type `Max` or possibly even `Ma` and `pc` can usually figure out what you want.

```bash
$ pc Tristan Ma
Max.HP=68
```

However, many game systems use the same stat for different attributes.
For instance, in D&D your Wisdom (WIS) may be significant for both Wisdom-based skills and Wisdom-based saving throws.
In other systems, both armor and weapons could have a level assigned to them.
Non-unique stats return ambiguous results:

```bash
$ pc Tristan WIS
WIS=3
WIS=5
```

Any time a stat you need is non-unique, you can specify the category you want first, to narrow down the result:

```bash
$ pc Tristan Save WIS
WIS=5
$ pc Tristan Stat WIS
WIS=3
```

## View a whole category

If you want to see several related stats, you can view an entire category at once by just specifying it.
As long as it's sufficiently unique, you don't have to type the whole word:

```bash
$ pc Tristan Hea
[Health]
HP=42
Max.HP=68
AC=19
```

To see a list of categories in your character sheet, use the `--cat` (`-c` for short) option:

```bash
[Character]
[Health]
[Stat]
[Save]
[Skills]
[Proficiencies]
[Immune]
[Lang]
```

You can omit all arguments to see the whole character sheet:

```bash
$ pc Tristan
[Character]
Name=Tristan
Ancestry=Human
Background=Urchin
Class=Paladin
Level=8

[Health]
HP=42
Max.HP=68
AC=19
[...]
```

## Update a stat

Most role-playing games require that you track certain statistics as you play.
For instance, when you're battling a group of baddies, your health or hit points (HP) probably goes down as you take hits.
In other systems, you might gain points in a skill as you utilize and gain experience with it.

While `pc` is by no means intended to be an editor, it can perform minor changes for you.
To update a stat, use the `--set` (`-s` for short):

```bash
$ pc Tristan HP 
HP=68

$ pc Tristan HP --set 60
HP=68
HP updated to 60

$ pc Tristan HP
HP=60
```

## Easy character management

There are lots of ways to manage a character for an RPG, including the open source character generator [PCGen](https://opensource.com/article/18/4/pcgen-rpg-character-generator), the traditional pen and paper method, and specialized websites.
The `pc` command is another way for you to keep track of data, and for me it feels like a natural and convenient method that fits into the way I manage most of the data in my real life.
Give `pc` a try the next time you sign up for an online game, and if you're a Perl programmer, see what new features you might be able to add to it.