Token-based Handout System

Show off your RPG maps, campaigns, and tokens. Share your gaming experiences and stories under General Discussion and save this forum for things you've created that may help others run their own games. Use the subforums when appropriate.

Moderators: Azhrei, dorpond, trevor, Gamerdude

DEDEN
Kobold
Posts: 12
Joined: Sat Sep 05, 2009 8:21 pm

Token-based Handout System

Post by DEDEN »

I've been doing a bit of scripting here and there with map tool macros since I started DMing a D&D4 campaign about five or six weeks ago and like most people I've run across the issue of handouts and player-specific messages. After reading through some of the posts on these forums I didn't really find any solution I liked, so I figured I'd write my own.

What I came up with isn't a framework by any means. With the exception of a campaign macro and a couple of tables, all of the functionality and all of the data is stored within a single library token (or more if you want to get fancy), which can be exported/imported from campaign to campaign as necessary.

As usual, try it out at your own risk. It's still rough around the edges and in no way thoroughly bulletproofed or tested. I've only put the scripts together in the last couple of days, so there's probably all sorts of issues waiting to be found -- and I haven't had a chance to check out that image-not-loading-over-the-internet issue (largely because I run a subversion repository for the asset cache -- players just double-click a batch file prior to running map tools and it updates everything for them -- so they always have the latest assets).

All that being said, it did seem to work pretty well for the game I played last night, so...

Image

OVERVIEW
This macro system provides an interface and backend functionality to create, edit, store, delete, and view handouts, to notify players of handouts that are now available to them, and to allow players to view a current list of their handouts, highlighting those that have not yet been viewed. It also allows a GM to limit access to handouts, setting their permissions on a player-by-player basis.

Handout functionality and data is all stored in a library token and accessed by a campaign macro. Two tables store information about handout styles and some icons used for the handout menus and so on.

INSTALLATION
1) Import the Handout Styles and Handout Icons tables into your campaign.
2) Add the handouts library token to a map in your campaign (preferrably on the hidden layer). Ensure it is visible to players and its name begins with "Lib:". These values should be enabled by default for this token.
3) Import the Handouts macro into your campaign macros.

REQUIREMENTS
- Map Tools 1.3.b57. I can't vouch it'll work on earlier versions but it probably will. Maybe. =)
- When you start your server, ensure that Player's Receive Campaign Macros is enabled.

FILES
Handouts Library Token
Handouts Campaign Macro
Handouts Icons Table
Handouts Styles Table

EXAMPLES
Handouts Campaign File

USAGE GUIDE
All of the functionality of this handouts system is available via the "Handouts" campaign macro. Simply click it to bring up the relevant frame (either the GM Handouts frame if you are the GM or the Player Handouts frame if you are a player).

HANDOUT DATA
Handouts contain a bunch of different types of data, only a little of which is actually useful to the player/GM. THere are five primary pieces of information that are important (the remainder are pretty much hidden from the end user so they can safely be ignored). These are: title, summary, content, and style.

The handout title is what appears at the top of the handout. It's a simple text string. Not much more you can say about it. I like to keep handout titles fairly full of flavour text, so that players have to view the handout to actually get an idea of what it's about. eg. "A Dark And Hungry God Arises". Gotta love stealing book titles. =)

The summary is a single line of text which gives a bit more detail about the handout. I usually use it for descriptions of where the handout was found or what it's about. eg. "Found on the body of a dead cleric in the tombs of the Al'harach."

The content is just what it sounds like. It's the bulk of what the handout is about. It can contain html (limited to 3.2 ugh) and can also be used to add images like portraits and so on. At the moment I'm only doing minimal amounts of formatting on the content of a handout (simple line breaks and so on), but sometime in the future I'm thinking of implementing things like decoration initial text and so on. Until then, you can always just do something like what's below to get your decorative text.

Code: Select all

<span style = "font-family: Impact; font-size:3em;">D</span>ecorative


The last type of data that a handout can contain is its style. This is essentially just a simple index into the Handout Styles table -- which provides a background and allows the css styles of the default handout to be overriden. If you want a new background with a different type of text, just add it into the appropriate table. You can then select it by simply ticking the relevant checkbox on the edit handout dialog.

Individual handout data is completely contained within the library token. Thus, exporting the library token will effectively save all your handouts out to a separate file which you can then import into other campaigns.


GM HANDOUT
Image
The GM handout view is a frame which forms the core interface for the GM. So far I've been using it docked over to the right of the screen so I can quickly flick it open and add/remove/adjust handouts as needed. That seems to work fairly well for me.

The GM handout view allows a GM to create new handouts (by clicking the create button at the top-left), to remove existing handouts (by pressing the remove button adjacent to each handout entry, and then checking "Yes" when prompted for whether you want to confirm the deletion), to refresh the current list of handouts (by clicking the refresh button at the top-right -- handy if you have multiple GMs adding separate entries), and to edit existing handouts (by clicking on an individual handout entry).

At the moment, the only way to adjust handout permissions is to click on the handout entry and go into the edit handout dialog and then adjust them there. I'm thinking about re-working the GM handout view slightly to allow you to set the permissions directly from that interface, but I dunno... I guess I'll see how much of a hassle it is to have to go through an extra screen every time first.


CREATE/EDIT HANDOUT
Image
The create/edit handout dialog is the next screen of importance. It allows you to fill out the main details of the handout (title, summary, content, and style, by typing into the relevant field or selecting a style from the list), to preview what the handout currently looks like given the values currently in the fields (by clicking the Preview button at the top-right), and to edit which players have permission to access the handout (by clicking the permissions button at the top-left).

Also of note on the create/edit handout dialog are the options to add GM Notes, Image, Notes, or a Portrait from a token to the content. Simply click the relevant button and you'll be prompted to select an NPC token on the current map to grab the data from. This data will then be appended to the current content. I'm afraid limitations in the scripting language prevent me from putting together a full inline-type editor for it all, but I'm sure you know how to use cut-and-paste by now right? =)

The thing to remember about this system for adding token information (notes, gm notes, image, or portrait) is that you only have to be on the same map as the token when you're adding that token information to the content. Once it's been added to the content of the handout, you're free to do what you want and you can change maps as desired. In fact, the way it works you can even select a portrait from a token in one map, switch to another map, then get GM notes or another portrait from a second token, then switch to a third map and get more data from a third token.

The main benefits of this system are that it allows data to be collected from multiple tokens on different maps, it allows users to view images and so on without being on the same map as the token (because it stores the asset id within an image tag rather than trying to look the data up dynamically from a token or static table, the image will always show up as long as it's within the client's asset cache), and that you can more easily customize the appearance of individual handouts.

The downside to this system however is that if you change a token's notes or portrait or whatever, you have to manually open up the handout and re-add the token information to the content. Personally I'm fine with that though, it only takes a few seconds.

EDIT PERMISSIONS
Image
This dialog allows you to simply tick/untick the checkboxes of which players you want to have permission to view the handout. If the box is checked, the player has access to the handout. If it's not checked, they don't (and it won't even show up in their list).

The GM(s) can set Permissions for each handout so that they are only available to certain players. If you're a player and you don't have permission to view a handout, you won't have it in your list and you won't be able to view it.

Once the GM sets permission for a player to view a handout, any players who have not been previously notified of the handout are sent a whisper which they can click on to both view the handout and refresh the player handout view.
Image

PLAYER HANDOUT
Image
The player handout view is a simple list of the handouts that the player has permission to view. Unread handouts are highlighted with a different icon and a coloured background to better indicate to the player which ones are new and which ones are old. The player view really only has two options for the player. He can opt to refresh the list (updating it with any new handouts he has permission to read, or compacting/expanding the entries if he checks the "compact" box in the top left) or he can click on a handout to view it.

Image

Currently I'm only allowing viewing one handout at a time. When I had players test out a prior version that opened each handout into its own dialog, they quickly got overwhelmed and frustrated by all the extra windows. It's a trivial change to adjust the functionality to allow multiple dialogs though, so if you want it...

HANDOUT CATEGORIES
It should be noted that I have designed the handout functionality to benefit from the use of multiple library tokens, each of which has identical functionality but acts as a separate "category" of data. This means you can keep different types of handouts separate, keep your lists of handouts within the bounds of reason, and more easily decide which handouts you want to switch from map to map. For example, you could create an adventure-specific list of handouts while having your campaign handouts in a separate token entirely.

To create a new category of handouts, simply import a new Handout library token into the campaign and set it up identically to your first one (hidden, visible to players, etc). Then double-click on the token and change it's name to Lib:<your_category_name> where <your_category_name> is the name of your handout category. For example, I use Lib:Adventure Handouts and Lib:Campaign Handouts as two separate library tokens.

Once you've got the appropriate library token in place, right-click on the Handouts macro in your campaign macro list and select Duplicate. Then right-click one of the two macros and select Edit. Change the label of the macro to something more descriptive, then adjust the command so that it points to your new library token. Simply replace the Lib:Handouts part of the macro with Lib:<your_category_name>. For example, for the campaign handouts library token from the earlier example, the command would become:

Code: Select all

[macro("[email protected]:Campaign Handouts"): ""]


Once that's all done, click OK and you're done. Clicking that new macro will bring up a separate category of handouts (though it'll use the same frame).

HANDOUT STYLES
The Handout Styles table stores information about the appearance of individual handouts -- cutting down how much html formatting you have to do to add them and reducing the size they take up in the token. The zeroth column of the table specifies how many entries there are in the table. Each subsequent entry has its range set to an incrementing value (1 for the first entry, 2 for the second, etc). The value for each entry is a text string -- simple css which overrides the default handout appearance. The css classes are handout_text, handout_summary, handout_title, and so on. The image for the table entry specifies the background to use for the handout. Two dark parchment/paper type ones are included by default.

FINAL WORDS
I'm still in the middle of developing this, but I figured it was worth putting out there. Hopefully people won't find this too broken to use. Any feedback or suggestions are appreciated.

User avatar
booga
Dragon
Posts: 365
Joined: Fri Dec 14, 2007 9:00 am

Re: Token-based Handout System

Post by booga »

Very nice work,

this macro goes beyond some of the previoulsy created handout macros. Definitelya move in the right direction IMHO ! Have you developped the idea any further ? If so I'd really like you to post it so that I can check it out.

Is it currently possible to manually edit the content of the handout to choose the size of the pic in pixels ?

User avatar
Hawke
Great Wyrm
Posts: 2261
Joined: Sat Apr 21, 2007 12:12 am
Location: Albuquerque, NM
Contact:

Re: Token-based Handout System

Post by Hawke »

This looks great! I have a number of things I'd like my players to have access to midgame... I think I'll look into using this.

Question, is there a "all players" permission? I don't limit information to certain players in my group, so all I'd need is a general visible/hidden ability.

MeMeMe
Dragon
Posts: 256
Joined: Tue Mar 31, 2009 7:44 pm

Re: Token-based Handout System

Post by MeMeMe »

This looks amazing.
MapTools Forks: Thread

User avatar
kazinsky
Giant
Posts: 220
Joined: Tue Nov 25, 2008 11:59 am

Re: Token-based Handout System

Post by kazinsky »

Looks very good! I'd be interested in testing it out. I assume that it plays well with existing frameworks in that it uses it's own Lib and such?

MeMeMe
Dragon
Posts: 256
Joined: Tue Mar 31, 2009 7:44 pm

Re: Token-based Handout System

Post by MeMeMe »

Feature suggestion!

You have the ability to grab images from tokens, which is cool. Would it be possible to add the ability to get images from tables, given the table name and row?
MapTools Forks: Thread

User avatar
Hawke
Great Wyrm
Posts: 2261
Joined: Sat Apr 21, 2007 12:12 am
Location: Albuquerque, NM
Contact:

Re: Token-based Handout System

Post by Hawke »

Just played with the sample campaign...

This rocks! Great job... the two above suggested features will round it out nicely.

DEDEN
Kobold
Posts: 12
Joined: Sat Sep 05, 2009 8:21 pm

Re: Token-based Handout System

Post by DEDEN »

I've been having a mess around with implementing decorative initials and page breaks and other formatting niceties -- things to make the text look a little less bland. I don't really like the idea of having more tables full of images to do it, but it looks like it's probably the best way. The alternative, which is somewhat nicer but also has its downsides is using specific decorative fonts and doing it inline with the text. The benefits are that it doesn't require any more futzing around with tables and if someone doesn't have the font they just get a default one rendered. The downsides are that it doesn't quite look as fancy as some of the images you can use and that you'd have to manually distribute the fonts you want to use to the players you want to view it. If maptools had a distributive font cache that wouldn't be an issue but I'm not sure it does, so... I guess we'll see how it goes.

@booga
Setting the image width and height is just a matter of including width=x and height=y within the image tags, for example:

Code: Select all

<img width = "300px" height = "300px" src = "asset://005dfeae90ca0c2dfd2ae3cc8eab55c8"></img>


I should probably add some fields to the token selection whatzit so that you can specify them with an input dialog. I'll stick that on my todo list.

@Hawke
Yeah. I just realized there's no "select all" option for permissions. I'll be adding that in. =)

@Kazinksky
It should play pretty nicely with anything, yeah.

@MeMeMe
I'll also have a look at the table thing. It shouldn't be too difficult, though it'd be nice to have a list of tables to select from. Not sure if you can do that but I'll have a fiddle with it and see if I can futz something out.

User avatar
Azhrei
Site Admin
Posts: 12050
Joined: Mon Jun 12, 2006 1:20 pm
Location: Tampa, FL

Re: Token-based Handout System

Post by Azhrei »

DEDEN wrote:If maptools had a distributive font cache that wouldn't be an issue but I'm not sure it does, so...

Hmm. If the font were considered an asset, it could be distributed via the repository or attached to a token. Then the asset:// URL could be used to access it. However, I can't think of a way to encode the font such that it would validate as an asset.

There's another URL built into MapTool that's not documented (it's cp://) that refers to something in the classpath of the application. The classpath currently includes a list of JARs in the lib/ directory of the unzipped download or the web site in the case of a WebStart. Unfortunately, I can't think of any easy way for a user to take advantage of this URL scheme either. :(

(Note the emphasis on "easy", as it's certainly possible to modify the classpath by modifying the MANIFEST.MF file in the MapTool JAR once the ZIP is unpacked, but that would invalidate the security certificate, so all JARs would have to be unpacked and the CP would have to be specified manually...)

It would be possible in the future to include some kind of font:// URL, but I think a better approach is to use the CSS support of the Swing components instead and then hook into the HTMLEditorKit so that font requests are processed first by MapTool. Not sure how viable this is as I have no experience doing this. 8)

DEDEN
Kobold
Posts: 12
Joined: Sat Sep 05, 2009 8:21 pm

Re: Token-based Handout System

Post by DEDEN »

It turns out getting a homebrew D&D4 campaign off the ground is a bit more work than it used to be -- or perhaps it's just that I have less free time to do it -- or maybe I'm getting old... Whatever it is, I've finally gotten around to doing some more scripting on the handout system.

UPDATES/IMPROVEMENTS
The following updates and improvements have been made to the existing system:

Allow All Permissions
You can now toggle the "allow all" permission by going into the Edit Permissions dialog and clicking on the "Select All" button. This will allow anyone and everyone to view the handout -- regardless of whether their name is listed in the edit permissions dialog or not. Clearing the "allow all" permission is a simple matter of clicking the "Clear all" button on the same dialog (which is visible only when the flag is set).

Image Attributes
To make including images and portraits in handouts a little easier, I've included a secondary input pop-up which appears after you've selected where to grab the relevant texture from. It allows you to set the height and width of the texture and to center it. You can, of course, do all this via standard html, but I figured it's a little nicer to have a dialog for it (not to mention it saves a little time). The input pop-up stores the values entered previously to make it a little easier to standardize handouts.

Table images/text
You can now import table values and text in the edit handout dialog. Given that I can't find any accessor methods for the client's table list or names or the number of entries per table (at least not in the web-accessible documentation anyway), it's a purely manual entry process. You type in the name of the table and the entry value and the macros do the rest. It's not ideal but it does allow you to get the data in there fairly easily. That being said, I have scripted it so that the input pop-ups store the values used previously, so if you've got all your images or data in a single table, you only need to enter the table name once. I'm also not sure whether the table/image bug will crop up when grabbing images from a table, so someone let me know if it bugs out. It didn't seem to on my quick tests, but then again I didn't really spend a lot of time on it 'cause it's not really a feature I plan on using, so...

View Handout from GM Handouts screen
You can now view handouts by clicking on the icon in the GM handouts list. Previously, to view a handout you had to edit it and then click preview. Clicking on the text part of the entry in the GM handouts list will edit the handout as it did previously.

UPGRADING
If you're using a previous version and want to keep your existing handouts, your only real option is to load up the example campaign, export the macro set from the handout token, then load your campaign, delete the macros from your existing handouts token, and import the macro set you previously exported. It's a bit of dicking around but it could be worse... =)

FILES
The links in my first post point to the newest files, but here's the ones that have changed:
Handouts Library Token

EXAMPLES
The example campaign has also been updated. It's got everything in one place for those of you too lazy to click individual files. =)
Handouts Campaign File

MeMeMe
Dragon
Posts: 256
Joined: Tue Mar 31, 2009 7:44 pm

Re: Token-based Handout System

Post by MeMeMe »

Nice work.

I think there is a kludgy way to check how many entries are in a table, which relies on the fact that if you attempt to get a table entry that is above the last entry, it always returns the last entry.

So you can use a loop based on While x != y, with x being a table row, and y being a the next table row.

But this only works for tables without empty slots - rows must be consecutive. As I said, a bit of a kludge.

Anyway, thanks again for updating this - I'll be using it a lot.
MapTools Forks: Thread

User avatar
Hawke
Great Wyrm
Posts: 2261
Joined: Sat Apr 21, 2007 12:12 am
Location: Albuquerque, NM
Contact:

Re: Token-based Handout System

Post by Hawke »

This looks great!

I'm not really sure how to use the table images though... I have created a table named ImageTable and inserted an image at index 0. I tried to click both the Table and Table Image buttons and input that information but I don't see the image anywhere. (edit: I figured it out - I had an image FOR the table, not an image IN the table - it works as expected with the table button pulling table info and the TableImage button pulling the image for that particular value)

Also, I added a link that didn't work - MT threw an exception and then seemed to crash:

Log.txt[spoiler]2009-05-26 20:51:36,850 [AWT-EventQueue-1] ERROR - Could not find image for asset: null
2009-06-06 11:39:35,668 [AWT-EventQueue-2] ERROR - Could not find image for asset: null
2009-06-06 12:30:28,202 [AWT-EventQueue-2] ERROR - Must supply a username
2009-06-06 12:59:04,731 [Thread-59] ERROR - ERROR: Wrong password
2009-06-06 12:59:05,015 [Thread-199] ERROR - Unable to register your server.<br>com.caucho.hessian.client.HessianRuntimeException: java.net.ConnectException: Connection timed out: connect
com.caucho.hessian.client.HessianRuntimeException: java.net.ConnectException: Connection timed out: connect
at com.caucho.hessian.client.HessianProxy.sendRequest(HessianProxy.java:295)
at com.caucho.hessian.client.HessianProxy.invoke(HessianProxy.java:161)
at $Proxy0.registerInstance(Unknown Source)
at net.rptools.maptool.client.MapToolRegistry.registerInstance(MapToolRegistry.java:54)
at net.rptools.maptool.client.MapTool.startServer(MapTool.java:678)
at net.rptools.maptool.client.AppActions$51$1.run(AppActions.java:1659)
at net.rptools.maptool.client.AppActions$ClientAction$1.run(AppActions.java:2518)
Caused by: java.net.ConnectException: Connection timed out: connect
at java.net.PlainSocketImpl.socketConnect(Native Method)
at java.net.PlainSocketImpl.doConnect(Unknown Source)
at java.net.PlainSocketImpl.connectToAddress(Unknown Source)
at java.net.PlainSocketImpl.connect(Unknown Source)
at java.net.SocksSocketImpl.connect(Unknown Source)
at java.net.Socket.connect(Unknown Source)
at java.net.Socket.connect(Unknown Source)
at sun.net.NetworkClient.doConnect(Unknown Source)
at sun.net.www.http.HttpClient.openServer(Unknown Source)
at sun.net.www.http.HttpClient.openServer(Unknown Source)
at sun.net.www.http.HttpClient.<init>(Unknown Source)
at sun.net.www.http.HttpClient.New(Unknown Source)
at sun.net.www.http.HttpClient.New(Unknown Source)
at sun.net.www.protocol.http.HttpURLConnection.getNewHttpClient(Unknown Source)
at sun.net.www.protocol.http.HttpURLConnection.plainConnect(Unknown Source)
at sun.net.www.protocol.http.HttpURLConnection.connect(Unknown Source)
at sun.net.www.protocol.http.HttpURLConnection.getOutputStream(Unknown Source)
at com.caucho.hessian.client.HessianProxy.sendRequest(HessianProxy.java:293)
... 6 more[/spoiler]
Last edited by Hawke on Sat Oct 10, 2009 6:13 pm, edited 1 time in total.

User avatar
mrobviousjosh
Dragon
Posts: 418
Joined: Sun Dec 16, 2007 12:14 am
Location: Fort Smith, Arkansas
Contact:

Re: Token-based Handout System

Post by mrobviousjosh »

I haven't had a chance to play with this yet, but it looks awesome! Thanks for sharing and keep up the good work. :)

User avatar
Hawke
Great Wyrm
Posts: 2261
Joined: Sat Apr 21, 2007 12:12 am
Location: Albuquerque, NM
Contact:

Re: Token-based Handout System

Post by Hawke »

The handouts load super quickly for me, but for some reason it seems to take forever to load for my players. Any thoughts why that might be?

DEDEN
Kobold
Posts: 12
Joined: Sat Sep 05, 2009 8:21 pm

Re: Token-based Handout System

Post by DEDEN »

Hawke wrote:The handouts load super quickly for me, but for some reason it seems to take forever to load for my players. Any thoughts why that might be?


At a guess I'd probably say it's a bandwidth issue. I don't think Map Tools is as network-friendly as it could be. I'd like to sit down and go through the code and fix it but I don't really have the time. ( =}

Post Reply

Return to “User Creations”