The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Game-HexDescribe-1.03
River stage zero No dependents
++
/ Game::HexDescribe

NAME

Game::HexDescribe - a web app to add random table driven data to map data

DESCRIPTION

Hex Describe is a web application which uses recursive random tables to create the description of a map. A map in this context is a hex map. This is different from other such tools like Tracery because a collection of locations on a maps differ from a list of unrelated items. Neighbouring locations can share features and thus a river can flow through many locations, a forest can cover many locations, and so on.

On a technical level, Hex Describe is a web app based on the Mojolicious framework. This class in particular uses Mojolicious::Lite.

See Mojolicious::Guides for more information.

Configuration

As a Mojolicious application, it will read a config file called hex-describe.conf in the same directory, if it exists. As the default log level is 'warn', one use of the config file is to change the log level using the loglevel key, and if you're not running the server in a terminal, using the logfile key to set a file.

The default map and table are stored in the contrib directory. You can change this directory using the contrib key. By default, the directory included with the distribution is used. Thus, if you're a developer, you probably want to use something like the following to use the files from the source directory.

    {
      loglevel => 'debug',
      logfile => undef,
      contrib => 'share',
    };

The default map was created using Text Mapper's Alpine algorithm at one point in time and the code has changed in the mean time, so it cannot be recreated anymore.

URLs

The code needs to know where Text Mapper and the Face Generator can be found. You can add these to the same config file we mentioned above. This is what you probably want as a developer:

    {
      text_mapper_url => 'http://localhost:3010',
      face_generator_url => 'http://localhost:3020',
    };

This assumes you are running the two locally. See Game::TextMapper for Text Mapper.

Entry Points

As this is a web app, the URLs you can call are basically the API it exposes. Each URL can accept either get or post requests, or any.

get /

The default entry point is where you edit your map and table. map is the map, url is the URL to an external table, table is the text of the table if you want to paste it. See /describe below if you want to display the result instead of allow the user to edit the form.

get /load/random/smale

This shows you the edit page again, with a new random map generated by Text Mapper using the Smale algorithm.

get /load/random/apocalypse

This shows you the edit page again, with a new random map generated by Text Mapper using the Apocalypse algorithm.

get /load/random/traveller

This shows you the edit page again, with a new random map generated by Text Mapper using the Traveller algorithm.

get /load/random/alpine

This shows you the edit page again, with a new random map generated by Text Mapper using the Alpine algorithm.

get /stats/random/alpine

This uses a random map and the Alpine algorithm, and describes the map, and then it presents you with some stats.

any /describe

This is where the actual map is described.

map is the map, url is the URL to an external table. table is the text of the table. load determines the table to load. Current valid values are seckler, strom, schroeder, johnston, and traveller. markdown returns Markdown and no map. faces determines whether images are kept in the HTML output. show determines whether the map is kept in the HTML output.

If we want to call this from the command line, we will need to request a map from Text Mapper, too.

    text-mapper get /alpine.txt > map.txt
    hex-describe get /describe --form map=@map.txt --form load=schroeder

Pipe through lynx -stdin -dump -nolist to get text instead of HTML.

get /describe/random/smale

This variant is for when you want to just keep reloading and getting different maps with different descriptions. Note that you may pass a url parameter, which determines the map retrieved by Text Mapper. This allows you to refer to an existing, random map, if you use the seed parameter in that URL. If you don't provide a URL, a random map using the Smale algorithm will get used. The description will be generated using the Seckler tables.

get /describe/random/alpine

Same thing for a map using the Alpine algorithm and the Schroeder random tables.

get /describe/random/strom

Same thing for a map using the Smale algorithm and the Strom random tables.

get /describe/random/johnston

Same thing for a map using the Apocalypse algorithm and the Johnston random tables.

get /describe/random/traveller

Same thing for a map using the Traveller algorithm and the Traveller random tables.

get /nomap

This shows you the edit page for use cases without a map. Now you're using Hex Describe like many of the existing random table driven text generators. This is where you can test your tables. If you've changed the code for the village table, for example, generate a few villages to see some examples:

    [village]
    [village]
    [village]
    [village]
    [village]

input is your source text. This is no longer a map. url is the URL to an external table, table is the text of the table if you want to paste it. See /describe/text below if you want to display the result instead of allow the user to edit the form.

/rules

This lists all the rules we have and allows you to pick one.

any /describe/text

This is where the text input is rendered. input is the text, url is the URL to an external table. If not provided, table is the text of the table. If neither is provided, the default table is used.

To call this from the command line:

    hex-describe get /describe/text --form input=[village] --form load=schroeder

Pipe through lynx -stdin -dump -nolist to get text instead of HTML.

get /default/map

This shows you the default map.

get /schroeder/table

This shows you the table by Alex Schroeder.

get /seckler/table

This shows you the table by Peter Seckler.

get /strom/table

This shows you the table by Matt Strom.

get /johnston/table

This shows you the table by Josh Johnston.

get /traveller/table

This shows you the Traveller table by Vicky Radcliffe and Alex Schroeder.

get /rorschachhamster/table

Für die deutschen Tabellen von Rorschachhamster Alex Schroeder.

get /source

This gets you the source code of Hex Describe in case the source repository is no longer available.

get /authors

This lists the contributors to Hex Describe.

get /help

This shows you a little tutorial. Unlike this documentation, which is for programmers, the tutorial is for the users of the app.

Code

This chapter is used to document the code.

get_data

This is is the basic work horse to get data from a URL. It is used to download the table from a URL, if provided. This uses a simple GET request.

get_post_data

This is is used to get data from a URL when we need a POST request instead of a GET request. We need this for Text Mapper when rendering the map since we send the entire map to Text Mapper in order to render it. A simple GET request will not do.

get_table

This function gets a Mojolicious Controller object and looks for map, load, url and table parameters in order to determine the table data to use.

After we get the SVG map from Text Mapper, we need to add links to the hex descriptions. Text Mapper already allows us to define an URL such that labels get linked to that URL. This feature is of no use to us because we're not using labels. Basically, we want to add links to the coordinates. This function does that: it goes through the SVG and adds appropriate anchor elements.

helper example

This Mojolicious helper is used on the help page to make all the examples clickable.

Finally

Start the app at the very end. The rest is templates for the various web pages.