The Glest Wiki

GAE is able to customize the layout of the GUI via a Widget file, which is an engine-wide configuration file located in data/core/widget.cfg. This page tries to document the functions of the configuration file, which is written in Lua.


addColour(name, colourString);[]

Add a named colour. The name should be unique and the colourString is a hexadecimal representation of the colour (0xRRGGBBAA, or #RRGGBBAA, or RRGGBBAAh).

loadTexture(name, path, mipmap);[]

Load a named texture. The name should be unique and path is the complete path to the desired image file from the 'root' glest directory. An optioinal boolean 'mipmap' tells the engine whether to generate mipmaps for the texture or not, if omitted the default value is true, and this is generally appropriate, textures with 'fine detail' (such as those used for borders) being the exception to the general rule.

setOverlayTexture(type, texName);[]

The three texture overlays used on auto-command toggles are set via this function, it should be called three times with type 'tick', 'cross', & 'question'. The texName parameter is a previously loaded texture.

loadFont(name, path, size);[]

Load a named font. The name should be unique and path is the complete path to the desired font file from the 'root' glest directory. The size parameter sets the size in points. NOTE: size will not be exactly respected, and is scaled based on the window size/resolution the user is playing the game with.

setDefaultFont(type, fontName);[]

Set default and fallback fonts, should be called four times, with types 'menu', 'game', 'title' & 'version'. The menu and game fonts are fallbacks for text styles that are missing fonts, while title and version are used only for the 'advanced engine' and version labels on the root menu.

Style definitions[]

WidgetType = {
	Default = { --[[ Style definition for default state ]] },
	States = {
		Disabled = { --[[ style definition (or 'overrides') for disabled state ]] },
		Hover = { --[[ style definition (or 'overrides') for hover state ]] },
		Focus = { --[[ style definition (or 'overrides') for focus state ]] },
		Selected = { --[[ style definition (or 'overrides') for selected state ]] },

The default state determines a widgets 'normal' look, the tables within the States table determine their appearance in various behavioural states, any individual style elements that are not specified in a special state are copied from the default state.

A style definition consists of a table each for borders, background, highlight, text and overlay.


  • Type: A border style must contain a Type field, which must be one of 'none', 'invisible', 'raise', 'embed', 'solid', 'custom-sides', 'custom-corners' or 'texture'.
  • Sizes: If the Type is anything other than 'none', then a sizes table should be included, if not type texture it should contain four integers for the left, top, right & bottom border respectively, for type texture it should contain two integers for the side and corner size.
  • Colours: A table of one to four named colours, used where type is solid (single colour), raise or embed (two colours, light and dark respectively), custom-sides or custom-corners (four colours, [left, top, right, bottom or top-left, top-right, bottom-right, bottom-left). Not used for types none, invisible or texture.
  • Texture: A named texture, used only for type texture.


  • Type: A background style must contain a type, which should be 'none', 'colour', 'custom-colours' or 'texture'.
  • InsideBorders: boolean value indicating whether the background should be rendered only within the widgets borders, or over the entire widget's size.
  • Colours: A table of one or four named colours, used where type is colour (single entry) or custom-colours (four values: top-left, top-right, bottom-right, bottom-left).
  • Texture: named texture to use if type is texture.


  • Type: Style type, one of 'none', 'oscillate' or 'fixed'.
  • Colour: a named colour for the highlight.


  • Font: A named font that this widget should use for any text.
  • Colour: A named colour to render the font in.
  • Shadow: boolean value indicating whether text should be shadowed.
  • ShadowColour: a named colour the shadow should be rendered with.


  • Texture: a named texture identifying the overlat image.
  • InsideBorders: boolean value indicating whether the overlay should be rendered only within the widgets borders, or over the entire widget's size.

Widget Types[]

The following is a list of tables the engine looks for to style certain widgets,

  • StaticWidgetGamButton
  • CheckBox.Checked
  • CheckBox.UnChecked
  • TextBox
  • ListItem
  • ListBox
  • DropList
  • ScrollBar
  • ScrollBarButtonUp
  • ScrollBarButtonDown
  • ScrollBarButtonLeft
  • ScrollBarButtonRight
  • ScrollBarVerticalShaft
  • ScrollBarVerticalThumb
  • ScrollBarHorizontalShaft
  • ScrollBarHorizontalThumb
  • Slider
  • SliderVerticalShaft
  • SliderVerticalThumb
  • SliderHorizontalShaft
  • SliderHorizontalThumb
  • TitleBar
  • TitleBarCloseButton
  • TitleBarRollUpButton
  • TitleBarRollDownButton
  • TitleBarExpandButton
  • TitleBarShrinkButton
  • MessageBox
  • GameWidgetFrame
  • ToolTip
  • ToolTip.Header
  • ToolTip.Main
  • ToolTip.Item
  • ToolTip.RequirementMet
  • ToolTip.RequirementNotMet
  • ColourPicker
  • ColourButton
  • TickerTape
  • InfoWidget
  • Logger
  • Logger.Header
  • Logger.LogLine
  • CodeView
  • CodeEdit
  • ResourceBar
  • MiniMap
  • Display
  • Console
  • GameStats

See also[]