/hex-describe

A web app to add random table driven data to map data

Primary LanguagePerlOtherNOASSERTION

Hex Describe

This application takes a map generated by Text Mapper and a set of random tables to generate a textual description of the region. It's ideal if your players are wandering into unprepared regions, and it's great if you need some seed material to base your work on.

You can provide your own random tables if you have the file online somewhere in a Pastebin or shared it from Dropbox, etc.

The format is simple: every word in the map description and every two word combo from the map description is a potential table in your file. If it exists, it will be used.

Assuming the following description:

0101 dark-green trees village

The description will be generated from any tables that match:

  • dark-green
  • trees
  • village

It would make sense to just provide tables for "trees" and "village", for example.

Tables looks like this:

;trees
1,some trees
1,you encounter [forest monster]

;forest monster
3,[3d6] bandits
1,an elf

A semicolon and some text begin a new table. A number, a comma, and some text are an entry in the table. The text needs to be on one line. The numbers are relative probabilities. The chances for an encounter in the forest are thus 50% and the chances to encounter an elf, if you are encountering anything at all, are 25%. The example also shows how you can link from one table to another using square brackets.

Square brackets are also used for dice rolls. A dice roll can look like this: 3d6, 3d6+5 3d6x10, or 3d6x10+5.

There's an built-in help page with more details for end users. If you intend to host the application yourself, use perldoc hex-describe.pl to get a more technical documentation based on the comments in the code.

Try it.

The app comes with a tutorial built in. See the Help link.

Dependencies

Perl Modules (or Debian modules):

  • Array::Utils or libarray-utils-perl
  • IO::Socket::SSL or libio-socket-ssl-perl
  • LWP::UserAgent or liblwp-useragent-perl
  • List::MoreUtils or liblist-moreutils-perl
  • Modern::Perl or libmodern-perl-perl
  • Mojolicious or libmojolicious-perl
  • Text::Autoformat or libtext-autoformat-perl
  • File::ShareDir or libfile-sharedir-perl
  • File::ShareDir::Install or libfile-sharedir-install-perl

The IO::Socket::SSL dependency means that you’ll need OpenSSL development libraries installed as well: openssl-devel or equivalent, depending on your package manager.

To install from the working directory (which will also install all the dependencies) use cpan or cpanm.

Example:

cpanm .

Installation

Use cpan or cpanm to install Game::HexDescribe.

Using cpan:

cpan Game::HexDescribe

Manual install:

perl Makefile.PL
make
make install

Configuration

In the directory you want to run it from, you may create a config file named hex-describe.conf like the following:

{
  # error, warn, info, or debug
  loglevel => 'debug',
  # undef means stderr, or a file name
  logfile => undef,
  # undef means the default directory, or a directory name
  contrib => 'share',
  # the URL where you run Text Mapper to generate maps (optional)
  text_mapper_url => 'http://localhost:3010',
  # the URL where you run Face Generator to generate faces (optional)
  face_generator_url => 'http://localhost:3020',
}

Development

As a developer, morbo makes sure to restart the web app whenever a file changes:

morbo --mode development --listen "http://*:3000" script/hex-describe

Alternatively:

script/hex-describe daemon --mode development --listen "http://*:3000"