Token halo shapes and styles

[Baaaaaz]

Identify the Bug or Feature request

closes #5786
progresses #1616

Description of the Change

Introduces token halo shapes and styles.

HALO SHAPES

Halo shapes include: GRID, TOKEN, CIRCLE, DIAMOND, SQUARE, TOPOLOGY

GRID is the default and matches current behavior.

If Halo Shape is set to GRID a token's halo will reflect the map grid shape.

If Halo Shape is set to TOKEN:

• a CIRCLE shaped token will have a CIRCLE shaped halo
• a SQUARE shaped token will have a SQUARE shaped halo
• a TOP_DOWN shaped token will have a TOPOLOGY shaped halo
• a FIGURE shaped token will have a GRID shaped halo

If Halo Shape is set to TOPOLOGY the halo shape is determined via Token VBL and is cached for each token with this halo shape.

Token halo shapes sizes may be tweaked depending on the map grid type and the halo shape. For example the DIAMOND shape on an ISOMETRIC grid will fit the GRID shape, but can be rotated and stretched square on other grids.

HALO STYLES

Token styles include: SOLID, SPOTTED, DASHED, DOTTED, DASHED_DOTTED, SPIKED, NUBBED_1, NUBBED_2, ... NUBBED_10

SOLID is the default and matches current behavior

CODE CHANGE SUMMARY

Token:

• addition of Halo Shapes (via enum): GRID, TOKEN, CIRCLE, DIAMOND, SQUARE, TOPOLOGY
• addition of Halo Styles (via enum): SOLID, SPOTTED, DASHED, DOTTED, DASHED_DOTTED, SPIKED, NUBBED_1, NUBBED_2, ... NUBBED_10

TokenHaloFunctions:

• renamed from singular TokenHaloFunction
• added get/set functions for halo shapes and halo styles
• renamed get/set functions from getHalo and setHalo to getHaloColor and setHaloColor
• users using getHalo and setHalo still work and now point to getHaloColor and setHaloColor

TokenPopupMenu:
GUI for changing halo shapes and styles for selected tokens on the map

HaloRenderer:

• Rendered Halo shape can now depend on the Token's halo shape attribute and/or the grid shape and/or the token shape
• Rendered Halo line stroke is now depend on the Token's halo style attribute
• added caches to support the above, which are cleared when the grid changes

MapToolVariableResolver & MapToolExpressionParser:

• reflect the changes in TokenHaloFunctions

data_transfer_objects:

• handle the new attributes and enums added to Token

i18n:

• new items for Halo Shapes and Halo Items

Possible Drawbacks

First release of halo changes.

1. Halo menu items in TokenPopupMenu is now a long list. Could be restructured or added to the Token Editor dialog following feedback, but as of right now it is an MVP working GUI.
2. Different shapes sourced from different places seem to be rendered in different ways (e.g. nubs on the square grid halo shape go anti-clockwise from top-left, where as the square halo shape has them going clockwise from top-left).
3. Preset list of nubbed number styles from 1 to 10. Thoughts at this stage was that this should be a limited list rather than a user input. Could be reviewed following feedback. Nub numbers are converted into big nubs = 5, and small nubs = 1. Similar to Roman numerals V and I.
4. The TOPOLOGY shape is determined via TokenVBL and is cached for each token with this shape, if the token image is changed the TOPOLOGY is not refreshed until the grid changes (or restarting maptool). Really need's a way to trigger a cache update if the token's image is changed.

Documentation Notes

New Halo Shapes:

New Halo Styles:

New Halo Styles Continued (NUBBED 1 ... NUBBED 10, big nubs = 5 and small nubs = 1 similar to Roman numerals V and I:

New Token Popup Meu Items :
(and yes it is long, perhaps too long, but it is all visible in one place and can be scanned at a glance)

New Halo Shapes (on HexH map):

New Halo Shapes (on HexV map):

New Halo Shapes (on Iso map):

New Halo Shapes (on Gridless map):

New MT Script functions:

• getHaloColor -> as getHalo
• setHaloColor -> as setHalo
• getHaloShape(tokenRef)
• setHaloShape(shape [, tokenRef]) -> shape = "GRID", "TOKEN", "CIRCLE", "DIAMOND", "SQUARE", "TOPOLOGY"
• getHaloStyle(tokenRef)
• setHaloStyle(style [, tokenRef]) -> style = "SOLID", "SPOTTED", "DASHED", "DOTTED", "DASHED_DOTTED", "SPIKED", "NUBBED_1", "NUBBED_2", ... "NUBBED_10"

Release Notes

Added new token halo shapes and styles

---

This change is 

[Baaaaaz]

This is ready for a review!

[Baaaaaz]

Attachment below can be used for testing. Unzip and import macro set to GM or Campaign panel.

5787 Token halo shapes and styles (4 GM or Campaign Panel).zip

[kwvanderlinde]

@bubblobill I tagged you for review since you've worked on similar improvements recently.

[FullBleed]

Very nice!

I think the token shaped halos are a great addition... and I'll have to see about finding some uses for the nubs.

That context menu looks a bit obnoxious though. With this many options I suggest that we get a Tab for Halos in the Edit Token dialog. I have a similar freq (#5756) in for expanding the Sight, Lights, and Auras tabs as those context menus can be unwieldy, too.

[cwisniew]

Looking at the above context menu I think it has gotten to a point where a context menu makes no sense for all of that and the context menu should just have two options, enable/disable halo, edit halo... And the edit halo... should pull up a dialog box that allows users to pick shapes, colours, etc.

[bubblobill]

@cwisniew This is what happens when I listen to you. Someone else comes along and gazumps months of my work.

[bubblobill]

@kwvanderlinde @Baaaaaz
Mine are prettier. I'll have to check the code to see if it is extensible enough to cope with my big dreams.

[bubblobill]

@Baaaaaz
A) This is awesome work.

1. Can you show examples of Large tokens on Hex grids?
2. If we ever get custom footprints implemented, how will halos cope?

Personal preferences:

1. Not fond of deformed shapes on Hex and Iso maps. Circles should stay circular.
2. Top-Down should default to circle.

B) Whilst awesome, you remain locked in a narrow paradigm. You started to break out with NUBBED, but you stalled.

nb: Nubbed needs to go as a name. I can't imagine how the translators would cope with it.

Think about how people use halos, how they want to use halos, and moreover, how they will want to abuse the crapulence out of halos if given a little power. What can we do to give them that power?

You are limiting people to a single halo. This is one of the problems with the current implementation. Halos make an excellent alternative to states. Nubbly bits starts to work with this idea but stops short. Think of being able to have multiple colours for different conditions in concentric rings or differing shapes.

Since we are rewriting halos, better to make them a collection. Since we have contemplated making it a collection, wouldn't Halos benefit from having their own class and DTO so we can build extra bits into them in the future?

If I get keen and decide to implement an "outer-glow" halo effect (so it looks like, you know, a "halo"), how would I shoe-horn it into what exists? Or a swirly magical animated gif background? Interfaces for the renderer to look for?

You are restricting users to a limited collection of presets. We need presets and default options, they make things usable, but they don't make us truly awesome. Would we not be some kind of fancy-pants god-like beings if there was a way of defining your own?

Users can now create their own shapes through the use of Shape Functions. I created these as part of creating the ability for users to define their own halos. I think this would work well with the concept of nubby markers. Where you currently have nubs set as a line segment normal to the shape, It could instead be a Shape that gets drawn around the edge. If a user specifies an array of shapes, you paint the appropriate shape for the index.

Before you cry: I'm not saying you have to implement all my comments, but it would be nice for the design to be able to cope with it. Start with tokens having a halo collection of size one and let foolish people work out how to add more later.

As for the context menu; the context menu is broken as it is. It can already run off the screen if someone has a bunch of custom colours. At the very least it needs to split into sub-menus along the lines of...

Halos -> Add
      -> Halo-1 -> Colour
                -> Weight
                -> Shape
                -> Dash
                -> Features -> Marker count +
                            -> Marker count -
                            -> Marker count 1
                            -> Marker count 2
                            -> Marker count 3
                -> Custom
                -> Remove

[FullBleed]

Let the Halo Wars BEGIN!!

@bubblobill Does Baaaaaz's implementation look like a base you can continue to build on? Your approach seems to be more focused on customization that requires more significant structural changes. Whereas it appears that he's got this ready to go now and it doesn't look like a huge paradigm shift from what we have... it appears to be more like a (significant) iterative improvement.

[Baaaaaz]

@cwisniew @FullBleed - Yeah, fair points about the token popup menu for halos. It definitely needs redoing to be more usable as I really don't want people to rotate their screens to portrait just to use new halos ;)

[Baaaaaz]

@bubblobill Thanks for all the comments!

Mine are prettier.

Well, beauty is in the eye of the beholder!

Can you show examples of Large tokens on Hex grids?

If I pasted examples of a large tokens with a halo on a hex grid I think it will show what you suspect - a halo of hex grid shape and not the footprint.

If we ever get custom footprints implemented, how will halos cope?

If the custom footprints can expose the footprint area (and any transforms), just add a new value to the Token.HaloShape enum for FOOTPRINT and add it to the halo renderer in a fashion similar to the TOPOLOGY shape.

Not fond of deformed shapes on Hex and Iso maps. Circles should stay circular.

I wanted to have something in there from the start for these other gridded maps as sometimes they don't get much attention for new stuff. I was sitting on the fence but on those grids went with the halo surrounding the grid cell rather than within it. I'll change them to what you prefer unless there is a swell of counter preferences (which I doubt).

Top-Down should default to circle.

Why do you prefer that?

You started to break out with NUBBED, but you stalled.

True, but to quote a wise man once replied similarly elsewhere: #4886 (comment)

Nubbed needs to go as a name. I can't imagine how the translators would cope with it.

Add it to their lexicon? ;) Yeah fair point though, what about NUMERAL or any other suggestions (if they are kept in iteration 2 that is)?

You are limiting people to a single halo.

Wait, that limitation was already there and I have not made it worse!

Halos make an excellent alternative to states.

Good point.

I'm not saying you have to implement all my comments, but it would be nice for the design to be able to cope with it. Start with tokens having a halo collection of size one...

Good idea about using collections, let me look into it. I also wants GM only, or owner only token halos.

I was thinking something similar to lights and auras so halos could be grouped, named, and configured via campaign settings and available via the Token Popup menu that way (though noting @FullBleed 's first comment and link to another ticket about that). I have yet to dig into that area of the code base so have yet determine the feasibility of me actually doing it.

[Baaaaaz]

Let the Halo Wars BEGIN!!

@bubblobill Does Baaaaaz's implementation look like a base you can continue to build on? Your approach seems to be more focused on customization that requires more significant structural changes. Whereas it appears that he's got this ready to go now and it doesn't look like a huge paradigm shift from what we have... it appears to be more like a (significant) iterative improvement.

Yeah I was going for evolution rather than revolution, but bubblorevbill raises some good points about doing some foundational stuff.

[Baaaaaz]

rework-in-progress:

Also including a cog for @bubblobill (and for some odd reason when getting stuff from the experimental shape cache for halo it draws the outline shape?!).