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.

The GitHub source files for SCPUI are available 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.

The FSO Engine's Lua API provides a library of methods for interfacing with UI code. Please consult the scripting.html file and the UserInterface (ui) library for details.

Visual Customization

Unlike FSO's built-in User Interface, SCPUI liberally re-uses visual assets wherever possible. Because of this, there are only about 225 image files compared to retail's thousands. This makes changing the look and feel of the UI incredibly easy even for those who are not interested in modifying the underlying Lua code.

Background

You can change the main background image for all SCPUI screens by simply replacing bg.png.

Logo

There are several UI screens that use a logo image. It comes in three main variants...

• Standard
  • Replace logo.png to replace the standard logo throughout all of SCPUI.
• Wide
  • For FS2, this logo is the version with the "wings". Replace logo-wide.png to change this one.
• Loop
  • In FS2 this is the SOC logo used in the Loop Brief UI. For this one replace loop-logo.png

Elements

The main UI elements (window boxes, button panels, etc) are all re-used liberally throughout SCPUI. At the time of writing this article, there are 53 of these files in total. You can modify them however you like.

• It is highly recommended you do not change the aspect ratio of these images if you do not want to have to modify RML and RCSS files.

Buttons

There are a number of button styles that SCPUI uses to match FS2's retail UI. Each button has at least three images: Main, Hover, and On. Generally they are designated like the following example:

arrow-up.png ;;Main
arrow-up-h.png ;;Hover
arrow-up-o.png ;;On

In some cases there are Positive and Negative versions. These are named like the following example:

select.png ;;Main
select-pos-h.png ;;Positive Hover
select-pos-o.png ;;Positive On
select-neg-h.png ;;Negative Hover
select-neg-o.png ;;Negative On

3D Select Icons

SCPUI supports both 2D pre-drawn icons as well as generated 3D icons. However, they are handled a little differently than inside base FSO. Instead of drawing the 3D models each frame in place of an icon, SCPUI pre-generates icon images on game start and displays those in place of the actual icons.

In order to efficiently generate icons for only the ships and weapons that are player-selectable, some additional data is needed in the ships.tbl and weapons.tbl.

Ships

For ships, the following Custom Data value must be set.

$Custom Data:
	+Val: PlayerShip true
$end_custom_data

Weapons

For weapons, the following Custom Data value must be set.

$Custom Data:
	+Val: PlayerWeapon true
$end_custom_data

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 ScpuiSystem: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 Ashes 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 scpui_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 scpui_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 ScpuiOptionValues 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 ScpuiOptionValues.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 scpui_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 ScpuiOptionValues' 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 are currently supported by SCPUI.

• Barracks
• Briefing
• Campaign Select
• Command Briefing
• Control Config
• Debriefing
• Fiction Viewer
• Game Paused
• Game Help
• Hotkey Config
• HUD Config
• Loop Briefing
• Medals
• Mission Log
• Options
  • Multi Options are not yet supported
• Pilot Select
• Red Alert
• Ship Select
• 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
• Tech Room Missions
• Weapon Select

Development and Debugging

There are three main things to know when developing and debugging SCPUI.

1. You can view the librocket debugger by pressing ctrl-shift-d
2. You can live-reload RML and RCSS files by pressing ctrl-shift-r

• • It's worth noting that Librocket will drop the existing elements and lose them in memory. This will cause a warning on game-exit.

1. Librocket API warnings and errors are not currently forwarded to FSO's error handling. Because of this, simple bugs in your Lua code that uses the API cause cause FSO to crash.

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.

• The Medals UI cannot be done programmatically. New art is required and mod-specific RML and RCSS files need to be created. The base release of SCPUI includes the necessary setup for FS2's medals.

• For 3D weapon selection, SCPUI can only use Tech models and you need to make sure you have Closeup_Pos and Closeup_Zoom set. If you don't have a tech model, just set the regular model file as the tech model in your table.

Tutorials

• TODO