HUD Customization

[FileEX]

Closes #3682

This PR adds customization for the default HUD in GTA.

Here is the full list of available properties:

General

• position (x, y) - The position of the component.
• size (w, h) - The size of the component. For text components, this corresponds to font scale.
• fillColor (number tocolor) - The primary color of the component, e.g., bar fill color, weapon icon color or text color.
• fillColorSecondary (number tocolor) - A secondary color, used for components like
• • money - Color when the value is negative
• • wanted - Color of "empty" stars
• • weapon - Specific color for the fist icon
• • radio - Text color when a station is "loading" (this seems to be skipped in MTA)
• useCustomAlpha (bool) - By default, settings like fillColor and dropColor ignore the provided alpha value to preserve original fade-in/fade-out animations. Use this parameter to override that behavior.
• all - Used for resetting all properties of a component in resetPlayerHudComponentProperty.

Bars

• drawBlackBorder (bool) - Adds a black border around the bar.
• drawPercentage (bool) - Displays the percentage value as text on the bar.
• blinkingValue (number) - Specific to the health bar, determines the HP threshold below which the bar will start blinking.

Texts

• dropColor (number tocolor) - The color of the text's shadow or outline.
• fontOutline (number) - The size of the text's outline.
• fontShadow (number) - The shadow offset for the text.
• fontStyle (string) - The font style, selected from GTA's default fonts:
• • menu
• • subtitles
• • gothic
• • pricedown
• fontAlignment (string) - Specifies the text alignment, useful for custom positioning
• • left
• • right
• • center
• proportional (bool) - Adjusts uneven character spacing when changing fonts.
• textSize (w, h) - Read-only, returns the width and height of the text for the specified component.

Components

Components like crosshair, radar, help_text, and vital_stats remain unchanged and are not supported by these functions. Adapting the radar to these functions would take significant time, and the same effect can be achieved by replacing textures with shaders or creating a custom radar.

It’s also possible to use all to reset all properties of a specific component or all properties of all components (the entire HUD).

resetPlayerHudComponentProperty("all", "all") -- resets entire hud
resetPlayerHudComponentProperty("money", "all") -- resets all properties for money component

Syntax

bool setPlayerHudComponentProperty(string component, string property, mixed value)
bool resetPlayerHudComponentProperty(string component, string property)
mixed getPlayerHudComponentProperty(string component, string property)

Colors are returned in the format r, g, b, a.

Example (from screenshoots)

setPlayerHudComponentProperty('clock', 'fillColor', tocolor(50, 168, 82, 255));
setPlayerHudComponentProperty('clock', 'dropColor', tocolor(94, 14, 7, 255));
setPlayerHudComponentProperty('clock', 'fontOutline', 1);
setPlayerHudComponentProperty('clock', 'fontStyle', 'subtitles');
setPlayerHudComponentProperty('clock', 'proportional', true);

setPlayerHudComponentProperty('money', 'fillColor', tocolor(11, 102, 158, 255));
setPlayerHudComponentProperty('money', 'fillColorSecondary', tocolor(176, 23, 130, 255));
setPlayerHudComponentProperty('money', 'fontOutline', 1);
setPlayerHudComponentProperty('money', 'fontStyle', 'subtitles');

setPlayerHudComponentProperty('health', 'fillColor', tocolor(50, 168, 82, 255));

setPlayerHudComponentProperty('ammo', 'fillColor', tocolor(245, 66, 126, 255));
setPlayerHudComponentProperty('vehicle_name', 'fillColor', tocolor(217, 242, 73, 255));
setPlayerHudComponentProperty('area_name', 'fillColor', tocolor(252, 153, 91, 255));
setPlayerHudComponentProperty('radio', 'fillColor', tocolor(113, 240, 93, 255));

setPlayerHudComponentProperty('weapon', 'fillColor', tocolor(235, 76, 52, 255));

setPlayerHudComponentProperty('wanted', 'fillColorSecondary', tocolor(140, 138, 137, 255));
setPlayerHudComponentProperty('wanted', 'fillColor', tocolor(66, 33, 252, 255));

Known Issues

Due to a rendering bug in GTA, setting transparency for text with outline or shadow causes a visual glitch, resulting in blurred/smudged text. Transparency only works correctly on text without outline and shadow.

[Fernando-A-Rocha]

Nice, what about #3444 ?

[Proxy-99]

Nice, what about #3444 ?

this is a patch for wide screens has nothing to do with customization

[Fernando-A-Rocha]

Nice, what about #3444 ?

this is a patch for wide screens has nothing to do with customization

This PR alters HUD component sizes, won't it conflict with wide screen HUD sizing PR?

[Proxy-99]

Nice, what about #3444 ?

this is a patch for wide screens has nothing to do with customization

This PR alters HUD component sizes, won't it conflict with wide screen HUD sizing PR?

this is normal but we compare conflicts according to multitheftauto:master rely on which pr will be merged first other pr has to adjuct to the new changes

[FileEX]

Update

Properties have been added for HUD texts (components under development). Possible properties for text components (clock, money, ammo, etc.):

• fillColor_second - The text color for money when the value is negative.
• dropColor - The color of the outline or shadow.
• fontOutline - Text outline.
• fontShadow - Text shadow. Shadow and outline are mutually exclusive, so you cannot enable both at the same time.
• fontStyle - Specifies the font to use. The default GTA fonts are available (gothic, pricedown, menu, subtitles).
• fontAlignment - Positions the text (left, right, center) relative to its position. Useful if you use own position.
• proportional - Improves letter spacing when changing the font via fontStyle, e.g., from pricedown to subtitles. By default, spacing is uneven after such changes, so setting this value to true is helpful.

setPlayerHudComponentProperty('clock', 'fillColor', tocolor(50, 168, 82, 255));
setPlayerHudComponentProperty('clock', 'dropColor', tocolor(94, 14, 7, 255));
setPlayerHudComponentProperty('clock', 'fontOutline', 1);
setPlayerHudComponentProperty('clock', 'fontStyle', 'subtitles');
setPlayerHudComponentProperty('clock', 'proportional', true);

setPlayerHudComponentProperty('money', 'fillColor', tocolor(11, 102, 158, 255));
setPlayerHudComponentProperty('money', 'fillColor_second', tocolor(176, 23, 130, 255));
setPlayerHudComponentProperty('money', 'fontOutline', 1);
setPlayerHudComponentProperty('money', 'fontStyle', 'subtitles');

[Fernando-A-Rocha]

This is one of the most game-changing features, literally, because the HUD is a big part of the game that has been disabled on servers in most cases to create custom ones instead. With this, devs will save computing resources to have the HUD edited within the game's engine. Very cool.

[FileEX]

Done

Finally, thanks to the holiday break, I found time to finish this PR. At this point, the main objectives have been achieved, and I consider the PR ready for review and complete. Check the main message on the top.

[Weaita]

It's a great job, but I'd like to emphasize that the radar is precisely the component that most needs this function. Programming a new radar with all the features of the original is not trivial, and the performance impact is always high. Being able to change its position and scale would be great

[lynconsix]

It's a great job, but I'd like to emphasize that the radar is precisely the component that most needs this function. Programming a new radar with all the features of the original is not trivial, and the performance impact is always high. Being able to change its position and scale would be great

I liked your comment. But let's get to the point, this pull is more focused on the HUD itself, in the future it will be a pull only for the radar, etc.

[Fernando-A-Rocha]

@FileEX What about changing size or shape of the HUD radar minimap circle?

[FileEX]

It's a great job, but I'd like to emphasize that the radar is precisely the component that most needs this function. Programming a new radar with all the features of the original is not trivial, and the performance impact is always high. Being able to change its position and scale would be great

@FileEX What about changing size or shape of the HUD radar minimap circle?

I understand that the radar might be one of the most anticipated parts of this PR. However, implementing changes to the radar requires a tremendous amount of time and effort. The radar is not just a single image drawn on the screen at position x, y, with dimensions w, h. It consists of many components, some of which are not even visible to the naked eye. It is far more than a single sprite.

We need to consider map tiles, the radar border, the radar mask, blips, radar areas, the altimeter, and more. The source code includes many functions responsible for drawing different parts of the radar, such as DrawMapSection, DrawRadarSection, DrawRadarSprite, DrawLegend, Draw3dMarkers, DrawArea, and so on. Adjusting all these functions to accommodate changes in position or size would require a significant rewrite, making this PR exceptionally large. Detailed information about the radar code can be found here: https://github.com/gta-reversed/gta-reversed/blob/700dfa8a9c9cd2b2c916b17903426e0637e528d7/source/game_sa/Radar.cpp

While I’m not ruling out the possibility of working on the radar in the future, it certainly won't be part of this PR. Including it would delay this PR for several more months, and reviewing such a large PR would be significantly more challenging. If I find that these functions are widely used and in high demand, I’ll be motivated to start working on the radar and create a separate PR specifically for it.

[botder]

Did you investigate with a debugger? Manually stepping through assembly code?

[FileEX]

No, I decided it’s not significant in the context of this PR. I resolved the crash as you can see. I can address it later and potentially fix EnumToString, but it shouldn’t have a major impact on this PR or, for example, block its merge.

[botder]

If you already have the branch and code in front of you, please invest a few minutes and debug the issue.

[FileEX]

The FindValue function for some reason overwrites the value of the variable on the stack. As seen here, outResult equals 0x0177dc13, which is the variable val, but for some reason, 0x0177dc14 (the variable hud) is also overwritten, as shown by the breakpoint data. I don't know why this is happening; the ASM code doesn't indicate stack overwriting. Most likely, inlining this function is a bad idea but idk

[ghost]

I'm glad this PR got merged, nice work @FileEX

Maybe In the future you could add a barRange property which sets the minimum and maximum value of a bar.

It would fix this issue: #3807

For e.g. currently the healthbar has a 0 minimum and 176 maximum value and because of that the excess hp is not shown. (not sure if i used the right words here sorry)

The logic is already done in GTA, just take a look at lung capacity bar and armor bar. They share the same width but works with total different maximum values.