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.

Librocket

Librocket is a pseudo html/css rendering library included with FSO. It is designed as a complete solution for any project's interface needs.SCPUI uses this library to create and manage each UI context.

LibRocket uses the time-tested open standards XHTML1.0 and CSS2.0 (while borrowing features from HTML5 and CSS3), and extends them with features suited towards real-time applications.

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

Game State Management

SCPUI's game state management is handled by the scpui.tbl 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's state management system is setup with scpui.tbl or xxx-ui.tbm files. Documentation on scpui.tbl is available here.

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

The Custom Options in the Between the Aahes mod.

SCPUI comes with a built-in feature to allow for custom in-game options specific to a particular mod. These options are defined by options.tbl and saved to the player folder as mod_options.cfg. Scripts can take advantage of this feature to allow players to customize how scripts run, or if they even run at all.

For example, you could take the HUD Icons script and create a global toggle. This allows players to turn HUD Icons on or off entirely. Furthermore you could allow customizing the max opacity of the icons, the distance at which the icons become fully transparent, and the distance at which the icons become fully opaque. These options will all within the in-game Options UI.

'Note that $Mod_title: in game_settings.tbl is required for this feature to work!'
It's a good idea to make sure your mod title is unique to avoid mod options collisions.

Options.tbl

This table file is used to define the Options buttons within the Options UI.

It can be extended with xxx-optn.tbl
Documentation on the options.tbl is available here.

Save Structure

The player's options are saved to mod_options.cfg in data/players. This makes the options available across mod versions. The save structure within the file follows a player->mod->option hierarchy. (See example below.) This allows for each player to have their own preferences for each mod they play without interfering with other players' preferences.

"John": {
	"Between The Ashes": {
		"Alarm_Voice": "Vasudan",
		"Verbose_Debugging": "Off",
		"Font_Multiplier": 2,
		"Icon_Far": 2,
		"Icon_Near": 5,
		"Brief_Render_Option": "Texture",
		"Icon_Opacity": "1",
		"Cockpit_Alarms": "On",
		"HUD_Icons": "Off",
		"Cockpit_Rendering": "Off",
		"Easter_Eggs": "On"
	}
},
"Mike": {
	"Between The Ashes": {
		"Cockpit_Rendering": "Off",
		"Easter_Eggs": "On",
		"Font_Multiplier": 5,
		"Icon_Far": 2,
		"Icon_Near": 5,
		"Brief_Render_Option": "Texture",
		"Icon_Opacity": "1",
		"Cockpit_Alarms": "On",
		"HUD_Icons": "Off",
		"Verbose_Debugging": "On",
		"Alarm_Voice": "Female"
	}
}

Accessing Save Data

Modifying Options within the in-game UI and saving those values to a file is just a start. In order for these options to do anything, you'll need to hook them into your scripts. After the Pilot Select screen and a player is chosen, the current Options are available in a global variable called modOptionValues with direct access to a specific option by specifying the option key.

It may be recommended to create a script-tbl.tbm that runs $On State End and checks if hv.OldState is either "GS_STATE_INITIAL_PLAYER_SELECT" or "GS_STATE_OPTIONS_MENU". If true, then forward the option preferences to your script's local values.

#Conditional Hooks
$Application: FS2_Open
$On State End:
[
if hv.OldState.Name == "GS_STATE_INITIAL_PLAYER_SELECT" or hv.OldState.Name == "GS_STATE_OPTIONS_MENU" then
	if modOptionValues.HUD_Icons == "On" then
		ba.print("MOD OPTION: Player enabled HUD Icons")
		RadarIcon.PlayerEnabled = true
	else
		ba.print("MOD OPTION: Player disabled HUD Icons")
		RadarIcon.PlayerEnabled = false
	end
end
]
#End

Font Size Multiplier

It is worth noting that this option, included in SCPUI by default, is hard coded into each SCPUI interface. If the option is not present then a default will be used. It is highly recommended that this option is not removed.

Pilot Select

The pilot select UI has special handling of custom mod options, including Font Size Multiplier because player preferences cannot be loaded until a player is selected. For this specific use case, SCPUI creates a mod_options_global.cfg whenever user preferences are saved. This file contains no mod or player specific information in the save structure. It is just a list of key/value pairs for the most recently used pilot.

This setup was created specifically to handle the font size option during player selection, but it can be used to perform script actions before a player is selected if necessary.
In this case, options are still available as modOptionValues' and accessed the same way, but there is no guarantee that the option will exist depending on the last mod the player played.

Individual UIs

The following FSO UIs states are currently supported by SCPUI.

Barracks
Briefing
- Uses an OnFrame drawing method
Campaign Select
Command Briefing
Control Config
Debriefing
Fiction Viewer
Game Paused
Game Help
Hotkey Config
HUD Config
- Uses an OnFrame drawing method
Loop Briefing
Medals
Mission Log
Options
- Multi Options are not yet supported
Pilot Select
Red Alert
Ship Select
- Uses an OnFrame drawing method
Tech Room Credits
Tech Room Cutscenes
- Because of FSO/Librocket limitations, viewing a cutscene actually sets SCPUI to a Scripting Substate for the duration of the cutscene itself.
Tech Room Database
- Uses an OnFrame drawing method
Tech Room Missions
Weapon Select
- Uses an OnFrame drawing method

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