Re-implement reclaim labels

[Garanas]

This issue is under construction

Context and previous attempts

This is a large and involved issue that tackles a core mechanic of the game. It is far from trivial and not recommended as a first issue. On the other end, the issue can be solved without keeping mod compatibility in mind and you'll be able to re-implement the mechanic from the ground up.

Therefore, heaps of fun and challenges ahead of us 😄 !

Before we talk about what we'll be building, we'll first have to talk about the issue. The issue can be seen when you start any map with a lot of reclaim that generate labels, usually a generated map works.

Zoomed out with 400+ fps, no reclaim labels

Zoomed out with 130+ fps, showing reclaim labels

Starting from what is most obvious:

• There is a significant reduction in fps
• Some parts of the screen have so many labels that it becomes cluttered, making them unreadable

And then based on my personal experience and looking at what the vault offers in terms of mods:

• For me personally, 9 / 10 times I use reclaim labels to know where to click when I issue reclaim orders. But the labels show up even though the camera is too far away to issue reclaim orders. In particular manual orders are crippled by this, which can be quite a bad experience as described by this post on the forums
• As mods add, the reclaim labels are too uniform. Color cues can be used to help identify to the user what is going on
• As mods surrounding reclaim labels show, the current implementation is not moddable and can essentially only be hard-hooked

There is enough 'wrong' with the current implementation that it can use some attention. And that is what we're here for. The primary files / functions involved are:

• reclaim.lua
• props.lua

Previous attempts can be found in these pull requests:

• From #3534, see: https://github.com/Garanas/fa/blob/c95b3c2b1b0a3231e5e9737e9f5eb8469e67c833/lua/ui/game/reclaim.lua
• From #3584, see: https://github.com/FAForever/fa/blob/28f4cd2c1f6c8de0e336dcf62cd58d82f6ae28c4/lua/ui/game/reclaim.lua

With all of that said, lets dive into what we'll be building.

Description

From a user perspective, we'll have two separate views:

• 1. When zoomed in sufficient such that you can perform reclaim orders, a detailed overview of each individual reclaim label on screen. You can issue reclaim orders with a focus distance of 130 or lower
• 2. In all other cases, an abstract overview per iMAP grid that tells you the amount of reclaim that is available in that cell

The first view (when up close) is visually the same as what we have now. It guarantees that reclaim orders work as you expect. The second view is used when you can't issue reclaim orders anyway and acts as an informative overlay of what areas of the map are high on reclaim. For those that are unaware what the iMAP grid is, it is the threat grid used by AIs to understand the map.

An example iMAP grid, as rendered using the map utilities window. You can find it in the hotkeys menu by searching for map

From a user perspective, we'll have a few quality of life improvements:

• 1. Reclaim labels are colored according to their value, starting with green, moving towards yellow, orange and then dark red to indicate low to high valued wrecks. Due to the high diversity in reclaim value it should be a logaritmic scale, as an example: anything below 100 is green, above 100 but below 1.000 is yellow, above 1.000 but below 10.000 is orange and all that remains is dark red.
• 2. There will be an indicator that tells the user when it is in the reclaim view (where you can issue orders) and when it is in the overview view (where you get the amount of reclaim per iMAP cell)

From a coding perspective, we'll have a few easy-to-use / easy-to-hook functions. These are more difficult to describe as they depend on the code written. But as a few examples:

• 1. A function with the sole purpose to translate the value of a reclaim label to a color.
• 2. A function with the sole purpose to take a location, a value

Course of action

Test plan

Learning goals

Progress

[Hdt80bro]

I highly recommend sorting the reclaim into a quadtree and combining close enough labels based on camera distance. It'll be a little ugly when the camera rotates, but that should be fine in 99.9% of use-cases.