UI Scripting

The script has extensive powers to query and modify the UI. Historically, this comes from the UI actually being driven by script back in Empire: Total War. The UI is now driven by code but much of the script interface still remains.

A link to the uicomponent interface documentation is provided here: uicomponent.

Back to top

The UI Hierarchy

The visible and invisible screen objects that make up the UI are arranged into a hierarchy which can be traversed over by code and by script. Each uicomponent in the hierarchy is the child of one parent uicomponent, and may itself have many child uicomponents, which may themselves contain children and so on. This architecture allows a change to the properties of a parent uicomponent, such as its position on the screen or its visibility, to cascade down through all its children.

At the top of the uicomponent hierarchy sits a special uicomponent, called root, which is the only uicomponent with no parent. When the UI is created a UICreated script event is triggered, which may be queried in script to get a handle to the root uicomponent*. It is from the root that all other uicomponents are accessed.

*note that in battle this is not actually the mechanism by which the root uicomponent is accessed, but the end result is the same.

Some script library functions that can assist in finding specific components in the hierarchy may be found here: UIComponents. In particular, find_uicomponent is the main script function used to obtain handles to uicomponents.

Back to top

UIComponent Interface

Once a handle to a uicomponent has been obtained, calls may be made to it to query and modify its state. The suite of functions that may be called on a uicomponent is documented here: uicomponent

Back to top

UI Script Events

As well as UICreated, the UI sends a number of other events to script when certain things happen in the UI. These include events to do with advice, uicomponents being clicked on and panels opening and closing. Like other script events, the context these events supply can be queried to determine more information about what has happened in the game. See the page on scripted_events for more information about events in general.

Back to top

Modifying the Game State from UI Events

Care must be taken when writing scripts that may be run in multiplayer mode not to modify the game state in scripts that are triggered by UI events. Whereas the game model state is guaranteed to be the same on each machine in a multiplayer game, the UI on each machine is likely to be in a different state. Therefore, modifying the model in scripts triggered from UI events (on panel open, or on mouse click for example) is likely to cause changes on one machine in a multiplayer game and not on other machines in the same game, which will cause the multiplayer game to desync and terminate.

Last updated 12/10/19 15:46:49