Scpui

SCPUI is a term that refers to both the LUA Script implementation and the user interface LUA API in the FreespaceOpen engine available from versions 23.2 onwards. It is intended to be used with the librocket libraries to replace the base Freespace Open interface in an easily customizable way through LUA scripts.

The original implementation of SCPUI was started by m!m and finished by MjnMixael. It is available here. This specific implementation attempts to replicate the original Freespace UI experience while offering enhancements such as in-game options not normally available.

For documentation on the Librocket API, go here.

Overview

SCPUI works by completely overriding a given game state's internal code. Everything that interface should be expected to do must be handled in the Lua scripts. Methods to get and set appropriate game data are supplied by FSO's UI API. The core file that handles this is ui_system-sct.tbl. This file is SCPUI's state management controller. If it detects a valid SCPUI interface for a given game state, it will load a librocket file and begin execution of the appropriate scripts.

At the time of writing this, SCPUI is not compatible with multiplayer and will automatically disable itself if the game is put into multiplayer mode.

An SCPUI game state definition has three main files; RML, RCSS, and LUA. More information is available on those specific pages, but for now it's enough to know that RML is a kind of base HTML, RCSS is a base CSS, and LUA is an FSO compatible LUA file.

The lua file for that state will be run until an FSO game state change is detected. When that happens, the ui_system-sct will clean up the librocket elements and then check if a new set of SCPUI files should be loaded.

Game State Management

SCPUI's game state management is handled by a config file that simply lists the game state from FSO's game states and matches it with an RML file that will be associated. One notable exception is GS_STATE_SCRIPTING which allows for substates. This feature means that you can effectively create an unlimited amount of custom UIs that all exist within GS_STATE_SCRIPTING.

• To call a built-in game state use ba.postGameEvent("gamestate").
• To call a scripting substate use RocketUiSystem:beginSubstate("substate")

SCPUI.tbl

• SCPUI defines what game states and substates exist for SCPUI through the use of this table file and modular -ui.tbms.
• Begins with #State Replacement and ends with #End

$State:

• The game state to replace from FSO's game states
• Syntax: string

+Substate:

• The name of the substate
• Required for GS_STATE_SCRIPTING
• Syntax: string

+Markup:

• The path to the RML file definition to use for the game state
• Must include the file path
• Syntax: string

Example

#State Replacement

$State: GS_STATE_INITIAL_PLAYER_SELECT
+Markup: data/interface/markup/pilot_select.rml

$State: GS_STATE_SCRIPTING
+Substate: Newsroom
+Markup: data/interface/markup/journal.rml

#End

Dialog Popups

Freespace Open has a number of built-in dialog popups throughout the user interface. SCPUI automatically intercepts those popups and displays them as a librocket styled popup window.

You can create your own custom dialog popups within the UI scripts. To do this you must include local dialogs = require("dialogs") within the scope of your script. The dialogs function has several parameters for you to define.

Title

• Used to define the title of the dialog window.
• dialog:title("yourtitle")

Text

• Used to define the text or description your popup will contain.
• dialog:text("yourtext")

Input

• Defines if the user can type a string as input
• Useful for allowing the user to name pilots, saves, etc
• User must press ENTER to allow the code to execute on the provided string
• True to allow input, false to disallow. Defaults to false if this parameter is not provided.
  • dialog:input(boolean)

Buttons

• Defines the user-clickable buttons that will be included in the dialog. It has the following parameters
• Type can be one of the following:
  • dialogs.BUTTON_TYPE_POSITIVE
  • dialogs.BUTTON_TYPE_NEGATIVE
  • dialogs.BUTTON_TYPE_NEUTRAL
• Text is the text for the button, such as "Okay".
• Value is the data that will be returned when the button is clicked.
• Keypress is the keyboard shortcut for this button.
• dialog:buttons(type, text, value, keypress)

Escape

• Used to define if the user should be able to cancel the dialog popup with the ESC key.
• A non nil value enables ESC and will be the return value if ESC is pressed
• dialog:escape(value)

Show

• This is the final step that displays the popup and defines how to handle the return values
• return values come back as the parameter response
• The ui.enableInput() here specifically enables input on the dialog popup context. The dialog will automatically return input to the SCPUI context when it's closed.

dialog:show(self.document.context)
   :continueWith(function(response)
      "Execute code here"
   end)
ui.enableInput(self.document.context)

Custom Mod Options

• TODO

Individual UIs

• TODO

Save Data System

• TODO

Librocket

Documentation on how to interface with the librocket API can be found here.

Tips

• In general, the ui system will handle passing control back and forth between the SCPUI context and FSO. In rare cases you may need to handle this manually. The FSO API methods ui.enableInput() and ui.disableInput() are provided to handle this case.

Tutorials

• TODO