madsciencezone / gma-mapper

Fantasy role-playing battle grid map for use with GMA or standalone.

gma-mapper

Fantasy role-playing battle grid map for use with GMA or standalone.

The current implementation of the mapper is in Tcl/Tk, but is showing a definite need for refactoring at this point. The rest of GMA has already been moved to Python and Go, so the next major revision of the mapper is likely to be rewritten in one or both of those languages.

Introduction

The GMA toolset (see below) includes facilities to support tracking of initiative in combat and the location of creatures on the game map. If using the full GMA toolset, each player may run a gma-mapper client. These are networked together so each person can move their pieces around and see the same tactical view of the battle.

It may also be used stand-alone to create maps ahead of the game, or for the GM to display the battle map using a large monitor or projector, without the need for any networking at all.

GMA?

This is part of a larger project called GMA (Game Master's Assistant) which is a suite of tools to facilitate the play of table-top fantasy role-playing games. It provides a GM toolset for planning encounters, tracking character state, and running encounters in a comprehensive way. This includes a multi-user interactive tactical battle map where players can move their tokens around the map, initiative is managed automatically, etc.

While we intend to open source GMA later in 2023 2024, it's not quite ready for general use (mostly because it needs to be generalized more to be playable on multiple game systems and less tied to the author's game group). The manual describing the full GMA product may be downloaded here (PDF, 61Mb).

In the mean time, we're moving individual parts of GMA (specifically the map server and clients) into their own repositories. This is the client repository.

Documentation

In the repository you will find manpages which document the usage of the client itself, the file format used for storage of map data, and the network protocol used when networked.

The GMA Game Master's Guide includes full tutorials describing how to use the mapper (in addition to the rest of GMA). Players should refer to Appendices G, H, and I, while the GM would want to read Chapters 4, 5, and possibly 8–10.

Standalone Note

In the documentation, the invocation of the mapper client is shown as gma mapper ... which only makes sense if using the full GMA toolset. The gma script merely sets up some convenient environment variables and allows you to avoid having to have all the bits of GMA in your $PATH. When using mapper on its own, merely execute bin/mapper.tcl as a command by having it in your $PATH or using the Tcl/Tk wish command (e.g. wish mapper.tcl).

Integrated Usage

If using with the full GMA toolset, the gma mapper command will use the environment variable GMA_MAPPER to find the top-level directory of where you cloned this repository (thus $GMA_MAPPER/bin/mapper.tcl is the executable mapper script). You may need to set GMA_TCLSH to point to your tclsh interpreter if the gma script can't find it on its own.

Versioning

Although intended for use with the GMA software suite, the gma-mapper tool has an independent version number from that project.

Other Software

Includes Paul Walton's scrollable frame code sframe.tcl, available at http://wiki.tcl.tk/9223.

Also uses a modified version of Silk Icons.

Game System Neutral

The GMA software and the gma-mapper client in this repository are intended to be game-system-neutral. They are not written specifically for, nor intended specifically for use with, the oldest fantasy role-playing game, nor do they rely upon OGL-licensed intellectual property from Wizards of the Coast. Where any game system was in mind for these tools, it was the Pathfinder role-playing game system from Paizo, Inc.

gma-mapper's Issues

option to adjust font/size of token labels.

Some clients not getting background images

Sometimes random clients will fail to get room tiles or map elements. This may be a server issue but needs to be debugged.

Update GMA manual appendices to mention new repository and process to install mapper clients

With the move to the current github repo (and renaming of the same) the information in the GMA manual is out of date.

die-roll result formatting for labels

A small modification to the way die-roll labels (user-supplied titles) are displayed would reduce confusion and improve readability.
Currently a player assigns a label by prefixing the die roll spec with label= like so:
attack roll = d20+12

But on output it is displayed with a colon like this:
attack roll: d20{14}+12

It's a little confusing to have = in the definition and : in the output, but I'd rather not use : in the roll spec string or use = in the output since that could be confused with the calculation details. A better way to show the label would be to use something like the labels you see attached to tickets here: put the label in a colored box without punctuation to clearly show that it's a label attached to the die-roll expression, not part of the expression itself. That also lets the eye recognize labels on sight without mentally parsing anything.

Unable to save dice presets on Mac

Attempts to save dice presets on MAC (Big Sur, 11.6) results in:
2021-10-17 12:30:27.502 Wish[32696:2954073] WARNING: <NSSavePanel: 0x7fddc8934540> running implicitly; please run panels using NSSavePanel rather than NSApplication.
Named file is never saved.

level displays

Currently levels are not supported.
how to display levels? isometric? onion skin? similarly for altitudes?

UI cosmetic issues with light theme

This is noticeable when viewing the clock display using light color theme. Some of the bits of the window's background are not set to the same color as the widgets in the window.

Conserve memory when loading images

Currently, when the client receives an AI message from the server to notify it that it should cache that image (presumably because it will be used soon), it not only ensures it has a cached copy but also loads it in memory so it's ready to use immediately on the canvas.

It would be better to wait to load into memory until it's actually used so that just preparing the cache before a game session doesn't load the universe into memory up front. Deleting old images from memory after they're removed from the canvas would be good as well.

Fog of war/lighting displays

It would be nice to show each person's POV or group fog of war, as well as an indication of light sources and visibility distances.

Don't consider some combatants based on status

The mapper should ignore (for combat reasons) creatures whose condition state(s) mean they cannot act.
This means adding some kind of way to indicate that a status has that connotation (e.g., petrified, unconscious, etc). This should remove threat zone displays from the creature since it can't threaten anyone anymore.

full support for BBheight/BBwidth

Error when removing combatants from initiative list

When clicking the skip button on the GM console to remove someone from the initiative list, the mapper client throws an error stating "key '6' is not known in dictionary" from ::gmaclock::set_initiative_slots

chat message sync on reconnect

when reconnecting to server, consider what chat messages you already have before asking the server to send more

Logging in via mapper client

Is your feature request related to a problem? Please describe.
N/A

Describe the solution you'd like
Specify a mapper config file to use from inside the mapper, rather than specifying on the command line. Or the ability to login to a server from the mapper itself, rather than using a config file or command line options.

Dynamic threat zones

Currently, the mapper has some standard creature threat zone templates defined which align with the standard Pathfinder rules, but there have been a couple of custom hacks added including a combined reach+adjacent mode used for things like the long arm spell and special sizes for creatures with special abilities.

Proposal:

• Add multiple reach zones for creatures who have different reach areas for different weapons (e.g., tail sweeps)
• Add the ability to specify any arbitrary reach-zone diameter which will dynamically calculate the threat zone at runtime even if there's no defined template for it.

condition confusion

mapper gets confused between conditions it imposes automatically due to hit points and those manually applied.

Threat zone option: normal+reach

Currently, a creature token has its threat zone highlighted for "normal" attacks and "reach" attacks, but not both at the same time. This is expected for things like pole arms, where you can only strike at range and not up close. However, some attacks (e.g., the long arm spell) simply extend the normal threat zone to include reach but the creature can still attack in the normal zone too.

The change would need to simply add an option to indicate this from the context menu, and render any square that exists in either zone (effectively an "OR" of both regions).

Reset creature token title bars when someone moves above them.

Currently, the mapper places nameplates above the creature token unless there is a creature in the space(s) directly above them on the map; in that case it puts the nameplate lower to be out of the way of the other creature.

However, if you move a token to a new location just above another creature, nothing tells that other creature that it needs to move its nameplate out of the way. You need to move or refresh the other creature to get it to move.

Proposed solution: when you move a creature, force a redraw of any creature(s) immediately below it.

altitude distance calculation

mapper: consider altitude in calculating range to targets and who is threatening whom

Rewrite and Port Mapper Tool

The mapper client has badly needed some refactoring for a while, as well as being the only hold out from the version 3 GMA tool suite that's still written in Tcl/Tk.
This issue is to port the tool away from a Tcl script and at the same time refactor all the code to be more sanely implemented and shake out the bugs that have crept in.
The initial effort here is to port it to the Go language, in the hopes that the compiled binary will perform better and be simpler to install for end users.
In addition to simply porting it, make the following upgrades while we're in there:

• Introduce file format 20, which changes from unorganized text lines marshaled as Tcl lists to a structured file with JSON marshaling.
  • The current version (17) file format must also be understood on input, although format 20 may be written unconditionally on output.
• Implement server protocol 400, which similarly changes the protocol from Tcl-list-based to JSON-based data marshaling.
• Change to OS-standard directories for storing cache and configuration files.

Change wording of toggle menu items

Change "toggle" in menus to say either "show" or "hide" as appropriate.

Make informational windows' location dynamic

Creature tokens have information windows for elevation, notes, name, and health bar. Currently they are always drawn inside the bounding box of the token (except for long names or notes). However that hides the token image.

Proposal: draw them outside the bounding box unless there is another creature token adjacent in the space the window would go into, and only in that case pull the window back inside the creature token's bounding box.

Character Encoding Issue on Windows

Describe the bug
Unicode characters outside the ASCII 7-bit range are misinterpreted on Windows clients, which in turn causes die-roll formatting to be displayed incorrectly.

To Reproduce
Run the mapper client on Windows. Send a die-roll with the new formatting codes.

spell effect zones

draw lines (not normally visible) that denote solid barriers, which spell effects and threat zones can be blocked by.
Also need better support for showing areas of effect of spells including spreads.

creature image tag queries too frequent

need to settle down asking so often about creature image tags; also maybe expand equivalent names server-side?

Show condition effects in mouse-over

When mousing over a creature affected by one or more conditions, pop up a help window that indicates the effects of those conditions (e.g., helpless would give "Effective dexterity 0 (-5); melee attackers get +4 to hit; may be coup-de-graced")

Dying status not shown for creatures

In the 4.0 mapper, the dying status (single slash through the token) is not displayed even though the dying status is known by the mapper.

Truncate filename displayed in mapper window title

Currently, the full pathname of the map file loaded into the mapper is displayed, which may be a cached file (making the full path useless and lengthy).
I would like to see this shortened to just contain the base filename.
It may even be better to display the room comment instead of the filename at all.

Background color behind token labels

The name labels on creature tokens is difficult to read against dark background colors.
Suggest displaying a contrasting background color behind them.

Visual indicator for critical confirmation rolls

In the die-roll results display, it should be visually more apparent that a roll was to confirm a critical hit rather than a normal attack roll.

Accurate grid highlighting for distance to targets

When you ask for a report of distance from a starting point to every creature, the indication of which square is the closest one may be off if more than one square is the same distance after rounding off to even-grid units.

Instead, when there is more than one grid that could be highlighted, pick the one along the direct line of sight as indicated by the arrow drawn to the target.

bug loading spell AoE from file

If a map contains a spell area of effect zone, that does not load properly again from the saved file.

UI cleanup

The new icon for the game clock is ever so slightly smaller than the other buttons in the toolbar.
Also, if you're not connected to a server that button should be disabled.

Zoom inaccuracy at 0.25 level

I've noticed that it still looks like images aren't accurately scaled at the 0.25 zoom factor. This may be a bug in rendersizes instead of the mapper, though. Best to check both.

Add an initiative clock display for the mapper (was: A GMA Client for a player)

A client run by a player that would include a game clock, initiative list served from the master GMA application

Move tool doesn't work when at non-zero zoom level

It doesn't look like the move tool follows the zoom level, so if you're zoomed in or out at all, objects will end up in the wrong places.

Limit mouse-over zone for creature tokens

Currently, hovering the mouse over a creature token or its threat zone displays status information about that creature. In close quarters, this causes misidentification of creatures too often. Instead, just consider a hover over the token itself, not the threat zone, too.

CLR commands sent to clients

CLR commands sent to clients doesn't always match the local behavior of functions such as load/merge, leading to inconsistencies between map clients.

Chat groups

if you select a group of >1 person for a chat, client should create a "group" for that set of people to easily select them again and/or allow a "pop-out" of a dedicated chat window for that group's ongoing chat apart from the main one. Probably implement this upon receipt of a group message, including the sender's initial one that comes back to them, so that everyone in the chat gets the group selection option. Probably good to switch the receivers to that channel upon receipt so they can just reply back without having to stop and select the recipients... but then probably don't do that if there's any text in the message box so that you don't inadvertently make someone redirect a message they were in the middle of typing because yours came in while they were typing it.

Remove nameplate on dead creatures

Un-clutters the battlefield.

Need GIF support as fallback option

The mapper uses PNG icons and image files, but if the user's Tcl/Tk interpreter is old enough, it won't have PNG support built-in, so the mapper will fail.

Propose a fall-back to GIF format if this happens.

Chat/Die roller scrollbars not always displaying right

The dynamic Tk code that makes scrollbars show up when needed in the panes of this dialog seem buggy.

1. Sometimes the controls on the far right of the pane aren't visible unless the window is resized (which causes the widgets to be rendered again)
2. Sometimes when the contents of a pane are updated the view isn't scrolled so all the content might be off-screen

Better creature token stacking rules

It would help if the algorithm used to place creature tokens on the map always put dead creatures under living ones. As it is now, if a creature is killed, and someone stands on the same square to continue fighting, the dead token might end up on top of the living one, hiding it from view.

improved zoom and scroll support

Currently when you zoom in or out, the mapper preserves the scrollbar placement but that means the actual map contents shift, sometimes off-screen, making you hunt to find them again.

Also, when one mapper client tells others to adjust their scroll bars to match its own, it sends its scroll position as the fraction along the x and y axes the window is scrolled, which will be inaccurate if the other mappers are not at the same zoom (or possibly window size).

Proposal:

Add a Grid field to the AV server command and supporting mapper functions, which change the command between mapper clients to indicate which square on the map grid should currently be at the top left of the screen. Use these same routines to ensure that the same top-left grid square is in the top-left display position after a zoom operation.

Clear message window on startup

Describe the bug
The mapper's sign-on messages don't get cleared until something else is written to that part of the screen, so you get a "Server signon successful" message that lingers on. It would be better to make it disappear, possibly after a short delay.

To Reproduce
Start the mapper to talk to a server with authentication.

Documentation out of date

The mapper installation and usage guides in the GMA documentation need to be updated for the newest features of the mapper and the installation instructions in particular need more guidance on how to resolve issues like missing libraries.

Feature: supply resized tokens for characters

When setting up encounters with the GMA toolsuite, you can provide multiple images (each at different sizes) for polymorphing or shapechanging creatures. It would be nice to also supply character tokens at various sizes as well, perhaps by extending the polymorph naming convention, to make resized character tokens look right when a character casts something like reduce person or enlarge person.

Race condition in initial chat message sync

If new chat messages come in while the mapper client is reading its cached chat log, an error will be raised about a channel not being opened for writing. This is because the cache file is being read in to the mapper at that point, and it hasn't yet opened it up for appending to record new messages yet.

case sensitivity in file names

Provide installer tool

The detailed instructions in the manual to get the correct tcl/tk environment set up for the mapper to run, as well as setting up the mapper itself, are fine and all, but really they shouldn't be necessary in order to get the mapper up and going. Instead, an install script should be included which checks for the requisite environment, guiding the user to correct any problems it detects.

In addition, the mapper's own startup code should check that it's being run from a working environment, flagging errors with advice on how to resolve them up front instead of waiting for something to explode later on in the session.