Persona is a library designed for tracking and manipulating data about fictional people -- primarily characters in roleplaying games, but probably suitable for characters in stories as well.

It is very far from a complete project, currently. You may not find any particular use for it without contributing significant code yourself.


This project is currently in the process of being reorganized. Some of the following information may fall in and out of effective usefulness during this process. There is a gemspec file, but trying to build a gem right now will not result in something that is likely to work properly when installed as a gem during this time. Let the buyer beware.


As things stand, the "official" way to "install" Persona with its modules and the pertracker.rb shell initiator looks something like this:

  1. Clone the source repository from Bitbucket using Mercurial.

  2. Set up an application directory for Persona. The default, as defined in personaconf.rb, is ~/.persona. As an alternative, change the application directory to suit your needs or those of your operating system by changing the value of the BASEDIR constant in personaconf.rb.

  3. Create two subdirectories within the .persona directory: data and mods. As an alternative, change the data directory to suit your needs by changing the value of the DATADIR constant in personaconf.rb.

  4. Create symlinks or copies of all the .rb files in the Persona project in the mods directory except persona.rb itself and personaconf.rb. As an alternative, change the mods directory to suit your needs by changing the value of the MODULES constant in personaconf.rb.

  5. Create symlinks in the mods directory (or wherever you set your default module location) for all the .rb files in the Persona project, or make copies of those files there.

  6. Create symlinks somewhere in your Ruby load path for the persona.rb and personaconf.rb files, or make copies of them there. If you wish, you may create a directory (e.g. ~/rubylib) and add it to your Ruby load path, such as by adding one of the two following lines to your shell's rc file (e.g. ~/.bashrc or ~/.tcshrc), depending on the shell you use:

    export RUBYLIB='/path/to/home/you/lib'
    setenv RUBYLIB '/path/to/home/you/lib'
  7. Create a symlink somewhere in your execution path for pertracker.rb, or make a copy of the file there, if you want to use the interactive Ruby shell interface for Persona. You may wish to shorten the name somewhat to make it quicker and easier to type, such as by creating a symlink or copy of the pertracker.rb file with the name pt. You could also do this with an alias. Accomplishing this is left as an exercise for the reader.

At some later date, the installation process will probably become more streamlined, but for now Persona is still development software and we're focusing on other things.

Persona requires Ruby, of course, and the pertracker.rb script relies on irb (which should be installed along with Ruby in most cases).

Persona also requires the Date and Digest libraries, from the Ruby standard library.

The PersonaYAML module requires Ruby's YAML library.

Code Examples

The Persona class can be used with an interactive shell application easily enough, leveraging irb for the heavy lifting. The following uses a (varation on the) pertracker.rb script in the Persona project repository:

>> rys = Persona.open 'EolrysAzrith'
=> #<Persona:0x7f6e96509900>
>> tara = Persona.open 'TaraWeiss'
=> #<Persona:0x7f6e964f3128>
>> rys.personalia[:race]            # personalia provides raw data access
=> Rostlander Quarter-Orc
>> rys.strength                     # also aliased as str and s
=> 12
>> rys.dexterity
=> 16
>> rys.coordination                 # also aliased as dc
=> 18
>> rys.birthdate
=> 4689-07-03
>> rys.calendar
=> Golarion
>> rys.today
=> 4711-04-18
>> rys.age
=> 21
>> puts rys.appearance
>> rys.attractiveness_to tara.prefs
=> 23

The pertracker.rb script should be adjusted to account for any quirks of library path configuration on your system. This example assumes that persona data files EolrysAzrith.yaml and TaraWeiss.yaml are located in the current working directory. The example also assumes the use of the following ~/.irbrc configuration option:


It also assumes a personaconf.rb something like the version included with this project.

A default filename may be specified by setting a value for a :record key:

>> cormac.personalia[:record] = 'CormacWeiss'

The character object's personalia data may then be saved to the CormacWeiss.yaml file with the dump message:

>> cormac.dump

Loading a persona from a file in the data directory automatically sets the value associated with the :record key appropriately so that dump can be used to automatically save changed data to the same file.

Reporting Issues

If you want a feature that does not already exist, please label the issue a Proposal.

If you want a new module, please assign the issue to the Module System component.

If you want changes made in the configuration system or in the default configuration file personaconfig.rb, please assign the issue to the Configuration File component.

If your issue's classification defies description by one of the existing component types, please assign it to the Other component. This may lead to more components being added to the issue tracker system, so keep an eye out for new components in the future.



The preferred means for new contributors to contribute code to the project is via the Pull Request feature on the Bitbucket site. If you wish to contribute by some other means, please contact me via the Send Message feature of Mercurial to discuss it, if you do not already have a better way to get in touch with me. Using Mercurial commits to contribute (via the Pull Request feature of Bitbucket, most conveniently) has several benefits, including giving the developer credit for his or her work within the version control system's history itself.

Once some commits have been accepted via pull request, contributors may be granted more direct commit access to the Bitbucket repository. Criteria for commit access will depend on factors such as how much the code needs to be altered before committing to the main repository and how often contributions are accepted at all.

The goal is to make this a thoroughly test-driven project, at this time using Ruby's default xUnit testing framework, Test::Unit. One factor that will weigh heavily in how quickly a contribution is accepted is how complete a set of tests comes with the contributed code.

Another factor that will weigh heavily is whether a usable module is contributed that does not duplicate effort already underway.


Documentation contributions are as welcome as code contributions. Please do your reasonable best to ensure everything is spelled correctly, grammatically correct, clear, and formatted in the style of already existing documentation.