DOCSEARCHbyAlgolia
Submit Docs

ScaleformUI

repository·master·Indexed 41 days ago

https://github.com/manups4e/scaleformui

A UI library for GTA V that separates raw engine interaction from domain-specific logic using a two-layer architecture of low-level wrappers and high-level components. It implements a tick-based rendering model for transient Scaleforms and provides comprehensive C# and Lua design patterns, along with a wide array of enums for HUD colors, icons, and navigation.

Tokens
76.5K
Snippets
261
Records
333
Agent score
49%

What's inside ScaleformUI

  1. What is ScaleformUI?

    master

    ScaleformUI is a library designed to help developers build Rockstar-style menus and pause menus. It provides tools for handling notifications, markers, and common in-game HUD features using Scaleform.

    Language Support:

    • C#: Full API support with event-based callbacks.
    • Lua: Full API support. Note that in Lua, many functions return a value when no parameter is provided or nil is sent; it is recommended to check the source code for specific return behaviors.
    • JS/TypeScript: Planned for future support.

  2. Overview of the HUD and Notifications API

    master
    ScaleformUI provides a static API for managing in-game HUD elements, notifications, markers, and 3D text drawing. This API allows developers to interface with the game's UI layer to display information to the player both on the 2D screen (HUD) and within the 3D game world (World Elements).

  3. Overview of the Scaleforms API

    master
    ScaleformUI provides a static, user-friendly API designed to manage various scaleforms (UI overlays) within a game environment. Instead of low-level manipulation, developers use high-level API calls to trigger specific UI elements like mission banners, countdowns, or player lists. Each scaleform type has its own dedicated documentation page detailing its specific methods and configuration options.

  4. Create a UIMenuListItem

    master

    A UIMenuListItem is a menu item that displays a list of values which the user can scroll through (left/right). It inherits all standard UIMenuItem functions.

    Warning: This item is scheduled to become obsolete and legacy. For future-proof, runtime-friendly implementations, use UIMenuDynamicListItem instead.

    // C# Constructors
UIMenuListItem(string text, List<dynamic> items, int index)
UIMenuListItem(string text, List<dynamic> items, int index, string description)
UIMenuListItem(string text, List<dynamic> items, int index, string description, HudColor mainColor, HudColor higlightColor)
    -- Lua Constructor
UIMenuListItem.New(Text, Items, Index, Description, mainColor, highlightColor, textColor, highlightedTextColor)

  6. Display world elements in 3D space

    master

    To render information directly within the 3D game environment, use the following features:

    • Markers: Create 3D world markers with customizable types, positions, scales, and colors. Markers can include behaviors like bobbing or rotating.
    • DrawText3D: Draw text directly in the 3D game world at specified coordinates with customizable fonts, sizes, and colors.

  7. Access the Rankbar instance

    master

    The Rankbar is a Scaleform UI component used to display experience and rank progress. Depending on your environment, you can access the instance via C# or Lua:

    • C#: Use Main.RankBarInstance.
    • Lua: Use ScaleformUI.Scaleforms.RankbarHandler.
    // C# Access
Main.RankBarInstance
    -- Lua Access
ScaleformUI.Scaleforms.RankbarHandler

  9. Create a menu with UIMenu

    master

    ScaleformUI provides different classes depending on the type of interface you want to build:

    • UIMenu: The main class for standard menus and item management.
    • TabView: Used for creating Pause Menus.
    • MainView: Used for creating Lobby Screens.

    Menu Items

    All items inherit from UIMenuItem. Common item types include:

    • UIMenuItem: Basic items.
    • UIMenuDynamicListItem: List items with runtime execution (replaces the soon-to-be-deprecated UIMenuListItem).
    • UIMenuCheckboxItem: For true/false toggles.
    • UIMenuSliderItem: For slider controls.
    • UIMenuProgressItem: For progress bars (e.g., volume controls).
    • UIMenuSeparatorItem: To separate groups of items.
    • UIMenuStatsItem: Special items used for character creation (similar to progress items).

    Advanced UI Elements

    Beyond items, a menu can also contain:

    • Panels: Displayed below or beside the menu.
    • Windows: Specialized UI elements like the Heritage window or Statistics window.

  11. How the tick-based rendering model works

    master

    Because Scaleforms in GTA V are transient and must be drawn every frame to remain visible, ScaleformUI uses a tick-based rendering model:

    • Registration: Components register themselves within a global tick loop (via C# Tick events or Lua Citizen.CreateThread).
    • State Check: Every tick, the loop verifies which components are active and loaded.
    • Drawing: Active components invoke internal update methods that call low-level render methods (like Render2D or Render3D), which in turn call native drawing functions (e.g., DrawScaleformMovieFullscreen).
    • Disposal: When a component is closed, it is disposed of, stopping the tick loop for that component and releasing the movie handle from memory.

  12. Lua design patterns in ScaleformUI

    master

    When using ScaleformUI in Lua, the library uses table-based and procedural patterns idiomatic to Lua:

    • Getter/Setter Methods: Since Lua lacks native properties, use methods for state checks (e.g., IsShowing(), IsValid(), IsLoaded()).
    • Callback Functions: Handle interactions by assigning functions to table fields (e.g., OnButtonPressed = function(button) ... end).
    • Dynamic Typing: Arguments are checked at runtime and mapped to scaleform types.
    • Promises: Use promises and callbacks when awaiting scaleform return values or loading states.