DGSH - a tool for Dungeon Masters

DGSH - the DunGeon Shell
$Id: index.shtml,v 1.6 2002/09/08 08:18:14 jmettraux Exp $
* home
* features
* installing
* running
* tracking your party
* adding a PC or a NPC
* parsing stat blocks
* some fight
* commands
* scripted commands
* scripted triggers
* javadoc
* data files
* missing features
* mailing lists
* some links
* credits
* download
* dgsh on sf.net
* sources
* contact

Dgsh is for Dungeon Masters

The DunGeon SHell is a shell-like interface for tracking a party of d20 characters and their opponents.

I wrote dgsh because I was tired as a DM of rolling initiative for 5, 6 more goblins and tracking who's the next to play. The rest of the features came naturally.

Dgsh hasn't any fancy graphical user interface because I wanted to concentrate on fonctionality. If your machine can run Java 1.4.0, even if it's an old machine, you can run dgsh... A good choice would be an old Pentium laptop, with linux and no X server running,...

Dgsh is not a character generator. But it will soon be able to parse standard stat blocks to turn them into its own (XML) format. If you're looking for a character generator, PCGEN might be the best choice.


dgsh is a shell, it has no user-friendly interface, you must type commands, there is nothing to click.
It concentrates on functionality and tries not to drag you away from your real DM tasks.


Don't be shy or too polite, tell me what you think of dgsh and what you await from such a soft.

My mail address is jmettraux @ burningbox.org, but the best thing would be to send your mail to the users mailing list.

Thanks in advance !

New :

Game time is now tracked ! At the end of each combat, time elapsed is added to the game clock. With commands like 'clock add 3h' you can add durations to the game clock.
It should be easier now to respond to the player classical question : "What time is it now ?"

There is now a sample session you can browse.
It displays how dgsh is used. You can also browse the generated log file.

Added 'charge', 'fidef' and 'todef' commands.
They implement respectively 'charge', 'fighting defensively' and 'total defense'. They can only get used during combat and tags the creature whose has the turn as 'charging', or 'fighting defensively'...
The modifiers are set on the creature

Added a 'treasure' command for generating random treasure. For the moment, only the 1st level SRD treasure table is implemented.
The other tables will follow as well as well as a mechanism for rolling on your scenario encounter tables.


Dgsh doesn't abolish scenario study and session preparation. It is designed to help you during the game session.

  • hit points and subdual damage tracking
  • initiative roll and tracking
  • temporary ability loss
  • experience computing
  • AC automatic determination
  • attacks of opportunity tracking (even with 'Combat Reflexes')
  • load computing (with application of modifiers and penalties)
  • sessions get logged into a file you can directly browse
  • effects that spans multiple rounds
  • scriptable in j[p]ython (custom commands, spell triggers, effects...)
  • skills (ranks, modifiers, total, ...)
  • feats (and their impact on weapons' attack modifiers)
  • a growing catalog of monsters with their special attacks and abilities
  • spellbooks, spell preparation and spell slots count
  • domain spells for clerics
  • SRD documents browsing
  • scenario documents browsing
  • data is stored in XML (java 1.4.x Object XML Encoding)
  • XML random treasure tables and random encounters table (soon)
  • tracking of 'charge', 'fighting defensively' and 'total defense'
  • game time tracking through the clock command. At the end of each combat, the time elapsed is added to the game clock.
  • raptor tool for parsing standard stat blocks

Installing dgsh

Requirements :
you need at least a 1.4.0 Java Virtual Machine. You don't need any fancy monitor, dgsh is a plain ASCII shell.

Download the zip file of the latest binary release and then unpack it in any of your directory.

Running dgsh

Into the unpacked dgsh/ dir type ./dgsh.sh and start using dgsh. Make sure your JAVA_HOME is set, either in the env, either directly in dgsh.sh

On windows, get into the dgsh directory and type dgsh

Tracking your party

At first, you've got to load your party into the game session. Type load p.xml party to load a sample party. Then use display shana to show who and what Shana is.

Dgsh knows 2 states : normal or fight. You enter normal mode when you start the shell. You enter the fight mode with the fight command and then leave it with relax.

After you've typed relax, dgsh will tell you how many XP your party should earn for this encounter, but after, it's up to you as the DM to award them to the PCs and this can be done with the xp command.

Some fight

Make sure your party is loaded (if you haven't any, take mine by typing load p.xml p).

Type fight to enter combat mode (it enables the opponents set).

Then load monsters.xml and inst goblin 10 gob to instantiate 10 goblins named gob1 to gob10.
You can display your freshly generated little monsters with the opp command.

Type init to automatically roll initiative for the goblins. Dgsh will then ask you the result of yours PC rolls (My player love to add themselves their initiative modifiers, so dgsh doesn't add this modifier to the result you type).

next will tell you 'in detail' who's the next to play.

When the fight is over, it's time to relax.

Scripted triggers

Triggers are pieces of code called at given times.

A good example of trigger is the regeneration trigger, which allows creatures like trolls to regenerate.

The barbarian rage script also contains a trigger which applies at the end of the rage and inits the barbarian's depression.

Spells have a trigger : some code that is called when they are cast. I haven't much worked on implementing a trigger for each spell that diserves it, but I might do it one day or the other. For the moment, only 'Magic Missile' has a trigger, but a dummy demo one.

If you are interested in writing spell triggers, study the barbarian rage script... And don't hesitate to contact me

The regeneration script doesn't strictly match the rules for regeneration for the moment. It is sufficient though.
I'm thinking about having a different system of hit points, and this future system will include 'subdual' damages for regenerating creatures.


It's rather terse now, but it could improve. Anyway, you can take a look at it.

The data files of dgsh

Dgsh uses XML and Java 1.4.x XML bean externalization.

you can have a look at the data files.

Classes and races are the dnd standards, the Monk class has not been included : there is no monk in my campaign so. Also not included are prestige classes, I haven't thought about it, but they should match the current data model for character classes.

If you want to add your own data files (do it !), add them somewhere and then modify etc/dsh-config.xml to add an entry that should read like :

    <void method="add">

under the 'dataFileNames' property of the file. Note that the my_campaign_races.xml file is referred with its absolute path in this example : relative paths are also allowed (They are relative to the working directory from which you launched dgsh).

Mailing lists

  • subscribe to the dgsh mailing list
  • browse the list archive (there is nothing right now, we're waiting for your feedback)

Missing features

I will implement these features sooner or later :

  • spells management ... DONE
  • session logging then browsing ... DONE
  • special abilities for monsters ... DONE
  • temporary ability loss (poison tracking) ... DONE with the ab command and the Effects
  • time tracking during session and especially combat sessions ... DONE
  • bodycount ... DONE
  • XP count ... DONE
  • automatic treasure generation ... almost DONE
  • more equipment
  • a variable system (player1 could be $p1)
  • a bit of junit testing (or pyunit...)
  • PCGEN characters conversion to dgsh (should wait for their new XML format)
  • As soon as the VP/WP (vitality/wounds) system hits the SRD, I will implement it.

Some ideas in my head (why_nots) :

  • using embedded jython for spells and effects ... DONE
  • using jython scripts to easily generate party.xml files ... DONE
  • having ASCII art for each PC or monster, or at least a skull displayed when a PC dies...

Ideas you won't find anywhere in my head (nots) :

  • implementing a GUI (graphical user interface) for dgsh (though it could easily get done with jython) ... (But if somebody insists on developing it...)
  • implementing a .NET UI for dgsh ;-)

Some links

Links to tools close to dgsh :

  • RolePlayingMaster is a complete Windows-only program for managing your party and its opponents. Far more advanced than dgsh.
  • PCGen is a great character generator written in Java. Also hosted on sf.net
  • DM Familiar is a Windows software package to help the DM prepare for and run his game
  • Jamis Buck's generators for generating NPCs, towns, dungeons or treasures online.


You are welcome to use the SourceForge facilities for requesting features, support or patches.
You can also contact me directly at jmettraux@ burningbox.org


D20 and Dungeons and Dragons are registered trademarks of Wizards of the Coast.

Java is a registered trademark of Sun Microsystems.


Make sure to download the latest release (the highest on the page). You can download dgsh either packed as a zipfile or a tar.gz archive.

Remember that dgsh requires a Java Virtual Machine, which you can download at http://java.sun.com/j2se/1.4/download.html. A Java Runtime Environment (JRE) should suffice.

$Id: index.shtml,v 1.6 2002/09/08 08:18:14 jmettraux Exp $

hosted on SourceForge Logo and