Soulforge
Christopher Han <xiphux@gmail.com


---

Extending Soulforge

Soulforge is designed to be an extensible multi-universe
character sheet manager.  While adding support for another
universe is admittedly not a piece of cake, it's not extremely
difficult either, with just a little knowledge of the Python
programming language, wxWidgets, and XML.

There are basically three files you will need to edit.


soulforge/common/sfuniverses.py:
This holds the data on the universes - which ones are available,
and what to do for each one.  You'll want to import the modules
that your other universe code is in (we'll get to those shortly).

"universes" is just an array of the various universes available.
The string you put in here will be the unique identifier for your
universe, which will be used in sheets to identify the universe
as well as presented to the user in the universe chooser dialog.
So, for example,

universes = ['Vampire: The Masquerade','World of Darkness,'Vampire: The Requiem']

would make those three universes available.

There is an abstract base class "universe", which defines the methods
you'd need to implement in an actual universe, but raises exceptions
if run bare.  These are the methods you will need to implement in a
derived universe class:

  __init__(self): This can be used to set up runtime variables if necessary.
Otherwise it's just fine to leave it empty with a 'pass'.
  name(self): This should return the name of the universe - the unique identifier
that you used in the universes[] list.
  dtd(self): If you want, your universe can have an XML DTD that will be used
to verify whether or not a character file is valid.  This function returns that
DTD as one giant string - probably a triple-quoted string literal.  It's not
necessary, though - if you just leave it to return an empty string, soulforge will
assume you don't have/want a DTD and work fine - but beware that incorrect or corrupt
character data could crash the program.
  sheet(self, *args, **kwargs):  This is pretty much just a wrapper function that,
when called, will call the wxWidgets frame constructor for that particular universe's
sheet panel (discussed later).
  xml2sheet(self, *args, **kwargs):  This function will take an XML DOM in memory
with character data, and use that data to fill in the fields on a character sheet.
  sheet2xml(self, *args, **kwargs):  This is the opposite - when a sheet is OK'd, it
reads the data from the sheet fields and puts it into the XML DOM structure.

And finally, the 'getuniverse(univ)' function is pretty self-explanatory.  Given a
universe's identifier string, it will return the universe class for the program to use,
or None if not found.

soulforge/common/sheets/<your_universe>.py:
(with, of course, <your_universe> replaced with the actual universe name)
Technically, you don't even have to call it that.  It's just the convention
I used, so you should probably stick with it.  Inside this file is the class
that displays the editable character sheet.  There is too much to go into detail
about here - I recommend using wxGlade to create the interface.  You can
look at the file "wxg/vampire_the_masquerade.wxg" to see the wxglade template
used to create the "Vampire: The Masquerade" sheet.
There are two custom controls that you can use in the character sheets - the
"sfstat" and "sfpool" controls.  The "sfstat" control is the traditional
five-dot stat levels that you're used to.  Clicking at a certain dot will fill
all the previous dots in the chain, since they are prerequisites.  The "sfpool"
control represents a loose pool of something, a prime example being a blood pool.
In the pool, which boxes are selected does not matter at all - the only thing
that matters is how _many_ boxes are filled, e.g. how many blood points the
character has in his/her pool.


soulforge/common/sheets/<your_universe>_data.py:
This file contains the sheet2xml and xml2sheet functions.  Again, there's too
much to go into about here; I recommend just looking at the existing
vampire_the_masquerade functions to get an idea of what's going on.  I also
use this file to specify dynamic data that gets filled into the sheet - for
example, lists of disciplines, backgrounds, clans, etc.