Add widgets for compass

[dseguin]

Summary

None

Purpose of change

Widgets representing the cardinal directions, indicating visible creatures and threats.
Related to wapcaplet's work on widgets: #53957.

Describe the solution

---

New widgets/layouts

Added new set of compass widgets:

• "compass_N_text"
• "compass_S_text"
• "compass_E_text"
• "compass_W_text"
• "compass_NE_text"
• "compass_NW_text"
• "compass_SE_text"
• "compass_SW_text"
• "compass_local_text"
• "compass_legend_text"

Also added these layouts:

• "compass_top_layout" -> (NW - N - NE)
• "compass_middle_layout" -> (W - L - E)
• "compass_bottom_layout" -> (SW - S - SE)
• "compass_all_layout" -> (Combination of above layouts + legend)

---

Arrangement

These widgets can be arranged in any order, including columns similar to the existing compass:

Existing compass (hardcoded):

With the compass widgets:

The compass widgets can be modified in data/json/ui/compass.json, including the labels, widths, and arrangements.

---

Number of creatures displayed

Using the "width" field you can limit how many creatures to display in a compass segment:

Width = 6

Width = 3

---

Compass "direction"

The compass directions are defined using the "direction" field:

{
  "id": "compass_N_text",
  "type": "widget",
  "label": "N",
  "style": "text",
  "direction": "N",
  "var": "compass_text",
  "width": 6
}

---

Compass legend

Using the "height" field you can reserve multiple lines for the compass legend, which allows more creatures to be displayed in the list. See #54050 for details.

{
  "id": "compass_legend_text",
  "type": "widget",
  "style": "text",
  "var": "compass_legend_text",
  "height": 3
}

---

Describe alternatives you've considered

Testing

Added some tests to check that creatures are displayed in the appropriate directions. Also tested in-game by spawning creatures around and nearby the player (see screenshots above).

Additional context

Here's a comparison between the existing compass and the widget compass (available from the custom sidebar):

[wapcaplet]

This is a great idea!

I think I would prefer if the direction could be a separate field, instead of part of the widget_var name. Something like:

"var": "compass",
"direction": "NE"

We don't have any other immediate uses for a "direction" field but I could see it being applicable to things like terrain, furniture, items and whatnot - in other words, this one is a "monster compass" showing nearby monsters, but maybe a "terrain compass" showing the predominant terrain in each direction, or an "item compass" showing nearby items, might one day be useful.

Even if we don't come up with other good uses for "direction", I think it's worth it just to keep the var list from getting too cluttered.

[dseguin]

I think I would prefer if the direction could be a separate field, instead of part of the widget_var name. Something like [...]

Sure, I can do that. I wonder if it might also be useful to have a generic field to pass additional data to widgets.

[PatrikLundell]

What happens with the code description part of the the hard coded panel? A bunch of letters that may mean different things at different times isn't that useful without a key.

[dseguin]

What happens with the code description part of the the hard coded panel? A bunch of letters that may mean different things at different times isn't that useful without a key.

Cheers for the feedback. I've added another widget for the compass legend:
(top is the existing compass, bottom is using compass widgets)

[PatrikLundell]

It's easy to drop things along the way...
The next problem is with the legends widget: it needs to be variable height to account for more than two characters (you've got Z z... there showcasing the problem).

[dseguin]

It's easy to drop things along the way... The next problem is with the legends widget: it needs to be variable height to account for more than two characters (you've got Z z... there showcasing the problem).

That may have to wait for a separate change to address the 1-line limitation for widgets.

[PatrikLundell]

Optional legend widget 2, 3, 4, 5, ... that are displayed only when they contain anything? Might not be a reasonable option, though. If so I'd probably go for a fixed number of e.g. 3 legend widgets that would just be blank if there isn't anything to show.

[wapcaplet]

I think I see what you did here - the compass_text_color returns a std::string that already embeds colorized strings for each threat, and the second nc_color part is just a (dummy?) c_white that ends up being ignored.

There is a little bit of precedent in panels.h in the display namespace for functions that return only a std::string - sometimes even colorized, like display::get_moon_graphic. So I think you could change compass_legend_text_color to return an already-colorized string (instead of a string/color pair), and change its name to something like colorized_compass_legend_text, to avoid this little hack of ignoring the second part of the pair.

I'm also not crazy about doing a return from the middle of this switch/case statement; I would propose using a flag, like:

bool do_colorize = true;
switch( _var ) {
    // ...
    case widget_var::compass_text:
        desc.first = display::colorized_compass_legend_text( _direction, _width );
        do_colorize = false;
        break;
    // case ...
}
if( do_colorize ) {
    ret += colorize( desc.first, desc.second );
} else {
    ret += desc.first; // assume already colorized
}
return ret;

I expect this to come up again (in fact I was thinking about it for the vehicle and bodypart widgets too), and have a feeling this would give us a cleaner logical flow for these exceptional cases.

[dseguin]

No problem, I didn't realize I was breaking the pattern, haha.

I changed the return types for the compass display functions and removed the early returns. I'll try to stick to your format here going forward (sorry!).

[wapcaplet]

Playtested a bit, and it works great!

For fun, I bumped the width to 50, each compass point width to 9, and the legend to 6 lines - this is a little better equipped to deal with typical CDDA mobs:

I think the legend portion would be more readable if the monster-count came after the monster-symbol, like the old legend does. It's a legend, so the symbol ought to come first, ex. @ 5 feral humans instead of 5 @ feral humans.

The only other minor change I'd suggest in the legend is to separate monsters with 2 spaces instead of just 1. Due to wrapping limitations, there is often a space or three at the end that don't have anything better to do, so that may improve readability a little as well.

Edit Feral humans occasionally seem duplicated in the legend

[dseguin]

I think the legend portion would be more readable if the monster-count came after the monster-symbol, like the old legend does. It's a legend, so the symbol ought to come first, ex. @ 5 feral humans instead of 5 @ feral humans.

The only other minor change I'd suggest in the legend is to separate monsters with 2 spaces instead of just 1. Due to wrapping limitations, there is often an space or three at the end that don't have anything better to do, so that may improve readability a little as well.

Thanks for giving it a try (and the feedback)! I'll hold off on making this ready until I fix the formatting.

Edit Feral humans occasionally seem duplicated in the legend

I found that happens because there are multiple different mtypes that use the "feral human" name. Not sure if I should address that by comparing the name strings instead of the id (it's a bit of a performance hit)...

Edit: Thankfully the formatting fixes were pretty straightforward. Moved the count after the symbol, and added 2 spaces between creatures:

[wapcaplet]

Ha, you think you have enough zombie dogs there? That looks good. I am already stealing that bit of apply_color logic for the bodypart status widgets in #53975, since embedded colors will be much nicer.

[dseguin]

I somehow completely forgot about monster difficulty colours. I've squashed those into the previous commit. Here's how it looks:

[wapcaplet]

I somehow completely forgot about monster difficulty colours.

So did I, until the subject came up on discord last night, and I couldn't remember if you'd included it. Nice catch.

[wapcaplet]

Suggested change

	std::string colorized_compass_text_color( const cardinal_direction dir, int width );
	std::string colorized_compass_legend_text_color( int width, int height );
	std::string colorized_compass_text( const cardinal_direction dir, int width );
	std::string colorized_compass_legend_text( int width, int height );

Sorry, one last nitpick - the _text_color suffix naming convention was intended for the ones returning a std::pair<std::string, nc_color> (both text and color).

The ones that return just a std::string don't follow a particular pattern so much, but for these pre-colorized ones I'm leaning toward colorized_xxx_text, hence the suggestion here. I went with colorized_bodypart_status_text for the recently merged bodypart status widgets, and will probably do colorized_overmap_text for the upcoming overmap one, so would like to set a good precent early if possible. Thanks!

[dseguin]

Cheers! I folded those name changes into the previous commit.