Add script for finding and tracking HF's

[Sulter]

Gui script for finding and tracking in real time of historical figures.
The positions updates/switches automatically when moving/traveling and changing between local and world map view.

[myk002]

Before I check out the code, let's discuss UX.

I think this could be significantly condensed and streamlined. How about a flow more like gui/quickfort, where it pops up a dialog at start asking for a target. The list is already populated when the dialog comes up and the search is dynamic (i.e. a standard FilteredList). The dialog also has some filters that allow, for example, filtering out dead histfigs. Once a selection is made, the dialog disappears and what is left is a small window on the right side of the screen that shows a compass direction and number of steps to target. A section at the bottom can display some information about the target (e.g. race, the site that they are in, etc.). A button/hotkey can bring up the dialog again in case you want to switch targets.

Since this can be easily extended to cover sites, artifacts, armies, etc., it could take a more general name, like, say gui/compass or gui/gps or gui/tracker

@Ozzatron what do you think?

Edit: Once we add an API for world map painting, it can also highlight the destination tile on the map, but that can be added later too.

Edit2: followup discussion on Discord: https://discord.com/channels/793331351645323264/793331351645323267/1253784635377319996

[myk002]

further ideas: clicking on the compass should zoom the viewport to the destination.

it would be nice to extend this tool (in the future) to also work on the embark world map and on the fort world map. Players have similar searching needs there, and the interface would be exactly the same.

[Ozzatron]

@Ozzatron what do you think?

• No need to expand scope to include sites, artifacts, or traveling armies yet. The most difficult thing to find bar none is a random historical figure, as nobody will ever give you information beyond site-level and oftentimes even that information is inaccurate. This provides the most value to adventure mode players and maximal frustration reduction with minimum further UI/UX investment.
• I approve of making a flow that mimics a "GPS wizard". Users should be able to run the tool from the command line and/or hotkey and immediately get a window which prompts "what/who are you looking for?" Ideally you'd be given a single text prompt which can search sites, histfigs, artifacts, and armies all at once.
  • Ideally, you should be able to GPS to locations inside sites as well. This would default to navigating to the site until said site realization is loaded, at which point it queries the location for more precise directions.
• In the GPS wizard, you could put checkboxes below the text entry field to filter what you want. By default, I would expect histfigs to be checked with others unchecked. Dead histfigs would be a checkbox to the side of living ones which can't be selected unless the histfig checkbox is checked.
• Once a tracker is active, it could have tabs like a web browser. Opening another tab would prompt you with the same search field. I believe a web browser tab-like interface with a search bar at the top will be as intuitive as possible for the vast majority of users, because it is a paradigm that all computer users will be well familiar with.
• Players would be able to switch between their "GPS Tabs" or "Tracker Tabs" at will, and none of the tabs are closed until the user closes them. Tabs persist between adventure mode sessions and closing the tool's window does not close individual tabs. Re-opening the tool via command or hotkey will manifest it just like a browser which remembered your tabs from last session.
• Exact coordinates would be an option, but that option shouldn't be enabled by default. DF coordinates are notoriously opaque. Destination information should be by default limited to:
  • Direction (NNW, SE, etc.) with an arrow, akin to the vanilla interface
  • Approx or exact tiles/blocks/steps (do we have consistent terminology?) to destination
  • Enclosing site of the destination, or "Wilderness" if no site
  • An indication whether the destination is on the surface or underground. This is important, as oftentimes histfigs and artifacts will be in Dwarven fortresses or deep sites that are difficult to reach from the surface.
• Further, non-positional information about the item, person, or army you are looking for should be extremely minimal, as the tool's purpose is to locate things, not give you a briefing.
• Sites should be given basic information akin to the base game: indicated as "human hamlet" or "goblin dark pit", similar to what the world map gives you, with a population estimate.
• Enclosing sites of non-site destinations should have the same basic information.

[myk002]

This sound like very good ideas -- @Sulter let me reiterate that we can work towards this vision and we don't have to do everything at once. We can start with just the (non-persistent) HF compass and work up to a persistent tabbed interface later : P

[Bumber64]

Does it need to show region coords? These are always just global / 48, and fast travel moves in global coords (a.k.a map blocks). Are region tiles even still shown in fast travel?

We can set the quest/destination marker to the appropriate site once that gets re-implemented.

[Crystalwarrior]

Plz make it include the Race of the histfig in the list as well, some histfigs don't have names.
As well as English-readable names so you can search for "Amxu Peachsniffer" rather than Amxu Furdboter or w/e
I also think the Global coordinates should always be visible, as you can travel between global coordinate tiles while in local map

[Sulter]

Does it need to show region coords? These are always just global / 48, and fast travel moves in global coords (a.k.a map blocks). Are region tiles even still shown in fast travel?

We can set the quest/destination marker to the appropriate site once that gets re-implemented.

As discussed above, it will always show distance in one coordinate system - tiles/steps. So you just get the direction and the distance.
When we have a API for map markings, that can be added as well.

Plz make it include the Race of the histfig in the list as well, some histfigs don't have names. As well as English-readable names so you can search for "Amxu Peachsniffer" rather than Amxu Furdboter or w/e I also think the Global coordinates should always be visible, as you can travel between global coordinate tiles while in local map

The displayed name is the translated one, but you can actually search for both the original as well as the translated.

Interesting - I never realized that there are histfig without names. Currently I'm not including those, but I guess they could still be on the list.

[Bumber64]

You can probably replace the world.armies loops with df.army.find(hf.info.whereabouts.army_id), including for the adventurer.

You might also be able to get the site with df.world_site.find(hf.info.whereabouts.site_id). (This seems to give lair for megabeasts, at least in fort mode.)

I'd also use local world = df.global.world near the top of the script to shorten some code.