MapTool Mod: Card Game Edition (Not Just For Card Games)

[Lord.Ashes]

MapTool-1.3.b89.CGE.CC.S Rev 1.1

Disclaimer: This is an unofficial MapTool modification. Please do not request support from the MapTool team for any functionality added by this modification. Instead post bugs in this thread.

The Card Game Edition of MapTool (i.e. this Mod of MapTool) is a modification of MapTool-1.3.b89 which adds the below functionality. Although these modifications are geared to implementing Card Games in MapTool, these modifications can be of benefit for other more traditional uses of MapTool.

The modification is provided as a MapTool distribution (i.e. a ZIP file that contains everything you need to use MapTool-1.3.b89.CGE.CC.S) similar to how official MapTool releases are provided. However, for those of you who are less trusting, I am also providing the modification as a Eclipse Patch so that you can verify my modification and patch your own source code.

MapTool-1.3.b89 Card Game Edition with Cache Cleaner and Sound (hence CGE.CC.S) provides the following modifications:

1. Sounds support allow sounds to be played both locally and remotely with a number of supporting sound functions for features such as switching between two different channels (allowing, for example, sounds effects to be played while background music or speech is going on), locking and unlocking sound functionality to the GM only, playing repetitions, stopping sounds abruptly and curiously, using earplugs to avoid playing sounds (but still getting visual cues) and so on. Comes complete with a caching system so that sounds play faster when re-requested, allows larger sounds files to be pre-cached so that they are ready when they are requested and specifying sound files (on the server) which should not be cached.

2. Token macros are now available, from the token right click context menu, even when multiple tokens are selected. This allows common macros to be applied to all selected tokens in a faster manner since the user does not need to use the Selected or Campaign window to activate such macros.

3. Since most Card Game Implementations (and many other implementations) are Token Macro heavy (i.e. frequently use Token Macros) the token's macros now appear in the root of the Token's right click context menu as opposed to the macro sub-folder. The macros are divided into section similar to the sections shown in the Selected window. Along the same lines most of the functions normally available in the root of the token's right click context menu have been removed to provide focus on the token's macros. This makes selecting the token's macro easier and rids the context menu of less frequently used function. It should be noted that although these functions have been removed from the context menu, they have not been removed from MapTool. As such, if any of these functions are commonly used, they can be "re-added" by creating a token macro that performs the necessary action.

4. SetOwnerByAll has been improved so that when the provided list of players is the same as all connected players, MapTool actually re-selects the All Players checkbox as opposed to adding each player into the ownership list. This ensures that any players connecting after this point will also own the token. This modification also provides support of a "All" owner which does the same thing. Obviously the "All" modification will only work with other modified MapTools and thus the need for the first part of this fix.

5. Cache Cleaner keeps an eye on your cache directory and can provide warnings or automatic smart cleaning of your cache directory when it exceeds a given size.

More details can be found in...

MapTool-1.3.b89.CGE.CC.S.rev1.txt

(29.33 KiB) Downloaded 84 times

For a complete Card Game Edition solution, this Modded MapTool can be used with my N-State Framework (see thread http://forums.rptools.net/viewtopic.php?f=8&t=24006) which provides the necessary token implementation and support macros for implementing Card Games as well as more traditional campaigns.


Requirements:

Java 7. This modified MapTool will not run on Java 6 or lower.


Download:

http://www.mediafire.com/folder/ejadl2lz4drok/MapTool

Use the following link to download the Modified MapTool. Typically one should download files from the folder with the highest revision but previous revisions have not been removed for anyone who wishes to study the exact changes between versions.

The Single File ZIP Archive section has a complete MapTool installation. Just unzip and use. Very similar to how the official MapTool releases are provided.
The Individual Files section provide all the modified files and documentation to turn an existing MapTool installation into a Modded one.
The Source Code section provides the Eclipse Patch to build the Modified MapTool from the unmodified MapTool source code.

Typically you want to just download the Single File ZIP Archive and use that unless you want to build your own build of a Modified MapTool in which case download the Source Code files.

The Cache Cleaner functionality is provided through a library JAR file. It is included in the ZIP Archive and the source code for this JAR file is included in the Source Code section. If this JAR file is not placed into the Libs sub-directory of MapTool then MapTool will default to a Java 6 implementation of Cache Cleaner which is not as optimal (since it uses the Last Modified Time of files instead of the Last Access Time of files to determine which cache assets to delete).


Revision Log:

2013.10.03 - Release 1.1 which fixes the getOwners() bug and has verified that isOwner() already works as expected.
2013.10.02 - Initial release Rev 1.0


Known Bugs:

* Play sounds function do not seem to support spaces in the file name. Work Around: Replace spaces in sound file and requests with underscore or similar character.
[Resolved] getOwners() returns empty when owned by all.


Related Links:

This Modified version of MapTool works great with the N-State Framework (see thread http://forums.rptools.net/viewtopic.php?f=8&t=24006)


Edit Log:

* Added the comment about using my N-State Framework for a complete Card Game solution.
* Added Known Bugs section and Revision Log section
* Added updates for Rev 1.1
* Corrected download link
* Added Known Bug about spaces in file name

[wolph42]

Thanks for the contribution, will surely check it out. Couple of comments though (based on reading your post)

SetOwnerByAll

so if a gm starts a game and in preparation takes ownership of a couple of tokens, then sometime later players start to log in, will they also own that token?
if so then I would immediately categorize it as an 'unwanted feature'.

same if a player starts a server (not unheard off) and does the same for his own token and then later the rest logs in?

Did you also rewrite Wiki: isOwner() and/or Wiki: getOwners() ? as these do not function correctly when 'is owned by all' is selected. Which again can throw off quite some macros that check certain players and then assume that 'getOwners' will function while it may not cause of this 'feature'.

Code: Select all

The Card Game Edition

is it correct that this has to do with 'token context menu' but has not actually anything to do with functions used for cards in MT (e.g. create deck, shuffle, etc)
I find it a bit confusing that you call this a 'card edition'. I get it that its useful when using mt for playing cards (and more) but you did not actually added something to this mix that has to do with cards?

[Lord.Ashes]

Thanks for the contribution, will surely check it out. Couple of comments though (based on reading your post)

SetOwnerByAll

so if a gm starts a game and in preparation takes ownership of a couple of tokens, then sometime later players start to log in, will they also own that token?
if so then I would immediately categorize it as an 'unwanted feature'.

No. The GM would still have to issue a [wfunc]SetOwener(getAllPlayerNames("json"))[/wfunc]. The only difference between the unmodified version and the modified version, in this respect, is that in the unmodified version when you use the above macro functon, it actually does not actually set ownership to all (i.e. the All Player checkbox is not set), it adds all the players to the ownership list. This is slightly different for two reasons: 1) if a player joins after ownership has been given to all, in the unmodified MapTool that player would not get ownership of the token (unlike all other players) because the unmodified MapTool just sets ownership to all of the connected players at the time that the macro function is used. 2) The isOwnedByAll macro function returns false in the unmodified MapTool version after the [wfunc]SetOwener(getAllPlayerNames("json"))[/wfunc] is used. The modified version just compares the list of token owners provided to SetOwner and if they match the list of all connected players then it assumes that the function is trying to do a OwnedByAll and thus, instead of adding all current players to the ownership list, it actually removes all players from the list and sets the All Players checkbox. This means, while owned by All, any new players will also have ownership of that token and the isOwnedByAll macro function will return true. However, if a token is NOT owned by all the new players will not automatically get ownership of it.

Did you also rewrite Wiki: isOwner() and/or Wiki: getOwners() ? as these do not function correctly when 'is owned by all' is selected.

No. I will look into that but I have a feeling I did confirm that isOwner does return true if All Players are set. However, I will re-check both isOwned and getOwners. Thanks for the suggestion. I definitely want to keep all these function backwards compatible so that my modded MapTool can use all unmodded MapTool campaigns without modification.

Code: Select all

The Card Game Edition

is it correct that this has to do with 'token context menu' but has not actually anything to do with functions used for cards in MT (e.g. create deck, shuffle, etc). I find it a bit confusing that you call this a 'card edition'. I get it that its useful when using mt for playing cards (and more) but you did not actually added something to this mix that has to do with cards?

Yes and no. The Mod is all geared to implementing Card Games. This is why I moved the Macro sub menu to the root and removed most of the other "junk" from the right context menu, so that when using it with Card tokens one can right click the card and select an action. However, you are correct that on its own it is not really a Card Game implementation. The reason for that is that it is intended to be used with my N-State Token Framework which does provide those functions.

However, I decided to post my N-State Framework in a separate post for two reasons: 1) Some users may want to use it for Card Game implementation but with the regular unmodified MapTool (although this is not ideal there is nothing preventing someone from using it that way) and 2) The N-State Framework is geared towards implementing card games but can be used for other more traditional campaign implementations also.

At the end of the Card Game Edition post there is a actually a reference link to my N-State Framework.

In retrospect, it might have been better to post my MapTool mod under a different name and then do a separate post referencing this Mod and the N-State Token Framework and indicating that together they make the ideal MapTool Card Game Edition combo.

[wolph42]

clear, thanks!

I think the issue lies with getOwners() returning "" when 'isownedbyall' is selected (and thus no owner is selected)

[Lord.Ashes]

clear, thanks!

I think the issue lies with getOwners() returning "" when 'isownedbyall' is selected (and thus no owner is selected)

It probably does because when the All Players checkbox is checked, it removes all players from the ownership list.

I will modify it so that when the All Players is selected getOwners() returns the same as getAllPlayerNames(). This should maintain backwards compatibility.

[Lord.Ashes]

Just posted Rev 1.1 which addresses the [wfunc]getOwners()[/wfunc] issues. This macro function now correctly returns the owners (as a string or json) regardless if the token is owned by specific players or owned by all. When the token is owned by all, the Wiki: getOwners() macro function returns the same result as [wfunc]getAllPlayerNames()[/wfunc]. The Wiki: isOwner() macro function was checked and it already supported provisions for owned by All Players and thus was not modified.

Please note that the download link has changed to a generic MapTool directory from which you can selected the latest release (currently Rev 1.1). The folders for previous releases (in this case Rev 1.0) have not been removed in case someone wants to compare the exact changes between revisions. The Eclipse Patch provided in the Rev 1.1 directory is still made against the unmodified MapTool (as opposed to being a Patch to the Rev 1.1 Modded MapTool) so only the Rev 1.1 folder is necessary to use or build the latest Modded MapTool.

[Lord.Ashes]

A Note On Cached Sounds:

Unless the audio repository (sound server) specifies otherwise (see documentation for more details) sounds that are either played (playSound) or pre-cached (cacheSound) are stored in the MapTool assetcache directory for future use. As is indicated in the documentation, the MapTool play functions first check to see if the requested sounds exists locally (in the assetcache directory). If the requested sound file exists, it is played from the local source which is not only faster but also does not require access to the audio repository. Only if the sound file is not available locally do the MapTool play function attempt to play and cache the sound file from the audio repository.

This fact can be used, especially in conjunction with the cacheSound macro function, to pre-load all necessary sound files from the audio repository to the local (client) machines after which the audio repository can be shut down.

For example, a campaign might use 20 different sound files throughout the campaign. The host can create a macro file which executes a cacheSound() macro function for each of these sounds. When the session starts (and all players are connected) the GM can start the audio repository and execute this prepared macro. The cacheSound requests will get distributed to the connected clients causing them to download the desired sound files (without actually playing them). At the end of the session the GM can turn off the audio repository. Next time the campaign is continued, assuming the clients are the same, the GM does not need to turn on the audio repository anymore because all of the clients should already have the sounds pre-loaded and thus available without needing the external audio repository.

Edit:

Because MapTool looks for a local cached version of sounds, if the audio repository contains a new (updated) version of the sound, the MapTool play functions, at this time, will not fetch the new version because they will find the local cached version. If a newer version exists on the audio repository, the current local version needs to be deleted (manually) from the assetcache directory in order for MapTool to re-download the file from the audio repository. Future versions may include a function for doing this without having to manually delete the local copy but at this point there is not macro function for doing this.

According to the web, although it has not been tested yet, the functions used to implement the caching overwrite the destination if a file already exists at the destination. This means while the playSound macro function will not get a new version of a sound file from the audio repository if it already exists locally (because it will use the local version) the new version can be obtained (copied from the audio repository to the local cache) by using the cacheSound function. The cacheSound function caches files from the audio repository regardless if a local version already exists and since it overwrites the local version (if any) it will mean that the newer audio repository version will be left in the local cache.

It should also be noted that the MapTool play function do not care how the sound files got to the assetcache directory so, for example, the sound files could be prepared, in advance, by copying the required sound files into the assetcache directory without actually using the cache functionality of the MapTool play functions. This solution can be used, for example, when playing a campaign over LAN and not wanting to bother setting up an audio repository. In that case the necessary files can be passed around using a USB key (or similar).

[Lord.Ashes]

A Note On Campaign Specific vs Campaign Global Sounds:

Unlike image assets in the assetcache directory which are named after the MD5 hash, cached sound files retain their original name. This was done mostly to avoid having to map the play request names to file names but, as an added bonus, this makes the sound files easy to locate in the assetcache directory if one is, for example, doing manual cleaning of the assetcache directory.

Normally no campaign identification is added to the sound files when they are cached so that the sound files can have maximum re-usability. For example, character's battle cries or catch phrases, sounds of battle and other sound effects are likely to be used throughout may campaigns. My not making the sound assets campaign specific these sound files can be loaded once and then re-used in multiple campaigns without needing to re-download them and without storing them multiple times.

However, campaign builders need to be aware of this fact because in some cases sound files are campaign specific. For example, a sound file like Quest_Instructions.wav may be used in multiple campaigns but each campaign would have different contents for that file. In such a case you do not want to use the same file name in multiple campaigns because MapTool would end up using the first version for all campaigns. To get around this, files that are campaign specific can be prefixed by the campaign's identification. This will ensure that the file name between campaigns is different and thus will not produce conflicts. Typically sounds, within the campaign, are activated using macros (as opposed to players actually typing the playSound macro command) and thus the fact that the file name is prefixed by the campaign identification will be transparent to the players because the macro name does not have to include it.

[Lord.Ashes]

I am currently testing a mod of MapTool based on my ""1.3b90beta with Plugin Support" version which supports a Card Game Edition feature. It mod supports running MapTool in two different modes. Currently the desired mode is selected by a configuration file but I am looking into seeing how feasible it would be to add this as a GUI Setting.

In "Full" mode, MapTool runs like it has for many years with a full context menu when a token is right clicked.

In "CGE" (Card Game Edition) mode, almost all of the right click context menu for a token is removed and instead the contents of the Macros sub-menu is brought to the root of the context menu. This mode is ideal for campaigns that make heavy use of token macros but don't commonly use the other context menu options. This is typically the case when using MapTools to implement card games and/or boardgames as opposed to actual role playing campaigns.

It should be noted that in "CGE" mode all of the regular MapTool functions are still there...they are just removed from the context menu. This means, for example, the use can not apply or remove any of the "State" overlays from the context menu but macros can still be used to do that.

An additional benefit of the "CGE" mode is if the token macros are in different groups the right click context menu will show these groups as headers making it easy to arrange your macros.

I'll keep you posted on progress.