How-to: Use the ui_indicator command

[HouseOfHam]

Uh, the ui_indicator and ui_indicator_remove commands.

This is what CA documentation says about them:

Identifier:         ui_indicator
Parameters: <slot number> <animation type> {<x> <y>} or {track <x> <y> <z>} or {track_3d <x> <y> <z> <radius>} or {track_ground <x> <z>} or {track_ground_3d <x> <z> <radius>} or {track_unit <unit_label>} or {track_unit_3d <unit_label> <radius>} [colour <r> <g> <b>] [scale <scale factor>] [period <animation period>] [loop]
Description:        Display a UI indicator
Sample use:         ui_indicator 0 circle 500 500 colour 255 255 0 scale 2.0 period 2.0 loop
Class:              UI_INDICATOR_COMMAND
Implemented:        Yes
Author:             Charlie
---------------------------------------------------
Identifier:         ui_indicator_remove
Parameters:         <slot number>
Description:        Remove a UI indicator
Sample use:         ui_indicator_remove 0
Class:              UI_INDICATOR_REMOVE_COMMAND
Implemented:        Yes
Author:             Charlie

Back when we were working on RTR VII: TIC, I did a little bit of research & testing. Here is what I've found:

The ui_indicator command belongs to the same family as other indicator commands and produces similar effects.

Other related commands are:

• ui_indicator_remove
• ui_flash_start/ui_flash_stop
• settlement_flash_start/settlement_flash_stop
• character_flash_start/character_flash_stop
• point_at_character/point_at_settlement/e_point_at_settlement/point_at_strat_position/point_at_message
• point_at_location/point_at_unit_pos/point_at_unit_group_pos/remove_battle_map_arrow/point_at_card/point_at_unit_card/e_point_at_unit_card

The main differences are:

• On one hand, it's a lot more flexible, since you can specify your own values for the color, scale, and type of indicator to show.
• On the other hand, the ui_indicator command uses absolute display coordinates which do not automatically adjust when you move around the strategy map or open/close scrolls.

One use for it is to point to a position on the mini-map or to a UI element not selectable with any of the other commands.

Parameters:

• Valid slot numbers: 0, 1, 2
• The maximum number of ui_indicators you can have on screen at the same time is 2. If you try to show a 3rd, one of the other 2 will disappear.
• x and y are screen offset coordinates from the top left corner. Not sure what they're measured in but it doesn't look like either pixels or tile coordinates. These coordinates are not affected by resolution though.
• The track_... form of coordinate parameter can only be used in battle mode
• Scale values:
  
  • can be as small as 0.05 (probably would work with smaller values, but would be pretty hard to see when that small).
  • 1 is big enough to go around the faction button
  • I'd recommend something around 0.7 or smaller for most things
  • Anything above 1 is going to be pretty big and 4 is huge and would most likely run off screen.
  
  
• Colour values are RGB, just like the documentation says. For example, 255 0 0 is red, 0 255 0 is green, 0 0 255 is blue.
• If the period parameter is not used, the animation will draw once and stay on screen until erased. If used, it will automatically erase the indicator after the specified number of seconds. If the loop keyword was used, it will then re-draw it.
• Animations:
  
  • circle - same animation as point_at_character
  • new_arrow_down - same animation as point_at_strat_position
  • arrow_down_left, arrow_down_right, arrow_up_left, arrow_up_right - same animation as those supported by point_at_message. If you use the same coordinates and just change the animation, in all 4 cases the arrow points to the same spot, but from different directions
  
  

Notes:

• The ui_flash_start command always uses slot 2. I'm pretty sure, so do the rest of them.

Example (adopted from RTR VII: TIC code) :

Display a blue circle surrounding Hamilcar's starting position on the strategy map and a red arrow on the mini-map to mark Hamilcar's invasion force arriving from Africa to Iberia, then erase both after 30 seconds.

ui_indicator 0 circle 585 505 colour 0 0 255 scale .7            ; Hamilcar
ui_indicator 1 arrow_up_left 110 727 colour 255 0 0 scale .3    ; mini-map: Invasion from Africa
wait 30
ui_indicator_remove 1
ui_indicator_remove 0

This is by no means an exhaustive research of every possible combination of parameters, but hopefully gave you a basic understanding of its usage and will get you to try it out in your scripts.

[Pat89]

x and y are screen offset coordinates from the top left corner. Not sure what they're measured in but it doesn't look like either pixels or tile coordinates. These coordinates are not affected by resolution though.

I think they're based on the basic resolution of 1024x768 like almost all elements in RTW (campaign/battle UI, menu, splash screen etc)

[IMPERATOR AUGUSTUS CAESAR]

so.... with this i can give a specific portrait to a specific character?
and can i make in the ui folder an other folder with portraits and cards for each faction?

[HouseOfHam]

no... where did you get that idea?

[Withwnar]

Brilliant... just what I was looking for. Thanks HouseOfHam.

x and y are screen offset coordinates from the top left corner. Not sure what they're measured in but it doesn't look like either pixels or tile coordinates. These coordinates are not affected by resolution though.

I noticed that when I took a screenshot and opened it in Photoshop the coordinates and pixels were 1:1. Screenshots are 1024x768, confirming PatricianS' comment I believe.