Skip to content

UI Configuration and Development

Jump to bottom
lythx edited this page Apr 7, 2023 · 3 revisions

Introduction

Trakman UI plugin is a powerful tool which makes UI configuration and development easy. Changes to each widget placement and appearance can be made through configuration files without the need for any programming knowledge. Basic elements such as buttons can be added without any coding required.

UI Config Files

Every UI component has its own config file (js file in the same directory as the component). These config can be used to modify appearance and behaviour of specific widgets for example change height, width or colours. There are also main UI configs in ui/config folder, which can be used to add simple elements, modify general UI appearance, widget placement, mods and IDS. The main configs are:

  • Buttons - Simple static buttons placement, appearance and utility. Modify this file if you want to add static buttons to your UI layout, or change the appearance of existing ones.
  • RaceUi - General appearance of widgets used in race mode and widget layouts for each gamemode. Modify this file if you want to change position of a race mode widget, add a new widget to the layout or change stuff like background colours or margins.
  • ResultUi - General appearance of widgets used in result mode and widget layout. Modify this file if you want to change position of a result mode widget, add a new widget to the layout or change stuff like background colours or margins.
  • ComponentIds - Manialink ids of all UI components. If you want to add a new component add an entry for it in this file. Remember to keep gaps between ids because many widgets need multiple manialink ids for click features. (recommended gap size is 10000)
  • Mod - Trackmania mods config. Supports multiple modes for each gamemode, has a random order option. Modify this file if you want to add a mod to your server.
  • Icons - UI icons urls. Modify this file if you want to change some icon or add a new one.
  • FlagIcons - UI flag icons urls. Modify this file if you want to change some flag or add a new one.
  • PopupWindow - General appearance of UI pop-up windows (for example Maplist, Sector Records). Modify this file if you want to change stuff like background colours, margins or default window size.
  • CustomUi - Special UI manialink config used to display or hide the default game appearance elements such as score table or chat.
  • UtilsIds - Manialink ids of UI utils.

UI Component Templates

Abstract classes used to create manialink components.

StaticComponent

Abstract class for static manialink components.
Methods:

  • constructor(id: number)
    • id Component manialink ID
  • getRelativePosition(): { x: number, y: number, side: boolean }
    Gets position relative to other static manialinks based on current static UI layout.
    • Returns Object containing coordinates and side of the component
  • abstract display(params?: any): void
    Displays the manialink to all the players**
    • params Optional params
  • abstract displayToPlayer(login: string, params?: any): void
    Displays the manialink to given player
    • login Player login
    • params Optional params
  • hide(): void
    Hides the manialink for all players
  • abstract getHeight(): number Gets component height. Used for static UI positioning
    • Returns Component height
  • updatePosition(): void
    Updates positionX, positionY, and side props, calls onPositionChange
  • onPositionChange(): void
    Executed on static UI layout change, by default calls the display() method
  • updateIsDisplayed(): void
    Updates _isDisplayed prop based on current static UI layout
  • static onComponentCreated(callback: (component: StaticComponent) => void): void
    Add a callback function to execute when new component object gets created
    • callback Function to execute on event
  • static refreshStaticLayouts(): void
    Refreshes static UI layouts and updates displayed components

Properties:

  • isDisplayed Boolean indicating whether component should be displayed according to preset display mode.
  • id Component manialink ID

DynamicComponent

Abstract class for dynamic manialink components.

Methods:

  • constructor(id: number)
    • id Component manialink ID
  • abstract displayToPlayer(login: string, params?: any): void
    Displays the manialink to given player
    • login Player login
    • params Optional params
  • hideToPlayer(login: string) : void
    Hides the manialink for given player
    • login Player login

Properties:

  • id Component manialink ID

PopupWindow

Abstract class for manialink popup windows.
generic <DisplayParams = any> DisplayParams is type passed from display function to construct functions.

Methods:

  • constructor(windowId: number, headerIcon: string, title: string, navbar: { name: string, actionId: number, privilege?: number }[] = [], windowWidth: number = config.windowWidth, windowHeight: number = config.windowHeight)

    • windowId Window ID. All PopupWindows have the same manialink ID. Use openId to access this property
    • headerIcon Header image url
    • title Header title
    • navbar Array of objects containing navbar entry name, action ID and optional privilege
    • windowWidth Window width
    • windowHeight Window height

  • displayToPlayer(login: string, params?: DisplayParams, topRightText?: string, privilege?: number, title?: string, icon?: string): Promise
    Displays window to given player based on manialink XML strings returned by construct methods.

  • login Player login

  • params Display params to be passed to construct methods

  • topRightText Text displayed in right part of the header

  • privilege Player privilege

  • title If set given title is displayed instead of the title passed in constructor

  • icon If set given icon is displayed instead of the icon passed in constructor

  • abstract constructContent(login: string, params?: DisplayParams, privilege?: number): string | Promise
    Method called on displayToPlayer. It returns manialink XML string to be displayed inside window content.

  • login Player login

  • params Display params passed to displayToPlayer

  • privilege Player privilege

  • Returns Content XML string

  • abstract constructFooter(login: string, params?: DisplayParams, privilege?: number): string | Promise
    Method called on displayToPlayer. It returns manialink XML string to be displayed inside window footer.

  • login Player login

  • params Display params passed to displayToPlayer

  • privilege Player privilege

  • Returns Footer XML string

  • constructNavbar(login: string, params?: DisplayParams, privilege?: number): string
    Method called on displayToPlayer, by default it constructs navbar from parameters passed to constructor.

  • login Player login

  • params Display params passed to displayToPlayer

  • privilege Player privilege

  • Returns Navbar XML string

  • onOpen(info: tm.ManialinkClickInfo): void
    Method called on openId action ID. By default it displays the window to the player.

  • info Manialink event info

  • onClose(info: tm.ManialinkClickInfo): void
    Method called on openId action ID. By default it hides the window to the player.

  • info Manialink event info

Properties:

  • openId Action ID used to open the window
  • closeId Action ID used to close the window
  • headerIcon Header image url
  • title Header title
  • navbar Navbar object
  • navbarHeight Navbar height
  • windowWidth Full window width
  • windowHeight Full window height
  • contentWidth Window content width (middle part)
  • contentHeight Window content height (middle part)
  • headerHeight Header height
  • headerBackground Header background colour
  • background Background colour
  • margin Margin between window parts
  • footerHeight Footer height
  • headerPageWidth Right header part width (usually used for page display)

UI Utils

Functions and classes providing utilities for manialink components.

Grid

Util to display tabular data in manialinks. It's used in almost every popup window and some static manialinks too.
Methods:

  • constructor(width: number, height: number, columnProportions: number[], rowProportions: number[], options?: { background?: string, margin?: number, headerBackground?: string })

    • width Grid width
    • height Grid height
    • columnProportions Grid column proportions (proportions are relative to eachother like in CSS flexbox)
    • rowProportions Grid row proportions
    • options Optional properties
      • background Grid cell background
      • headerBackground Grid header cell background (1st row)
      • margin Margin around grid cells

  • constructXml(objectsOrFunctions: (GridCellFunction | GridCellObject)[]): string
    Creates grid XML string from passed callback functions. Use GridCellObjects if you want to change some property for specific grid cell eg. rowspan.

    • objectsOrFunctions Array of GridCellFunctions functions or GridCellObjects
    • Returns Grid XML string

Properties:

  • width Grid width
  • height Grid height
  • columnWidths Width of each grid column
  • rowHeights Height of each grid row
  • columns Column count
  • rows Row count
  • background Background colour
  • margin Margin between cells and around grid
  • headerBg Header background colour

List

Util to display list data in manialinks. Displays 3 columns of data from which one is index. It's used in result screen static manialinks eg. Top Donations.
Methods:

  • constructor(entries: number, width: number, height: number, columnProportions: number[], options?: { background?: string, headerBg?: string })
    • entries Number of entries to display
    • width List width
    • height List height
    • columnProportions List column proportions (proportions are relative to eachother like in CSS flexbox)
    • options Optional properties
      • background List cell background
      • headerBackground List header background
  • constructXml(col1: string[], col2: string[]): string Constructs list XML from passed string arrays
    • col1 Array of strings to display in column 1
    • col2 Array of strings to display in column 2
    • Returns List XML string

Properties:

  • entries Displayed entries count
  • height List height
  • width List width
  • columnProportions List column proportions (proportions are relative to eachother like in CSS flexbox)
  • background Background colour
  • headerBg Header background colour

RecordList

Util to display record data in manialinks. It has index, name and time columns, but it also can display more data on click eg. checkpoints. Records and time colours are displayed relative to players personal record. It's used in static record lists eg. Local Records.
Methods:

  • constructor(preset: 'result' | 'race', parentId: number, width: number, height: number, rows: number, side: boolean, topCount: number, maxCount: number, noRecordEntry: boolean, options?: { getColoursFromPb?: true })
    • preset Default preset options to use
    • parentId Parent element manialink ID
    • width List width
    • height List height
    • rows List row count
    • side Side on which list is positioned needed for click info display (true is right)
    • topCount Number of records which are always displayed regardless of player personal record
    • maxCount Max record count needed for click actionIds
    • noRecordEntry If true, a placeholder entry gets displayed at the end of the list if the player has no personal record
    • options Optional parameters
      • getColoursFromPb If true list time colours are relative to player personal records
  • onClick(callback: (info: tm.ManialinkClickInfo) => void): void
    Registers a callback function to execute on record click
    • callback Callback function, it takes ManialinkClickInfo as a parameter
  • constructXml(login: string, allRecords: UiRecord[]): string
    Constructs record list XML for given player from passed array of record objects.
    • login Player login
    • allRecords Array of record objects TODO LINK
    • Returns Record list XML string

Properties:

  • infoColumns Info grid column count
  • infoColumnWidth Info grid column width
  • infoIconWidth Info icon width
  • infoIcon Info icon url
  • infoBackground Info background colour
  • background Background colour
  • headerBackground Header background colour
  • markerWidth Marker width
  • parentId Parent element manialink ID
  • config Present config used
  • columnWidths List column widths
  • rows List row count
  • rowHeight List row height
  • width List width
  • side List side (true is right)
  • topCount Number of records which are always displayed regardless of player personal record
  • markers Marker icons
  • downloadIcon Download icon url
  • timeColours: Time string colours

Types:

  • RLImage
    Record list image object
    • url Image url
    • horizontalPadding Optional horizontal padding, relative to the parent element
    • verticalPadding Optional vertical padding, relative to the parent element
  • RLRecord
    Record list record object
    • time Record time
    • text Text to display instead of time
    • login Player login (displayed on click)
    • name Player name
    • date Record date (displayed on click)
    • checkpoints Record checkpoints (displayed after click)
    • url If set the menu displayed on click will have a button redirecting to given url
    • points Points amount displayed next to the record
    • colour Points amount background colour
    • image Image to display instead of time
    • markerImage Custom marker image to display instead of default marker

Navbar

Util to display horizontal navbar, used by popup windows.
Methods:

  • constructor(buttons: { name: string, actionId: number, privilege?: number }[], width: number, height: number | null = config.height, background: string = config.background, hoverImgUrl: string = config.hoverImage)
    • buttons Array of button objects
    • width Navbar width
    • height Navbar height
    • background Navbar background
    • hoverImgUrl Background image to display on button hover
  • getButtonCount(privilege: number = 0): number
    Gets button count for given privilege
    • privilege Privilege (0 by default)
    • Returns Button count
  • constructXml(privilege: number = 0): string
    Creates navbar XML string for given privilege
    • privilege Privilege (0 by default)
    • Returns Navbar XML string

Properties:

  • width Navbar width
  • height Navbar height
  • hoverImage Background image displayed on button hover
  • background Background colour

StaticHeader

Util to display manialink headers in static UI. Methods:

  • constructor(preset: 'race' | 'result' = 'race', options: Partial = {})
    • preset Default preset options to use
    • options Optional parameters. Parameters in this object override preset parameters. TODO Interface
  • constructXml(text: string, icon: string, side: boolean, options: Partial = {}): string Constructs header manialink used in static UI
    • text Header text
    • icon Header icon
    • side Header side. Text and icon are displayed in different order depending on side (true is right)
    • options Optional parameters. Parameters in this object override parameters in preset and constructor. TODO Interface
    • Returns Header XML string

Properties:

  • options Header options TODO Interface
  • raceHeight Default height in race preset
  • resultHeight Defualt height in result preset
  • racePreset Race preset options
  • resultPreset = Result preset options

Paginator

Util to manage pagination and render page change buttons. It's used in almost every popup window. Use the onPageChange property to listen for page changes. Remember to use destroy() before deleting the object to avoid memory leaks.
Methods:

  • constructor(parentId: number, parentWidth: number, parentHeight: number, pageCount: number, defaultPage: number = 1, noMidGap?: true)
    • parentId Parent element manialink id
    • parentWidth Parent element width
    • parentHeight Parent element height
    • pageCount Initial page count
    • defaultPage Default page (will be displayed if no page is specified)
    • noMidGap If true there will be no bonus gap between previous and next buttons
  • constructXml(page: number): string
    Constructs page change buttons XML for given player login
    • login Player login
    • Returns Page change buttons XML string
  • constructXml(login: string): string
    Constructs page change buttons XML for given page number
    • page Page number
    • Returns Page change buttons XML string
  • getPageByLogin(login: string): number
    Gets current page of a given player.
    • login Player login
    • Reset Page number
  • setPageForLogin(login: string, page: number): number
    Sets page for a given player
    • login Player login
    • page Page number
    • Returns Page number
  • setPageCount(pageCount: number): void
    Sets page count
    • pageCount Page count
  • resetPlayerPages(): void
    Resets current player page positions.
  • destroy(): void
    Removes click listener. Use this before deleting the object to avoid memory leaks.
    Properties:
    • onPageChange Sets function to execute on page change
    • pageCount Amount of pages
    • buttonCount Amount of currently displayed buttons. It's relative to the page count
    • parentId Parent element ID
    • defaultPage Default page (will be displayed if no page is specified)
    • buttonW Button width
    • buttonH Button height
    • padding Icon padding
    • margin Margin between buttons
    • iconW Icon width
    • iconH Icon height
    • ids Ids used by paginator buttons
    • width Paginator width
    • height Paginator height
    • yPos Y axis position of paginator buttons
    • xPos X axis positions of paginator buttons
    • noMidGap If true there is no bonus gap between previous and next buttons

VoteWindow

Util to manage votes and render vote manialink window.
Methods:

  • constructor(callerLogin: string, goal: number, headerMessage: string, chatMessage: string, seconds: number, iconUrl: string)
    • callerLogin Login of the player who called the vote
    • goal Ratio of votes needed to pass the vote (must be between 0 and 1)
    • headerMessage Message displayed in vote window header
    • chatMessage Chat message sent to chat on vote start
    • seconds Amount of time to vote
    • iconUrl Icon image url
  • startAndGetResult(eligibleLogins: string[]): Promise<boolean | { result: boolean, caller?: tm.Player }> | undefined
    Starts the vote and awaits result.
    • eligibleLogins List of logins of players that can vote
    • Returns Vote result as boolean if time ran out or all the players voted, object containing result and optional caller player object if vote got passed or cancelled, undefined if there is another vote running
  • pass(caller?: tm.Player): void
    Passes the vote
    • caller Caller player object
  • cancel(caller?: tm.Player): void
    Cancels the vote
    • caller Caller player object

closeButton

(actionId: number, parentWidth: number, parentHeight: number, options?: CloseButtonOptions): string
Constructs XML string for "X" button manialink. Used in popup windows.

  • actionId Action ID to execute on click
  • parentWidth Width of parent element
  • parentHeight Height of parent element
  • options Optional properties TODO LINK
  • Returns Button XML string

fullScreenListener

(actionId: number, zIndex: number = -100): string
Constructs an invisible manialink covering the entire screen with given actionId and zIndex.

  • actionId Manialink Action ID
  • zIndex Manialink Z position
  • Returns Manialink XML string

getCpTypes

(checkpoints: number[][]): ('best' | 'worst' | 'equal' | undefined)[][]
Finds best, equal and worst times for each checkpoint.

  • checkpoints 2D array containing checkpoint times
  • Returns 2D array containing checkpoint types

addKeyListener

(key: 'F5' | 'F6' | 'F7', callback: (info: tm.ManialinkClickInfo) => void, importance: number)
Registers a callback function to execute on given key press.

  • key Key to register listener on
  • callback Function to execute on key press, it takes ManialinkClickInfo as a parameter
  • importance Importance index - only the function with highest importance index will get executed

removeKeyListener

(callback: (info: tm.ManialinkClickInfo) => void)
Removes a key listener.

  • callback Reference to function to remove

addManialinkListener

(actionId: number, callback: (info: tm.ManialinkClickInfo) => void): void
Adds a callback function to execute on given Action ID.

  • actionId Manialink Action ID
  • callback Callback function, it takes ManialinkClickInfo as a parameter

(actionId: number, range: number, callback: (info: tm.ManialinkClickInfo, actionIdOffset: number) => void): void
Adds a callback function to execute on given Action ID range.

  • actionId Starting manialink Action ID
  • range Range of Action IDs (inludes starting Action ID)
  • callback Callback function, it takes ManialinkClickInfo and id offset as a parameter

removeManialinkListener

(callback: (info: tm.ManialinkClickInfo) => void)
Removes a manialink listener.

  • callback Reference to function to remove

staticButton

(iconUrl: string, text1: string, text2: string, width: number, height: number, options?: StaticButtonOptions): string
Constructs button manialink used in static UI.

  • iconUrl Button image url
  • text1 Top text
  • text2 Bottom text
  • width Button width
  • height Button height
  • options Optional parameters TODO LINK
  • Returns Button XML string

centeredText

(text: string, parentWidth: number, parentHeight: number, options?: UITextOptions): string
Constructs manialink with centered text.

  • text Text to display
  • parentWidth Parent element width
  • parentHeight Parent element height
  • options Optional parameters TODO LINK
  • Returns Text XML string

leftAlignedText

(text: string, parentWidth: number, parentHeight: number, options?: UITextOptions): string
Constructs manialink with left aligned and vertically centered text.

  • text Text to display
  • parentWidth Parent element width
  • parentHeight Parent element height
  • options Optional parameters
  • Returns Text XML string

rightAlignedText

(text: string, parentWidth: number, parentHeight: number, options?: UITextOptions): string
Constructs manialink with right aligned and vertically centered text

  • text Text to display
  • parentWidth Parent element width
  • parentHeight Parent element height
  • options Optional parameters
  • Returns Text XML string

horizontallyCenteredText

(text: string, parentWidth: number, parentHeight: number, options?: UITextOptions): string
Constructs manialink with horizontally centered text

  • text Text to display
  • parentWidth Parent element width
  • parentHeight Parent element height
  • options Optional parameters
  • Returns Text XML string

Clone this wiki locally